diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index a315e336e25b737eee259ae99983bc02b808df7a..fe8c697cb823f94313d1476f9937dd35d1e2ee2c 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -1,2327 +1,2327 @@
-"""Wrap CLI commands to run through Headroom proxy.
-
-Usage:
-    headroom wrap claude                    # Start proxy + rtk + claude
-    headroom wrap copilot -- --model ...    # Start proxy + launch GitHub Copilot CLI
-    headroom wrap codex                     # Start proxy + OpenAI Codex CLI
-    headroom wrap aider                     # Start proxy + aider
-    headroom wrap cursor                    # Start proxy + print Cursor config instructions
-    headroom wrap openclaw                  # Install + configure OpenClaw plugin
-    headroom wrap claude --no-rtk           # Without rtk hooks
-    headroom wrap claude --port 9999        # Custom proxy port
-    headroom wrap claude -- --model opus    # Pass args to claude
-"""
-
-from __future__ import annotations
-
-import io
-import json
-import os
-import shutil
-import signal
-import socket
-import subprocess
-import sys
-import time
-from pathlib import Path
-from typing import Any, cast
-
-# Fix Windows cp1252 encoding — box-drawing characters require UTF-8
-if sys.platform == "win32" and hasattr(sys.stdout, "buffer"):
-    if sys.stdout.encoding and sys.stdout.encoding.lower().replace("-", "") != "utf8":
-        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
-        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
-
-import click
-
-from headroom.copilot_auth import DEFAULT_API_URL as COPILOT_API_URL
-from headroom.copilot_auth import has_oauth_auth, resolve_client_bearer_token
-from headroom.providers.aider import build_launch_env as _build_aider_launch_env
-from headroom.providers.claude import proxy_base_url as _claude_proxy_base_url
-from headroom.providers.codex import build_launch_env as _build_codex_launch_env
-from headroom.providers.copilot import (
-    build_launch_env as _build_copilot_launch_env,
-)
-from headroom.providers.copilot import (
-    detect_running_proxy_backend as _copilot_detect_running_proxy_backend,
-)
-from headroom.providers.copilot import (
-    model_configured as _copilot_model_configured_impl,
-)
-from headroom.providers.copilot import (
-    provider_key_source as _copilot_provider_key_source,
-)
-from headroom.providers.copilot import (
-    query_proxy_config as _copilot_query_proxy_config,
-)
-from headroom.providers.copilot import (
-    resolve_provider_type as _copilot_resolve_provider_type,
-)
-from headroom.providers.copilot import (
-    validate_configuration as _validate_copilot_configuration,
-)
-from headroom.providers.cursor import render_setup_lines as _render_cursor_setup_lines
-from headroom.providers.openclaw import (
-    build_plugin_entry as _build_openclaw_plugin_entry_impl,
-)
-from headroom.providers.openclaw import (
-    build_unwrap_entry as _build_openclaw_unwrap_entry_impl,
-)
-from headroom.providers.openclaw import (
-    decode_entry_json as _decode_openclaw_entry_json_impl,
-)
-from headroom.providers.openclaw import (
-    normalize_gateway_provider_ids as _normalize_openclaw_gateway_provider_ids_impl,
-)
-
-from .main import main
-
-
-def _live_wrap_module() -> Any:
-    """Return the current live wrap module instance."""
-    return cast(Any, sys.modules[__name__])
-
-
-def _print_telemetry_notice() -> None:
-    """Print a telemetry notice when anonymous telemetry is enabled.
-
-    Respects the HEADROOM_TELEMETRY and HEADROOM_TELEMETRY_WARN feature flags.
-    Does nothing when telemetry or warnings are disabled.
-    """
-    from headroom.telemetry.beacon import format_telemetry_notice
-
-    notice = format_telemetry_notice(prefix="  ")
-    if notice:
-        click.echo(notice)
-
-
-# Proxy health check (reused from evals/suite_runner.py pattern)
-
-
-def _check_proxy(port: int) -> bool:
-    """Check if Headroom proxy is running on given port."""
-    try:
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-            s.settimeout(1)
-            s.connect(("127.0.0.1", port))
-            return True
-    except (TimeoutError, ConnectionRefusedError, OSError):
-        return False
-
-
-def _get_log_path() -> Path:
-    """Get path for proxy log file."""
-    from headroom import paths as _paths
-
-    log_dir = _paths.log_dir()
-    log_dir.mkdir(parents=True, exist_ok=True)
-    return log_dir / "proxy.log"
-
-
-def _start_proxy(
-    port: int,
-    *,
-    learn: bool = False,
-    memory: bool = False,
-    agent_type: str = "unknown",
-    code_graph: bool = False,
-    backend: str | None = None,
-    anyllm_provider: str | None = None,
-    region: str | None = None,
-    openai_api_url: str | None = None,
-) -> subprocess.Popen:
-    """Start Headroom proxy as a background subprocess.
-
-    Logs are written to ~/.headroom/logs/proxy.log to avoid pipe buffer
-    deadlocks (macOS pipe buffer is ~64KB — a busy proxy fills it quickly,
-    blocking the process).
-    """
-    cmd = [sys.executable, "-m", "headroom.cli", "proxy", "--port", str(port)]
-
-    # Forward HEADROOM_MODE env var so the proxy respects the user's mode choice
-    headroom_mode = os.environ.get("HEADROOM_MODE")
-    if headroom_mode:
-        cmd.extend(["--mode", headroom_mode])
-
-    # Forward --learn flag to proxy subprocess
-    if learn:
-        cmd.append("--learn")
-
-    # Forward --memory flag to proxy subprocess
-    if memory:
-        cmd.append("--memory")
-
-    # Forward --code-graph flag to proxy subprocess (live file watcher)
-    if code_graph:
-        cmd.append("--code-graph")
-
-    # Forward backend configuration to proxy subprocess
-    _backend = backend or os.environ.get("HEADROOM_BACKEND")
-    if _backend:
-        cmd.extend(["--backend", _backend])
-
-    _anyllm = anyllm_provider or os.environ.get("HEADROOM_ANYLLM_PROVIDER")
-    if _anyllm:
-        cmd.extend(["--anyllm-provider", _anyllm])
-
-    _region = region or os.environ.get("HEADROOM_REGION")
-    if _region:
-        cmd.extend(["--region", _region])
-
-    if openai_api_url:
-        cmd.extend(["--openai-api-url", openai_api_url])
-
-    log_path = _get_log_path()
-    log_file = open(log_path, "a")  # noqa: SIM115
-
-    # Ensure proxy subprocess uses UTF-8 (Windows defaults to cp1252)
-    proxy_env = os.environ.copy()
-    proxy_env["PYTHONIOENCODING"] = "utf-8"
-
-    # Tell the proxy which agent is being wrapped (for traffic learning output)
-    if agent_type != "unknown":
-        proxy_env["HEADROOM_AGENT_TYPE"] = agent_type
-        proxy_env.setdefault("HEADROOM_STACK", f"wrap_{agent_type}")
-
-    proc = subprocess.Popen(
-        cmd,
-        stdout=log_file,
-        stderr=log_file,
-        env=proxy_env,
-    )
-
-    # Wait for proxy to be ready (up to 45 seconds).
-    # ML components (Kompress, Magika, Tree-sitter) load synchronously before
-    # uvicorn binds the port. On slower machines this can take 20-30 seconds.
-    for _i in range(45):
-        time.sleep(1)
-        if _check_proxy(port):
-            click.echo(f"  Logs: {log_path}")
-            return proc
-        # Check if process died
-        if proc.poll() is not None:
-            log_file.close()
-            # Read last few lines of log for error context
-            try:
-                tail = log_path.read_text()[-500:]
-            except Exception:
-                tail = "(no log output)"
-            raise RuntimeError(f"Proxy exited with code {proc.returncode}: {tail}")
-
-    proc.kill()
-    log_file.close()
-    raise RuntimeError(f"Proxy failed to start on port {port} within 45 seconds")
-
-
-def _setup_rtk(verbose: bool = False) -> Path | None:
-    """Ensure rtk is installed and hooks are registered."""
-    from headroom.rtk import get_rtk_path
-    from headroom.rtk.installer import ensure_rtk, register_claude_hooks
-
-    rtk_path = get_rtk_path()
-
-    if rtk_path:
-        if verbose:
-            click.echo(f"  rtk found at {rtk_path}")
-    else:
-        click.echo("  Downloading rtk (Rust Token Killer)...")
-        rtk_path = ensure_rtk()
-        if rtk_path:
-            click.echo(f"  rtk installed at {rtk_path}")
-        else:
-            click.echo("  rtk download failed — continuing without it")
-            return None
-
-    # Register hooks (idempotent)
-    if register_claude_hooks(rtk_path):
-        if verbose:
-            click.echo("  rtk hooks registered in Claude Code")
-    else:
-        click.echo("  rtk hook registration failed — continuing without it")
-
-    return rtk_path
-
-
-_CBM_MCP_SERVER_NAME = "codebase-memory-mcp"
-
-
-def _register_cbm_mcp_server(cbm_bin: str) -> None:
-    """Register codebase-memory-mcp as an MCP server in Claude Code.
-
-    Uses ``claude mcp add`` so the tools appear in ``/mcp`` automatically.
-    Idempotent — skips if already registered.
-    """
-    claude_cli = shutil.which("claude")
-    if not claude_cli:
-        return
-
-    # Check if already registered
-    check = subprocess.run(
-        [claude_cli, "mcp", "get", _CBM_MCP_SERVER_NAME],
-        capture_output=True,
-        text=True,
-    )
-    if check.returncode == 0:
-        return  # Already registered
-
-    result = subprocess.run(
-        [claude_cli, "mcp", "add", _CBM_MCP_SERVER_NAME, "-s", "user", "--", cbm_bin],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode == 0:
-        click.echo(f"  Code graph: registered {_CBM_MCP_SERVER_NAME} MCP server")
-    else:
-        pass  # Non-critical — tools won't appear in /mcp but graph still works
-
-
-def _setup_code_graph(verbose: bool = False) -> bool:
-    """Ensure codebase-memory-mcp is installed, registered as MCP server, and project is indexed.
-
-    codebase-memory-mcp builds a knowledge graph of the codebase using
-    tree-sitter, enabling the LLM to query code structure (call chains,
-    function definitions, impact analysis) instead of reading entire files.
-
-    Steps:
-    1. Download the binary if not already present.
-    2. Register as an MCP server in Claude Code (``claude mcp add``).
-    3. Index the current project (fast, idempotent).
-
-    With Claude Code's MCP Tool Search, the 14 graph tools add ~200 tokens
-    overhead per request (not the full ~1,915) — they're lazy-loaded.
-
-    Returns True if graph is ready, False if setup failed.
-    """
-    from headroom.graph.installer import ensure_cbm, get_cbm_path
-
-    cbm_path = get_cbm_path()
-    if not cbm_path:
-        click.echo("  Code graph: downloading codebase-memory-mcp...")
-        cbm_path = ensure_cbm()
-        if cbm_path:
-            click.echo(f"  Code graph: installed at {cbm_path}")
-        else:
-            click.echo("  Code graph: download failed — skipping")
-            return False
-
-    cbm_bin = str(cbm_path)
-
-    # Register as MCP server so tools appear in /mcp
-    _register_cbm_mcp_server(cbm_bin)
-
-    # Index current project (fast — ~1s for most repos, idempotent)
-    project_dir = str(Path.cwd())
-    try:
-        result = subprocess.run(
-            [
-                cbm_bin,
-                "cli",
-                "index_repository",
-                json.dumps({"repo_path": project_dir, "mode": "fast"}),
-            ],
-            capture_output=True,
-            text=True,
-            timeout=30,
-        )
-        if result.returncode == 0:
-            # Parse node/edge counts from output
-            for line in result.stdout.splitlines():
-                if '"nodes"' in line:
-                    try:
-                        # Parse the JSON response to extract node/edge counts
-                        import re
-
-                        m_nodes = re.search(r'"nodes":(\d+)', line)
-                        m_edges = re.search(r'"edges":(\d+)', line)
-                        if m_nodes and m_edges:
-                            nodes = int(m_nodes.group(1))
-                            edges = int(m_edges.group(1))
-                            click.echo(
-                                f"  Code graph: indexed ({nodes:,} symbols, "
-                                f"{edges:,} relationships)"
-                            )
-                        else:
-                            click.echo("  Code graph: indexed")
-                    except (ValueError, AttributeError):
-                        click.echo("  Code graph: indexed")
-                    return True
-            click.echo("  Code graph: indexed")
-            return True
-        else:
-            if verbose:
-                click.echo(f"  Code graph: indexing failed ({result.stderr[:100]})")
-            return False
-    except subprocess.TimeoutExpired:
-        click.echo("  Code graph: indexing timed out (will complete in background)")
-        return False
-    except Exception as e:
-        if verbose:
-            click.echo(f"  Code graph: setup failed ({e})")
-        return False
-
-
-# rtk instructions for tools without hook support (Codex, Cursor, Aider).
-# These get injected into AGENTS.md / .cursorrules so the LLM voluntarily
-# uses rtk-prefixed commands. Kept concise to minimize instruction overhead.
-RTK_INSTRUCTIONS_BLOCK = """\
-<!-- headroom:rtk-instructions -->
-# RTK (Rust Token Killer) - Token-Optimized Commands
-
-When running shell commands, **always prefix with `rtk`**. This reduces context
-usage by 60-90% with zero behavior change. If rtk has no filter for a command,
-it passes through unchanged — so it is always safe to use.
-
-## Key Commands
-```bash
-# Git (59-80% savings)
-rtk git status          rtk git diff            rtk git log
-
-# Files & Search (60-75% savings)
-rtk ls <path>           rtk read <file>         rtk grep <pattern>
-rtk find <pattern>      rtk diff <file>
-
-# Test (90-99% savings) — shows failures only
-rtk pytest tests/       rtk cargo test          rtk test <cmd>
-
-# Build & Lint (80-90% savings) — shows errors only
-rtk tsc                 rtk lint                rtk cargo build
-rtk prettier --check    rtk mypy                rtk ruff check
-
-# Analysis (70-90% savings)
-rtk err <cmd>           rtk log <file>          rtk json <file>
-rtk summary <cmd>       rtk deps                rtk env
-
-# GitHub (26-87% savings)
-rtk gh pr view <n>      rtk gh run list         rtk gh issue list
-
-# Infrastructure (85% savings)
-rtk docker ps           rtk kubectl get         rtk docker logs <c>
-
-# Package managers (70-90% savings)
-rtk pip list            rtk pnpm install        rtk npm run <script>
-```
-
-## Rules
-- In command chains, prefix each segment: `rtk git add . && rtk git commit -m "msg"`
-- For debugging, use raw command without rtk prefix
-- `rtk proxy <cmd>` runs command without filtering but tracks usage
-<!-- /headroom:rtk-instructions -->
-"""
-
-# Marker used to detect if instructions are already injected
-_RTK_MARKER = "<!-- headroom:rtk-instructions -->"
-
-# Memory MCP markers
-_MEMORY_MCP_MARKER = "# --- Headroom memory MCP (auto-injected) ---"
-_MEMORY_MCP_END = "# --- end Headroom memory ---"
-_MEMORY_AGENTS_MARKER = "<!-- headroom:memory-instructions -->"
-
-# Codex config injection markers
-_CODEX_TOP_LEVEL_MARKER = "# --- Headroom proxy (auto-injected by headroom wrap codex) ---"
-_CODEX_END_MARKER = "# --- end Headroom ---"
-# File name used for the pre-wrap snapshot of ~/.codex/config.toml.  The
-# snapshot lets `headroom unwrap codex` restore the exact prior state, even
-# if the user had their own `model_provider` / `[model_providers.*]` config
-# before running wrap.
-_CODEX_CONFIG_BACKUP_SUFFIX = ".headroom-backup"
-
-
-def _codex_config_paths() -> tuple[Path, Path]:
-    """Return ``(config_file, backup_file)`` paths for the Codex TOML config."""
-    config_dir = Path.home() / ".codex"
-    config_file = config_dir / "config.toml"
-    backup_file = config_dir / f"config.toml{_CODEX_CONFIG_BACKUP_SUFFIX}"
-    return config_file, backup_file
-
-
-def _strip_codex_headroom_blocks(content: str) -> str:
-    """Remove all Headroom-managed blocks from a Codex ``config.toml`` string.
-
-    Returns the cleaned content.  Safe to call on content that never contained
-    any markers — it will be returned effectively unchanged (only trailing
-    whitespace is normalized).
-    """
-    import re
-
-    # Remove any top-level-marker → end-marker span, possibly repeated.
-    while _CODEX_TOP_LEVEL_MARKER in content and _CODEX_END_MARKER in content:
-        start = content.index(_CODEX_TOP_LEVEL_MARKER)
-        end_idx = content.index(_CODEX_END_MARKER, start)
-        if end_idx < start:
-            break
-        end = end_idx + len(_CODEX_END_MARKER)
-        content = content[:start].rstrip("\n") + "\n" + content[end:].lstrip("\n")
-
-    # Remove any stale top-level marker or end marker that lost its partner
-    # (e.g. a crashed prior wrap).
-    content = content.replace(_CODEX_TOP_LEVEL_MARKER + "\n", "")
-    content = content.replace(_CODEX_END_MARKER + "\n", "")
-
-    # Strip any leftover top-level `model_provider = "headroom"` line, which
-    # older versions of `wrap codex` wrote outside the marker block.
-    content = re.sub(r'(?m)^[ \t]*model_provider[ \t]*=[ \t]*"headroom"[ \t]*\r?\n', "", content)
-
-    # Strip any orphaned `[model_providers.headroom]` table with the fields we
-    # write.  We only remove it if the table is recognisably ours (base_url
-    # mentions localhost and a Headroom proxy port).  This protects users who
-    # happen to have a differently configured `headroom` provider.
-    orphan_headroom_table = re.compile(
-        r"(?ms)^\[model_providers\.headroom\][^\[]*?"
-        r'base_url[ \t]*=[ \t]*"http://127\.0\.0\.1:\d+/v1"[^\[]*?'
-        r"(?=^\[|\Z)"
-    )
-    content = orphan_headroom_table.sub("", content)
-
-    return content.lstrip("\n").rstrip() + "\n" if content.strip() else ""
-
-
-def _snapshot_codex_config_if_unwrapped(config_file: Path, backup_file: Path) -> None:
-    """Snapshot ``config.toml`` to ``backup_file`` before the first injection.
-
-    Called as the first step of every Headroom injection into Codex's
-    ``config.toml``.  Guarantees that ``headroom unwrap codex`` can restore the
-    user's original file byte-for-byte.
-
-    Rules:
-
-    * If the backup already exists, leave it alone — we only snapshot the
-      *pre-wrap* state, so running wrap repeatedly must not clobber it.
-    * If the config file doesn't exist yet, there's nothing to back up; unwrap
-      will remove the file entirely instead of restoring a snapshot.
-    * If the config already contains a Headroom marker, a wrap run is already
-      active: do not snapshot the injected state.
-    """
-    if backup_file.exists():
-        return
-    if not config_file.exists():
-        return
-    try:
-        content = config_file.read_text()
-    except OSError:
-        return
-    if _CODEX_TOP_LEVEL_MARKER in content or _CODEX_END_MARKER in content:
-        return
-    backup_file.parent.mkdir(parents=True, exist_ok=True)
-    shutil.copy2(config_file, backup_file)
-
-
-def _ensure_rtk_binary(verbose: bool = False) -> Path | None:
-    """Ensure rtk binary is installed (download if needed). No hook registration."""
-    from headroom.rtk import get_rtk_path
-    from headroom.rtk.installer import ensure_rtk
-
-    rtk_path = get_rtk_path()
-
-    if rtk_path:
-        if verbose:
-            click.echo(f"  rtk found at {rtk_path}")
-        return rtk_path
-
-    click.echo("  Downloading rtk (Rust Token Killer)...")
-    rtk_path = ensure_rtk()
-    if rtk_path:
-        click.echo(f"  rtk installed at {rtk_path}")
-        return rtk_path
-
-    click.echo("  rtk download failed — continuing without it")
-    return None
-
-
-def _prepare_wrap_rtk(verbose: bool = False, *, label: str | None = None) -> Path | None:
-    """Ensure rtk is present for host-bridged wrap flows without host-specific setup."""
-    if label:
-        click.echo(f"  Preparing rtk for {label}...")
-    return _ensure_rtk_binary(verbose=verbose)
-
-
-def _inject_codex_provider_config(port: int) -> None:
-    """Inject a Headroom model provider into Codex's config.toml.
-
-    Codex ignores OPENAI_BASE_URL for WebSocket transport unless a custom
-    provider declares ``supports_websockets = true``.  This writes a
-    ``[model_providers.headroom]`` section that routes both HTTP and WS
-    through the proxy, and sets ``model_provider = "headroom"``.
-
-    Safe to call multiple times — the injected block is fully replaced on
-    each call, so re-running with a different ``port`` updates the config.
-    Before the first injection, the pre-wrap file is snapshotted to
-    ``~/.codex/config.toml.headroom-backup`` so ``headroom unwrap codex``
-    can restore it byte-for-byte.
-    """
-    config_file, backup_file = _codex_config_paths()
-    config_dir = config_file.parent
-
-    # The injected content is split into two self-contained, marker-delimited
-    # blocks: a top-level key block (at the start of the file, because bare
-    # TOML keys must precede any [section]) and a provider-table block (at
-    # the end).  Each block has its own matching begin/end marker pair so
-    # stripping them is unambiguous and never consumes user content that
-    # happens to sit between the two.
-    top_level_block = (
-        f'{_CODEX_TOP_LEVEL_MARKER}\nmodel_provider = "headroom"\n{_CODEX_END_MARKER}\n'
-    )
-    provider_section = (
-        f"{_CODEX_TOP_LEVEL_MARKER}\n"
-        "[model_providers.headroom]\n"
-        'name = "OpenAI via Headroom proxy"\n'
-        f'base_url = "http://127.0.0.1:{port}/v1"\n'
-        f'env_key = "OPENAI_API_KEY"\n'
-        f"requires_openai_auth = true\n"
-        f"supports_websockets = true\n"
-        f"{_CODEX_END_MARKER}\n"
-    )
-
-    try:
-        config_dir.mkdir(parents=True, exist_ok=True)
-
-        # Snapshot the pre-wrap state before touching anything.  No-op if the
-        # config is already wrapped, is missing, or we've already snapshotted.
-        _snapshot_codex_config_if_unwrapped(config_file, backup_file)
-
-        if config_file.exists():
-            content = config_file.read_text()
-            # Remove any prior Headroom-managed blocks before re-injecting so
-            # the operation is idempotent and supports port changes.
-            content = _strip_codex_headroom_blocks(content)
-
-            # Place the top-level key block at the very beginning of the file
-            # (bare TOML keys must precede any [section]) and the provider
-            # table at the end.  User content, if any, sits between them.
-            user_content = content.strip()
-            if user_content:
-                content = top_level_block + "\n" + user_content + "\n\n" + provider_section
-            else:
-                content = top_level_block + "\n" + provider_section
-        else:
-            content = top_level_block + "\n" + provider_section
-
-        config_file.write_text(content)
-        click.echo(f"  Codex config: injected Headroom provider (WS + HTTP) into {config_file}")
-    except Exception as e:
-        click.echo(f"  Warning: could not update Codex config: {e}")
-
-
-def _restore_codex_provider_config() -> tuple[str, Path]:
-    """Undo ``_inject_codex_provider_config`` for ``~/.codex/config.toml``.
-
-    Returns a tuple of ``(status, config_file)`` where status is one of:
-
-    * ``"restored"`` — a pre-wrap backup existed and was restored; backup
-      file has been removed.
-    * ``"cleaned"``  — no backup existed, but the Headroom-managed block was
-      found and stripped out (preserving surrounding user content).
-    * ``"removed"``  — the config file only contained Headroom-managed
-      content (created by wrap) and has been deleted.
-    * ``"noop"``     — nothing to undo; no Headroom marker and no backup.
-    """
-    config_file, backup_file = _codex_config_paths()
-
-    # Case 1: pre-wrap snapshot exists — restore it exactly.
-    if backup_file.exists():
-        shutil.copy2(backup_file, config_file)
-        backup_file.unlink()
-        return "restored", config_file
-
-    # Case 2: no backup, but config file exists and has markers — strip them.
-    if config_file.exists():
-        original = config_file.read_text()
-        if _CODEX_TOP_LEVEL_MARKER in original or _CODEX_END_MARKER in original:
-            cleaned = _strip_codex_headroom_blocks(original)
-            if not cleaned.strip():
-                # Nothing left but Headroom content — remove the file entirely
-                # so Codex falls back to its default config.
-                config_file.unlink()
-                return "removed", config_file
-            config_file.write_text(cleaned)
-            return "cleaned", config_file
-
-    # Nothing to undo.
-    return "noop", config_file
-
-
-def _inject_rtk_instructions(file_path: Path, verbose: bool = False) -> bool:
-    """Inject rtk instructions into a file (AGENTS.md, .cursorrules, etc.).
-
-    Idempotent — skips if marker already present. Appends to existing content.
-    Returns True if instructions were written.
-    """
-    if file_path.exists():
-        existing = file_path.read_text()
-        if _RTK_MARKER in existing:
-            if verbose:
-                click.echo(f"  rtk instructions already in {file_path.name}")
-            return True
-        # Append to existing file
-        with open(file_path, "a") as f:
-            f.write("\n\n" + RTK_INSTRUCTIONS_BLOCK)
-    else:
-        file_path.parent.mkdir(parents=True, exist_ok=True)
-        file_path.write_text(RTK_INSTRUCTIONS_BLOCK)
-
-    click.echo(f"  rtk instructions injected into {file_path}")
-    return True
-
-
-def _inject_memory_mcp_config(db_path: str, user_id: str) -> None:
-    """Register headroom memory as an MCP server in Codex's config.toml.
-
-    Idempotent — replaces existing section if present.
-    """
-    import sys
-
-    config_dir = Path.home() / ".codex"
-    config_file = config_dir / "config.toml"
-
-    # Use forward slashes in TOML paths (works on all platforms, avoids
-    # backslash escaping issues on Windows)
-    python_bin = sys.executable.replace("\\", "/")
-    db_path_toml = db_path.replace("\\", "/")
-    mcp_section = (
-        f"\n{_MEMORY_MCP_MARKER}\n"
-        f"[mcp_servers.headroom_memory]\n"
-        f'command = "{python_bin}"\n'
-        f'args = ["-m", "headroom.memory.mcp_server", "--db", "{db_path_toml}", "--user", "{user_id}"]\n'
-        f"startup_timeout_sec = 30\n"
-        f"tool_timeout_sec = 30\n"
-        f"{_MEMORY_MCP_END}\n"
-    )
-
-    try:
-        config_dir.mkdir(parents=True, exist_ok=True)
-
-        # Snapshot pre-wrap state before touching config.toml so `unwrap codex`
-        # can fully restore it even when only `--memory` (not a full provider
-        # injection) was used.
-        _, backup_file = _codex_config_paths()
-        _snapshot_codex_config_if_unwrapped(config_file, backup_file)
-
-        if config_file.exists():
-            content = config_file.read_text()
-            if _MEMORY_MCP_MARKER in content:
-                start = content.index(_MEMORY_MCP_MARKER)
-                end = content.index(_MEMORY_MCP_END) + len(_MEMORY_MCP_END)
-                content = content[:start].rstrip("\n") + mcp_section + content[end:].lstrip("\n")
-            else:
-                content = content.rstrip() + "\n" + mcp_section
-        else:
-            content = mcp_section
-
-        config_file.write_text(content)
-        click.echo(f"  Memory MCP: registered in {config_file}")
-    except Exception as e:
-        click.echo(f"  Warning: could not register memory MCP: {e}")
-
-
-def _inject_memory_agents_md(file_path: Path) -> bool:
-    """Inject memory usage guidance into AGENTS.md.
-
-    Idempotent — skips if marker already present.
-    """
-    memory_block = (
-        f"{_MEMORY_AGENTS_MARKER}\n"
-        "## Memory\n\n"
-        "Use the `headroom_memory` MCP server for persistent cross-session knowledge.\n\n"
-        "**Before** answering questions about prior decisions, conventions, project context,\n"
-        "architecture, user preferences, org info, codenames, debugging history, or anything\n"
-        "from past sessions — call `memory_search` first.\n\n"
-        "**After** making durable decisions, discovering conventions, or learning important\n"
-        "facts — call `memory_save` to persist them for future sessions.\n\n"
-        "Memory is your first source of truth for anything not visible in the current conversation.\n"
-    )
-
-    if file_path.exists():
-        existing = file_path.read_text()
-        if _MEMORY_AGENTS_MARKER in existing:
-            return True  # Already injected
-        with open(file_path, "a") as f:
-            f.write("\n\n" + memory_block)
-    else:
-        file_path.parent.mkdir(parents=True, exist_ok=True)
-        file_path.write_text(memory_block)
-
-    click.echo(f"  Memory guidance injected into {file_path.name}")
-    return True
-
-
-def _resolve_copilot_provider_type(backend: str | None, provider_type: str) -> str:
-    """Resolve Copilot BYOK provider type for the current proxy backend."""
-    return _copilot_resolve_provider_type(backend, provider_type)
-
-
-def _query_proxy_config(port: int) -> dict[str, Any] | None:
-    """Query the running proxy's feature configuration via /health.
-
-    Returns a dict with keys like backend, optimize, cache, rate_limit,
-    memory, learn, code_graph, pid.  Returns None if unreachable or the
-    response lacks a config block.
-    """
-    return _copilot_query_proxy_config(port)
-
-
-def _detect_running_proxy_backend(port: int) -> str | None:
-    """Read the backend of an already-running proxy from its health endpoint."""
-    return _copilot_detect_running_proxy_backend(port)
-
-
-def _kill_proxy_by_pid(pid: int, port: int) -> bool:
-    """Terminate a proxy process by PID and wait for the port to free up.
-
-    Sends SIGTERM first, falls back to SIGKILL after 5 seconds.
-    Returns True if the port is free afterwards, False otherwise.
-    """
-    try:
-        os.kill(pid, signal.SIGTERM)
-    except ProcessLookupError:
-        pass  # Already gone
-    except PermissionError:
-        click.echo(f"  Warning: No permission to kill proxy PID {pid}")
-        return False
-
-    # Wait for port to free (up to 5 seconds)
-    for _ in range(50):
-        time.sleep(0.1)
-        if not _check_proxy(port):
-            return True
-
-    # SIGTERM didn't work — escalate to SIGKILL (Unix) or terminate (Windows)
-    try:
-        _kill_signal = getattr(signal, "SIGKILL", signal.SIGTERM)
-        os.kill(pid, _kill_signal)
-    except (ProcessLookupError, PermissionError):
-        pass
-
-    for _ in range(20):
-        time.sleep(0.1)
-        if not _check_proxy(port):
-            return True
-
-    return False
-
-
-def _find_persistent_manifest(port: int) -> Any:
-    """Return a matching persistent deployment manifest for the requested port."""
-    from headroom.install.state import list_manifests
-
-    manifests = [manifest for manifest in list_manifests() if manifest.port == port]
-    manifests.sort(key=lambda manifest: (manifest.profile != "default", manifest.profile))
-    return manifests[0] if manifests else None
-
-
-def _recover_persistent_proxy(port: int) -> bool:
-    """Start or recover a matching persistent deployment for the requested port."""
-    from headroom.install.health import probe_ready
-    from headroom.install.models import InstallPreset, SupervisorKind
-    from headroom.install.runtime import start_detached_agent, start_persistent_docker, wait_ready
-    from headroom.install.supervisors import start_supervisor
-
-    manifest = _find_persistent_manifest(port)
-    if manifest is None:
-        return False
-
-    if probe_ready(manifest.health_url):
-        click.echo(f"  Reusing persistent deployment '{manifest.profile}' on port {port}")
-        return True
-
-    if manifest.supervisor_kind == SupervisorKind.TASK.value:
-        click.echo(
-            f"  Warning: task-based deployment '{manifest.profile}' cannot be auto-recovered via wrap"
-        )
-        return False
-
-    click.echo(f"  Recovering persistent deployment '{manifest.profile}' on port {port}...")
-    try:
-        if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
-            start_persistent_docker(manifest)
-        elif manifest.supervisor_kind == SupervisorKind.SERVICE.value:
-            start_supervisor(manifest)
-        else:
-            start_detached_agent(manifest.profile)
-    except Exception as exc:
-        click.echo(
-            f"  Warning: could not recover persistent deployment '{manifest.profile}': {exc}"
-        )
-        return False
-
-    if wait_ready(manifest, timeout_seconds=45):
-        click.echo(f"  Recovered persistent deployment '{manifest.profile}' on port {port}")
-        return True
-
-    click.echo(f"  Warning: persistent deployment '{manifest.profile}' did not become ready")
-    return False
-
-
-def _copilot_model_configured(copilot_args: tuple[str, ...], env: dict[str, str]) -> bool:
-    """Return True when Copilot BYOK model selection is configured."""
-    return _copilot_model_configured_impl(copilot_args, env)
-
-
-def _should_use_copilot_oauth(
-    *,
-    backend: str | None,
-    provider_type: str,
-    env: dict[str, str],
-) -> bool:
-    """Prefer a reusable Copilot OAuth session when the requested routing supports it."""
-    if env.get("COPILOT_PROVIDER_API_KEY") or env.get("COPILOT_PROVIDER_BEARER_TOKEN"):
-        return False
-    if provider_type == "anthropic":
-        return False
-
-    effective_backend = backend or os.environ.get("HEADROOM_BACKEND")
-    if effective_backend not in (None, "", "anthropic"):
-        return False
-
-    return has_oauth_auth()
-
-
-def _ensure_proxy(
-    port: int,
-    no_proxy: bool,
-    *,
-    learn: bool = False,
-    memory: bool = False,
-    agent_type: str = "unknown",
-    code_graph: bool = False,
-    backend: str | None = None,
-    anyllm_provider: str | None = None,
-    region: str | None = None,
-    openai_api_url: str | None = None,
-) -> subprocess.Popen | None:
-    """Start or verify proxy. Returns process handle if we started it."""
-    helpers = _live_wrap_module()
-    if not no_proxy:
-        manifest = helpers._find_persistent_manifest(port)
-        if manifest is not None:
-            from headroom.install.health import probe_ready
-
-            if probe_ready(manifest.health_url):
-                click.echo(f"  Proxy already running on port {port}")
-                return None
-            if helpers._recover_persistent_proxy(port):
-                return None
-            if helpers._check_proxy(port):
-                raise click.ClickException(
-                    f"Persistent deployment '{manifest.profile}' on port {port} is not healthy."
-                )
-            click.echo(
-                f"  Warning: persistent deployment '{manifest.profile}' on port {port} "
-                "is stale; starting a fresh proxy instead."
-            )
-
-        if helpers._check_proxy(port):
-            # Proxy is running — check if it has the features we need
-            needs_restart = False
-            running_config = helpers._query_proxy_config(port)
-
-            if running_config is not None:
-                missing = []
-                if memory and not running_config.get("memory"):
-                    missing.append("memory")
-                if learn and not running_config.get("learn"):
-                    missing.append("learn")
-                if code_graph and not running_config.get("code_graph"):
-                    missing.append("code_graph")
-
-                if missing:
-                    needs_restart = True
-                    flags_str = ", ".join(f"--{f.replace('_', '-')}" for f in missing)
-                    click.echo(f"  Proxy on port {port} is missing: {flags_str}")
-                    click.echo("  Restarting proxy with upgraded configuration...")
-
-                    # Merge: keep features the running proxy already has
-                    memory = memory or bool(running_config.get("memory"))
-                    learn = learn or bool(running_config.get("learn"))
-                    code_graph = code_graph or bool(running_config.get("code_graph"))
-
-                    proxy_pid = running_config.get("pid")
-                    if proxy_pid is not None:
-                        if not helpers._kill_proxy_by_pid(int(proxy_pid), port):
-                            raise click.ClickException(
-                                f"Failed to stop existing proxy (PID {proxy_pid}) on port {port}. "
-                                "Stop it manually and retry."
-                            )
-                    else:
-                        click.echo(
-                            "  Warning: Running proxy does not expose PID. "
-                            "Cannot restart automatically."
-                        )
-                        click.echo(
-                            f"  Please stop the proxy on port {port} manually "
-                            f"and rerun with {flags_str}."
-                        )
-                        return None
-
-            if not needs_restart:
-                click.echo(f"  Proxy already running on port {port}")
-                return None
-
-        # Start (or restart) the proxy with the requested flags
-        click.echo(f"  Starting Headroom proxy on port {port}...")
-        try:
-            proc = cast(
-                subprocess.Popen[Any],
-                _live_wrap_module()._start_proxy(
-                    port,
-                    learn=learn,
-                    memory=memory,
-                    agent_type=agent_type,
-                    code_graph=code_graph,
-                    backend=backend,
-                    anyllm_provider=anyllm_provider,
-                    region=region,
-                    openai_api_url=openai_api_url,
-                ),
-            )
-            click.echo(f"  Proxy ready on http://127.0.0.1:{port}")
-            return proc
-        except RuntimeError as e:
-            click.echo(f"  Error: {e}")
-            raise SystemExit(1) from e
-    else:
-        if not helpers._check_proxy(port):
-            click.echo(f"  Warning: No proxy detected on port {port}")
-        return None
-
-
-def _make_cleanup(proxy_proc_holder: list, port: int = 8787) -> Any:
-    """Create a cleanup function that terminates the proxy on exit.
-
-    Only kills the proxy if no other headroom-wrapped clients are using it.
-    Checks by looking for other processes with ANTHROPIC_BASE_URL or
-    OPENAI_BASE_URL pointing at our port.
-    """
-
-    def _other_clients_exist() -> bool:
-        """Check if other processes are using this proxy."""
-        try:
-            # Count headroom wrap processes (excluding ourselves)
-            result = subprocess.run(
-                ["pgrep", "-f", f"127.0.0.1:{port}"],
-                capture_output=True,
-                text=True,
-            )
-            pids = [p.strip() for p in result.stdout.strip().split("\n") if p.strip()]
-            my_pid = str(os.getpid())
-            other_pids = [p for p in pids if p != my_pid]
-            return len(other_pids) > 0
-        except Exception:
-            return False  # If we can't check, assume no others
-
-    def cleanup(signum: int | None = None, frame: Any = None) -> None:
-        proc = proxy_proc_holder[0] if proxy_proc_holder else None
-        if proc and proc.poll() is None:
-            if _other_clients_exist():
-                # Other clients still using the proxy — leave it running
-                return
-            proc.terminate()
-            try:
-                proc.wait(timeout=5)
-            except subprocess.TimeoutExpired:
-                proc.kill()
-
-    return cleanup
-
-
-def _launch_tool(
-    binary: str,
-    args: tuple,
-    env: dict[str, str],
-    port: int,
-    no_proxy: bool,
-    tool_label: str,
-    env_vars_display: list[str],
-    *,
-    learn: bool = False,
-    memory: bool = False,
-    agent_type: str = "unknown",
-    code_graph: bool = False,
-    backend: str | None = None,
-    anyllm_provider: str | None = None,
-    region: str | None = None,
-    openai_api_url: str | None = None,
-) -> None:
-    """Common logic: start proxy, launch tool, clean up."""
-    proxy_holder: list[subprocess.Popen | None] = [None]
-    cleanup = _make_cleanup(proxy_holder, port)
-    signal.signal(signal.SIGINT, cleanup)
-    signal.signal(signal.SIGTERM, cleanup)
-
-    try:
-        click.echo()
-        padded = f"HEADROOM WRAP: {tool_label}".center(47)
-        click.echo("  ╔═══════════════════════════════════════════════╗")
-        click.echo(f"  ║{padded}║")
-        click.echo("  ╚═══════════════════════════════════════════════╝")
-        click.echo()
-
-        proxy_holder[0] = _ensure_proxy(
-            port,
-            no_proxy,
-            learn=learn,
-            memory=memory,
-            agent_type=agent_type,
-            code_graph=code_graph,
-            backend=backend,
-            anyllm_provider=anyllm_provider,
-            region=region,
-            openai_api_url=openai_api_url,
-        )
-
-        if code_graph:
-            _setup_code_graph(verbose=False)
-
-        click.echo()
-        click.echo(f"  Launching {tool_label} (API routed through Headroom)...")
-        for var in env_vars_display:
-            click.echo(f"  {var}")
-        if args:
-            click.echo(f"  Extra args: {' '.join(args)}")
-        _print_telemetry_notice()
-        click.echo()
-
-        result = subprocess.run([binary, *args], env=env)
-        raise SystemExit(result.returncode)
-
-    except SystemExit:
-        raise
-    except Exception as e:
-        click.echo(f"  Error: {e}")
-        raise SystemExit(1) from e
-    finally:
-        cleanup()
-
-
-def _run_checked(
-    cmd: list[str],
-    *,
-    cwd: Path | None = None,
-    action: str,
-) -> subprocess.CompletedProcess[str]:
-    """Run subprocess and raise a ClickException with actionable context on failure."""
-    try:
-        return subprocess.run(
-            cmd,
-            cwd=str(cwd) if cwd else None,
-            check=True,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-        )
-    except FileNotFoundError as e:
-        raise click.ClickException(f"{action} failed: command not found: {cmd[0]}") from e
-    except subprocess.CalledProcessError as e:
-        stderr = (e.stderr or "").strip()
-        stdout = (e.stdout or "").strip()
-        details = stderr or stdout or f"exit code {e.returncode}"
-        raise click.ClickException(f"{action} failed: {details}") from e
-
-
-def _resolve_openclaw_extensions_dir(openclaw_bin: str) -> Path:
-    """Resolve OpenClaw extension root from active config file path."""
-    result = _run_checked([openclaw_bin, "config", "file"], action="openclaw config file")
-    lines = result.stdout.strip().splitlines()
-    config_path_str = lines[-1].strip() if lines else ""
-    if not config_path_str:
-        raise click.ClickException(
-            "Unable to resolve OpenClaw config path from `openclaw config file`."
-        )
-    config_path = Path(config_path_str).expanduser()
-    return config_path.parent / "extensions"
-
-
-def _normalize_openclaw_gateway_provider_ids(provider_ids: tuple[str, ...] | None) -> list[str]:
-    """Normalize configured OpenClaw provider ids, defaulting to openai-codex."""
-    return _normalize_openclaw_gateway_provider_ids_impl(provider_ids)
-
-
-def _read_openclaw_config_value(openclaw_bin: str, path: str) -> Any | None:
-    """Read an OpenClaw config value when present, returning None on missing paths."""
-    result = subprocess.run(
-        [openclaw_bin, "config", "get", path],
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-    )
-    if result.returncode != 0:
-        return None
-
-    output = result.stdout.strip()
-    if not output:
-        return None
-
-    try:
-        return json.loads(output)
-    except json.JSONDecodeError:
-        return output
-
-
-def _decode_openclaw_entry_json(raw_value: str | None) -> Any | None:
-    """Decode a JSON payload captured from `openclaw config get` when available."""
-    return _decode_openclaw_entry_json_impl(raw_value)
-
-
-def _build_openclaw_plugin_entry(
-    *,
-    existing_entry: Any,
-    proxy_port: int,
-    startup_timeout_ms: int,
-    python_path: str | None,
-    no_auto_start: bool,
-    gateway_provider_ids: tuple[str, ...] | None,
-    enabled: bool,
-) -> dict[str, object]:
-    """Merge managed Headroom plugin settings with any existing entry payload."""
-    return _build_openclaw_plugin_entry_impl(
-        existing_entry=existing_entry,
-        proxy_port=proxy_port,
-        startup_timeout_ms=startup_timeout_ms,
-        python_path=python_path,
-        no_auto_start=no_auto_start,
-        gateway_provider_ids=gateway_provider_ids,
-        enabled=enabled,
-    )
-
-
-def _build_openclaw_unwrap_entry(existing_entry: Any) -> dict[str, object]:
-    """Disable the managed plugin while preserving unrelated user config."""
-    return _build_openclaw_unwrap_entry_impl(existing_entry)
-
-
-def _write_openclaw_plugin_entry(openclaw_bin: str, entry: dict[str, object]) -> None:
-    """Persist the Headroom plugin config entry."""
-    _run_checked(
-        [
-            openclaw_bin,
-            "config",
-            "set",
-            "plugins.entries.headroom",
-            json.dumps(entry, separators=(",", ":")),
-            "--strict-json",
-        ],
-        action="openclaw config set plugins.entries.headroom",
-    )
-
-
-def _set_openclaw_context_engine_slot(openclaw_bin: str, engine_id: str) -> None:
-    """Persist the selected OpenClaw context engine slot."""
-    _run_checked(
-        [
-            openclaw_bin,
-            "config",
-            "set",
-            "plugins.slots.contextEngine",
-            json.dumps(engine_id),
-            "--strict-json",
-        ],
-        action="openclaw config set plugins.slots.contextEngine",
-    )
-
-
-def _restart_or_start_openclaw_gateway(openclaw_bin: str) -> tuple[str, str]:
-    """Restart the gateway when running, otherwise start it."""
-    restart_result = subprocess.run(
-        [openclaw_bin, "gateway", "restart"],
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-    )
-    if restart_result.returncode == 0:
-        output = restart_result.stdout.strip() or restart_result.stderr.strip()
-        return "restarted", output
-
-    start_result = _run_checked(
-        [openclaw_bin, "gateway", "start"],
-        action="openclaw gateway start",
-    )
-    output = start_result.stdout.strip() or start_result.stderr.strip()
-    return "started", output
-
-
-def _copy_openclaw_plugin_into_extensions(
-    *,
-    plugin_dir: Path,
-    openclaw_bin: str,
-) -> Path:
-    """Fallback install path when `openclaw plugins install` is blocked on linked source."""
-    dist_dir = plugin_dir / "dist"
-    if not dist_dir.exists():
-        raise click.ClickException(
-            f"Plugin dist folder missing at {dist_dir}. Build the plugin first."
-        )
-    hook_shim_dir = plugin_dir / "hook-shim"
-    if not hook_shim_dir.exists():
-        raise click.ClickException(
-            f"Plugin hook-shim folder missing at {hook_shim_dir}. Build the plugin first."
-        )
-
-    extensions_dir = _resolve_openclaw_extensions_dir(openclaw_bin)
-    target_dir = extensions_dir / "headroom"
-    target_dist = target_dir / "dist"
-    target_hook_shim = target_dir / "hook-shim"
-    target_dir.mkdir(parents=True, exist_ok=True)
-    if target_dist.exists():
-        shutil.rmtree(target_dist)
-    if target_hook_shim.exists():
-        shutil.rmtree(target_hook_shim)
-    shutil.copytree(dist_dir, target_dist)
-    shutil.copytree(hook_shim_dir, target_hook_shim)
-
-    for filename in ("openclaw.plugin.json", "package.json", "README.md"):
-        source = plugin_dir / filename
-        if source.exists():
-            shutil.copy2(source, target_dir / filename)
-
-    return target_dir
-
-
-@main.group()
-def wrap() -> None:
-    """Wrap CLI tools to run through Headroom.
-
-    \b
-    Starts a Headroom proxy, configures the environment, and launches
-    the target tool so all API calls route through Headroom automatically.
-
-    \b
-    Supported tools:
-        headroom wrap claude              # Claude Code (Anthropic)
-        headroom wrap copilot -- --model claude-sonnet-4-20250514
-        headroom wrap codex               # OpenAI Codex CLI
-        headroom wrap aider               # Aider
-        headroom wrap cursor              # Cursor (prints config instructions)
-        headroom wrap openclaw            # OpenClaw plugin bootstrap
-    """
-
-
-@main.group()
-def unwrap() -> None:
-    """Undo durable Headroom wrapping for supported tools."""
-
-
-# =============================================================================
-# Claude Code
-# =============================================================================
-
-
-@wrap.command(context_settings={"ignore_unknown_options": True})
-@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
-@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and hook registration")
-@click.option(
-    "--code-graph",
-    is_flag=True,
-    help="Enable code graph indexing via codebase-memory-mcp (optional)",
-)
-@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
-@click.option(
-    "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to MEMORY.md)"
-)
-@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
-@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
-@click.option("--prepare-only", is_flag=True, hidden=True)
-@click.argument("claude_args", nargs=-1, type=click.UNPROCESSED)
-def claude(
-    port: int,
-    no_rtk: bool,
-    code_graph: bool,
-    no_proxy: bool,
-    learn: bool,
-    memory: bool,
-    verbose: bool,
-    prepare_only: bool,
-    claude_args: tuple,
-) -> None:
-    """Launch Claude Code through Headroom proxy.
-
-    \b
-    Sets ANTHROPIC_BASE_URL to route all Anthropic API calls through Headroom.
-    All unknown flags are passed through to claude (e.g. --resume, --model).
-
-    \b
-    Examples:
-        headroom wrap claude                    # Start everything
-        headroom wrap claude --memory           # With persistent memory
-        headroom wrap claude --resume <id>      # Resume a session
-        headroom wrap claude -- -p              # Claude in print mode
-        headroom wrap claude --code-graph        # With code graph intelligence
-        headroom wrap claude --no-rtk           # Skip rtk (proxy only)
-    """
-    if prepare_only:
-        if not no_rtk:
-            _prepare_wrap_rtk(verbose=verbose, label="Claude")
-        return
-
-    claude_bin = shutil.which("claude")
-    if not claude_bin:
-        click.echo("Error: 'claude' not found in PATH.")
-        click.echo("Install Claude Code: https://docs.anthropic.com/en/docs/claude-code")
-        raise SystemExit(1)
-
-    # Setup rtk before launching (Claude-specific)
-    proxy_holder: list[subprocess.Popen | None] = [None]
-    cleanup = _make_cleanup(proxy_holder, port)
-    signal.signal(signal.SIGINT, cleanup)
-    signal.signal(signal.SIGTERM, cleanup)
-
-    # Memory sync BEFORE proxy startup — sync headroom DB ↔ Claude's files
-    if memory:
-        try:
-            import subprocess as _sp
-
-            mem_dir = Path.cwd() / ".headroom"
-            mem_dir.mkdir(parents=True, exist_ok=True)
-            _sync_db = str(mem_dir / "memory.db")
-            _sync_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))
-
-            click.echo(f"  Syncing memory (user={_sync_user})...")
-            sync_result = _sp.run(
-                [
-                    sys.executable,
-                    "-m",
-                    "headroom.memory.sync",
-                    "--db",
-                    _sync_db,
-                    "--user",
-                    _sync_user,
-                    "--agent",
-                    "claude",
-                    "--force",
-                ],
-                capture_output=True,
-                text=True,
-                timeout=30,
-            )
-            if sync_result.returncode == 0 and sync_result.stdout.strip():
-                import json as _json
-
-                stats = _json.loads(sync_result.stdout.strip().split("\n")[-1])
-                imp, exp, ms = stats["imported"], stats["exported"], stats["ms"]
-                if imp or exp:
-                    click.echo(f"  Memory synced: {imp} imported, {exp} exported ({ms}ms)")
-                else:
-                    click.echo(f"  Memory: up to date ({ms}ms)")
-            elif sync_result.returncode != 0:
-                click.echo(f"  Warning: memory sync error: {sync_result.stderr[-200:]}")
-        except Exception as e:
-            click.echo(f"  Warning: memory sync failed: {e}")
-
-    try:
-        click.echo()
-        click.echo("  ╔═══════════════════════════════════════════════╗")
-        click.echo("  ║            HEADROOM WRAP: CLAUDE              ║")
-        click.echo("  ╚═══════════════════════════════════════════════╝")
-        click.echo()
-
-        proxy_holder[0] = _ensure_proxy(
-            port, no_proxy, learn=learn, memory=memory, agent_type="claude", code_graph=code_graph
-        )
-
-        if not no_rtk:
-            click.echo("  Setting up rtk...")
-            _setup_rtk(verbose=verbose)
-        elif verbose:
-            click.echo("  Skipping rtk (--no-rtk)")
-
-        if code_graph:
-            _setup_code_graph(verbose=verbose)
-
-        click.echo()
-        click.echo("  Launching Claude Code (API routed through Headroom)...")
-        click.echo(f"  ANTHROPIC_BASE_URL={_claude_proxy_base_url(port)}")
-        if claude_args:
-            click.echo(f"  Extra args: {' '.join(claude_args)}")
-        _print_telemetry_notice()
-        click.echo()
-
-        env = os.environ.copy()
-        env["ANTHROPIC_BASE_URL"] = _claude_proxy_base_url(port)
-
-        result = subprocess.run([claude_bin, *claude_args], env=env)
-        raise SystemExit(result.returncode)
-
-    except SystemExit:
-        raise
-    except Exception as e:
-        click.echo(f"  Error: {e}")
-        raise SystemExit(1) from e
-    finally:
-        cleanup()
-
-
-# =============================================================================
-# GitHub Copilot CLI
-# =============================================================================
-
-
-@wrap.command(context_settings={"ignore_unknown_options": True})
-@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
-@click.option(
-    "--no-rtk",
-    is_flag=True,
-    help="Skip rtk installation and Copilot instructions injection",
-)
-@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
-@click.option(
-    "--backend",
-    default=None,
-    help="API backend for the proxy: 'anthropic', 'anyllm', 'litellm-vertex', etc. (env: HEADROOM_BACKEND)",
-)
-@click.option(
-    "--anyllm-provider",
-    default=None,
-    help="Provider for any-llm backend: openai, mistral, groq, etc. (env: HEADROOM_ANYLLM_PROVIDER)",
-)
-@click.option(
-    "--region", default=None, help="Cloud region for Bedrock/Vertex (env: HEADROOM_REGION)"
-)
-@click.option(
-    "--provider-type",
-    type=click.Choice(["auto", "anthropic", "openai"]),
-    default="auto",
-    show_default=True,
-    help="Copilot BYOK provider mode. 'auto' uses anthropic for the default proxy backend and openai for translated backends.",
-)
-@click.option(
-    "--wire-api",
-    type=click.Choice(["completions", "responses"]),
-    default=None,
-    help="OpenAI-compatible Copilot wire API. Defaults to 'completions' when provider-type resolves to openai.",
-)
-@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
-@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
-@click.argument("copilot_args", nargs=-1, type=click.UNPROCESSED)
-def copilot(
-    port: int,
-    no_rtk: bool,
-    no_proxy: bool,
-    backend: str | None,
-    anyllm_provider: str | None,
-    region: str | None,
-    provider_type: str,
-    wire_api: str | None,
-    memory: bool,
-    verbose: bool,
-    copilot_args: tuple[str, ...],
-) -> None:
-    """Launch GitHub Copilot CLI through Headroom proxy.
-
-    \b
-    Configures Copilot CLI BYOK provider variables so Copilot routes through
-    the local Headroom proxy. In auto mode, the wrapper uses Anthropic-style
-    routing for the stock proxy backend and OpenAI-compatible routing for
-    translated backends such as any-llm and LiteLLM.
-
-    \b
-    Examples:
-        headroom wrap copilot -- --model claude-sonnet-4-20250514
-        headroom wrap copilot --backend anyllm --anyllm-provider groq -- --model gpt-4o
-        headroom wrap copilot --provider-type openai --wire-api responses -- --model gpt-5.4
-        headroom wrap copilot --no-rtk -- --prompt "explain this file"
-    """
-    copilot_bin = shutil.which("copilot")
-    if not copilot_bin:
-        click.echo("Error: 'copilot' not found in PATH.")
-        click.echo(
-            "Install GitHub Copilot CLI: "
-            "https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli"
-        )
-        raise SystemExit(1)
-
-    effective_backend = backend or os.environ.get("HEADROOM_BACKEND")
-    if _check_proxy(port):
-        running_backend = _detect_running_proxy_backend(port)
-        if effective_backend and running_backend and effective_backend != running_backend:
-            raise click.ClickException(
-                f"Proxy already running on port {port} with backend '{running_backend}'. "
-                f"Stop it or rerun with --backend {running_backend}."
-            )
-        effective_backend = running_backend or effective_backend
-
-    effective_provider_type = _resolve_copilot_provider_type(effective_backend, provider_type)
-    _validate_copilot_configuration(
-        provider_type=effective_provider_type,
-        wire_api=wire_api,
-        backend=effective_backend,
-    )
-
-    if not no_rtk:
-        click.echo("  Setting up rtk for Copilot...")
-        rtk_path = _ensure_rtk_binary(verbose=verbose)
-        if rtk_path:
-            copilot_instructions = Path.cwd() / ".github" / "copilot-instructions.md"
-            _inject_rtk_instructions(copilot_instructions, verbose=verbose)
-
-    env = os.environ.copy()
-    openai_api_url: str | None = None
-    if _should_use_copilot_oauth(
-        backend=effective_backend,
-        provider_type=provider_type,
-        env=env,
-    ):
-        client_bearer = resolve_client_bearer_token()
-        if not client_bearer:
-            raise click.ClickException(
-                "GitHub Copilot auth was detected but no reusable bearer token could be resolved."
-            )
-
-        effective_wire_api = wire_api or "completions"
-        env["COPILOT_PROVIDER_TYPE"] = "openai"
-        env["COPILOT_PROVIDER_BASE_URL"] = f"http://127.0.0.1:{port}/v1"
-        env["COPILOT_PROVIDER_WIRE_API"] = effective_wire_api
-        env["COPILOT_PROVIDER_BEARER_TOKEN"] = client_bearer
-        env.pop("COPILOT_PROVIDER_API_KEY", None)
-        env_vars_display = [
-            "COPILOT_PROVIDER_TYPE=openai",
-            f"COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:{port}/v1",
-            f"COPILOT_PROVIDER_WIRE_API={effective_wire_api}",
-            "COPILOT_AUTH_MODE=github-oauth",
-        ]
-        openai_api_url = COPILOT_API_URL
-    else:
-        env, env_vars_display = _build_copilot_launch_env(
-            port=port,
-            provider_type=effective_provider_type,
-            wire_api=wire_api,
-            environ=env,
-        )
-
-        if not env.get("COPILOT_PROVIDER_API_KEY"):
-            src = _copilot_provider_key_source(effective_provider_type)
-            click.echo(
-                f"\n  Error: Copilot BYOK mode requires a provider API key.\n"
-                f"  `headroom wrap copilot` uses Copilot's BYOK mode, which bypasses GitHub's\n"
-                f"  Copilot API and routes requests directly to the model provider through the\n"
-                f"  Headroom proxy. A GitHub Copilot subscription alone is not sufficient.\n\n"
-                f"  Set one of:\n"
-                f"    export {src}=sk-...          # recommended\n"
-                f"    export COPILOT_PROVIDER_API_KEY=sk-...  # also works\n"
-            )
-            raise SystemExit(1)
-
-    if not _copilot_model_configured(copilot_args, env):
-        click.echo(
-            "  Note: Copilot BYOK requires a model. Pass `--model <name>` "
-            "or set `COPILOT_MODEL` / `COPILOT_PROVIDER_MODEL_ID`."
-        )
-
-    _launch_tool(
-        binary=copilot_bin,
-        args=copilot_args,
-        env=env,
-        port=port,
-        no_proxy=no_proxy,
-        tool_label="COPILOT",
-        env_vars_display=env_vars_display,
-        learn=False,
-        memory=memory,
-        agent_type="copilot",
-        backend=backend,
-        anyllm_provider=anyllm_provider,
-        region=region,
-        openai_api_url=openai_api_url,
-    )
-
-
-# =============================================================================
-# OpenAI Codex CLI
-# =============================================================================
-
-
-@wrap.command(context_settings={"ignore_unknown_options": True})
-@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
-@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and AGENTS.md injection")
-@click.option(
-    "--code-graph",
-    is_flag=True,
-    help="Enable code graph indexing via codebase-memory-mcp (optional)",
-)
-@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
-@click.option(
-    "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to AGENTS.md)"
-)
-@click.option(
-    "--backend",
-    default=None,
-    help="API backend for the proxy: 'anthropic', 'anyllm', 'litellm-vertex', etc. (env: HEADROOM_BACKEND)",
-)
-@click.option(
-    "--anyllm-provider",
-    default=None,
-    help="Provider for any-llm backend: openai, mistral, groq, etc. (env: HEADROOM_ANYLLM_PROVIDER)",
-)
-@click.option(
-    "--region", default=None, help="Cloud region for Bedrock/Vertex (env: HEADROOM_REGION)"
-)
-@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
-@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
-@click.option("--prepare-only", is_flag=True, hidden=True)
-@click.argument("codex_args", nargs=-1, type=click.UNPROCESSED)
-def codex(
-    port: int,
-    no_rtk: bool,
-    code_graph: bool,
-    no_proxy: bool,
-    learn: bool,
-    memory: bool,
-    backend: str | None,
-    anyllm_provider: str | None,
-    region: str | None,
-    verbose: bool,
-    prepare_only: bool,
-    codex_args: tuple,
-) -> None:
-    """Launch OpenAI Codex CLI through Headroom proxy.
-
-    \b
-    Sets OPENAI_BASE_URL to route all OpenAI API calls through Headroom.
-    Installs rtk and injects instructions into AGENTS.md so Codex uses
-    token-optimized commands (60-90% savings on shell output).
-
-    \b
-    Examples:
-        headroom wrap codex                         # Start proxy + rtk + codex
-        headroom wrap codex -- "fix the bug"        # Pass prompt to codex
-        headroom wrap codex --no-rtk                # Skip rtk setup
-        headroom wrap codex --port 9999             # Custom proxy port
-        headroom wrap codex --backend anyllm --anyllm-provider groq
-    """
-    # Setup rtk for Codex (binary + AGENTS.md instructions, no hooks)
-    if not no_rtk:
-        click.echo("  Setting up rtk for Codex...")
-        rtk_path = _ensure_rtk_binary(verbose=verbose)
-        if rtk_path:
-            # Inject into project AGENTS.md (Codex reads this automatically)
-            agents_md = Path.cwd() / "AGENTS.md"
-            _inject_rtk_instructions(agents_md, verbose=verbose)
-
-            # Also inject into global ~/.codex/AGENTS.md
-            global_agents = Path.home() / ".codex" / "AGENTS.md"
-            _inject_rtk_instructions(global_agents, verbose=verbose)
-
-    # Setup memory MCP server for Codex (native tool integration)
-    if memory:
-        click.echo("  Setting up memory for Codex...")
-        mem_dir = Path.cwd() / ".headroom"
-        mem_dir.mkdir(parents=True, exist_ok=True)
-        db_path = str(mem_dir / "memory.db")
-        mem_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))
-
-        # Register MCP server in Codex config
-        _inject_memory_mcp_config(db_path, mem_user)
-
-        # Inject memory guidance into project AGENTS.md
-        agents_md = Path.cwd() / "AGENTS.md"
-        _inject_memory_agents_md(agents_md)
-
-        # Sync Claude's memories → DB so MCP search finds them
-        try:
-            import asyncio
-
-            from headroom.memory.backends.local import LocalBackend, LocalBackendConfig
-            from headroom.memory.sync import sync_import
-            from headroom.memory.sync_adapters.claude_code import (
-                ClaudeCodeAdapter,
-                get_claude_memory_dir,
-            )
-
-            claude_memory_dir = get_claude_memory_dir()
-
-            async def _import_claude_memories() -> int:
-                config = LocalBackendConfig(db_path=db_path)
-                backend = LocalBackend(config)
-                await backend._ensure_initialized()
-                adapter = ClaudeCodeAdapter(claude_memory_dir)
-                count = await sync_import(backend, adapter, mem_user)
-                await backend.close()
-                return count
-
-            imported = asyncio.run(_import_claude_memories())
-            if imported:
-                click.echo(f"  Memory: imported {imported} memories from Claude")
-        except Exception as e:
-            click.echo(f"  Warning: Claude memory import failed: {e}")
-
-    if prepare_only:
-        _inject_codex_provider_config(port)
-        return
-
-    codex_bin = shutil.which("codex")
-    if not codex_bin:
-        click.echo("Error: 'codex' not found in PATH.")
-        click.echo("Install Codex CLI: npm install -g @openai/codex")
-        raise SystemExit(1)
-
-    env, env_vars_display = _build_codex_launch_env(port, os.environ)
-
-    # Inject Headroom provider into Codex config so WebSocket traffic also
-    # routes through the proxy.  Codex ignores OPENAI_BASE_URL for its WS
-    # transport unless a custom provider declares supports_websockets = true.
-    # NOTE: this must run BEFORE _inject_memory_mcp_config because it rewrites
-    # the config file.  Re-inject MCP config after if memory is enabled.
-    _inject_codex_provider_config(port)
-    if memory:
-        mem_dir = Path.cwd() / ".headroom"
-        _inject_memory_mcp_config(
-            str(mem_dir / "memory.db"),
-            os.environ.get("USER", os.environ.get("USERNAME", "default")),
-        )
-
-    _launch_tool(
-        binary=codex_bin,
-        args=codex_args,
-        env=env,
-        port=port,
-        no_proxy=no_proxy,
-        tool_label="CODEX",
-        env_vars_display=env_vars_display,
-        learn=learn,
-        memory=memory,
-        agent_type="codex",
-        code_graph=code_graph,
-        backend=backend,
-        anyllm_provider=anyllm_provider,
-        region=region,
-    )
-
-
-# =============================================================================
-# Aider
-# =============================================================================
-
-
-@wrap.command(context_settings={"ignore_unknown_options": True})
-@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
-@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and conventions injection")
-@click.option(
-    "--code-graph",
-    is_flag=True,
-    help="Enable code graph indexing via codebase-memory-mcp (optional)",
-)
-@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
-@click.option("--learn", is_flag=True, help="Enable live traffic learning")
-@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
-@click.option(
-    "--backend", default=None, help="API backend: 'anthropic', 'anyllm', 'litellm-vertex', etc."
-)
-@click.option("--anyllm-provider", default=None, help="Provider for any-llm backend")
-@click.option("--region", default=None, help="Cloud region for Bedrock/Vertex")
-@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
-@click.option("--prepare-only", is_flag=True, hidden=True)
-@click.argument("aider_args", nargs=-1, type=click.UNPROCESSED)
-def aider(
-    port: int,
-    no_rtk: bool,
-    code_graph: bool,
-    no_proxy: bool,
-    learn: bool,
-    memory: bool,
-    backend: str | None,
-    anyllm_provider: str | None,
-    region: str | None,
-    verbose: bool,
-    prepare_only: bool,
-    aider_args: tuple,
-) -> None:
-    """Launch aider through Headroom proxy.
-
-    \b
-    Sets OPENAI_API_BASE to route all API calls through Headroom.
-    Installs rtk and injects instructions into .aider.conf.yml conventions
-    so aider uses token-optimized commands.
-
-    \b
-    Examples:
-        headroom wrap aider                              # Start proxy + rtk + aider
-        headroom wrap aider -- --model gpt-4o            # Use GPT-4o
-        headroom wrap aider -- --model claude-sonnet-4   # Use Claude
-        headroom wrap aider --no-rtk                     # Skip rtk setup
-        headroom wrap aider --backend litellm-vertex --region us-central1
-    """
-    # Setup rtk for aider (binary + CONVENTIONS.md instructions)
-    if not no_rtk:
-        click.echo("  Setting up rtk for aider...")
-        rtk_path = _ensure_rtk_binary(verbose=verbose)
-        if rtk_path:
-            # aider reads CONVENTIONS.md from project root
-            conventions = Path.cwd() / "CONVENTIONS.md"
-            _inject_rtk_instructions(conventions, verbose=verbose)
-
-    if prepare_only:
-        return
-
-    aider_bin = shutil.which("aider")
-    if not aider_bin:
-        click.echo("Error: 'aider' not found in PATH.")
-        click.echo("Install aider: pip install aider-chat")
-        raise SystemExit(1)
-
-    env, env_vars_display = _build_aider_launch_env(port, os.environ)
-
-    _launch_tool(
-        binary=aider_bin,
-        args=aider_args,
-        env=env,
-        port=port,
-        no_proxy=no_proxy,
-        tool_label="AIDER",
-        env_vars_display=env_vars_display,
-        learn=learn,
-        memory=memory,
-        agent_type="aider",
-        code_graph=code_graph,
-        backend=backend,
-        anyllm_provider=anyllm_provider,
-        region=region,
-    )
-
-
-# =============================================================================
-# Cursor
-# =============================================================================
-
-
-@wrap.command(context_settings={"ignore_unknown_options": True})
-@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
-@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and .cursorrules injection")
-@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
-@click.option(
-    "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to .cursor/rules/)"
-)
-@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
-@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
-@click.option("--prepare-only", is_flag=True, hidden=True)
-def cursor(
-    port: int,
-    no_rtk: bool,
-    no_proxy: bool,
-    learn: bool,
-    memory: bool,
-    verbose: bool,
-    prepare_only: bool,
-) -> None:
-    """Start Headroom proxy for use with Cursor.
-
-    \b
-    Cursor reads its API configuration from its settings UI, not from
-    environment variables. This command starts the proxy, installs rtk
-    with .cursorrules instructions, and prints the Cursor settings.
-
-    \b
-    After running this command, open Cursor and configure:
-        Settings > Models > OpenAI API Key > Advanced > Override Base URL
-
-    \b
-    Example:
-        headroom wrap cursor                # Start proxy + rtk + instructions
-        headroom wrap cursor --no-rtk       # Proxy only, no rtk
-        headroom wrap cursor --port 9999    # Custom proxy port
-    """
-    if not no_rtk:
-        click.echo("  Setting up rtk for Cursor...")
-        rtk_path = _ensure_rtk_binary(verbose=verbose)
-        if rtk_path:
-            cursorrules = Path.cwd() / ".cursorrules"
-            _inject_rtk_instructions(cursorrules, verbose=verbose)
-
-    if prepare_only:
-        return
-
-    proxy_holder: list[subprocess.Popen | None] = [None]
-    cleanup = _make_cleanup(proxy_holder, port)
-    signal.signal(signal.SIGINT, cleanup)
-    signal.signal(signal.SIGTERM, cleanup)
-
-    try:
-        click.echo()
-        click.echo("  ╔═══════════════════════════════════════════════╗")
-        click.echo("  ║            HEADROOM WRAP: CURSOR              ║")
-        click.echo("  ╚═══════════════════════════════════════════════╝")
-        click.echo()
-
-        proxy_holder[0] = _ensure_proxy(
-            port, no_proxy, learn=learn, memory=memory, agent_type="cursor"
-        )
-
-        click.echo()
-        for line in _render_cursor_setup_lines(port):
-            click.echo(line)
-        if not no_rtk:
-            click.echo()
-            click.echo("  rtk instructions injected into .cursorrules")
-            click.echo("  Cursor will use token-optimized commands automatically.")
-        click.echo()
-        click.echo("  Press Ctrl+C to stop the proxy.")
-        click.echo()
-
-        # Block until Ctrl+C
-        try:
-            while True:
-                time.sleep(1)
-                proc = proxy_holder[0]
-                if proc and proc.poll() is not None:
-                    click.echo("  Proxy process exited unexpectedly.")
-                    raise SystemExit(1)
-        except KeyboardInterrupt:
-            click.echo("\n  Shutting down...")
-
-    except SystemExit:
-        raise
-    except Exception as e:
-        click.echo(f"  Error: {e}")
-        raise SystemExit(1) from e
-    finally:
-        cleanup()
-
-
-# =============================================================================
-# OpenClaw
-# =============================================================================
-
-
-@wrap.command("openclaw")
-@click.option(
-    "--plugin-path",
-    type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
-    default=None,
-    help="Path to local OpenClaw plugin source directory (advanced/dev override)",
-)
-@click.option(
-    "--plugin-spec",
-    default="headroom-ai/openclaw",
-    show_default=True,
-    help="NPM plugin spec for OpenClaw install (used when --plugin-path is omitted)",
-)
-@click.option(
-    "--skip-build",
-    is_flag=True,
-    help="Skip npm install/build in local source mode (--plugin-path)",
-)
-@click.option(
-    "--copy",
-    is_flag=True,
-    help="Install by copying plugin path instead of using --link",
-)
-@click.option("--proxy-port", default=8787, type=int, help="Headroom proxy port")
-@click.option("--startup-timeout-ms", default=20000, type=int, help="Proxy startup timeout")
-@click.option(
-    "--gateway-provider-id",
-    "gateway_provider_ids",
-    multiple=True,
-    help="OpenClaw provider id to route through Headroom (repeatable; default: openai-codex)",
-)
-@click.option(
-    "--python-path",
-    default=None,
-    help="Optional Python executable for proxy launcher fallback",
-)
-@click.option(
-    "--no-auto-start",
-    is_flag=True,
-    help="Disable plugin auto-start of local headroom proxy",
-)
-@click.option(
-    "--no-restart",
-    is_flag=True,
-    help="Do not restart OpenClaw gateway at the end",
-)
-@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
-@click.option("--prepare-only", is_flag=True, hidden=True)
-@click.option("--existing-entry-json", default=None, hidden=True)
-def openclaw(
-    plugin_path: Path | None,
-    plugin_spec: str,
-    skip_build: bool,
-    copy: bool,
-    proxy_port: int,
-    startup_timeout_ms: int,
-    gateway_provider_ids: tuple[str, ...],
-    python_path: str | None,
-    no_auto_start: bool,
-    no_restart: bool,
-    verbose: bool,
-    prepare_only: bool,
-    existing_entry_json: str | None,
-) -> None:
-    """Install and configure Headroom OpenClaw plugin in one command.
-
-    \b
-    What this command does:
-      1. Installs OpenClaw plugin from npm (or local --plugin-path)
-      2. Builds plugin source if --plugin-path is used
-      3. Writes minimal plugin config and sets contextEngine slot
-      4. Validates config
-      5. Restarts OpenClaw gateway (unless --no-restart)
-
-    \b
-    Example:
-      headroom wrap openclaw
-      headroom wrap openclaw --plugin-path C:\\git\\headroom\\plugins\\openclaw
-    """
-    if prepare_only:
-        entry = _build_openclaw_plugin_entry(
-            existing_entry=_decode_openclaw_entry_json(existing_entry_json),
-            proxy_port=proxy_port,
-            startup_timeout_ms=startup_timeout_ms,
-            python_path=python_path,
-            no_auto_start=no_auto_start,
-            gateway_provider_ids=gateway_provider_ids,
-            enabled=True,
-        )
-        click.echo(json.dumps(entry, separators=(",", ":")))
-        return
-
-    openclaw_bin = shutil.which("openclaw")
-    if not openclaw_bin:
-        raise click.ClickException("'openclaw' not found in PATH. Install OpenClaw CLI first.")
-
-    plugin_dir = plugin_path.resolve() if plugin_path else None
-    local_source_mode = plugin_dir is not None
-    if plugin_dir:
-        if not plugin_dir.exists():
-            raise click.ClickException(f"Plugin path not found: {plugin_dir}.")
-        if not (plugin_dir / "package.json").exists():
-            raise click.ClickException(f"Invalid plugin path (missing package.json): {plugin_dir}")
-        if not (plugin_dir / "openclaw.plugin.json").exists():
-            raise click.ClickException(
-                f"Invalid plugin path (missing openclaw.plugin.json): {plugin_dir}"
-            )
-
-    npm_bin = shutil.which("npm")
-    if local_source_mode and not skip_build and not npm_bin:
-        raise click.ClickException(
-            "'npm' not found in PATH. Install Node/npm or rerun with --skip-build."
-        )
-
-    click.echo()
-    click.echo("  ╔═══════════════════════════════════════════════╗")
-    click.echo("  ║           HEADROOM WRAP: OPENCLAW             ║")
-    click.echo("  ╚═══════════════════════════════════════════════╝")
-    click.echo()
-    if local_source_mode:
-        click.echo(f"  Plugin source: local ({plugin_dir})")
-    else:
-        click.echo(f"  Plugin source: npm ({plugin_spec})")
-
-    if local_source_mode and not skip_build:
-        click.echo("  Building OpenClaw plugin (npm install + npm run build)...")
-        _run_checked([npm_bin or "npm", "install"], cwd=plugin_dir, action="npm install")
-        _run_checked([npm_bin or "npm", "run", "build"], cwd=plugin_dir, action="npm run build")
-    elif not local_source_mode and skip_build:
-        click.echo("  Skipping build: npm install mode does not build local source.")
-
-    effective_python_path = python_path
-    if effective_python_path is None and not no_auto_start and sys.executable:
-        effective_python_path = sys.executable
-
-    existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")
-    entry = _build_openclaw_plugin_entry(
-        existing_entry=existing_entry,
-        proxy_port=proxy_port,
-        startup_timeout_ms=startup_timeout_ms,
-        python_path=effective_python_path,
-        no_auto_start=no_auto_start,
-        gateway_provider_ids=gateway_provider_ids,
-        enabled=True,
-    )
-
-    click.echo("  Writing plugin configuration...")
-    _write_openclaw_plugin_entry(openclaw_bin, entry)
-
-    install_cmd = [
-        openclaw_bin,
-        "plugins",
-        "install",
-        "--dangerously-force-unsafe-install",
-    ]
-    if local_source_mode:
-        if copy:
-            install_cmd.append(str(plugin_dir))
-            install_cwd = None
-        else:
-            install_cmd.extend(["--link", "."])
-            install_cwd = plugin_dir
-    else:
-        install_cmd.append(plugin_spec)
-        install_cwd = None
-
-    click.echo("  Installing OpenClaw plugin with required unsafe-install flag...")
-    install_result = subprocess.run(
-        install_cmd,
-        cwd=str(install_cwd) if install_cwd else None,
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-    )
-    if install_result.returncode != 0:
-        combined_error = "\n".join(
-            x for x in [install_result.stderr.strip(), install_result.stdout.strip()] if x
-        )
-        plugin_already_exists = "plugin already exists" in combined_error.lower()
-        linked_install_bug = (
-            "also not a valid hook pack" in combined_error.lower()
-            and "--dangerously-force-unsafe-install" in " ".join(install_cmd)
-        )
-        if plugin_already_exists:
-            click.echo("  Plugin already installed; continuing with configuration/update steps.")
-        elif linked_install_bug and local_source_mode and plugin_dir is not None:
-            click.echo(
-                "  OpenClaw linked-path install bug detected; applying extension-path fallback..."
-            )
-            target_dir = _copy_openclaw_plugin_into_extensions(
-                plugin_dir=plugin_dir,
-                openclaw_bin=openclaw_bin,
-            )
-            click.echo(f"  Fallback plugin copy completed: {target_dir}")
-        else:
-            details = combined_error or f"exit code {install_result.returncode}"
-            raise click.ClickException(f"openclaw plugins install failed: {details}")
-    elif verbose and install_result.stdout.strip():
-        click.echo(install_result.stdout.strip())
-
-    _set_openclaw_context_engine_slot(openclaw_bin, "headroom")
-    _run_checked(
-        [openclaw_bin, "config", "validate"],
-        action="openclaw config validate",
-    )
-
-    if no_restart:
-        click.echo("  Skipping gateway restart (--no-restart).")
-        click.echo(
-            "  Run `openclaw gateway restart` (or `openclaw gateway start`) to apply plugin changes."
-        )
-    else:
-        click.echo("  Applying plugin changes to OpenClaw gateway...")
-        gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)
-        click.echo(f"  Gateway {gateway_action}.")
-        if verbose and gateway_output:
-            click.echo(gateway_output)
-
-    inspect_result = _run_checked(
-        [openclaw_bin, "plugins", "inspect", "headroom"],
-        action="openclaw plugins inspect headroom",
-    )
-    if verbose and inspect_result.stdout.strip():
-        click.echo(inspect_result.stdout.strip())
-
-    click.echo()
-    click.echo("✓ OpenClaw is configured to use Headroom context compression.")
-    click.echo("  Plugin: headroom")
-    click.echo("  Slot:   plugins.slots.contextEngine = headroom")
-    click.echo()
-
-
-@unwrap.command("openclaw")
-@click.option("--no-restart", is_flag=True, help="Do not restart OpenClaw gateway at the end")
-@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
-@click.option("--prepare-only", is_flag=True, hidden=True)
-@click.option("--existing-entry-json", default=None, hidden=True)
-def unwrap_openclaw(
-    no_restart: bool,
-    verbose: bool,
-    prepare_only: bool,
-    existing_entry_json: str | None,
-) -> None:
-    """Disable the Headroom OpenClaw plugin and restore the legacy engine slot."""
-    if prepare_only:
-        click.echo(
-            json.dumps(
-                _build_openclaw_unwrap_entry(_decode_openclaw_entry_json(existing_entry_json)),
-                separators=(",", ":"),
-            )
-        )
-        return
-
-    openclaw_bin = shutil.which("openclaw")
-    if not openclaw_bin:
-        raise click.ClickException("'openclaw' not found in PATH. Install OpenClaw CLI first.")
-
-    click.echo()
-    click.echo("  ╔═══════════════════════════════════════════════╗")
-    click.echo("  ║          HEADROOM UNWRAP: OPENCLAW            ║")
-    click.echo("  ╚═══════════════════════════════════════════════╝")
-    click.echo()
-    click.echo("  Disabling Headroom plugin and removing engine mapping...")
-
-    existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")
-    entry = _build_openclaw_unwrap_entry(existing_entry)
-    _write_openclaw_plugin_entry(openclaw_bin, entry)
-    _set_openclaw_context_engine_slot(openclaw_bin, "legacy")
-    _run_checked(
-        [openclaw_bin, "config", "validate"],
-        action="openclaw config validate",
-    )
-
-    if no_restart:
-        click.echo("  Skipping gateway restart (--no-restart).")
-        click.echo(
-            "  Run `openclaw gateway restart` (or `openclaw gateway start`) to apply unwrap changes."
-        )
-    else:
-        click.echo("  Applying unwrap changes to OpenClaw gateway...")
-        gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)
-        click.echo(f"  Gateway {gateway_action}.")
-        if verbose and gateway_output:
-            click.echo(gateway_output)
-
-    if verbose:
-        inspect_result = _run_checked(
-            [openclaw_bin, "plugins", "inspect", "headroom"],
-            action="openclaw plugins inspect headroom",
-        )
-        if inspect_result.stdout.strip():
-            click.echo(inspect_result.stdout.strip())
-
-    click.echo()
-    click.echo("✓ OpenClaw Headroom wrap removed.")
-    click.echo("  Plugin: headroom (installed, disabled)")
-    click.echo("  Slot:   plugins.slots.contextEngine = legacy")
-    click.echo()
-
-
-# =============================================================================
-# OpenAI Codex CLI (unwrap)
-# =============================================================================
-
-
-@unwrap.command("codex")
-def unwrap_codex() -> None:
-    """Undo ``headroom wrap codex`` edits to ``~/.codex/config.toml``.
-
-    Behaviour:
-
-    * If a pre-wrap backup (``config.toml.headroom-backup``) exists, the
-      original file is restored byte-for-byte and the backup is removed.
-    * Otherwise, if the config file still contains the Headroom-managed
-      block, that block is stripped out and the rest of the file is
-      preserved.
-    * If the config only ever contained Headroom-written content, the file
-      is removed entirely so Codex falls back to its defaults.
-    * If neither a backup nor a Headroom block is present, this is a safe
-      no-op (the user either never wrapped, or already unwrapped).
-    """
-    click.echo()
-    click.echo("  ╔═══════════════════════════════════════════════╗")
-    click.echo("  ║           HEADROOM UNWRAP: CODEX              ║")
-    click.echo("  ╚═══════════════════════════════════════════════╝")
-    click.echo()
-
-    try:
-        status, config_file = _restore_codex_provider_config()
-    except Exception as e:  # pragma: no cover - filesystem-level errors
-        raise click.ClickException(f"could not unwrap Codex config: {e}") from e
-
-    if status == "restored":
-        click.echo(f"  Restored prior {config_file} from pre-wrap backup.")
-    elif status == "cleaned":
-        click.echo(f"  Removed Headroom block from {config_file}; other content preserved.")
-    elif status == "removed":
-        click.echo(f"  Removed {config_file} (contained only Headroom-written config).")
-    else:
-        click.echo(f"  Nothing to undo: {config_file} has no Headroom wrap markers.")
-
-    click.echo()
-    click.echo("✓ Codex is no longer routed through the Headroom proxy.")
-    click.echo()
+"""Wrap CLI commands to run through Headroom proxy.
+
+Usage:
+    headroom wrap claude                    # Start proxy + rtk + claude
+    headroom wrap copilot -- --model ...    # Start proxy + launch GitHub Copilot CLI
+    headroom wrap codex                     # Start proxy + OpenAI Codex CLI
+    headroom wrap aider                     # Start proxy + aider
+    headroom wrap cursor                    # Start proxy + print Cursor config instructions
+    headroom wrap openclaw                  # Install + configure OpenClaw plugin
+    headroom wrap claude --no-rtk           # Without rtk hooks
+    headroom wrap claude --port 9999        # Custom proxy port
+    headroom wrap claude -- --model opus    # Pass args to claude
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, cast
+
+# Fix Windows cp1252 encoding — box-drawing characters require UTF-8
+if sys.platform == "win32" and hasattr(sys.stdout, "buffer"):
+    if sys.stdout.encoding and sys.stdout.encoding.lower().replace("-", "") != "utf8":
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+
+import click
+
+from headroom.copilot_auth import DEFAULT_API_URL as COPILOT_API_URL
+from headroom.copilot_auth import has_oauth_auth, resolve_client_bearer_token
+from headroom.providers.aider import build_launch_env as _build_aider_launch_env
+from headroom.providers.claude import proxy_base_url as _claude_proxy_base_url
+from headroom.providers.codex import build_launch_env as _build_codex_launch_env
+from headroom.providers.copilot import (
+    build_launch_env as _build_copilot_launch_env,
+)
+from headroom.providers.copilot import (
+    detect_running_proxy_backend as _copilot_detect_running_proxy_backend,
+)
+from headroom.providers.copilot import (
+    model_configured as _copilot_model_configured_impl,
+)
+from headroom.providers.copilot import (
+    provider_key_source as _copilot_provider_key_source,
+)
+from headroom.providers.copilot import (
+    query_proxy_config as _copilot_query_proxy_config,
+)
+from headroom.providers.copilot import (
+    resolve_provider_type as _copilot_resolve_provider_type,
+)
+from headroom.providers.copilot import (
+    validate_configuration as _validate_copilot_configuration,
+)
+from headroom.providers.cursor import render_setup_lines as _render_cursor_setup_lines
+from headroom.providers.openclaw import (
+    build_plugin_entry as _build_openclaw_plugin_entry_impl,
+)
+from headroom.providers.openclaw import (
+    build_unwrap_entry as _build_openclaw_unwrap_entry_impl,
+)
+from headroom.providers.openclaw import (
+    decode_entry_json as _decode_openclaw_entry_json_impl,
+)
+from headroom.providers.openclaw import (
+    normalize_gateway_provider_ids as _normalize_openclaw_gateway_provider_ids_impl,
+)
+
+from .main import main
+
+
+def _live_wrap_module() -> Any:
+    """Return the current live wrap module instance."""
+    return cast(Any, sys.modules[__name__])
+
+
+def _print_telemetry_notice() -> None:
+    """Print a telemetry notice when anonymous telemetry is enabled.
+
+    Respects the HEADROOM_TELEMETRY and HEADROOM_TELEMETRY_WARN feature flags.
+    Does nothing when telemetry or warnings are disabled.
+    """
+    from headroom.telemetry.beacon import format_telemetry_notice
+
+    notice = format_telemetry_notice(prefix="  ")
+    if notice:
+        click.echo(notice)
+
+
+# Proxy health check (reused from evals/suite_runner.py pattern)
+
+
+def _check_proxy(port: int) -> bool:
+    """Check if Headroom proxy is running on given port."""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.settimeout(1)
+            s.connect(("127.0.0.1", port))
+            return True
+    except (TimeoutError, ConnectionRefusedError, OSError):
+        return False
+
+
+def _get_log_path() -> Path:
+    """Get path for proxy log file."""
+    from headroom import paths as _paths
+
+    log_dir = _paths.log_dir()
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir / "proxy.log"
+
+
+def _start_proxy(
+    port: int,
+    *,
+    learn: bool = False,
+    memory: bool = False,
+    agent_type: str = "unknown",
+    code_graph: bool = False,
+    backend: str | None = None,
+    anyllm_provider: str | None = None,
+    region: str | None = None,
+    openai_api_url: str | None = None,
+) -> subprocess.Popen:
+    """Start Headroom proxy as a background subprocess.
+
+    Logs are written to ~/.headroom/logs/proxy.log to avoid pipe buffer
+    deadlocks (macOS pipe buffer is ~64KB — a busy proxy fills it quickly,
+    blocking the process).
+    """
+    cmd = [sys.executable, "-m", "headroom.cli", "proxy", "--port", str(port)]
+
+    # Forward HEADROOM_MODE env var so the proxy respects the user's mode choice
+    headroom_mode = os.environ.get("HEADROOM_MODE")
+    if headroom_mode:
+        cmd.extend(["--mode", headroom_mode])
+
+    # Forward --learn flag to proxy subprocess
+    if learn:
+        cmd.append("--learn")
+
+    # Forward --memory flag to proxy subprocess
+    if memory:
+        cmd.append("--memory")
+
+    # Forward --code-graph flag to proxy subprocess (live file watcher)
+    if code_graph:
+        cmd.append("--code-graph")
+
+    # Forward backend configuration to proxy subprocess
+    _backend = backend or os.environ.get("HEADROOM_BACKEND")
+    if _backend:
+        cmd.extend(["--backend", _backend])
+
+    _anyllm = anyllm_provider or os.environ.get("HEADROOM_ANYLLM_PROVIDER")
+    if _anyllm:
+        cmd.extend(["--anyllm-provider", _anyllm])
+
+    _region = region or os.environ.get("HEADROOM_REGION")
+    if _region:
+        cmd.extend(["--region", _region])
+
+    if openai_api_url:
+        cmd.extend(["--openai-api-url", openai_api_url])
+
+    log_path = _get_log_path()
+    log_file = open(log_path, "a")  # noqa: SIM115
+
+    # Ensure proxy subprocess uses UTF-8 (Windows defaults to cp1252)
+    proxy_env = os.environ.copy()
+    proxy_env["PYTHONIOENCODING"] = "utf-8"
+
+    # Tell the proxy which agent is being wrapped (for traffic learning output)
+    if agent_type != "unknown":
+        proxy_env["HEADROOM_AGENT_TYPE"] = agent_type
+        proxy_env.setdefault("HEADROOM_STACK", f"wrap_{agent_type}")
+
+    proc = subprocess.Popen(
+        cmd,
+        stdout=log_file,
+        stderr=log_file,
+        env=proxy_env,
+    )
+
+    # Wait for proxy to be ready (up to 45 seconds).
+    # ML components (Kompress, Magika, Tree-sitter) load synchronously before
+    # uvicorn binds the port. On slower machines this can take 20-30 seconds.
+    for _i in range(45):
+        time.sleep(1)
+        if _check_proxy(port):
+            click.echo(f"  Logs: {log_path}")
+            return proc
+        # Check if process died
+        if proc.poll() is not None:
+            log_file.close()
+            # Read last few lines of log for error context
+            try:
+                tail = log_path.read_text()[-500:]
+            except Exception:
+                tail = "(no log output)"
+            raise RuntimeError(f"Proxy exited with code {proc.returncode}: {tail}")
+
+    proc.kill()
+    log_file.close()
+    raise RuntimeError(f"Proxy failed to start on port {port} within 45 seconds")
+
+
+def _setup_rtk(verbose: bool = False) -> Path | None:
+    """Ensure rtk is installed and hooks are registered."""
+    from headroom.rtk import get_rtk_path
+    from headroom.rtk.installer import ensure_rtk, register_claude_hooks
+
+    rtk_path = get_rtk_path()
+
+    if rtk_path:
+        if verbose:
+            click.echo(f"  rtk found at {rtk_path}")
+    else:
+        click.echo("  Downloading rtk (Rust Token Killer)...")
+        rtk_path = ensure_rtk()
+        if rtk_path:
+            click.echo(f"  rtk installed at {rtk_path}")
+        else:
+            click.echo("  rtk download failed — continuing without it")
+            return None
+
+    # Register hooks (idempotent)
+    if register_claude_hooks(rtk_path):
+        if verbose:
+            click.echo("  rtk hooks registered in Claude Code")
+    else:
+        click.echo("  rtk hook registration failed — continuing without it")
+
+    return rtk_path
+
+
+_CBM_MCP_SERVER_NAME = "codebase-memory-mcp"
+
+
+def _register_cbm_mcp_server(cbm_bin: str) -> None:
+    """Register codebase-memory-mcp as an MCP server in Claude Code.
+
+    Uses ``claude mcp add`` so the tools appear in ``/mcp`` automatically.
+    Idempotent — skips if already registered.
+    """
+    claude_cli = shutil.which("claude")
+    if not claude_cli:
+        return
+
+    # Check if already registered
+    check = subprocess.run(
+        [claude_cli, "mcp", "get", _CBM_MCP_SERVER_NAME],
+        capture_output=True,
+        text=True,
+    )
+    if check.returncode == 0:
+        return  # Already registered
+
+    result = subprocess.run(
+        [claude_cli, "mcp", "add", _CBM_MCP_SERVER_NAME, "-s", "user", "--", cbm_bin],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        click.echo(f"  Code graph: registered {_CBM_MCP_SERVER_NAME} MCP server")
+    else:
+        pass  # Non-critical — tools won't appear in /mcp but graph still works
+
+
+def _setup_code_graph(verbose: bool = False) -> bool:
+    """Ensure codebase-memory-mcp is installed, registered as MCP server, and project is indexed.
+
+    codebase-memory-mcp builds a knowledge graph of the codebase using
+    tree-sitter, enabling the LLM to query code structure (call chains,
+    function definitions, impact analysis) instead of reading entire files.
+
+    Steps:
+    1. Download the binary if not already present.
+    2. Register as an MCP server in Claude Code (``claude mcp add``).
+    3. Index the current project (fast, idempotent).
+
+    With Claude Code's MCP Tool Search, the 14 graph tools add ~200 tokens
+    overhead per request (not the full ~1,915) — they're lazy-loaded.
+
+    Returns True if graph is ready, False if setup failed.
+    """
+    from headroom.graph.installer import ensure_cbm, get_cbm_path
+
+    cbm_path = get_cbm_path()
+    if not cbm_path:
+        click.echo("  Code graph: downloading codebase-memory-mcp...")
+        cbm_path = ensure_cbm()
+        if cbm_path:
+            click.echo(f"  Code graph: installed at {cbm_path}")
+        else:
+            click.echo("  Code graph: download failed — skipping")
+            return False
+
+    cbm_bin = str(cbm_path)
+
+    # Register as MCP server so tools appear in /mcp
+    _register_cbm_mcp_server(cbm_bin)
+
+    # Index current project (fast — ~1s for most repos, idempotent)
+    project_dir = str(Path.cwd())
+    try:
+        result = subprocess.run(
+            [
+                cbm_bin,
+                "cli",
+                "index_repository",
+                json.dumps({"repo_path": project_dir, "mode": "fast"}),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode == 0:
+            # Parse node/edge counts from output
+            for line in result.stdout.splitlines():
+                if '"nodes"' in line:
+                    try:
+                        # Parse the JSON response to extract node/edge counts
+                        import re
+
+                        m_nodes = re.search(r'"nodes":(\d+)', line)
+                        m_edges = re.search(r'"edges":(\d+)', line)
+                        if m_nodes and m_edges:
+                            nodes = int(m_nodes.group(1))
+                            edges = int(m_edges.group(1))
+                            click.echo(
+                                f"  Code graph: indexed ({nodes:,} symbols, "
+                                f"{edges:,} relationships)"
+                            )
+                        else:
+                            click.echo("  Code graph: indexed")
+                    except (ValueError, AttributeError):
+                        click.echo("  Code graph: indexed")
+                    return True
+            click.echo("  Code graph: indexed")
+            return True
+        else:
+            if verbose:
+                click.echo(f"  Code graph: indexing failed ({result.stderr[:100]})")
+            return False
+    except subprocess.TimeoutExpired:
+        click.echo("  Code graph: indexing timed out (will complete in background)")
+        return False
+    except Exception as e:
+        if verbose:
+            click.echo(f"  Code graph: setup failed ({e})")
+        return False
+
+
+# rtk instructions for tools without hook support (Codex, Cursor, Aider).
+# These get injected into AGENTS.md / .cursorrules so the LLM voluntarily
+# uses rtk-prefixed commands. Kept concise to minimize instruction overhead.
+RTK_INSTRUCTIONS_BLOCK = """\
+<!-- headroom:rtk-instructions -->
+# RTK (Rust Token Killer) - Token-Optimized Commands
+
+When running shell commands, **always prefix with `rtk`**. This reduces context
+usage by 60-90% with zero behavior change. If rtk has no filter for a command,
+it passes through unchanged — so it is always safe to use.
+
+## Key Commands
+```bash
+# Git (59-80% savings)
+rtk git status          rtk git diff            rtk git log
+
+# Files & Search (60-75% savings)
+rtk ls <path>           rtk read <file>         rtk grep <pattern>
+rtk find <pattern>      rtk diff <file>
+
+# Test (90-99% savings) — shows failures only
+rtk pytest tests/       rtk cargo test          rtk test <cmd>
+
+# Build & Lint (80-90% savings) — shows errors only
+rtk tsc                 rtk lint                rtk cargo build
+rtk prettier --check    rtk mypy                rtk ruff check
+
+# Analysis (70-90% savings)
+rtk err <cmd>           rtk log <file>          rtk json <file>
+rtk summary <cmd>       rtk deps                rtk env
+
+# GitHub (26-87% savings)
+rtk gh pr view <n>      rtk gh run list         rtk gh issue list
+
+# Infrastructure (85% savings)
+rtk docker ps           rtk kubectl get         rtk docker logs <c>
+
+# Package managers (70-90% savings)
+rtk pip list            rtk pnpm install        rtk npm run <script>
+```
+
+## Rules
+- In command chains, prefix each segment: `rtk git add . && rtk git commit -m "msg"`
+- For debugging, use raw command without rtk prefix
+- `rtk proxy <cmd>` runs command without filtering but tracks usage
+<!-- /headroom:rtk-instructions -->
+"""
+
+# Marker used to detect if instructions are already injected
+_RTK_MARKER = "<!-- headroom:rtk-instructions -->"
+
+# Memory MCP markers
+_MEMORY_MCP_MARKER = "# --- Headroom memory MCP (auto-injected) ---"
+_MEMORY_MCP_END = "# --- end Headroom memory ---"
+_MEMORY_AGENTS_MARKER = "<!-- headroom:memory-instructions -->"
+
+# Codex config injection markers
+_CODEX_TOP_LEVEL_MARKER = "# --- Headroom proxy (auto-injected by headroom wrap codex) ---"
+_CODEX_END_MARKER = "# --- end Headroom ---"
+# File name used for the pre-wrap snapshot of ~/.codex/config.toml.  The
+# snapshot lets `headroom unwrap codex` restore the exact prior state, even
+# if the user had their own `model_provider` / `[model_providers.*]` config
+# before running wrap.
+_CODEX_CONFIG_BACKUP_SUFFIX = ".headroom-backup"
+
+
+def _codex_config_paths() -> tuple[Path, Path]:
+    """Return ``(config_file, backup_file)`` paths for the Codex TOML config."""
+    config_dir = Path.home() / ".codex"
+    config_file = config_dir / "config.toml"
+    backup_file = config_dir / f"config.toml{_CODEX_CONFIG_BACKUP_SUFFIX}"
+    return config_file, backup_file
+
+
+def _strip_codex_headroom_blocks(content: str) -> str:
+    """Remove all Headroom-managed blocks from a Codex ``config.toml`` string.
+
+    Returns the cleaned content.  Safe to call on content that never contained
+    any markers — it will be returned effectively unchanged (only trailing
+    whitespace is normalized).
+    """
+    import re
+
+    # Remove any top-level-marker → end-marker span, possibly repeated.
+    while _CODEX_TOP_LEVEL_MARKER in content and _CODEX_END_MARKER in content:
+        start = content.index(_CODEX_TOP_LEVEL_MARKER)
+        end_idx = content.index(_CODEX_END_MARKER, start)
+        if end_idx < start:
+            break
+        end = end_idx + len(_CODEX_END_MARKER)
+        content = content[:start].rstrip("\n") + "\n" + content[end:].lstrip("\n")
+
+    # Remove any stale top-level marker or end marker that lost its partner
+    # (e.g. a crashed prior wrap).
+    content = content.replace(_CODEX_TOP_LEVEL_MARKER + "\n", "")
+    content = content.replace(_CODEX_END_MARKER + "\n", "")
+
+    # Strip any leftover top-level `model_provider = "headroom"` line, which
+    # older versions of `wrap codex` wrote outside the marker block.
+    content = re.sub(r'(?m)^[ \t]*model_provider[ \t]*=[ \t]*"headroom"[ \t]*\r?\n', "", content)
+
+    # Strip any orphaned `[model_providers.headroom]` table with the fields we
+    # write.  We only remove it if the table is recognisably ours (base_url
+    # mentions localhost and a Headroom proxy port).  This protects users who
+    # happen to have a differently configured `headroom` provider.
+    orphan_headroom_table = re.compile(
+        r"(?ms)^\[model_providers\.headroom\][^\[]*?"
+        r'base_url[ \t]*=[ \t]*"http://127\.0\.0\.1:\d+/v1"[^\[]*?'
+        r"(?=^\[|\Z)"
+    )
+    content = orphan_headroom_table.sub("", content)
+
+    return content.lstrip("\n").rstrip() + "\n" if content.strip() else ""
+
+
+def _snapshot_codex_config_if_unwrapped(config_file: Path, backup_file: Path) -> None:
+    """Snapshot ``config.toml`` to ``backup_file`` before the first injection.
+
+    Called as the first step of every Headroom injection into Codex's
+    ``config.toml``.  Guarantees that ``headroom unwrap codex`` can restore the
+    user's original file byte-for-byte.
+
+    Rules:
+
+    * If the backup already exists, leave it alone — we only snapshot the
+      *pre-wrap* state, so running wrap repeatedly must not clobber it.
+    * If the config file doesn't exist yet, there's nothing to back up; unwrap
+      will remove the file entirely instead of restoring a snapshot.
+    * If the config already contains a Headroom marker, a wrap run is already
+      active: do not snapshot the injected state.
+    """
+    if backup_file.exists():
+        return
+    if not config_file.exists():
+        return
+    try:
+        content = config_file.read_text()
+    except OSError:
+        return
+    if _CODEX_TOP_LEVEL_MARKER in content or _CODEX_END_MARKER in content:
+        return
+    backup_file.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(config_file, backup_file)
+
+
+def _ensure_rtk_binary(verbose: bool = False) -> Path | None:
+    """Ensure rtk binary is installed (download if needed). No hook registration."""
+    from headroom.rtk import get_rtk_path
+    from headroom.rtk.installer import ensure_rtk
+
+    rtk_path = get_rtk_path()
+
+    if rtk_path:
+        if verbose:
+            click.echo(f"  rtk found at {rtk_path}")
+        return rtk_path
+
+    click.echo("  Downloading rtk (Rust Token Killer)...")
+    rtk_path = ensure_rtk()
+    if rtk_path:
+        click.echo(f"  rtk installed at {rtk_path}")
+        return rtk_path
+
+    click.echo("  rtk download failed — continuing without it")
+    return None
+
+
+def _prepare_wrap_rtk(verbose: bool = False, *, label: str | None = None) -> Path | None:
+    """Ensure rtk is present for host-bridged wrap flows without host-specific setup."""
+    if label:
+        click.echo(f"  Preparing rtk for {label}...")
+    return _ensure_rtk_binary(verbose=verbose)
+
+
+def _inject_codex_provider_config(port: int) -> None:
+    """Inject a Headroom model provider into Codex's config.toml.
+
+    Codex ignores OPENAI_BASE_URL for WebSocket transport unless a custom
+    provider declares ``supports_websockets = true``.  This writes a
+    ``[model_providers.headroom]`` section that routes both HTTP and WS
+    through the proxy, and sets ``model_provider = "headroom"``.
+
+    Safe to call multiple times — the injected block is fully replaced on
+    each call, so re-running with a different ``port`` updates the config.
+    Before the first injection, the pre-wrap file is snapshotted to
+    ``~/.codex/config.toml.headroom-backup`` so ``headroom unwrap codex``
+    can restore it byte-for-byte.
+    """
+    config_file, backup_file = _codex_config_paths()
+    config_dir = config_file.parent
+
+    # The injected content is split into two self-contained, marker-delimited
+    # blocks: a top-level key block (at the start of the file, because bare
+    # TOML keys must precede any [section]) and a provider-table block (at
+    # the end).  Each block has its own matching begin/end marker pair so
+    # stripping them is unambiguous and never consumes user content that
+    # happens to sit between the two.
+    top_level_block = (
+        f'{_CODEX_TOP_LEVEL_MARKER}\nmodel_provider = "headroom"\n{_CODEX_END_MARKER}\n'
+    )
+    provider_section = (
+        f"{_CODEX_TOP_LEVEL_MARKER}\n"
+        "[model_providers.headroom]\n"
+        'name = "OpenAI via Headroom proxy"\n'
+        f'base_url = "http://127.0.0.1:{port}/v1"\n'
+        f'env_key = "OPENAI_API_KEY"\n'
+        f"requires_openai_auth = true\n"
+        f"supports_websockets = true\n"
+        f"{_CODEX_END_MARKER}\n"
+    )
+
+    try:
+        config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Snapshot the pre-wrap state before touching anything.  No-op if the
+        # config is already wrapped, is missing, or we've already snapshotted.
+        _snapshot_codex_config_if_unwrapped(config_file, backup_file)
+
+        if config_file.exists():
+            content = config_file.read_text()
+            # Remove any prior Headroom-managed blocks before re-injecting so
+            # the operation is idempotent and supports port changes.
+            content = _strip_codex_headroom_blocks(content)
+
+            # Place the top-level key block at the very beginning of the file
+            # (bare TOML keys must precede any [section]) and the provider
+            # table at the end.  User content, if any, sits between them.
+            user_content = content.strip()
+            if user_content:
+                content = top_level_block + "\n" + user_content + "\n\n" + provider_section
+            else:
+                content = top_level_block + "\n" + provider_section
+        else:
+            content = top_level_block + "\n" + provider_section
+
+        config_file.write_text(content)
+        click.echo(f"  Codex config: injected Headroom provider (WS + HTTP) into {config_file}")
+    except Exception as e:
+        click.echo(f"  Warning: could not update Codex config: {e}")
+
+
+def _restore_codex_provider_config() -> tuple[str, Path]:
+    """Undo ``_inject_codex_provider_config`` for ``~/.codex/config.toml``.
+
+    Returns a tuple of ``(status, config_file)`` where status is one of:
+
+    * ``"restored"`` — a pre-wrap backup existed and was restored; backup
+      file has been removed.
+    * ``"cleaned"``  — no backup existed, but the Headroom-managed block was
+      found and stripped out (preserving surrounding user content).
+    * ``"removed"``  — the config file only contained Headroom-managed
+      content (created by wrap) and has been deleted.
+    * ``"noop"``     — nothing to undo; no Headroom marker and no backup.
+    """
+    config_file, backup_file = _codex_config_paths()
+
+    # Case 1: pre-wrap snapshot exists — restore it exactly.
+    if backup_file.exists():
+        shutil.copy2(backup_file, config_file)
+        backup_file.unlink()
+        return "restored", config_file
+
+    # Case 2: no backup, but config file exists and has markers — strip them.
+    if config_file.exists():
+        original = config_file.read_text()
+        if _CODEX_TOP_LEVEL_MARKER in original or _CODEX_END_MARKER in original:
+            cleaned = _strip_codex_headroom_blocks(original)
+            if not cleaned.strip():
+                # Nothing left but Headroom content — remove the file entirely
+                # so Codex falls back to its default config.
+                config_file.unlink()
+                return "removed", config_file
+            config_file.write_text(cleaned)
+            return "cleaned", config_file
+
+    # Nothing to undo.
+    return "noop", config_file
+
+
+def _inject_rtk_instructions(file_path: Path, verbose: bool = False) -> bool:
+    """Inject rtk instructions into a file (AGENTS.md, .cursorrules, etc.).
+
+    Idempotent — skips if marker already present. Appends to existing content.
+    Returns True if instructions were written.
+    """
+    if file_path.exists():
+        existing = file_path.read_text()
+        if _RTK_MARKER in existing:
+            if verbose:
+                click.echo(f"  rtk instructions already in {file_path.name}")
+            return True
+        # Append to existing file
+        with open(file_path, "a") as f:
+            f.write("\n\n" + RTK_INSTRUCTIONS_BLOCK)
+    else:
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(RTK_INSTRUCTIONS_BLOCK)
+
+    click.echo(f"  rtk instructions injected into {file_path}")
+    return True
+
+
+def _inject_memory_mcp_config(db_path: str, user_id: str) -> None:
+    """Register headroom memory as an MCP server in Codex's config.toml.
+
+    Idempotent — replaces existing section if present.
+    """
+    import sys
+
+    config_dir = Path.home() / ".codex"
+    config_file = config_dir / "config.toml"
+
+    # Use forward slashes in TOML paths (works on all platforms, avoids
+    # backslash escaping issues on Windows)
+    python_bin = sys.executable.replace("\\", "/")
+    db_path_toml = db_path.replace("\\", "/")
+    mcp_section = (
+        f"\n{_MEMORY_MCP_MARKER}\n"
+        f"[mcp_servers.headroom_memory]\n"
+        f'command = "{python_bin}"\n'
+        f'args = ["-m", "headroom.memory.mcp_server", "--db", "{db_path_toml}", "--user", "{user_id}"]\n'
+        f"startup_timeout_sec = 30\n"
+        f"tool_timeout_sec = 30\n"
+        f"{_MEMORY_MCP_END}\n"
+    )
+
+    try:
+        config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Snapshot pre-wrap state before touching config.toml so `unwrap codex`
+        # can fully restore it even when only `--memory` (not a full provider
+        # injection) was used.
+        _, backup_file = _codex_config_paths()
+        _snapshot_codex_config_if_unwrapped(config_file, backup_file)
+
+        if config_file.exists():
+            content = config_file.read_text()
+            if _MEMORY_MCP_MARKER in content:
+                start = content.index(_MEMORY_MCP_MARKER)
+                end = content.index(_MEMORY_MCP_END) + len(_MEMORY_MCP_END)
+                content = content[:start].rstrip("\n") + mcp_section + content[end:].lstrip("\n")
+            else:
+                content = content.rstrip() + "\n" + mcp_section
+        else:
+            content = mcp_section
+
+        config_file.write_text(content)
+        click.echo(f"  Memory MCP: registered in {config_file}")
+    except Exception as e:
+        click.echo(f"  Warning: could not register memory MCP: {e}")
+
+
+def _inject_memory_agents_md(file_path: Path) -> bool:
+    """Inject memory usage guidance into AGENTS.md.
+
+    Idempotent — skips if marker already present.
+    """
+    memory_block = (
+        f"{_MEMORY_AGENTS_MARKER}\n"
+        "## Memory\n\n"
+        "Use the `headroom_memory` MCP server for persistent cross-session knowledge.\n\n"
+        "**Before** answering questions about prior decisions, conventions, project context,\n"
+        "architecture, user preferences, org info, codenames, debugging history, or anything\n"
+        "from past sessions — call `memory_search` first.\n\n"
+        "**After** making durable decisions, discovering conventions, or learning important\n"
+        "facts — call `memory_save` to persist them for future sessions.\n\n"
+        "Memory is your first source of truth for anything not visible in the current conversation.\n"
+    )
+
+    if file_path.exists():
+        existing = file_path.read_text()
+        if _MEMORY_AGENTS_MARKER in existing:
+            return True  # Already injected
+        with open(file_path, "a") as f:
+            f.write("\n\n" + memory_block)
+    else:
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(memory_block)
+
+    click.echo(f"  Memory guidance injected into {file_path.name}")
+    return True
+
+
+def _resolve_copilot_provider_type(backend: str | None, provider_type: str) -> str:
+    """Resolve Copilot BYOK provider type for the current proxy backend."""
+    return _copilot_resolve_provider_type(backend, provider_type)
+
+
+def _query_proxy_config(port: int) -> dict[str, Any] | None:
+    """Query the running proxy's feature configuration via /health.
+
+    Returns a dict with keys like backend, optimize, cache, rate_limit,
+    memory, learn, code_graph, pid.  Returns None if unreachable or the
+    response lacks a config block.
+    """
+    return _copilot_query_proxy_config(port)
+
+
+def _detect_running_proxy_backend(port: int) -> str | None:
+    """Read the backend of an already-running proxy from its health endpoint."""
+    return _copilot_detect_running_proxy_backend(port)
+
+
+def _kill_proxy_by_pid(pid: int, port: int) -> bool:
+    """Terminate a proxy process by PID and wait for the port to free up.
+
+    Sends SIGTERM first, falls back to SIGKILL after 5 seconds.
+    Returns True if the port is free afterwards, False otherwise.
+    """
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        pass  # Already gone
+    except PermissionError:
+        click.echo(f"  Warning: No permission to kill proxy PID {pid}")
+        return False
+
+    # Wait for port to free (up to 5 seconds)
+    for _ in range(50):
+        time.sleep(0.1)
+        if not _check_proxy(port):
+            return True
+
+    # SIGTERM didn't work — escalate to SIGKILL (Unix) or terminate (Windows)
+    try:
+        _kill_signal = getattr(signal, "SIGKILL", signal.SIGTERM)
+        os.kill(pid, _kill_signal)
+    except (ProcessLookupError, PermissionError):
+        pass
+
+    for _ in range(20):
+        time.sleep(0.1)
+        if not _check_proxy(port):
+            return True
+
+    return False
+
+
+def _find_persistent_manifest(port: int) -> Any:
+    """Return a matching persistent deployment manifest for the requested port."""
+    from headroom.install.state import list_manifests
+
+    manifests = [manifest for manifest in list_manifests() if manifest.port == port]
+    manifests.sort(key=lambda manifest: (manifest.profile != "default", manifest.profile))
+    return manifests[0] if manifests else None
+
+
+def _recover_persistent_proxy(port: int) -> bool:
+    """Start or recover a matching persistent deployment for the requested port."""
+    from headroom.install.health import probe_ready
+    from headroom.install.models import InstallPreset, SupervisorKind
+    from headroom.install.runtime import start_detached_agent, start_persistent_docker, wait_ready
+    from headroom.install.supervisors import start_supervisor
+
+    manifest = _find_persistent_manifest(port)
+    if manifest is None:
+        return False
+
+    if probe_ready(manifest.health_url):
+        click.echo(f"  Reusing persistent deployment '{manifest.profile}' on port {port}")
+        return True
+
+    if manifest.supervisor_kind == SupervisorKind.TASK.value:
+        click.echo(
+            f"  Warning: task-based deployment '{manifest.profile}' cannot be auto-recovered via wrap"
+        )
+        return False
+
+    click.echo(f"  Recovering persistent deployment '{manifest.profile}' on port {port}...")
+    try:
+        if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
+            start_persistent_docker(manifest)
+        elif manifest.supervisor_kind == SupervisorKind.SERVICE.value:
+            start_supervisor(manifest)
+        else:
+            start_detached_agent(manifest.profile)
+    except Exception as exc:
+        click.echo(
+            f"  Warning: could not recover persistent deployment '{manifest.profile}': {exc}"
+        )
+        return False
+
+    if wait_ready(manifest, timeout_seconds=45):
+        click.echo(f"  Recovered persistent deployment '{manifest.profile}' on port {port}")
+        return True
+
+    click.echo(f"  Warning: persistent deployment '{manifest.profile}' did not become ready")
+    return False
+
+
+def _copilot_model_configured(copilot_args: tuple[str, ...], env: dict[str, str]) -> bool:
+    """Return True when Copilot BYOK model selection is configured."""
+    return _copilot_model_configured_impl(copilot_args, env)
+
+
+def _should_use_copilot_oauth(
+    *,
+    backend: str | None,
+    provider_type: str,
+    env: dict[str, str],
+) -> bool:
+    """Prefer a reusable Copilot OAuth session when the requested routing supports it."""
+    if env.get("COPILOT_PROVIDER_API_KEY") or env.get("COPILOT_PROVIDER_BEARER_TOKEN"):
+        return False
+    if provider_type == "anthropic":
+        return False
+
+    effective_backend = backend or os.environ.get("HEADROOM_BACKEND")
+    if effective_backend not in (None, "", "anthropic"):
+        return False
+
+    return has_oauth_auth()
+
+
+def _ensure_proxy(
+    port: int,
+    no_proxy: bool,
+    *,
+    learn: bool = False,
+    memory: bool = False,
+    agent_type: str = "unknown",
+    code_graph: bool = False,
+    backend: str | None = None,
+    anyllm_provider: str | None = None,
+    region: str | None = None,
+    openai_api_url: str | None = None,
+) -> subprocess.Popen | None:
+    """Start or verify proxy. Returns process handle if we started it."""
+    helpers = _live_wrap_module()
+    if not no_proxy:
+        manifest = helpers._find_persistent_manifest(port)
+        if manifest is not None:
+            from headroom.install.health import probe_ready
+
+            if probe_ready(manifest.health_url):
+                click.echo(f"  Proxy already running on port {port}")
+                return None
+            if helpers._recover_persistent_proxy(port):
+                return None
+            if helpers._check_proxy(port):
+                raise click.ClickException(
+                    f"Persistent deployment '{manifest.profile}' on port {port} is not healthy."
+                )
+            click.echo(
+                f"  Warning: persistent deployment '{manifest.profile}' on port {port} "
+                "is stale; starting a fresh proxy instead."
+            )
+
+        if helpers._check_proxy(port):
+            # Proxy is running — check if it has the features we need
+            needs_restart = False
+            running_config = helpers._query_proxy_config(port)
+
+            if running_config is not None:
+                missing = []
+                if memory and not running_config.get("memory"):
+                    missing.append("memory")
+                if learn and not running_config.get("learn"):
+                    missing.append("learn")
+                if code_graph and not running_config.get("code_graph"):
+                    missing.append("code_graph")
+
+                if missing:
+                    needs_restart = True
+                    flags_str = ", ".join(f"--{f.replace('_', '-')}" for f in missing)
+                    click.echo(f"  Proxy on port {port} is missing: {flags_str}")
+                    click.echo("  Restarting proxy with upgraded configuration...")
+
+                    # Merge: keep features the running proxy already has
+                    memory = memory or bool(running_config.get("memory"))
+                    learn = learn or bool(running_config.get("learn"))
+                    code_graph = code_graph or bool(running_config.get("code_graph"))
+
+                    proxy_pid = running_config.get("pid")
+                    if proxy_pid is not None:
+                        if not helpers._kill_proxy_by_pid(int(proxy_pid), port):
+                            raise click.ClickException(
+                                f"Failed to stop existing proxy (PID {proxy_pid}) on port {port}. "
+                                "Stop it manually and retry."
+                            )
+                    else:
+                        click.echo(
+                            "  Warning: Running proxy does not expose PID. "
+                            "Cannot restart automatically."
+                        )
+                        click.echo(
+                            f"  Please stop the proxy on port {port} manually "
+                            f"and rerun with {flags_str}."
+                        )
+                        return None
+
+            if not needs_restart:
+                click.echo(f"  Proxy already running on port {port}")
+                return None
+
+        # Start (or restart) the proxy with the requested flags
+        click.echo(f"  Starting Headroom proxy on port {port}...")
+        try:
+            proc = cast(
+                subprocess.Popen[Any],
+                _live_wrap_module()._start_proxy(
+                    port,
+                    learn=learn,
+                    memory=memory,
+                    agent_type=agent_type,
+                    code_graph=code_graph,
+                    backend=backend,
+                    anyllm_provider=anyllm_provider,
+                    region=region,
+                    openai_api_url=openai_api_url,
+                ),
+            )
+            click.echo(f"  Proxy ready on http://127.0.0.1:{port}")
+            return proc
+        except RuntimeError as e:
+            click.echo(f"  Error: {e}")
+            raise SystemExit(1) from e
+    else:
+        if not helpers._check_proxy(port):
+            click.echo(f"  Warning: No proxy detected on port {port}")
+        return None
+
+
+def _make_cleanup(proxy_proc_holder: list, port: int = 8787) -> Any:
+    """Create a cleanup function that terminates the proxy on exit.
+
+    Only kills the proxy if no other headroom-wrapped clients are using it.
+    Checks by looking for other processes with ANTHROPIC_BASE_URL or
+    OPENAI_BASE_URL pointing at our port.
+    """
+
+    def _other_clients_exist() -> bool:
+        """Check if other processes are using this proxy."""
+        try:
+            # Count headroom wrap processes (excluding ourselves)
+            result = subprocess.run(
+                ["pgrep", "-f", f"127.0.0.1:{port}"],
+                capture_output=True,
+                text=True,
+            )
+            pids = [p.strip() for p in result.stdout.strip().split("\n") if p.strip()]
+            my_pid = str(os.getpid())
+            other_pids = [p for p in pids if p != my_pid]
+            return len(other_pids) > 0
+        except Exception:
+            return False  # If we can't check, assume no others
+
+    def cleanup(signum: int | None = None, frame: Any = None) -> None:
+        proc = proxy_proc_holder[0] if proxy_proc_holder else None
+        if proc and proc.poll() is None:
+            if _other_clients_exist():
+                # Other clients still using the proxy — leave it running
+                return
+            proc.terminate()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+
+    return cleanup
+
+
+def _launch_tool(
+    binary: str,
+    args: tuple,
+    env: dict[str, str],
+    port: int,
+    no_proxy: bool,
+    tool_label: str,
+    env_vars_display: list[str],
+    *,
+    learn: bool = False,
+    memory: bool = False,
+    agent_type: str = "unknown",
+    code_graph: bool = False,
+    backend: str | None = None,
+    anyllm_provider: str | None = None,
+    region: str | None = None,
+    openai_api_url: str | None = None,
+) -> None:
+    """Common logic: start proxy, launch tool, clean up."""
+    proxy_holder: list[subprocess.Popen | None] = [None]
+    cleanup = _make_cleanup(proxy_holder, port)
+    signal.signal(signal.SIGINT, cleanup)
+    signal.signal(signal.SIGTERM, cleanup)
+
+    try:
+        click.echo()
+        padded = f"HEADROOM WRAP: {tool_label}".center(47)
+        click.echo("  ╔═══════════════════════════════════════════════╗")
+        click.echo(f"  ║{padded}║")
+        click.echo("  ╚═══════════════════════════════════════════════╝")
+        click.echo()
+
+        proxy_holder[0] = _ensure_proxy(
+            port,
+            no_proxy,
+            learn=learn,
+            memory=memory,
+            agent_type=agent_type,
+            code_graph=code_graph,
+            backend=backend,
+            anyllm_provider=anyllm_provider,
+            region=region,
+            openai_api_url=openai_api_url,
+        )
+
+        if code_graph:
+            _setup_code_graph(verbose=False)
+
+        click.echo()
+        click.echo(f"  Launching {tool_label} (API routed through Headroom)...")
+        for var in env_vars_display:
+            click.echo(f"  {var}")
+        if args:
+            click.echo(f"  Extra args: {' '.join(args)}")
+        _print_telemetry_notice()
+        click.echo()
+
+        result = subprocess.run([binary, *args], env=env)
+        raise SystemExit(result.returncode)
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"  Error: {e}")
+        raise SystemExit(1) from e
+    finally:
+        cleanup()
+
+
+def _run_checked(
+    cmd: list[str],
+    *,
+    cwd: Path | None = None,
+    action: str,
+) -> subprocess.CompletedProcess[str]:
+    """Run subprocess and raise a ClickException with actionable context on failure."""
+    try:
+        return subprocess.run(
+            cmd,
+            cwd=str(cwd) if cwd else None,
+            check=True,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except FileNotFoundError as e:
+        raise click.ClickException(f"{action} failed: command not found: {cmd[0]}") from e
+    except subprocess.CalledProcessError as e:
+        stderr = (e.stderr or "").strip()
+        stdout = (e.stdout or "").strip()
+        details = stderr or stdout or f"exit code {e.returncode}"
+        raise click.ClickException(f"{action} failed: {details}") from e
+
+
+def _resolve_openclaw_extensions_dir(openclaw_bin: str) -> Path:
+    """Resolve OpenClaw extension root from active config file path."""
+    result = _run_checked([openclaw_bin, "config", "file"], action="openclaw config file")
+    lines = result.stdout.strip().splitlines()
+    config_path_str = lines[-1].strip() if lines else ""
+    if not config_path_str:
+        raise click.ClickException(
+            "Unable to resolve OpenClaw config path from `openclaw config file`."
+        )
+    config_path = Path(config_path_str).expanduser()
+    return config_path.parent / "extensions"
+
+
+def _normalize_openclaw_gateway_provider_ids(provider_ids: tuple[str, ...] | None) -> list[str]:
+    """Normalize configured OpenClaw provider ids, defaulting to openai-codex."""
+    return _normalize_openclaw_gateway_provider_ids_impl(provider_ids)
+
+
+def _read_openclaw_config_value(openclaw_bin: str, path: str) -> Any | None:
+    """Read an OpenClaw config value when present, returning None on missing paths."""
+    result = subprocess.run(
+        [openclaw_bin, "config", "get", path],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        return None
+
+    output = result.stdout.strip()
+    if not output:
+        return None
+
+    try:
+        return json.loads(output)
+    except json.JSONDecodeError:
+        return output
+
+
+def _decode_openclaw_entry_json(raw_value: str | None) -> Any | None:
+    """Decode a JSON payload captured from `openclaw config get` when available."""
+    return _decode_openclaw_entry_json_impl(raw_value)
+
+
+def _build_openclaw_plugin_entry(
+    *,
+    existing_entry: Any,
+    proxy_port: int,
+    startup_timeout_ms: int,
+    python_path: str | None,
+    no_auto_start: bool,
+    gateway_provider_ids: tuple[str, ...] | None,
+    enabled: bool,
+) -> dict[str, object]:
+    """Merge managed Headroom plugin settings with any existing entry payload."""
+    return _build_openclaw_plugin_entry_impl(
+        existing_entry=existing_entry,
+        proxy_port=proxy_port,
+        startup_timeout_ms=startup_timeout_ms,
+        python_path=python_path,
+        no_auto_start=no_auto_start,
+        gateway_provider_ids=gateway_provider_ids,
+        enabled=enabled,
+    )
+
+
+def _build_openclaw_unwrap_entry(existing_entry: Any) -> dict[str, object]:
+    """Disable the managed plugin while preserving unrelated user config."""
+    return _build_openclaw_unwrap_entry_impl(existing_entry)
+
+
+def _write_openclaw_plugin_entry(openclaw_bin: str, entry: dict[str, object]) -> None:
+    """Persist the Headroom plugin config entry."""
+    _run_checked(
+        [
+            openclaw_bin,
+            "config",
+            "set",
+            "plugins.entries.headroom",
+            json.dumps(entry, separators=(",", ":")),
+            "--strict-json",
+        ],
+        action="openclaw config set plugins.entries.headroom",
+    )
+
+
+def _set_openclaw_context_engine_slot(openclaw_bin: str, engine_id: str) -> None:
+    """Persist the selected OpenClaw context engine slot."""
+    _run_checked(
+        [
+            openclaw_bin,
+            "config",
+            "set",
+            "plugins.slots.contextEngine",
+            json.dumps(engine_id),
+            "--strict-json",
+        ],
+        action="openclaw config set plugins.slots.contextEngine",
+    )
+
+
+def _restart_or_start_openclaw_gateway(openclaw_bin: str) -> tuple[str, str]:
+    """Restart the gateway when running, otherwise start it."""
+    restart_result = subprocess.run(
+        [openclaw_bin, "gateway", "restart"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if restart_result.returncode == 0:
+        output = restart_result.stdout.strip() or restart_result.stderr.strip()
+        return "restarted", output
+
+    start_result = _run_checked(
+        [openclaw_bin, "gateway", "start"],
+        action="openclaw gateway start",
+    )
+    output = start_result.stdout.strip() or start_result.stderr.strip()
+    return "started", output
+
+
+def _copy_openclaw_plugin_into_extensions(
+    *,
+    plugin_dir: Path,
+    openclaw_bin: str,
+) -> Path:
+    """Fallback install path when `openclaw plugins install` is blocked on linked source."""
+    dist_dir = plugin_dir / "dist"
+    if not dist_dir.exists():
+        raise click.ClickException(
+            f"Plugin dist folder missing at {dist_dir}. Build the plugin first."
+        )
+    hook_shim_dir = plugin_dir / "hook-shim"
+    if not hook_shim_dir.exists():
+        raise click.ClickException(
+            f"Plugin hook-shim folder missing at {hook_shim_dir}. Build the plugin first."
+        )
+
+    extensions_dir = _resolve_openclaw_extensions_dir(openclaw_bin)
+    target_dir = extensions_dir / "headroom"
+    target_dist = target_dir / "dist"
+    target_hook_shim = target_dir / "hook-shim"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    if target_dist.exists():
+        shutil.rmtree(target_dist)
+    if target_hook_shim.exists():
+        shutil.rmtree(target_hook_shim)
+    shutil.copytree(dist_dir, target_dist)
+    shutil.copytree(hook_shim_dir, target_hook_shim)
+
+    for filename in ("openclaw.plugin.json", "package.json", "README.md"):
+        source = plugin_dir / filename
+        if source.exists():
+            shutil.copy2(source, target_dir / filename)
+
+    return target_dir
+
+
+@main.group()
+def wrap() -> None:
+    """Wrap CLI tools to run through Headroom.
+
+    \b
+    Starts a Headroom proxy, configures the environment, and launches
+    the target tool so all API calls route through Headroom automatically.
+
+    \b
+    Supported tools:
+        headroom wrap claude              # Claude Code (Anthropic)
+        headroom wrap copilot -- --model claude-sonnet-4-20250514
+        headroom wrap codex               # OpenAI Codex CLI
+        headroom wrap aider               # Aider
+        headroom wrap cursor              # Cursor (prints config instructions)
+        headroom wrap openclaw            # OpenClaw plugin bootstrap
+    """
+
+
+@main.group()
+def unwrap() -> None:
+    """Undo durable Headroom wrapping for supported tools."""
+
+
+# =============================================================================
+# Claude Code
+# =============================================================================
+
+
+@wrap.command(context_settings={"ignore_unknown_options": True})
+@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
+@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and hook registration")
+@click.option(
+    "--code-graph",
+    is_flag=True,
+    help="Enable code graph indexing via codebase-memory-mcp (optional)",
+)
+@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
+@click.option(
+    "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to MEMORY.md)"
+)
+@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--prepare-only", is_flag=True, hidden=True)
+@click.argument("claude_args", nargs=-1, type=click.UNPROCESSED)
+def claude(
+    port: int,
+    no_rtk: bool,
+    code_graph: bool,
+    no_proxy: bool,
+    learn: bool,
+    memory: bool,
+    verbose: bool,
+    prepare_only: bool,
+    claude_args: tuple,
+) -> None:
+    """Launch Claude Code through Headroom proxy.
+
+    \b
+    Sets ANTHROPIC_BASE_URL to route all Anthropic API calls through Headroom.
+    All unknown flags are passed through to claude (e.g. --resume, --model).
+
+    \b
+    Examples:
+        headroom wrap claude                    # Start everything
+        headroom wrap claude --memory           # With persistent memory
+        headroom wrap claude --resume <id>      # Resume a session
+        headroom wrap claude -- -p              # Claude in print mode
+        headroom wrap claude --code-graph        # With code graph intelligence
+        headroom wrap claude --no-rtk           # Skip rtk (proxy only)
+    """
+    if prepare_only:
+        if not no_rtk:
+            _prepare_wrap_rtk(verbose=verbose, label="Claude")
+        return
+
+    claude_bin = shutil.which("claude")
+    if not claude_bin:
+        click.echo("Error: 'claude' not found in PATH.")
+        click.echo("Install Claude Code: https://docs.anthropic.com/en/docs/claude-code")
+        raise SystemExit(1)
+
+    # Setup rtk before launching (Claude-specific)
+    proxy_holder: list[subprocess.Popen | None] = [None]
+    cleanup = _make_cleanup(proxy_holder, port)
+    signal.signal(signal.SIGINT, cleanup)
+    signal.signal(signal.SIGTERM, cleanup)
+
+    # Memory sync BEFORE proxy startup — sync headroom DB ↔ Claude's files
+    if memory:
+        try:
+            import subprocess as _sp
+
+            mem_dir = Path.cwd() / ".headroom"
+            mem_dir.mkdir(parents=True, exist_ok=True)
+            _sync_db = str(mem_dir / "memory.db")
+            _sync_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))
+
+            click.echo(f"  Syncing memory (user={_sync_user})...")
+            sync_result = _sp.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "headroom.memory.sync",
+                    "--db",
+                    _sync_db,
+                    "--user",
+                    _sync_user,
+                    "--agent",
+                    "claude",
+                    "--force",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            if sync_result.returncode == 0 and sync_result.stdout.strip():
+                import json as _json
+
+                stats = _json.loads(sync_result.stdout.strip().split("\n")[-1])
+                imp, exp, ms = stats["imported"], stats["exported"], stats["ms"]
+                if imp or exp:
+                    click.echo(f"  Memory synced: {imp} imported, {exp} exported ({ms}ms)")
+                else:
+                    click.echo(f"  Memory: up to date ({ms}ms)")
+            elif sync_result.returncode != 0:
+                click.echo(f"  Warning: memory sync error: {sync_result.stderr[-200:]}")
+        except Exception as e:
+            click.echo(f"  Warning: memory sync failed: {e}")
+
+    try:
+        click.echo()
+        click.echo("  ╔═══════════════════════════════════════════════╗")
+        click.echo("  ║            HEADROOM WRAP: CLAUDE              ║")
+        click.echo("  ╚═══════════════════════════════════════════════╝")
+        click.echo()
+
+        proxy_holder[0] = _ensure_proxy(
+            port, no_proxy, learn=learn, memory=memory, agent_type="claude", code_graph=code_graph
+        )
+
+        if not no_rtk:
+            click.echo("  Setting up rtk...")
+            _setup_rtk(verbose=verbose)
+        elif verbose:
+            click.echo("  Skipping rtk (--no-rtk)")
+
+        if code_graph:
+            _setup_code_graph(verbose=verbose)
+
+        click.echo()
+        click.echo("  Launching Claude Code (API routed through Headroom)...")
+        click.echo(f"  ANTHROPIC_BASE_URL={_claude_proxy_base_url(port)}")
+        if claude_args:
+            click.echo(f"  Extra args: {' '.join(claude_args)}")
+        _print_telemetry_notice()
+        click.echo()
+
+        env = os.environ.copy()
+        env["ANTHROPIC_BASE_URL"] = _claude_proxy_base_url(port)
+
+        result = subprocess.run([claude_bin, *claude_args], env=env)
+        raise SystemExit(result.returncode)
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"  Error: {e}")
+        raise SystemExit(1) from e
+    finally:
+        cleanup()
+
+
+# =============================================================================
+# GitHub Copilot CLI
+# =============================================================================
+
+
+@wrap.command(context_settings={"ignore_unknown_options": True})
+@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
+@click.option(
+    "--no-rtk",
+    is_flag=True,
+    help="Skip rtk installation and Copilot instructions injection",
+)
+@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
+@click.option(
+    "--backend",
+    default=None,
+    help="API backend for the proxy: 'anthropic', 'anyllm', 'litellm-vertex', etc. (env: HEADROOM_BACKEND)",
+)
+@click.option(
+    "--anyllm-provider",
+    default=None,
+    help="Provider for any-llm backend: openai, mistral, groq, etc. (env: HEADROOM_ANYLLM_PROVIDER)",
+)
+@click.option(
+    "--region", default=None, help="Cloud region for Bedrock/Vertex (env: HEADROOM_REGION)"
+)
+@click.option(
+    "--provider-type",
+    type=click.Choice(["auto", "anthropic", "openai"]),
+    default="auto",
+    show_default=True,
+    help="Copilot BYOK provider mode. 'auto' uses anthropic for the default proxy backend and openai for translated backends.",
+)
+@click.option(
+    "--wire-api",
+    type=click.Choice(["completions", "responses"]),
+    default=None,
+    help="OpenAI-compatible Copilot wire API. Defaults to 'completions' when provider-type resolves to openai.",
+)
+@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.argument("copilot_args", nargs=-1, type=click.UNPROCESSED)
+def copilot(
+    port: int,
+    no_rtk: bool,
+    no_proxy: bool,
+    backend: str | None,
+    anyllm_provider: str | None,
+    region: str | None,
+    provider_type: str,
+    wire_api: str | None,
+    memory: bool,
+    verbose: bool,
+    copilot_args: tuple[str, ...],
+) -> None:
+    """Launch GitHub Copilot CLI through Headroom proxy.
+
+    \b
+    Configures Copilot CLI BYOK provider variables so Copilot routes through
+    the local Headroom proxy. In auto mode, the wrapper uses Anthropic-style
+    routing for the stock proxy backend and OpenAI-compatible routing for
+    translated backends such as any-llm and LiteLLM.
+
+    \b
+    Examples:
+        headroom wrap copilot -- --model claude-sonnet-4-20250514
+        headroom wrap copilot --backend anyllm --anyllm-provider groq -- --model gpt-4o
+        headroom wrap copilot --provider-type openai --wire-api responses -- --model gpt-5.4
+        headroom wrap copilot --no-rtk -- --prompt "explain this file"
+    """
+    copilot_bin = shutil.which("copilot")
+    if not copilot_bin:
+        click.echo("Error: 'copilot' not found in PATH.")
+        click.echo(
+            "Install GitHub Copilot CLI: "
+            "https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli"
+        )
+        raise SystemExit(1)
+
+    effective_backend = backend or os.environ.get("HEADROOM_BACKEND")
+    if _check_proxy(port):
+        running_backend = _detect_running_proxy_backend(port)
+        if effective_backend and running_backend and effective_backend != running_backend:
+            raise click.ClickException(
+                f"Proxy already running on port {port} with backend '{running_backend}'. "
+                f"Stop it or rerun with --backend {running_backend}."
+            )
+        effective_backend = running_backend or effective_backend
+
+    effective_provider_type = _resolve_copilot_provider_type(effective_backend, provider_type)
+    _validate_copilot_configuration(
+        provider_type=effective_provider_type,
+        wire_api=wire_api,
+        backend=effective_backend,
+    )
+
+    if not no_rtk:
+        click.echo("  Setting up rtk for Copilot...")
+        rtk_path = _ensure_rtk_binary(verbose=verbose)
+        if rtk_path:
+            copilot_instructions = Path.cwd() / ".github" / "copilot-instructions.md"
+            _inject_rtk_instructions(copilot_instructions, verbose=verbose)
+
+    env = os.environ.copy()
+    openai_api_url: str | None = None
+    if _should_use_copilot_oauth(
+        backend=effective_backend,
+        provider_type=provider_type,
+        env=env,
+    ):
+        client_bearer = resolve_client_bearer_token()
+        if not client_bearer:
+            raise click.ClickException(
+                "GitHub Copilot auth was detected but no reusable bearer token could be resolved."
+            )
+
+        effective_wire_api = wire_api or "completions"
+        env["COPILOT_PROVIDER_TYPE"] = "openai"
+        env["COPILOT_PROVIDER_BASE_URL"] = f"http://127.0.0.1:{port}/v1"
+        env["COPILOT_PROVIDER_WIRE_API"] = effective_wire_api
+        env["COPILOT_PROVIDER_BEARER_TOKEN"] = client_bearer
+        env.pop("COPILOT_PROVIDER_API_KEY", None)
+        env_vars_display = [
+            "COPILOT_PROVIDER_TYPE=openai",
+            f"COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:{port}/v1",
+            f"COPILOT_PROVIDER_WIRE_API={effective_wire_api}",
+            "COPILOT_AUTH_MODE=github-oauth",
+        ]
+        openai_api_url = COPILOT_API_URL
+    else:
+        env, env_vars_display = _build_copilot_launch_env(
+            port=port,
+            provider_type=effective_provider_type,
+            wire_api=wire_api,
+            environ=env,
+        )
+
+        if not env.get("COPILOT_PROVIDER_API_KEY"):
+            src = _copilot_provider_key_source(effective_provider_type)
+            click.echo(
+                f"\n  Error: Copilot BYOK mode requires a provider API key.\n"
+                f"  `headroom wrap copilot` uses Copilot's BYOK mode, which bypasses GitHub's\n"
+                f"  Copilot API and routes requests directly to the model provider through the\n"
+                f"  Headroom proxy. A GitHub Copilot subscription alone is not sufficient.\n\n"
+                f"  Set one of:\n"
+                f"    export {src}=sk-...          # recommended\n"
+                f"    export COPILOT_PROVIDER_API_KEY=sk-...  # also works\n"
+            )
+            raise SystemExit(1)
+
+    if not _copilot_model_configured(copilot_args, env):
+        click.echo(
+            "  Note: Copilot BYOK requires a model. Pass `--model <name>` "
+            "or set `COPILOT_MODEL` / `COPILOT_PROVIDER_MODEL_ID`."
+        )
+
+    _launch_tool(
+        binary=copilot_bin,
+        args=copilot_args,
+        env=env,
+        port=port,
+        no_proxy=no_proxy,
+        tool_label="COPILOT",
+        env_vars_display=env_vars_display,
+        learn=False,
+        memory=memory,
+        agent_type="copilot",
+        backend=backend,
+        anyllm_provider=anyllm_provider,
+        region=region,
+        openai_api_url=openai_api_url,
+    )
+
+
+# =============================================================================
+# OpenAI Codex CLI
+# =============================================================================
+
+
+@wrap.command(context_settings={"ignore_unknown_options": True})
+@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
+@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and AGENTS.md injection")
+@click.option(
+    "--code-graph",
+    is_flag=True,
+    help="Enable code graph indexing via codebase-memory-mcp (optional)",
+)
+@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
+@click.option(
+    "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to AGENTS.md)"
+)
+@click.option(
+    "--backend",
+    default=None,
+    help="API backend for the proxy: 'anthropic', 'anyllm', 'litellm-vertex', etc. (env: HEADROOM_BACKEND)",
+)
+@click.option(
+    "--anyllm-provider",
+    default=None,
+    help="Provider for any-llm backend: openai, mistral, groq, etc. (env: HEADROOM_ANYLLM_PROVIDER)",
+)
+@click.option(
+    "--region", default=None, help="Cloud region for Bedrock/Vertex (env: HEADROOM_REGION)"
+)
+@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--prepare-only", is_flag=True, hidden=True)
+@click.argument("codex_args", nargs=-1, type=click.UNPROCESSED)
+def codex(
+    port: int,
+    no_rtk: bool,
+    code_graph: bool,
+    no_proxy: bool,
+    learn: bool,
+    memory: bool,
+    backend: str | None,
+    anyllm_provider: str | None,
+    region: str | None,
+    verbose: bool,
+    prepare_only: bool,
+    codex_args: tuple,
+) -> None:
+    """Launch OpenAI Codex CLI through Headroom proxy.
+
+    \b
+    Sets OPENAI_BASE_URL to route all OpenAI API calls through Headroom.
+    Installs rtk and injects instructions into AGENTS.md so Codex uses
+    token-optimized commands (60-90% savings on shell output).
+
+    \b
+    Examples:
+        headroom wrap codex                         # Start proxy + rtk + codex
+        headroom wrap codex -- "fix the bug"        # Pass prompt to codex
+        headroom wrap codex --no-rtk                # Skip rtk setup
+        headroom wrap codex --port 9999             # Custom proxy port
+        headroom wrap codex --backend anyllm --anyllm-provider groq
+    """
+    # Setup rtk for Codex (binary + AGENTS.md instructions, no hooks)
+    if not no_rtk:
+        click.echo("  Setting up rtk for Codex...")
+        rtk_path = _ensure_rtk_binary(verbose=verbose)
+        if rtk_path:
+            # Inject into project AGENTS.md (Codex reads this automatically)
+            agents_md = Path.cwd() / "AGENTS.md"
+            _inject_rtk_instructions(agents_md, verbose=verbose)
+
+            # Also inject into global ~/.codex/AGENTS.md
+            global_agents = Path.home() / ".codex" / "AGENTS.md"
+            _inject_rtk_instructions(global_agents, verbose=verbose)
+
+    # Setup memory MCP server for Codex (native tool integration)
+    if memory:
+        click.echo("  Setting up memory for Codex...")
+        mem_dir = Path.cwd() / ".headroom"
+        mem_dir.mkdir(parents=True, exist_ok=True)
+        db_path = str(mem_dir / "memory.db")
+        mem_user = os.environ.get("USER", os.environ.get("USERNAME", "default"))
+
+        # Register MCP server in Codex config
+        _inject_memory_mcp_config(db_path, mem_user)
+
+        # Inject memory guidance into project AGENTS.md
+        agents_md = Path.cwd() / "AGENTS.md"
+        _inject_memory_agents_md(agents_md)
+
+        # Sync Claude's memories → DB so MCP search finds them
+        try:
+            import asyncio
+
+            from headroom.memory.backends.local import LocalBackend, LocalBackendConfig
+            from headroom.memory.sync import sync_import
+            from headroom.memory.sync_adapters.claude_code import (
+                ClaudeCodeAdapter,
+                get_claude_memory_dir,
+            )
+
+            claude_memory_dir = get_claude_memory_dir()
+
+            async def _import_claude_memories() -> int:
+                config = LocalBackendConfig(db_path=db_path)
+                backend = LocalBackend(config)
+                await backend._ensure_initialized()
+                adapter = ClaudeCodeAdapter(claude_memory_dir)
+                count = await sync_import(backend, adapter, mem_user)
+                await backend.close()
+                return count
+
+            imported = asyncio.run(_import_claude_memories())
+            if imported:
+                click.echo(f"  Memory: imported {imported} memories from Claude")
+        except Exception as e:
+            click.echo(f"  Warning: Claude memory import failed: {e}")
+
+    if prepare_only:
+        _inject_codex_provider_config(port)
+        return
+
+    codex_bin = shutil.which("codex")
+    if not codex_bin:
+        click.echo("Error: 'codex' not found in PATH.")
+        click.echo("Install Codex CLI: npm install -g @openai/codex")
+        raise SystemExit(1)
+
+    env, env_vars_display = _build_codex_launch_env(port, os.environ)
+
+    # Inject Headroom provider into Codex config so WebSocket traffic also
+    # routes through the proxy.  Codex ignores OPENAI_BASE_URL for its WS
+    # transport unless a custom provider declares supports_websockets = true.
+    # NOTE: this must run BEFORE _inject_memory_mcp_config because it rewrites
+    # the config file.  Re-inject MCP config after if memory is enabled.
+    _inject_codex_provider_config(port)
+    if memory:
+        mem_dir = Path.cwd() / ".headroom"
+        _inject_memory_mcp_config(
+            str(mem_dir / "memory.db"),
+            os.environ.get("USER", os.environ.get("USERNAME", "default")),
+        )
+
+    _launch_tool(
+        binary=codex_bin,
+        args=codex_args,
+        env=env,
+        port=port,
+        no_proxy=no_proxy,
+        tool_label="CODEX",
+        env_vars_display=env_vars_display,
+        learn=learn,
+        memory=memory,
+        agent_type="codex",
+        code_graph=code_graph,
+        backend=backend,
+        anyllm_provider=anyllm_provider,
+        region=region,
+    )
+
+
+# =============================================================================
+# Aider
+# =============================================================================
+
+
+@wrap.command(context_settings={"ignore_unknown_options": True})
+@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
+@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and conventions injection")
+@click.option(
+    "--code-graph",
+    is_flag=True,
+    help="Enable code graph indexing via codebase-memory-mcp (optional)",
+)
+@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
+@click.option("--learn", is_flag=True, help="Enable live traffic learning")
+@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
+@click.option(
+    "--backend", default=None, help="API backend: 'anthropic', 'anyllm', 'litellm-vertex', etc."
+)
+@click.option("--anyllm-provider", default=None, help="Provider for any-llm backend")
+@click.option("--region", default=None, help="Cloud region for Bedrock/Vertex")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--prepare-only", is_flag=True, hidden=True)
+@click.argument("aider_args", nargs=-1, type=click.UNPROCESSED)
+def aider(
+    port: int,
+    no_rtk: bool,
+    code_graph: bool,
+    no_proxy: bool,
+    learn: bool,
+    memory: bool,
+    backend: str | None,
+    anyllm_provider: str | None,
+    region: str | None,
+    verbose: bool,
+    prepare_only: bool,
+    aider_args: tuple,
+) -> None:
+    """Launch aider through Headroom proxy.
+
+    \b
+    Sets OPENAI_API_BASE to route all API calls through Headroom.
+    Installs rtk and injects instructions into .aider.conf.yml conventions
+    so aider uses token-optimized commands.
+
+    \b
+    Examples:
+        headroom wrap aider                              # Start proxy + rtk + aider
+        headroom wrap aider -- --model gpt-4o            # Use GPT-4o
+        headroom wrap aider -- --model claude-sonnet-4   # Use Claude
+        headroom wrap aider --no-rtk                     # Skip rtk setup
+        headroom wrap aider --backend litellm-vertex --region us-central1
+    """
+    # Setup rtk for aider (binary + CONVENTIONS.md instructions)
+    if not no_rtk:
+        click.echo("  Setting up rtk for aider...")
+        rtk_path = _ensure_rtk_binary(verbose=verbose)
+        if rtk_path:
+            # aider reads CONVENTIONS.md from project root
+            conventions = Path.cwd() / "CONVENTIONS.md"
+            _inject_rtk_instructions(conventions, verbose=verbose)
+
+    if prepare_only:
+        return
+
+    aider_bin = shutil.which("aider")
+    if not aider_bin:
+        click.echo("Error: 'aider' not found in PATH.")
+        click.echo("Install aider: pip install aider-chat")
+        raise SystemExit(1)
+
+    env, env_vars_display = _build_aider_launch_env(port, os.environ)
+
+    _launch_tool(
+        binary=aider_bin,
+        args=aider_args,
+        env=env,
+        port=port,
+        no_proxy=no_proxy,
+        tool_label="AIDER",
+        env_vars_display=env_vars_display,
+        learn=learn,
+        memory=memory,
+        agent_type="aider",
+        code_graph=code_graph,
+        backend=backend,
+        anyllm_provider=anyllm_provider,
+        region=region,
+    )
+
+
+# =============================================================================
+# Cursor
+# =============================================================================
+
+
+@wrap.command(context_settings={"ignore_unknown_options": True})
+@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
+@click.option("--no-rtk", is_flag=True, help="Skip rtk installation and .cursorrules injection")
+@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
+@click.option(
+    "--learn", is_flag=True, help="Enable live traffic learning (patterns saved to .cursor/rules/)"
+)
+@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--prepare-only", is_flag=True, hidden=True)
+def cursor(
+    port: int,
+    no_rtk: bool,
+    no_proxy: bool,
+    learn: bool,
+    memory: bool,
+    verbose: bool,
+    prepare_only: bool,
+) -> None:
+    """Start Headroom proxy for use with Cursor.
+
+    \b
+    Cursor reads its API configuration from its settings UI, not from
+    environment variables. This command starts the proxy, installs rtk
+    with .cursorrules instructions, and prints the Cursor settings.
+
+    \b
+    After running this command, open Cursor and configure:
+        Settings > Models > OpenAI API Key > Advanced > Override Base URL
+
+    \b
+    Example:
+        headroom wrap cursor                # Start proxy + rtk + instructions
+        headroom wrap cursor --no-rtk       # Proxy only, no rtk
+        headroom wrap cursor --port 9999    # Custom proxy port
+    """
+    if not no_rtk:
+        click.echo("  Setting up rtk for Cursor...")
+        rtk_path = _ensure_rtk_binary(verbose=verbose)
+        if rtk_path:
+            cursorrules = Path.cwd() / ".cursorrules"
+            _inject_rtk_instructions(cursorrules, verbose=verbose)
+
+    if prepare_only:
+        return
+
+    proxy_holder: list[subprocess.Popen | None] = [None]
+    cleanup = _make_cleanup(proxy_holder, port)
+    signal.signal(signal.SIGINT, cleanup)
+    signal.signal(signal.SIGTERM, cleanup)
+
+    try:
+        click.echo()
+        click.echo("  ╔═══════════════════════════════════════════════╗")
+        click.echo("  ║            HEADROOM WRAP: CURSOR              ║")
+        click.echo("  ╚═══════════════════════════════════════════════╝")
+        click.echo()
+
+        proxy_holder[0] = _ensure_proxy(
+            port, no_proxy, learn=learn, memory=memory, agent_type="cursor"
+        )
+
+        click.echo()
+        for line in _render_cursor_setup_lines(port):
+            click.echo(line)
+        if not no_rtk:
+            click.echo()
+            click.echo("  rtk instructions injected into .cursorrules")
+            click.echo("  Cursor will use token-optimized commands automatically.")
+        click.echo()
+        click.echo("  Press Ctrl+C to stop the proxy.")
+        click.echo()
+
+        # Block until Ctrl+C
+        try:
+            while True:
+                time.sleep(1)
+                proc = proxy_holder[0]
+                if proc and proc.poll() is not None:
+                    click.echo("  Proxy process exited unexpectedly.")
+                    raise SystemExit(1)
+        except KeyboardInterrupt:
+            click.echo("\n  Shutting down...")
+
+    except SystemExit:
+        raise
+    except Exception as e:
+        click.echo(f"  Error: {e}")
+        raise SystemExit(1) from e
+    finally:
+        cleanup()
+
+
+# =============================================================================
+# OpenClaw
+# =============================================================================
+
+
+@wrap.command("openclaw")
+@click.option(
+    "--plugin-path",
+    type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
+    default=None,
+    help="Path to local OpenClaw plugin source directory (advanced/dev override)",
+)
+@click.option(
+    "--plugin-spec",
+    default="headroom-ai/openclaw",
+    show_default=True,
+    help="NPM plugin spec for OpenClaw install (used when --plugin-path is omitted)",
+)
+@click.option(
+    "--skip-build",
+    is_flag=True,
+    help="Skip npm install/build in local source mode (--plugin-path)",
+)
+@click.option(
+    "--copy",
+    is_flag=True,
+    help="Install by copying plugin path instead of using --link",
+)
+@click.option("--proxy-port", default=8787, type=int, help="Headroom proxy port")
+@click.option("--startup-timeout-ms", default=20000, type=int, help="Proxy startup timeout")
+@click.option(
+    "--gateway-provider-id",
+    "gateway_provider_ids",
+    multiple=True,
+    help="OpenClaw provider id to route through Headroom (repeatable; default: openai-codex)",
+)
+@click.option(
+    "--python-path",
+    default=None,
+    help="Optional Python executable for proxy launcher fallback",
+)
+@click.option(
+    "--no-auto-start",
+    is_flag=True,
+    help="Disable plugin auto-start of local headroom proxy",
+)
+@click.option(
+    "--no-restart",
+    is_flag=True,
+    help="Do not restart OpenClaw gateway at the end",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--prepare-only", is_flag=True, hidden=True)
+@click.option("--existing-entry-json", default=None, hidden=True)
+def openclaw(
+    plugin_path: Path | None,
+    plugin_spec: str,
+    skip_build: bool,
+    copy: bool,
+    proxy_port: int,
+    startup_timeout_ms: int,
+    gateway_provider_ids: tuple[str, ...],
+    python_path: str | None,
+    no_auto_start: bool,
+    no_restart: bool,
+    verbose: bool,
+    prepare_only: bool,
+    existing_entry_json: str | None,
+) -> None:
+    """Install and configure Headroom OpenClaw plugin in one command.
+
+    \b
+    What this command does:
+      1. Installs OpenClaw plugin from npm (or local --plugin-path)
+      2. Builds plugin source if --plugin-path is used
+      3. Writes minimal plugin config and sets contextEngine slot
+      4. Validates config
+      5. Restarts OpenClaw gateway (unless --no-restart)
+
+    \b
+    Example:
+      headroom wrap openclaw
+      headroom wrap openclaw --plugin-path C:\\git\\headroom\\plugins\\openclaw
+    """
+    if prepare_only:
+        entry = _build_openclaw_plugin_entry(
+            existing_entry=_decode_openclaw_entry_json(existing_entry_json),
+            proxy_port=proxy_port,
+            startup_timeout_ms=startup_timeout_ms,
+            python_path=python_path,
+            no_auto_start=no_auto_start,
+            gateway_provider_ids=gateway_provider_ids,
+            enabled=True,
+        )
+        click.echo(json.dumps(entry, separators=(",", ":")))
+        return
+
+    openclaw_bin = shutil.which("openclaw")
+    if not openclaw_bin:
+        raise click.ClickException("'openclaw' not found in PATH. Install OpenClaw CLI first.")
+
+    plugin_dir = plugin_path.resolve() if plugin_path else None
+    local_source_mode = plugin_dir is not None
+    if plugin_dir:
+        if not plugin_dir.exists():
+            raise click.ClickException(f"Plugin path not found: {plugin_dir}.")
+        if not (plugin_dir / "package.json").exists():
+            raise click.ClickException(f"Invalid plugin path (missing package.json): {plugin_dir}")
+        if not (plugin_dir / "openclaw.plugin.json").exists():
+            raise click.ClickException(
+                f"Invalid plugin path (missing openclaw.plugin.json): {plugin_dir}"
+            )
+
+    npm_bin = shutil.which("npm")
+    if local_source_mode and not skip_build and not npm_bin:
+        raise click.ClickException(
+            "'npm' not found in PATH. Install Node/npm or rerun with --skip-build."
+        )
+
+    click.echo()
+    click.echo("  ╔═══════════════════════════════════════════════╗")
+    click.echo("  ║           HEADROOM WRAP: OPENCLAW             ║")
+    click.echo("  ╚═══════════════════════════════════════════════╝")
+    click.echo()
+    if local_source_mode:
+        click.echo(f"  Plugin source: local ({plugin_dir})")
+    else:
+        click.echo(f"  Plugin source: npm ({plugin_spec})")
+
+    if local_source_mode and not skip_build:
+        click.echo("  Building OpenClaw plugin (npm install + npm run build)...")
+        _run_checked([npm_bin or "npm", "install"], cwd=plugin_dir, action="npm install")
+        _run_checked([npm_bin or "npm", "run", "build"], cwd=plugin_dir, action="npm run build")
+    elif not local_source_mode and skip_build:
+        click.echo("  Skipping build: npm install mode does not build local source.")
+
+    effective_python_path = python_path
+    if effective_python_path is None and not no_auto_start and sys.executable:
+        effective_python_path = sys.executable
+
+    existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")
+    entry = _build_openclaw_plugin_entry(
+        existing_entry=existing_entry,
+        proxy_port=proxy_port,
+        startup_timeout_ms=startup_timeout_ms,
+        python_path=effective_python_path,
+        no_auto_start=no_auto_start,
+        gateway_provider_ids=gateway_provider_ids,
+        enabled=True,
+    )
+
+    click.echo("  Writing plugin configuration...")
+    _write_openclaw_plugin_entry(openclaw_bin, entry)
+
+    install_cmd = [
+        openclaw_bin,
+        "plugins",
+        "install",
+        "--dangerously-force-unsafe-install",
+    ]
+    if local_source_mode:
+        if copy:
+            install_cmd.append(str(plugin_dir))
+            install_cwd = None
+        else:
+            install_cmd.extend(["--link", "."])
+            install_cwd = plugin_dir
+    else:
+        install_cmd.append(plugin_spec)
+        install_cwd = None
+
+    click.echo("  Installing OpenClaw plugin with required unsafe-install flag...")
+    install_result = subprocess.run(
+        install_cmd,
+        cwd=str(install_cwd) if install_cwd else None,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if install_result.returncode != 0:
+        combined_error = "\n".join(
+            x for x in [install_result.stderr.strip(), install_result.stdout.strip()] if x
+        )
+        plugin_already_exists = "plugin already exists" in combined_error.lower()
+        linked_install_bug = (
+            "also not a valid hook pack" in combined_error.lower()
+            and "--dangerously-force-unsafe-install" in " ".join(install_cmd)
+        )
+        if plugin_already_exists:
+            click.echo("  Plugin already installed; continuing with configuration/update steps.")
+        elif linked_install_bug and local_source_mode and plugin_dir is not None:
+            click.echo(
+                "  OpenClaw linked-path install bug detected; applying extension-path fallback..."
+            )
+            target_dir = _copy_openclaw_plugin_into_extensions(
+                plugin_dir=plugin_dir,
+                openclaw_bin=openclaw_bin,
+            )
+            click.echo(f"  Fallback plugin copy completed: {target_dir}")
+        else:
+            details = combined_error or f"exit code {install_result.returncode}"
+            raise click.ClickException(f"openclaw plugins install failed: {details}")
+    elif verbose and install_result.stdout.strip():
+        click.echo(install_result.stdout.strip())
+
+    _set_openclaw_context_engine_slot(openclaw_bin, "headroom")
+    _run_checked(
+        [openclaw_bin, "config", "validate"],
+        action="openclaw config validate",
+    )
+
+    if no_restart:
+        click.echo("  Skipping gateway restart (--no-restart).")
+        click.echo(
+            "  Run `openclaw gateway restart` (or `openclaw gateway start`) to apply plugin changes."
+        )
+    else:
+        click.echo("  Applying plugin changes to OpenClaw gateway...")
+        gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)
+        click.echo(f"  Gateway {gateway_action}.")
+        if verbose and gateway_output:
+            click.echo(gateway_output)
+
+    inspect_result = _run_checked(
+        [openclaw_bin, "plugins", "inspect", "headroom"],
+        action="openclaw plugins inspect headroom",
+    )
+    if verbose and inspect_result.stdout.strip():
+        click.echo(inspect_result.stdout.strip())
+
+    click.echo()
+    click.echo("✓ OpenClaw is configured to use Headroom context compression.")
+    click.echo("  Plugin: headroom")
+    click.echo("  Slot:   plugins.slots.contextEngine = headroom")
+    click.echo()
+
+
+@unwrap.command("openclaw")
+@click.option("--no-restart", is_flag=True, help="Do not restart OpenClaw gateway at the end")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--prepare-only", is_flag=True, hidden=True)
+@click.option("--existing-entry-json", default=None, hidden=True)
+def unwrap_openclaw(
+    no_restart: bool,
+    verbose: bool,
+    prepare_only: bool,
+    existing_entry_json: str | None,
+) -> None:
+    """Disable the Headroom OpenClaw plugin and restore the legacy engine slot."""
+    if prepare_only:
+        click.echo(
+            json.dumps(
+                _build_openclaw_unwrap_entry(_decode_openclaw_entry_json(existing_entry_json)),
+                separators=(",", ":"),
+            )
+        )
+        return
+
+    openclaw_bin = shutil.which("openclaw")
+    if not openclaw_bin:
+        raise click.ClickException("'openclaw' not found in PATH. Install OpenClaw CLI first.")
+
+    click.echo()
+    click.echo("  ╔═══════════════════════════════════════════════╗")
+    click.echo("  ║          HEADROOM UNWRAP: OPENCLAW            ║")
+    click.echo("  ╚═══════════════════════════════════════════════╝")
+    click.echo()
+    click.echo("  Disabling Headroom plugin and removing engine mapping...")
+
+    existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")
+    entry = _build_openclaw_unwrap_entry(existing_entry)
+    _write_openclaw_plugin_entry(openclaw_bin, entry)
+    _set_openclaw_context_engine_slot(openclaw_bin, "legacy")
+    _run_checked(
+        [openclaw_bin, "config", "validate"],
+        action="openclaw config validate",
+    )
+
+    if no_restart:
+        click.echo("  Skipping gateway restart (--no-restart).")
+        click.echo(
+            "  Run `openclaw gateway restart` (or `openclaw gateway start`) to apply unwrap changes."
+        )
+    else:
+        click.echo("  Applying unwrap changes to OpenClaw gateway...")
+        gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)
+        click.echo(f"  Gateway {gateway_action}.")
+        if verbose and gateway_output:
+            click.echo(gateway_output)
+
+    if verbose:
+        inspect_result = _run_checked(
+            [openclaw_bin, "plugins", "inspect", "headroom"],
+            action="openclaw plugins inspect headroom",
+        )
+        if inspect_result.stdout.strip():
+            click.echo(inspect_result.stdout.strip())
+
+    click.echo()
+    click.echo("✓ OpenClaw Headroom wrap removed.")
+    click.echo("  Plugin: headroom (installed, disabled)")
+    click.echo("  Slot:   plugins.slots.contextEngine = legacy")
+    click.echo()
+
+
+# =============================================================================
+# OpenAI Codex CLI (unwrap)
+# =============================================================================
+
+
+@unwrap.command("codex")
+def unwrap_codex() -> None:
+    """Undo ``headroom wrap codex`` edits to ``~/.codex/config.toml``.
+
+    Behaviour:
+
+    * If a pre-wrap backup (``config.toml.headroom-backup``) exists, the
+      original file is restored byte-for-byte and the backup is removed.
+    * Otherwise, if the config file still contains the Headroom-managed
+      block, that block is stripped out and the rest of the file is
+      preserved.
+    * If the config only ever contained Headroom-written content, the file
+      is removed entirely so Codex falls back to its defaults.
+    * If neither a backup nor a Headroom block is present, this is a safe
+      no-op (the user either never wrapped, or already unwrapped).
+    """
+    click.echo()
+    click.echo("  ╔═══════════════════════════════════════════════╗")
+    click.echo("  ║           HEADROOM UNWRAP: CODEX              ║")
+    click.echo("  ╚═══════════════════════════════════════════════╝")
+    click.echo()
+
+    try:
+        status, config_file = _restore_codex_provider_config()
+    except Exception as e:  # pragma: no cover - filesystem-level errors
+        raise click.ClickException(f"could not unwrap Codex config: {e}") from e
+
+    if status == "restored":
+        click.echo(f"  Restored prior {config_file} from pre-wrap backup.")
+    elif status == "cleaned":
+        click.echo(f"  Removed Headroom block from {config_file}; other content preserved.")
+    elif status == "removed":
+        click.echo(f"  Removed {config_file} (contained only Headroom-written config).")
+    else:
+        click.echo(f"  Nothing to undo: {config_file} has no Headroom wrap markers.")
+
+    click.echo()
+    click.echo("✓ Codex is no longer routed through the Headroom proxy.")
+    click.echo()
diff --git a/headroom/compress.py b/headroom/compress.py
index 1a9c387ae2b8a4ad74573ec4789f39c8800bf6d1..09ac4f46fc61066d753998936d342641043b512b 100644
--- a/headroom/compress.py
+++ b/headroom/compress.py
@@ -1,347 +1,347 @@
-"""One-function compression API for Headroom.
-
-The simplest way to use Headroom — no proxy, no config, just compress:
-
-    from headroom import compress
-
-    result = compress(messages, model="claude-sonnet-4-5-20250929")
-    result.messages          # Compressed messages (same format, fewer tokens)
-    result.tokens_saved      # Tokens saved
-    result.compression_ratio # e.g., 0.35 means 65% saved
-
-Works with any LLM client, any proxy, any framework. Just compress
-the messages before sending them.
-
-Examples:
-
-    # With Anthropic SDK
-    from anthropic import Anthropic
-    from headroom import compress
-
-    client = Anthropic()
-    messages = [{"role": "user", "content": huge_tool_output}]
-    compressed = compress(messages, model="claude-sonnet-4-5-20250929")
-    response = client.messages.create(
-        model="claude-sonnet-4-5-20250929",
-        messages=compressed.messages,
-    )
-
-    # With OpenAI SDK
-    from openai import OpenAI
-    from headroom import compress
-
-    client = OpenAI()
-    messages = [{"role": "user", "content": "analyze this"}, {"role": "tool", "content": big_data}]
-    compressed = compress(messages, model="gpt-4o")
-    response = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)
-
-    # With LiteLLM
-    import litellm
-    from headroom import compress
-
-    messages = [...]
-    compressed = compress(messages, model="bedrock/claude-sonnet")
-    response = litellm.completion(model="bedrock/claude-sonnet", messages=compressed.messages)
-
-    # With any HTTP client
-    import httpx
-    from headroom import compress
-
-    compressed = compress(messages, model="claude-sonnet-4-5-20250929")
-    httpx.post("https://api.anthropic.com/v1/messages", json={
-        "model": "claude-sonnet-4-5-20250929",
-        "messages": compressed.messages,
-    })
-"""
-
-from __future__ import annotations
-
-import logging
-import threading
-from dataclasses import dataclass, field
-from typing import Any
-
-from .observability import get_otel_metrics
-from .pipeline import PipelineExtensionManager, PipelineStage, summarize_routing_markers
-from .utils import extract_user_query as _extract_user_query
-
-logger = logging.getLogger(__name__)
-
-
-# Lazy-initialized singleton pipeline
-_pipeline = None
-_pipeline_lock = threading.Lock()
-
-
-@dataclass
-class CompressConfig:
-    """User-facing compression options.
-
-    Controls what gets compressed, how aggressively, and with which model.
-    Pass to ``compress()`` or any integration that uses headroom.
-
-    Examples::
-
-        # Coding agent (default — skip user messages, protect recent)
-        compress(messages, model="gpt-4o")
-
-        # Financial document (compress everything, keep 50%)
-        compress(messages, model="claude-opus-4-20250514",
-            compress_user_messages=True,
-            target_ratio=0.5,
-            protect_recent=0,
-        )
-
-        # Aggressive (logs, search results)
-        compress(messages, model="gpt-4o", target_ratio=0.2)
-    """
-
-    # What to compress
-    compress_user_messages: bool = False
-    """Compress user messages too (default: skip them for coding agents).
-    Set True for document compression, RAG pipelines, or when user messages
-    contain large tool outputs."""
-
-    compress_system_messages: bool = True
-    """Compress system messages (default: True).
-    Set False to preserve system prompts exactly as-is. Useful for voice
-    agents where tool definitions and instructions must not be altered."""
-
-    protect_recent: int = 4
-    """Don't compress the last N messages (they're the active conversation).
-    Set 0 to compress everything."""
-
-    protect_analysis_context: bool = True
-    """Detect 'analyze'/'review' intent and protect code from compression."""
-
-    # How aggressive
-    target_ratio: float | None = None
-    """Keep ratio for Kompress. None = model decides (~15% kept, aggressive).
-    0.5 = keep 50% (safe for documents). 0.7 = keep 70% (conservative).
-    Only affects Kompress (text compression). SmartCrusher (JSON) has its
-    own logic based on array dedup."""
-
-    min_tokens_to_compress: int = 250
-    """Minimum token count for a message to be compressed.
-    Messages shorter than this are left unchanged. Default 250.
-    Set lower for voice agents where turns are short."""
-
-    # Model variant
-    kompress_model: str | None = None
-    """Kompress model ID. None = default (chopratejas/kompress-base).
-    Set to a HuggingFace model ID for domain-specific compression.
-    Set to 'disabled' to skip ML compression entirely
-    (only SmartCrusher + CacheAligner will run)."""
-
-
-@dataclass
-class CompressResult:
-    """Result of compressing messages.
-
-    Attributes:
-        messages: The compressed messages (same format as input).
-        tokens_before: Token count before compression.
-        tokens_after: Token count after compression.
-        tokens_saved: Tokens removed by compression.
-        compression_ratio: Ratio of tokens saved (0.0 = no savings, 1.0 = 100% removed).
-        transforms_applied: List of transforms that were applied.
-    """
-
-    messages: list[dict[str, Any]]
-    tokens_before: int = 0
-    tokens_after: int = 0
-    tokens_saved: int = 0
-    compression_ratio: float = 0.0
-    transforms_applied: list[str] = field(default_factory=list)
-
-
-def compress(
-    messages: list[dict[str, Any]],
-    model: str = "claude-sonnet-4-5-20250929",
-    model_limit: int = 200000,
-    optimize: bool = True,
-    hooks: Any = None,
-    config: CompressConfig | None = None,
-    **kwargs: Any,
-) -> CompressResult:
-    """Compress messages using Headroom's full compression pipeline.
-
-    This is the simplest way to use Headroom. No proxy, no config needed.
-    Just pass messages and get compressed messages back.
-
-    Args:
-        messages: List of messages in Anthropic or OpenAI format.
-        model: Model name (used for token counting and context limit).
-        model_limit: Model's context window size in tokens.
-        optimize: Whether to actually compress (False = passthrough for A/B testing).
-        hooks: Optional CompressionHooks instance for custom behavior.
-        config: Compression options (CompressConfig). Overrides defaults.
-        **kwargs: Shorthand for CompressConfig fields. These override config:
-            compress_user_messages, target_ratio, protect_recent,
-            protect_analysis_context, kompress_model.
-
-    Returns:
-        CompressResult with compressed messages and metrics.
-
-    Examples::
-
-        # Default (coding agent)
-        result = compress(messages, model="gpt-4o")
-
-        # Financial document (keep 50%, compress everything)
-        result = compress(messages, model="claude-opus-4-20250514",
-            compress_user_messages=True,
-            target_ratio=0.5,
-            protect_recent=0,
-        )
-    """
-    if not messages or not optimize:
-        return CompressResult(messages=messages)
-
-    # Build config from explicit config + kwargs
-    cfg = config or CompressConfig()
-    config_fields = {f.name for f in cfg.__dataclass_fields__.values()}
-    for key, value in kwargs.items():
-        if key in config_fields:
-            setattr(cfg, key, value)
-
-    pipeline = _get_pipeline()
-    pipeline_extensions = PipelineExtensionManager(hooks=hooks, discover=False)
-
-    try:
-        # Compute biases from hooks if provided
-        biases = None
-        if hooks:
-            from headroom.hooks import CompressContext
-
-            ctx = CompressContext(model=model)
-            messages = hooks.pre_compress(messages, ctx)
-            biases = hooks.compute_biases(messages, ctx)
-
-        received_event = pipeline_extensions.emit(
-            PipelineStage.INPUT_RECEIVED,
-            operation="compress",
-            model=model,
-            messages=messages,
-        )
-        if received_event.messages is not None:
-            messages = received_event.messages
-
-        # Extract user query from messages so transforms can score by
-        # relevance.  Without this, SmartCrusher selects items by statistics
-        # alone (position, anomaly) and may drop relevant content.
-        context = _extract_user_query(messages)
-
-        result = pipeline.apply(
-            messages=messages,
-            model=model,
-            model_limit=model_limit,
-            context=context,
-            biases=biases,
-            # Pass CompressConfig options through to transforms
-            compress_user_messages=cfg.compress_user_messages,
-            compress_system_messages=cfg.compress_system_messages,
-            target_ratio=cfg.target_ratio,
-            protect_recent=cfg.protect_recent,
-            protect_analysis_context=cfg.protect_analysis_context,
-            min_tokens_to_compress=cfg.min_tokens_to_compress,
-            kompress_model=cfg.kompress_model,
-        )
-
-        tokens_before = result.tokens_before
-        tokens_after = result.tokens_after
-        compressed_messages = result.messages
-
-        routing_markers = summarize_routing_markers(result.transforms_applied)
-        if routing_markers:
-            routed_event = pipeline_extensions.emit(
-                PipelineStage.INPUT_ROUTED,
-                operation="compress",
-                model=model,
-                messages=compressed_messages,
-                metadata={
-                    "routing_markers": routing_markers,
-                    "transforms_applied": result.transforms_applied,
-                },
-            )
-            if routed_event.messages is not None:
-                compressed_messages = routed_event.messages
-
-        compressed_event = pipeline_extensions.emit(
-            PipelineStage.INPUT_COMPRESSED,
-            operation="compress",
-            model=model,
-            messages=compressed_messages,
-            metadata={
-                "tokens_before": tokens_before,
-                "tokens_after": tokens_after,
-                "transforms_applied": result.transforms_applied,
-            },
-        )
-        if compressed_event.messages is not None:
-            compressed_messages = compressed_event.messages
-
-        tokens_saved = tokens_before - tokens_after
-        ratio = tokens_saved / tokens_before if tokens_before > 0 else 0.0
-
-        # Post-compress hook
-        if hooks and tokens_saved > 0:
-            from headroom.hooks import CompressEvent
-
-            hooks.post_compress(
-                CompressEvent(
-                    tokens_before=tokens_before,
-                    tokens_after=tokens_after,
-                    tokens_saved=tokens_saved,
-                    compression_ratio=ratio,
-                    transforms_applied=result.transforms_applied,
-                    model=model,
-                )
-            )
-
-        return CompressResult(
-            messages=compressed_messages,
-            tokens_before=tokens_before,
-            tokens_after=tokens_after,
-            tokens_saved=tokens_saved,
-            compression_ratio=ratio,
-            transforms_applied=result.transforms_applied,
-        )
-
-    except Exception as e:
-        get_otel_metrics().record_compression_failure(
-            model=model,
-            operation="compress",
-            error_type=type(e).__name__,
-        )
-        logger.warning("Compression failed, returning original messages: %s", e)
-        return CompressResult(
-            messages=messages,
-            tokens_before=0,
-            tokens_after=0,
-            tokens_saved=0,
-            compression_ratio=0.0,
-        )
-
-
-def _get_pipeline() -> Any:
-    """Get or create the singleton compression pipeline."""
-    global _pipeline
-
-    if _pipeline is not None:
-        return _pipeline
-
-    with _pipeline_lock:
-        if _pipeline is not None:
-            return _pipeline
-
-        from headroom.transforms import TransformPipeline
-
-        # Default pipeline: CacheAligner → ContentRouter → IntelligentContext
-        # CacheAligner: stabilizes prefix for provider KV cache hits
-        # ContentRouter: routes to the right compressor per content type
-        #   (SmartCrusher for JSON, CodeCompressor for code, Kompress for text)
-        # IntelligentContext: enforces token limits with score-based dropping
-        _pipeline = TransformPipeline()
-        logger.debug("Headroom compression pipeline initialized")
-        return _pipeline
+"""One-function compression API for Headroom.
+
+The simplest way to use Headroom — no proxy, no config, just compress:
+
+    from headroom import compress
+
+    result = compress(messages, model="claude-sonnet-4-5-20250929")
+    result.messages          # Compressed messages (same format, fewer tokens)
+    result.tokens_saved      # Tokens saved
+    result.compression_ratio # e.g., 0.35 means 65% saved
+
+Works with any LLM client, any proxy, any framework. Just compress
+the messages before sending them.
+
+Examples:
+
+    # With Anthropic SDK
+    from anthropic import Anthropic
+    from headroom import compress
+
+    client = Anthropic()
+    messages = [{"role": "user", "content": huge_tool_output}]
+    compressed = compress(messages, model="claude-sonnet-4-5-20250929")
+    response = client.messages.create(
+        model="claude-sonnet-4-5-20250929",
+        messages=compressed.messages,
+    )
+
+    # With OpenAI SDK
+    from openai import OpenAI
+    from headroom import compress
+
+    client = OpenAI()
+    messages = [{"role": "user", "content": "analyze this"}, {"role": "tool", "content": big_data}]
+    compressed = compress(messages, model="gpt-4o")
+    response = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)
+
+    # With LiteLLM
+    import litellm
+    from headroom import compress
+
+    messages = [...]
+    compressed = compress(messages, model="bedrock/claude-sonnet")
+    response = litellm.completion(model="bedrock/claude-sonnet", messages=compressed.messages)
+
+    # With any HTTP client
+    import httpx
+    from headroom import compress
+
+    compressed = compress(messages, model="claude-sonnet-4-5-20250929")
+    httpx.post("https://api.anthropic.com/v1/messages", json={
+        "model": "claude-sonnet-4-5-20250929",
+        "messages": compressed.messages,
+    })
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass, field
+from typing import Any
+
+from .observability import get_otel_metrics
+from .pipeline import PipelineExtensionManager, PipelineStage, summarize_routing_markers
+from .utils import extract_user_query as _extract_user_query
+
+logger = logging.getLogger(__name__)
+
+
+# Lazy-initialized singleton pipeline
+_pipeline = None
+_pipeline_lock = threading.Lock()
+
+
+@dataclass
+class CompressConfig:
+    """User-facing compression options.
+
+    Controls what gets compressed, how aggressively, and with which model.
+    Pass to ``compress()`` or any integration that uses headroom.
+
+    Examples::
+
+        # Coding agent (default — skip user messages, protect recent)
+        compress(messages, model="gpt-4o")
+
+        # Financial document (compress everything, keep 50%)
+        compress(messages, model="claude-opus-4-20250514",
+            compress_user_messages=True,
+            target_ratio=0.5,
+            protect_recent=0,
+        )
+
+        # Aggressive (logs, search results)
+        compress(messages, model="gpt-4o", target_ratio=0.2)
+    """
+
+    # What to compress
+    compress_user_messages: bool = False
+    """Compress user messages too (default: skip them for coding agents).
+    Set True for document compression, RAG pipelines, or when user messages
+    contain large tool outputs."""
+
+    compress_system_messages: bool = True
+    """Compress system messages (default: True).
+    Set False to preserve system prompts exactly as-is. Useful for voice
+    agents where tool definitions and instructions must not be altered."""
+
+    protect_recent: int = 4
+    """Don't compress the last N messages (they're the active conversation).
+    Set 0 to compress everything."""
+
+    protect_analysis_context: bool = True
+    """Detect 'analyze'/'review' intent and protect code from compression."""
+
+    # How aggressive
+    target_ratio: float | None = None
+    """Keep ratio for Kompress. None = model decides (~15% kept, aggressive).
+    0.5 = keep 50% (safe for documents). 0.7 = keep 70% (conservative).
+    Only affects Kompress (text compression). SmartCrusher (JSON) has its
+    own logic based on array dedup."""
+
+    min_tokens_to_compress: int = 250
+    """Minimum token count for a message to be compressed.
+    Messages shorter than this are left unchanged. Default 250.
+    Set lower for voice agents where turns are short."""
+
+    # Model variant
+    kompress_model: str | None = None
+    """Kompress model ID. None = default (chopratejas/kompress-base).
+    Set to a HuggingFace model ID for domain-specific compression.
+    Set to 'disabled' to skip ML compression entirely
+    (only SmartCrusher + CacheAligner will run)."""
+
+
+@dataclass
+class CompressResult:
+    """Result of compressing messages.
+
+    Attributes:
+        messages: The compressed messages (same format as input).
+        tokens_before: Token count before compression.
+        tokens_after: Token count after compression.
+        tokens_saved: Tokens removed by compression.
+        compression_ratio: Ratio of tokens saved (0.0 = no savings, 1.0 = 100% removed).
+        transforms_applied: List of transforms that were applied.
+    """
+
+    messages: list[dict[str, Any]]
+    tokens_before: int = 0
+    tokens_after: int = 0
+    tokens_saved: int = 0
+    compression_ratio: float = 0.0
+    transforms_applied: list[str] = field(default_factory=list)
+
+
+def compress(
+    messages: list[dict[str, Any]],
+    model: str = "claude-sonnet-4-5-20250929",
+    model_limit: int = 200000,
+    optimize: bool = True,
+    hooks: Any = None,
+    config: CompressConfig | None = None,
+    **kwargs: Any,
+) -> CompressResult:
+    """Compress messages using Headroom's full compression pipeline.
+
+    This is the simplest way to use Headroom. No proxy, no config needed.
+    Just pass messages and get compressed messages back.
+
+    Args:
+        messages: List of messages in Anthropic or OpenAI format.
+        model: Model name (used for token counting and context limit).
+        model_limit: Model's context window size in tokens.
+        optimize: Whether to actually compress (False = passthrough for A/B testing).
+        hooks: Optional CompressionHooks instance for custom behavior.
+        config: Compression options (CompressConfig). Overrides defaults.
+        **kwargs: Shorthand for CompressConfig fields. These override config:
+            compress_user_messages, target_ratio, protect_recent,
+            protect_analysis_context, kompress_model.
+
+    Returns:
+        CompressResult with compressed messages and metrics.
+
+    Examples::
+
+        # Default (coding agent)
+        result = compress(messages, model="gpt-4o")
+
+        # Financial document (keep 50%, compress everything)
+        result = compress(messages, model="claude-opus-4-20250514",
+            compress_user_messages=True,
+            target_ratio=0.5,
+            protect_recent=0,
+        )
+    """
+    if not messages or not optimize:
+        return CompressResult(messages=messages)
+
+    # Build config from explicit config + kwargs
+    cfg = config or CompressConfig()
+    config_fields = {f.name for f in cfg.__dataclass_fields__.values()}
+    for key, value in kwargs.items():
+        if key in config_fields:
+            setattr(cfg, key, value)
+
+    pipeline = _get_pipeline()
+    pipeline_extensions = PipelineExtensionManager(hooks=hooks, discover=False)
+
+    try:
+        # Compute biases from hooks if provided
+        biases = None
+        if hooks:
+            from headroom.hooks import CompressContext
+
+            ctx = CompressContext(model=model)
+            messages = hooks.pre_compress(messages, ctx)
+            biases = hooks.compute_biases(messages, ctx)
+
+        received_event = pipeline_extensions.emit(
+            PipelineStage.INPUT_RECEIVED,
+            operation="compress",
+            model=model,
+            messages=messages,
+        )
+        if received_event.messages is not None:
+            messages = received_event.messages
+
+        # Extract user query from messages so transforms can score by
+        # relevance.  Without this, SmartCrusher selects items by statistics
+        # alone (position, anomaly) and may drop relevant content.
+        context = _extract_user_query(messages)
+
+        result = pipeline.apply(
+            messages=messages,
+            model=model,
+            model_limit=model_limit,
+            context=context,
+            biases=biases,
+            # Pass CompressConfig options through to transforms
+            compress_user_messages=cfg.compress_user_messages,
+            compress_system_messages=cfg.compress_system_messages,
+            target_ratio=cfg.target_ratio,
+            protect_recent=cfg.protect_recent,
+            protect_analysis_context=cfg.protect_analysis_context,
+            min_tokens_to_compress=cfg.min_tokens_to_compress,
+            kompress_model=cfg.kompress_model,
+        )
+
+        tokens_before = result.tokens_before
+        tokens_after = result.tokens_after
+        compressed_messages = result.messages
+
+        routing_markers = summarize_routing_markers(result.transforms_applied)
+        if routing_markers:
+            routed_event = pipeline_extensions.emit(
+                PipelineStage.INPUT_ROUTED,
+                operation="compress",
+                model=model,
+                messages=compressed_messages,
+                metadata={
+                    "routing_markers": routing_markers,
+                    "transforms_applied": result.transforms_applied,
+                },
+            )
+            if routed_event.messages is not None:
+                compressed_messages = routed_event.messages
+
+        compressed_event = pipeline_extensions.emit(
+            PipelineStage.INPUT_COMPRESSED,
+            operation="compress",
+            model=model,
+            messages=compressed_messages,
+            metadata={
+                "tokens_before": tokens_before,
+                "tokens_after": tokens_after,
+                "transforms_applied": result.transforms_applied,
+            },
+        )
+        if compressed_event.messages is not None:
+            compressed_messages = compressed_event.messages
+
+        tokens_saved = tokens_before - tokens_after
+        ratio = tokens_saved / tokens_before if tokens_before > 0 else 0.0
+
+        # Post-compress hook
+        if hooks and tokens_saved > 0:
+            from headroom.hooks import CompressEvent
+
+            hooks.post_compress(
+                CompressEvent(
+                    tokens_before=tokens_before,
+                    tokens_after=tokens_after,
+                    tokens_saved=tokens_saved,
+                    compression_ratio=ratio,
+                    transforms_applied=result.transforms_applied,
+                    model=model,
+                )
+            )
+
+        return CompressResult(
+            messages=compressed_messages,
+            tokens_before=tokens_before,
+            tokens_after=tokens_after,
+            tokens_saved=tokens_saved,
+            compression_ratio=ratio,
+            transforms_applied=result.transforms_applied,
+        )
+
+    except Exception as e:
+        get_otel_metrics().record_compression_failure(
+            model=model,
+            operation="compress",
+            error_type=type(e).__name__,
+        )
+        logger.warning("Compression failed, returning original messages: %s", e)
+        return CompressResult(
+            messages=messages,
+            tokens_before=0,
+            tokens_after=0,
+            tokens_saved=0,
+            compression_ratio=0.0,
+        )
+
+
+def _get_pipeline() -> Any:
+    """Get or create the singleton compression pipeline."""
+    global _pipeline
+
+    if _pipeline is not None:
+        return _pipeline
+
+    with _pipeline_lock:
+        if _pipeline is not None:
+            return _pipeline
+
+        from headroom.transforms import TransformPipeline
+
+        # Default pipeline: CacheAligner → ContentRouter → IntelligentContext
+        # CacheAligner: stabilizes prefix for provider KV cache hits
+        # ContentRouter: routes to the right compressor per content type
+        #   (SmartCrusher for JSON, CodeCompressor for code, Kompress for text)
+        # IntelligentContext: enforces token limits with score-based dropping
+        _pipeline = TransformPipeline()
+        logger.debug("Headroom compression pipeline initialized")
+        return _pipeline
diff --git a/headroom/copilot_auth.py b/headroom/copilot_auth.py
index 4f8c8a5777c6ad212b4000caa280498efcb96f85..ef77d6cae1fb2a4bf1e2dc38307a25a9e47480ca 100644
--- a/headroom/copilot_auth.py
+++ b/headroom/copilot_auth.py
@@ -1,444 +1,444 @@
-"""GitHub Copilot OAuth discovery and API-token exchange helpers."""
-
-from __future__ import annotations
-
-import asyncio
-import ctypes
-import json
-import logging
-import os
-import subprocess
-import time
-from ctypes import wintypes
-from dataclasses import dataclass
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-from urllib import error as urllib_error
-from urllib import request as urllib_request
-from urllib.parse import urlparse
-
-logger = logging.getLogger(__name__)
-
-DEFAULT_API_URL = "https://api.githubcopilot.com"
-DEFAULT_TOKEN_EXCHANGE_URL = "https://api.github.com/copilot_internal/v2/token"
-DEFAULT_GITHUB_HOST = "github.com"
-_TOKEN_EXPIRY_BUFFER_S = 60
-_DEFAULT_EDITOR_VERSION = "vscode/1.104.1"
-_DEFAULT_USER_AGENT = "GitHubCopilotChat/0.1"
-
-_API_TOKEN_ENV_VARS = (
-    "GITHUB_COPILOT_API_TOKEN",
-    "COPILOT_PROVIDER_BEARER_TOKEN",
-)
-_OAUTH_TOKEN_ENV_VARS = (
-    "GITHUB_COPILOT_GITHUB_TOKEN",
-    "GITHUB_COPILOT_TOKEN",
-    "GITHUB_TOKEN",
-    "COPILOT_GITHUB_TOKEN",
-)
-_OAUTH_TOKEN_KEYS = (
-    "oauth_token",
-    "oauthToken",
-    "token",
-    "access_token",
-    "accessToken",
-)
-_EXPIRY_KEYS = ("expires_at", "expiresAt", "expiry", "expires")
-
-
-@dataclass(frozen=True)
-class CopilotAPIToken:
-    """Short-lived API token exchanged from a GitHub OAuth token."""
-
-    token: str
-    expires_at: float
-    api_url: str = DEFAULT_API_URL
-    refresh_in: int | None = None
-    sku: str | None = None
-
-    @property
-    def is_valid(self) -> bool:
-        return time.time() < (self.expires_at - _TOKEN_EXPIRY_BUFFER_S)
-
-
-def _github_host() -> str:
-    return (os.environ.get("GITHUB_COPILOT_HOST") or DEFAULT_GITHUB_HOST).strip().lower()
-
-
-def _token_exchange_url() -> str:
-    return os.environ.get("GITHUB_COPILOT_TOKEN_EXCHANGE_URL", DEFAULT_TOKEN_EXCHANGE_URL).strip()
-
-
-def _should_exchange_oauth_token() -> bool:
-    raw = os.environ.get("GITHUB_COPILOT_USE_TOKEN_EXCHANGE", "").strip().lower()
-    return raw in {"1", "true", "yes", "on"}
-
-
-def _resolve_token_file_paths() -> list[Path]:
-    override = os.environ.get("GITHUB_COPILOT_TOKEN_FILE", "").strip()
-    if override:
-        return [Path(override).expanduser()]
-
-    paths: list[Path] = []
-    local_appdata = os.environ.get("LOCALAPPDATA", "").strip()
-    if local_appdata:
-        base = Path(local_appdata) / "github-copilot"
-        paths.extend([base / "apps.json", base / "hosts.json"])
-
-    config_base = Path.home() / ".config" / "github-copilot"
-    paths.extend([config_base / "apps.json", config_base / "hosts.json"])
-    return paths
-
-
-def _read_gh_cli_oauth_token() -> str | None:
-    gh_bin = os.environ.get("GH_PATH", "").strip() or "gh"
-    command = [gh_bin, "auth", "token"]
-    host = _github_host()
-    if host and host != DEFAULT_GITHUB_HOST:
-        command.extend(["--hostname", host])
-
-    try:
-        result = subprocess.run(
-            command,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            check=False,
-        )
-    except OSError as exc:
-        logger.debug("Unable to invoke GitHub CLI for Copilot auth discovery: %s", exc)
-        return None
-
-    if result.returncode != 0:
-        logger.debug("GitHub CLI auth token lookup failed with exit code %s", result.returncode)
-        return None
-
-    token = result.stdout.strip()
-    return token or None
-
-
-def _read_windows_copilot_cli_oauth_token() -> str | None:
-    if os.name != "nt":
-        return None
-
-    class FILETIME(ctypes.Structure):
-        _fields_ = [
-            ("dwLowDateTime", wintypes.DWORD),
-            ("dwHighDateTime", wintypes.DWORD),
-        ]
-
-    class CREDENTIAL(ctypes.Structure):
-        _fields_ = [
-            ("Flags", wintypes.DWORD),
-            ("Type", wintypes.DWORD),
-            ("TargetName", wintypes.LPWSTR),
-            ("Comment", wintypes.LPWSTR),
-            ("LastWritten", FILETIME),
-            ("CredentialBlobSize", wintypes.DWORD),
-            ("CredentialBlob", ctypes.POINTER(ctypes.c_ubyte)),
-            ("Persist", wintypes.DWORD),
-            ("AttributeCount", wintypes.DWORD),
-            ("Attributes", wintypes.LPVOID),
-            ("TargetAlias", wintypes.LPWSTR),
-            ("UserName", wintypes.LPWSTR),
-        ]
-
-    cred_ptr = ctypes.POINTER(CREDENTIAL)
-    credentials = ctypes.POINTER(cred_ptr)()
-    count = wintypes.DWORD()
-    win_dll = getattr(ctypes, "WinDLL", None)
-    if win_dll is None:
-        return None
-
-    advapi32 = win_dll("Advapi32.dll")
-    advapi32.CredEnumerateW.argtypes = [
-        wintypes.LPCWSTR,
-        wintypes.DWORD,
-        ctypes.POINTER(wintypes.DWORD),
-        ctypes.POINTER(ctypes.POINTER(cred_ptr)),
-    ]
-    advapi32.CredEnumerateW.restype = wintypes.BOOL
-    advapi32.CredFree.argtypes = [wintypes.LPVOID]
-
-    try:
-        if not advapi32.CredEnumerateW(None, 0, ctypes.byref(count), ctypes.byref(credentials)):
-            return None
-    except OSError as exc:
-        logger.debug("Unable to enumerate Windows credentials for Copilot auth discovery: %s", exc)
-        return None
-
-    host = _github_host().lower()
-    service_prefixes = [f"copilot-cli/{host}:"]
-    if "://" not in host:
-        service_prefixes.append(f"copilot-cli/https://{host}:")
-
-    try:
-        for idx in range(count.value):
-            credential = credentials[idx].contents
-            target = (credential.TargetName or "").strip().lower()
-            if not any(target.startswith(prefix) for prefix in service_prefixes):
-                continue
-            if credential.CredentialBlobSize <= 0 or not credential.CredentialBlob:
-                continue
-            blob = ctypes.string_at(credential.CredentialBlob, credential.CredentialBlobSize)
-            token = blob.decode("utf-8", errors="replace").strip()
-            if token:
-                return token
-    finally:
-        if credentials:
-            advapi32.CredFree(credentials)
-
-    return None
-
-
-def _parse_expiry(value: Any) -> float | None:
-    if value in (None, ""):
-        return None
-
-    if isinstance(value, int | float):
-        number = float(value)
-        if number > 10_000_000_000:
-            return number / 1000.0
-        return number
-
-    if isinstance(value, str):
-        raw = value.strip()
-        if not raw:
-            return None
-        if raw.isdigit():
-            return _parse_expiry(int(raw))
-        try:
-            normalized = raw.replace("Z", "+00:00")
-            return datetime.fromisoformat(normalized).timestamp()
-        except ValueError:
-            return None
-
-    return None
-
-
-def _entry_expired(entry: dict[str, Any]) -> bool:
-    for key in _EXPIRY_KEYS:
-        expiry = _parse_expiry(entry.get(key))
-        if expiry is None:
-            continue
-        return time.time() >= (expiry - _TOKEN_EXPIRY_BUFFER_S)
-    return False
-
-
-def _extract_oauth_token(entry: dict[str, Any]) -> str | None:
-    if _entry_expired(entry):
-        return None
-
-    for key in _OAUTH_TOKEN_KEYS:
-        value = entry.get(key)
-        if isinstance(value, str) and value.strip():
-            return value.strip()
-
-    for value in entry.values():
-        if isinstance(value, dict):
-            nested = _extract_oauth_token(value)
-            if nested:
-                return nested
-
-    return None
-
-
-def _iter_file_entries(payload: Any) -> list[tuple[str, dict[str, Any]]]:
-    entries: list[tuple[str, dict[str, Any]]] = []
-    if isinstance(payload, dict):
-        for key, value in payload.items():
-            if isinstance(value, dict):
-                entries.append((str(key), value))
-    elif isinstance(payload, list):
-        for idx, value in enumerate(payload):
-            if isinstance(value, dict):
-                key = str(value.get("host") or value.get("githubHost") or idx)
-                entries.append((key, value))
-    return entries
-
-
-def read_cached_oauth_token() -> str | None:
-    """Return a GitHub OAuth token for Copilot, if one is available."""
-
-    for env_var in _OAUTH_TOKEN_ENV_VARS:
-        token = os.environ.get(env_var, "").strip()
-        if token:
-            return token
-
-    windows_copilot_token = _read_windows_copilot_cli_oauth_token()
-    if windows_copilot_token:
-        return windows_copilot_token
-
-    gh_token = _read_gh_cli_oauth_token()
-    if gh_token:
-        return gh_token
-
-    host = _github_host()
-    for path in _resolve_token_file_paths():
-        try:
-            payload = json.loads(path.read_text(encoding="utf-8"))
-        except FileNotFoundError:
-            continue
-        except Exception as exc:
-            logger.debug("Unable to read Copilot credentials file %s: %s", path, exc)
-            continue
-
-        for key, entry in _iter_file_entries(payload):
-            if host not in key.lower():
-                continue
-            cached_token = _extract_oauth_token(entry)
-            if cached_token:
-                return cached_token
-
-    return None
-
-
-def resolve_client_bearer_token() -> str | None:
-    """Return a bearer token suitable for satisfying Copilot provider auth checks."""
-
-    for env_var in _API_TOKEN_ENV_VARS:
-        token = os.environ.get(env_var, "").strip()
-        if token:
-            return token
-    return read_cached_oauth_token()
-
-
-def has_oauth_auth() -> bool:
-    """Return True when existing Copilot auth can be reused."""
-
-    return resolve_client_bearer_token() is not None
-
-
-def is_copilot_api_url(url: str | None) -> bool:
-    """Return True when the upstream URL points at GitHub Copilot."""
-
-    if not url:
-        return False
-    parsed = urlparse(url)
-    host = parsed.netloc.lower() or parsed.path.lower()
-    return "githubcopilot.com" in host
-
-
-def build_copilot_upstream_url(base_url: str, path: str) -> str:
-    """Build an upstream URL, normalizing GitHub Copilot's non-/v1 path layout."""
-
-    normalized_base = base_url.rstrip("/")
-    normalized_path = path if path.startswith("/") else f"/{path}"
-    if is_copilot_api_url(normalized_base) and normalized_path.startswith("/v1/"):
-        normalized_path = normalized_path[3:]
-    return f"{normalized_base}{normalized_path}"
-
-
-class CopilotTokenProvider:
-    """Resolve and cache short-lived Copilot API tokens."""
-
-    def __init__(self) -> None:
-        self._lock = asyncio.Lock()
-        self._cached: CopilotAPIToken | None = None
-
-    async def get_api_token(self) -> CopilotAPIToken:
-        explicit_api_token = os.environ.get("GITHUB_COPILOT_API_TOKEN", "").strip()
-        if explicit_api_token:
-            return CopilotAPIToken(
-                token=explicit_api_token,
-                expires_at=time.time() + 3600,
-                api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()
-                or DEFAULT_API_URL,
-            )
-
-        cached = self._cached
-        if cached is not None and cached.is_valid:
-            return cached
-
-        async with self._lock:
-            cached = self._cached
-            if cached is not None and cached.is_valid:
-                return cached
-
-            oauth_token = read_cached_oauth_token()
-            if not oauth_token:
-                raise RuntimeError("No GitHub Copilot OAuth token is available.")
-
-            if not _should_exchange_oauth_token():
-                direct_token = CopilotAPIToken(
-                    token=oauth_token,
-                    expires_at=time.time() + 3600,
-                    api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()
-                    or DEFAULT_API_URL,
-                )
-                self._cached = direct_token
-                return direct_token
-
-            exchanged = await self._exchange_token(oauth_token)
-            self._cached = exchanged
-            return exchanged
-
-    async def _exchange_token(self, oauth_token: str) -> CopilotAPIToken:
-        headers = {
-            "Authorization": f"token {oauth_token}",
-            "Accept": "application/json",
-            "Editor-Version": os.environ.get(
-                "GITHUB_COPILOT_EDITOR_VERSION", _DEFAULT_EDITOR_VERSION
-            ),
-            "User-Agent": _DEFAULT_USER_AGENT,
-        }
-        payload = await asyncio.to_thread(self._exchange_token_sync, headers)
-        token = str(payload.get("token") or "").strip()
-        if not token:
-            raise RuntimeError("Copilot token exchange returned an empty token.")
-
-        expires_at = _parse_expiry(payload.get("expires_at")) or (time.time() + 1800)
-        raw_endpoints = payload.get("endpoints")
-        endpoints: dict[str, Any] = raw_endpoints if isinstance(raw_endpoints, dict) else {}
-        api_url = str(endpoints.get("api") or DEFAULT_API_URL).strip() or DEFAULT_API_URL
-        refresh_in = payload.get("refresh_in")
-        sku = payload.get("sku")
-        return CopilotAPIToken(
-            token=token,
-            expires_at=expires_at,
-            api_url=api_url,
-            refresh_in=int(refresh_in) if isinstance(refresh_in, int | float) else None,
-            sku=str(sku) if isinstance(sku, str) and sku.strip() else None,
-        )
-
-    @staticmethod
-    def _exchange_token_sync(headers: dict[str, str]) -> dict[str, Any]:
-        request = urllib_request.Request(_token_exchange_url(), headers=headers, method="GET")
-        try:
-            with urllib_request.urlopen(request, timeout=10.0) as response:
-                payload = json.loads(response.read().decode("utf-8"))
-                return payload if isinstance(payload, dict) else {}
-        except urllib_error.HTTPError as exc:
-            body = exc.read().decode("utf-8", errors="replace")
-            raise RuntimeError(
-                f"Copilot token exchange failed with HTTP {exc.code}: {body}"
-            ) from exc
-
-
-_provider: CopilotTokenProvider | None = None
-
-
-def get_copilot_token_provider() -> CopilotTokenProvider:
-    """Return the shared Copilot token provider."""
-
-    global _provider
-    if _provider is None:
-        _provider = CopilotTokenProvider()
-    return _provider
-
-
-async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[str, str]:
-    """Replace Authorization with a fresh Copilot API token when targeting Copilot."""
-
-    resolved = dict(headers)
-    if not is_copilot_api_url(url):
-        return resolved
-
-    token = await get_copilot_token_provider().get_api_token()
-    for key in list(resolved):
-        if key.lower() == "authorization":
-            resolved.pop(key)
-    resolved["Authorization"] = f"Bearer {token.token}"
-    return resolved
+"""GitHub Copilot OAuth discovery and API-token exchange helpers."""
+
+from __future__ import annotations
+
+import asyncio
+import ctypes
+import json
+import logging
+import os
+import subprocess
+import time
+from ctypes import wintypes
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from urllib import error as urllib_error
+from urllib import request as urllib_request
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_API_URL = "https://api.githubcopilot.com"
+DEFAULT_TOKEN_EXCHANGE_URL = "https://api.github.com/copilot_internal/v2/token"
+DEFAULT_GITHUB_HOST = "github.com"
+_TOKEN_EXPIRY_BUFFER_S = 60
+_DEFAULT_EDITOR_VERSION = "vscode/1.104.1"
+_DEFAULT_USER_AGENT = "GitHubCopilotChat/0.1"
+
+_API_TOKEN_ENV_VARS = (
+    "GITHUB_COPILOT_API_TOKEN",
+    "COPILOT_PROVIDER_BEARER_TOKEN",
+)
+_OAUTH_TOKEN_ENV_VARS = (
+    "GITHUB_COPILOT_GITHUB_TOKEN",
+    "GITHUB_COPILOT_TOKEN",
+    "GITHUB_TOKEN",
+    "COPILOT_GITHUB_TOKEN",
+)
+_OAUTH_TOKEN_KEYS = (
+    "oauth_token",
+    "oauthToken",
+    "token",
+    "access_token",
+    "accessToken",
+)
+_EXPIRY_KEYS = ("expires_at", "expiresAt", "expiry", "expires")
+
+
+@dataclass(frozen=True)
+class CopilotAPIToken:
+    """Short-lived API token exchanged from a GitHub OAuth token."""
+
+    token: str
+    expires_at: float
+    api_url: str = DEFAULT_API_URL
+    refresh_in: int | None = None
+    sku: str | None = None
+
+    @property
+    def is_valid(self) -> bool:
+        return time.time() < (self.expires_at - _TOKEN_EXPIRY_BUFFER_S)
+
+
+def _github_host() -> str:
+    return (os.environ.get("GITHUB_COPILOT_HOST") or DEFAULT_GITHUB_HOST).strip().lower()
+
+
+def _token_exchange_url() -> str:
+    return os.environ.get("GITHUB_COPILOT_TOKEN_EXCHANGE_URL", DEFAULT_TOKEN_EXCHANGE_URL).strip()
+
+
+def _should_exchange_oauth_token() -> bool:
+    raw = os.environ.get("GITHUB_COPILOT_USE_TOKEN_EXCHANGE", "").strip().lower()
+    return raw in {"1", "true", "yes", "on"}
+
+
+def _resolve_token_file_paths() -> list[Path]:
+    override = os.environ.get("GITHUB_COPILOT_TOKEN_FILE", "").strip()
+    if override:
+        return [Path(override).expanduser()]
+
+    paths: list[Path] = []
+    local_appdata = os.environ.get("LOCALAPPDATA", "").strip()
+    if local_appdata:
+        base = Path(local_appdata) / "github-copilot"
+        paths.extend([base / "apps.json", base / "hosts.json"])
+
+    config_base = Path.home() / ".config" / "github-copilot"
+    paths.extend([config_base / "apps.json", config_base / "hosts.json"])
+    return paths
+
+
+def _read_gh_cli_oauth_token() -> str | None:
+    gh_bin = os.environ.get("GH_PATH", "").strip() or "gh"
+    command = [gh_bin, "auth", "token"]
+    host = _github_host()
+    if host and host != DEFAULT_GITHUB_HOST:
+        command.extend(["--hostname", host])
+
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except OSError as exc:
+        logger.debug("Unable to invoke GitHub CLI for Copilot auth discovery: %s", exc)
+        return None
+
+    if result.returncode != 0:
+        logger.debug("GitHub CLI auth token lookup failed with exit code %s", result.returncode)
+        return None
+
+    token = result.stdout.strip()
+    return token or None
+
+
+def _read_windows_copilot_cli_oauth_token() -> str | None:
+    if os.name != "nt":
+        return None
+
+    class FILETIME(ctypes.Structure):
+        _fields_ = [
+            ("dwLowDateTime", wintypes.DWORD),
+            ("dwHighDateTime", wintypes.DWORD),
+        ]
+
+    class CREDENTIAL(ctypes.Structure):
+        _fields_ = [
+            ("Flags", wintypes.DWORD),
+            ("Type", wintypes.DWORD),
+            ("TargetName", wintypes.LPWSTR),
+            ("Comment", wintypes.LPWSTR),
+            ("LastWritten", FILETIME),
+            ("CredentialBlobSize", wintypes.DWORD),
+            ("CredentialBlob", ctypes.POINTER(ctypes.c_ubyte)),
+            ("Persist", wintypes.DWORD),
+            ("AttributeCount", wintypes.DWORD),
+            ("Attributes", wintypes.LPVOID),
+            ("TargetAlias", wintypes.LPWSTR),
+            ("UserName", wintypes.LPWSTR),
+        ]
+
+    cred_ptr = ctypes.POINTER(CREDENTIAL)
+    credentials = ctypes.POINTER(cred_ptr)()
+    count = wintypes.DWORD()
+    win_dll = getattr(ctypes, "WinDLL", None)
+    if win_dll is None:
+        return None
+
+    advapi32 = win_dll("Advapi32.dll")
+    advapi32.CredEnumerateW.argtypes = [
+        wintypes.LPCWSTR,
+        wintypes.DWORD,
+        ctypes.POINTER(wintypes.DWORD),
+        ctypes.POINTER(ctypes.POINTER(cred_ptr)),
+    ]
+    advapi32.CredEnumerateW.restype = wintypes.BOOL
+    advapi32.CredFree.argtypes = [wintypes.LPVOID]
+
+    try:
+        if not advapi32.CredEnumerateW(None, 0, ctypes.byref(count), ctypes.byref(credentials)):
+            return None
+    except OSError as exc:
+        logger.debug("Unable to enumerate Windows credentials for Copilot auth discovery: %s", exc)
+        return None
+
+    host = _github_host().lower()
+    service_prefixes = [f"copilot-cli/{host}:"]
+    if "://" not in host:
+        service_prefixes.append(f"copilot-cli/https://{host}:")
+
+    try:
+        for idx in range(count.value):
+            credential = credentials[idx].contents
+            target = (credential.TargetName or "").strip().lower()
+            if not any(target.startswith(prefix) for prefix in service_prefixes):
+                continue
+            if credential.CredentialBlobSize <= 0 or not credential.CredentialBlob:
+                continue
+            blob = ctypes.string_at(credential.CredentialBlob, credential.CredentialBlobSize)
+            token = blob.decode("utf-8", errors="replace").strip()
+            if token:
+                return token
+    finally:
+        if credentials:
+            advapi32.CredFree(credentials)
+
+    return None
+
+
+def _parse_expiry(value: Any) -> float | None:
+    if value in (None, ""):
+        return None
+
+    if isinstance(value, int | float):
+        number = float(value)
+        if number > 10_000_000_000:
+            return number / 1000.0
+        return number
+
+    if isinstance(value, str):
+        raw = value.strip()
+        if not raw:
+            return None
+        if raw.isdigit():
+            return _parse_expiry(int(raw))
+        try:
+            normalized = raw.replace("Z", "+00:00")
+            return datetime.fromisoformat(normalized).timestamp()
+        except ValueError:
+            return None
+
+    return None
+
+
+def _entry_expired(entry: dict[str, Any]) -> bool:
+    for key in _EXPIRY_KEYS:
+        expiry = _parse_expiry(entry.get(key))
+        if expiry is None:
+            continue
+        return time.time() >= (expiry - _TOKEN_EXPIRY_BUFFER_S)
+    return False
+
+
+def _extract_oauth_token(entry: dict[str, Any]) -> str | None:
+    if _entry_expired(entry):
+        return None
+
+    for key in _OAUTH_TOKEN_KEYS:
+        value = entry.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+
+    for value in entry.values():
+        if isinstance(value, dict):
+            nested = _extract_oauth_token(value)
+            if nested:
+                return nested
+
+    return None
+
+
+def _iter_file_entries(payload: Any) -> list[tuple[str, dict[str, Any]]]:
+    entries: list[tuple[str, dict[str, Any]]] = []
+    if isinstance(payload, dict):
+        for key, value in payload.items():
+            if isinstance(value, dict):
+                entries.append((str(key), value))
+    elif isinstance(payload, list):
+        for idx, value in enumerate(payload):
+            if isinstance(value, dict):
+                key = str(value.get("host") or value.get("githubHost") or idx)
+                entries.append((key, value))
+    return entries
+
+
+def read_cached_oauth_token() -> str | None:
+    """Return a GitHub OAuth token for Copilot, if one is available."""
+
+    for env_var in _OAUTH_TOKEN_ENV_VARS:
+        token = os.environ.get(env_var, "").strip()
+        if token:
+            return token
+
+    windows_copilot_token = _read_windows_copilot_cli_oauth_token()
+    if windows_copilot_token:
+        return windows_copilot_token
+
+    gh_token = _read_gh_cli_oauth_token()
+    if gh_token:
+        return gh_token
+
+    host = _github_host()
+    for path in _resolve_token_file_paths():
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            continue
+        except Exception as exc:
+            logger.debug("Unable to read Copilot credentials file %s: %s", path, exc)
+            continue
+
+        for key, entry in _iter_file_entries(payload):
+            if host not in key.lower():
+                continue
+            cached_token = _extract_oauth_token(entry)
+            if cached_token:
+                return cached_token
+
+    return None
+
+
+def resolve_client_bearer_token() -> str | None:
+    """Return a bearer token suitable for satisfying Copilot provider auth checks."""
+
+    for env_var in _API_TOKEN_ENV_VARS:
+        token = os.environ.get(env_var, "").strip()
+        if token:
+            return token
+    return read_cached_oauth_token()
+
+
+def has_oauth_auth() -> bool:
+    """Return True when existing Copilot auth can be reused."""
+
+    return resolve_client_bearer_token() is not None
+
+
+def is_copilot_api_url(url: str | None) -> bool:
+    """Return True when the upstream URL points at GitHub Copilot."""
+
+    if not url:
+        return False
+    parsed = urlparse(url)
+    host = parsed.netloc.lower() or parsed.path.lower()
+    return "githubcopilot.com" in host
+
+
+def build_copilot_upstream_url(base_url: str, path: str) -> str:
+    """Build an upstream URL, normalizing GitHub Copilot's non-/v1 path layout."""
+
+    normalized_base = base_url.rstrip("/")
+    normalized_path = path if path.startswith("/") else f"/{path}"
+    if is_copilot_api_url(normalized_base) and normalized_path.startswith("/v1/"):
+        normalized_path = normalized_path[3:]
+    return f"{normalized_base}{normalized_path}"
+
+
+class CopilotTokenProvider:
+    """Resolve and cache short-lived Copilot API tokens."""
+
+    def __init__(self) -> None:
+        self._lock = asyncio.Lock()
+        self._cached: CopilotAPIToken | None = None
+
+    async def get_api_token(self) -> CopilotAPIToken:
+        explicit_api_token = os.environ.get("GITHUB_COPILOT_API_TOKEN", "").strip()
+        if explicit_api_token:
+            return CopilotAPIToken(
+                token=explicit_api_token,
+                expires_at=time.time() + 3600,
+                api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()
+                or DEFAULT_API_URL,
+            )
+
+        cached = self._cached
+        if cached is not None and cached.is_valid:
+            return cached
+
+        async with self._lock:
+            cached = self._cached
+            if cached is not None and cached.is_valid:
+                return cached
+
+            oauth_token = read_cached_oauth_token()
+            if not oauth_token:
+                raise RuntimeError("No GitHub Copilot OAuth token is available.")
+
+            if not _should_exchange_oauth_token():
+                direct_token = CopilotAPIToken(
+                    token=oauth_token,
+                    expires_at=time.time() + 3600,
+                    api_url=os.environ.get("GITHUB_COPILOT_API_URL", DEFAULT_API_URL).strip()
+                    or DEFAULT_API_URL,
+                )
+                self._cached = direct_token
+                return direct_token
+
+            exchanged = await self._exchange_token(oauth_token)
+            self._cached = exchanged
+            return exchanged
+
+    async def _exchange_token(self, oauth_token: str) -> CopilotAPIToken:
+        headers = {
+            "Authorization": f"token {oauth_token}",
+            "Accept": "application/json",
+            "Editor-Version": os.environ.get(
+                "GITHUB_COPILOT_EDITOR_VERSION", _DEFAULT_EDITOR_VERSION
+            ),
+            "User-Agent": _DEFAULT_USER_AGENT,
+        }
+        payload = await asyncio.to_thread(self._exchange_token_sync, headers)
+        token = str(payload.get("token") or "").strip()
+        if not token:
+            raise RuntimeError("Copilot token exchange returned an empty token.")
+
+        expires_at = _parse_expiry(payload.get("expires_at")) or (time.time() + 1800)
+        raw_endpoints = payload.get("endpoints")
+        endpoints: dict[str, Any] = raw_endpoints if isinstance(raw_endpoints, dict) else {}
+        api_url = str(endpoints.get("api") or DEFAULT_API_URL).strip() or DEFAULT_API_URL
+        refresh_in = payload.get("refresh_in")
+        sku = payload.get("sku")
+        return CopilotAPIToken(
+            token=token,
+            expires_at=expires_at,
+            api_url=api_url,
+            refresh_in=int(refresh_in) if isinstance(refresh_in, int | float) else None,
+            sku=str(sku) if isinstance(sku, str) and sku.strip() else None,
+        )
+
+    @staticmethod
+    def _exchange_token_sync(headers: dict[str, str]) -> dict[str, Any]:
+        request = urllib_request.Request(_token_exchange_url(), headers=headers, method="GET")
+        try:
+            with urllib_request.urlopen(request, timeout=10.0) as response:
+                payload = json.loads(response.read().decode("utf-8"))
+                return payload if isinstance(payload, dict) else {}
+        except urllib_error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            raise RuntimeError(
+                f"Copilot token exchange failed with HTTP {exc.code}: {body}"
+            ) from exc
+
+
+_provider: CopilotTokenProvider | None = None
+
+
+def get_copilot_token_provider() -> CopilotTokenProvider:
+    """Return the shared Copilot token provider."""
+
+    global _provider
+    if _provider is None:
+        _provider = CopilotTokenProvider()
+    return _provider
+
+
+async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[str, str]:
+    """Replace Authorization with a fresh Copilot API token when targeting Copilot."""
+
+    resolved = dict(headers)
+    if not is_copilot_api_url(url):
+        return resolved
+
+    token = await get_copilot_token_provider().get_api_token()
+    for key in list(resolved):
+        if key.lower() == "authorization":
+            resolved.pop(key)
+    resolved["Authorization"] = f"Bearer {token.token}"
+    return resolved
diff --git a/headroom/install/health.py b/headroom/install/health.py
index 1b4ae2fed1bd1376a2c61e7cbf94ec6e10cc8c74..9bad174c86c744a9bed54b38af8ee368178101b4 100644
--- a/headroom/install/health.py
+++ b/headroom/install/health.py
@@ -1,28 +1,28 @@
-"""Health helpers for persistent deployments."""
-
-from __future__ import annotations
-
-import json
-import urllib.error
-import urllib.request
-from typing import Any
-
-
-def probe_json(url: str, timeout: float = 2.0) -> dict[str, Any] | None:
-    """Return a JSON payload from the URL when reachable."""
-
-    try:
-        with urllib.request.urlopen(url, timeout=timeout) as response:
-            payload = json.loads(response.read().decode("utf-8"))
-    except (OSError, urllib.error.URLError, ValueError, json.JSONDecodeError):
-        return None
-    return payload if isinstance(payload, dict) else None
-
-
-def probe_ready(url: str, timeout: float = 2.0) -> bool:
-    """Return True when the ready endpoint reports readiness."""
-
-    payload = probe_json(url, timeout=timeout)
-    if not isinstance(payload, dict):
-        return False
-    return bool(payload.get("ready", False) or payload.get("status") == "healthy")
+"""Health helpers for persistent deployments."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+def probe_json(url: str, timeout: float = 2.0) -> dict[str, Any] | None:
+    """Return a JSON payload from the URL when reachable."""
+
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except (OSError, urllib.error.URLError, ValueError, json.JSONDecodeError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def probe_ready(url: str, timeout: float = 2.0) -> bool:
+    """Return True when the ready endpoint reports readiness."""
+
+    payload = probe_json(url, timeout=timeout)
+    if not isinstance(payload, dict):
+        return False
+    return bool(payload.get("ready", False) or payload.get("status") == "healthy")
diff --git a/headroom/install/providers.py b/headroom/install/providers.py
index 5c410d9ba6c6204bb6d267b2a49d52a70c339c87..4ee7c3d6ec624543239110b33a63e3f0de9cd4a4 100644
--- a/headroom/install/providers.py
+++ b/headroom/install/providers.py
@@ -1,174 +1,174 @@
-"""Tool-target configuration for persistent deployments."""
-
-from __future__ import annotations
-
-import os
-import re
-import subprocess
-from pathlib import Path
-
-from headroom.providers.install_registry import (
-    apply_provider_scope_mutations,
-    revert_provider_scope_mutation,
-)
-
-from .models import ConfigScope, DeploymentManifest, ManagedMutation
-from .paths import (
-    unix_system_env_targets,
-    unix_user_env_targets,
-)
-
-_ENV_MARKER_START = "# >>> headroom persistent env >>>"
-_ENV_MARKER_END = "# <<< headroom persistent env <<<"
-_ENV_PATTERN = re.compile(
-    re.escape(_ENV_MARKER_START) + r".*?" + re.escape(_ENV_MARKER_END),
-    re.DOTALL,
-)
-
-
-def _merge_marker_block(file_path: Path, block: str, pattern: re.Pattern[str], marker: str) -> str:
-    if file_path.exists():
-        existing = file_path.read_text()
-        if marker in existing:
-            return pattern.sub(block, existing)
-        return existing.rstrip() + "\n\n" + block + "\n"
-    return block + "\n"
-
-
-def _env_block(values: dict[str, str]) -> str:
-    lines = [_ENV_MARKER_START]
-    for name, value in values.items():
-        lines.append(f'export {name}="{value}"')
-    lines.append(_ENV_MARKER_END)
-    return "\n".join(lines)
-
-
-def _powershell_literal(value: str) -> str:
-    return "'" + value.replace("'", "''") + "'"
-
-
-def _unix_scope_values(manifest: DeploymentManifest) -> dict[str, str]:
-    merged = dict(manifest.base_env)
-    for env_map in manifest.tool_envs.values():
-        merged.update(env_map)
-    return merged
-
-
-def _apply_unix_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:
-    values = _unix_scope_values(manifest)
-    block = _env_block(values)
-    if manifest.scope == ConfigScope.USER.value:
-        targets = unix_user_env_targets()
-    else:
-        targets = unix_system_env_targets()
-    mutations: list[ManagedMutation] = []
-    for path in targets:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        merged = _merge_marker_block(path, block, _ENV_PATTERN, _ENV_MARKER_START)
-        path.write_text(merged)
-        mutations.append(ManagedMutation(target="env", kind="shell-block", path=str(path)))
-    return mutations
-
-
-def _remove_unix_env_scope(mutations: list[ManagedMutation]) -> None:
-    for mutation in mutations:
-        if mutation.kind != "shell-block" or not mutation.path:
-            continue
-        path = Path(mutation.path)
-        if not path.exists():
-            continue
-        content = path.read_text()
-        if _ENV_MARKER_START not in content:
-            continue
-        path.write_text(_ENV_PATTERN.sub("", content).strip() + "\n")
-
-
-def _apply_windows_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:
-    scope_name = "Machine" if manifest.scope == ConfigScope.SYSTEM.value else "User"
-    merged = _unix_scope_values(manifest)
-    mutations: list[ManagedMutation] = []
-    for name, value in merged.items():
-        previous = subprocess.run(
-            [
-                "powershell",
-                "-NoProfile",
-                "-Command",
-                f"$value = [Environment]::GetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(scope_name)}); "
-                "if ($null -eq $value) { '__HEADROOM_UNSET__' } else { $value }",
-            ],
-            capture_output=True,
-            text=True,
-            check=True,
-        ).stdout.strip()
-        command = [
-            "powershell",
-            "-NoProfile",
-            "-Command",
-            f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(value)},{_powershell_literal(scope_name)})",
-        ]
-        subprocess.run(command, check=True)
-        mutations.append(
-            ManagedMutation(
-                target="env",
-                kind="windows-env",
-                data={
-                    "name": name,
-                    "scope": scope_name,
-                    "previous": None if previous == "__HEADROOM_UNSET__" else previous,
-                },
-            )
-        )
-    return mutations
-
-
-def _remove_windows_env_scope(mutations: list[ManagedMutation]) -> None:
-    for mutation in mutations:
-        if mutation.kind != "windows-env":
-            continue
-        name = mutation.data.get("name")
-        if not isinstance(name, str):
-            raise ValueError("Windows environment mutation is missing a variable name")
-        scope_name = mutation.data.get("scope", "User")
-        if not isinstance(scope_name, str):
-            raise ValueError("Windows environment mutation is missing a valid scope")
-        previous = mutation.data.get("previous")
-        if previous is None:
-            value_literal = "$null"
-        else:
-            value_literal = _powershell_literal(previous)
-        command = [
-            "powershell",
-            "-NoProfile",
-            "-Command",
-            f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{value_literal},{_powershell_literal(scope_name)})",
-        ]
-        subprocess.run(command, check=True)
-
-
-def apply_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
-    """Apply provider/user/system configuration for a deployment."""
-
-    mutations: list[ManagedMutation] = []
-    if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:
-        if os.name == "nt":
-            mutations.extend(_apply_windows_env_scope(manifest))
-        else:
-            mutations.extend(_apply_unix_env_scope(manifest))
-        mutations.extend(apply_provider_scope_mutations(manifest))
-        return mutations
-
-    return [*mutations, *apply_provider_scope_mutations(manifest)]
-
-
-def revert_mutations(manifest: DeploymentManifest) -> None:
-    """Undo the stored mutations for a deployment."""
-
-    if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:
-        shell_mutations = [m for m in manifest.mutations if m.target == "env"]
-        if os.name == "nt":
-            _remove_windows_env_scope(shell_mutations)
-        else:
-            _remove_unix_env_scope(shell_mutations)
-
-    for mutation in manifest.mutations:
-        revert_provider_scope_mutation(manifest, mutation)
+"""Tool-target configuration for persistent deployments."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from headroom.providers.install_registry import (
+    apply_provider_scope_mutations,
+    revert_provider_scope_mutation,
+)
+
+from .models import ConfigScope, DeploymentManifest, ManagedMutation
+from .paths import (
+    unix_system_env_targets,
+    unix_user_env_targets,
+)
+
+_ENV_MARKER_START = "# >>> headroom persistent env >>>"
+_ENV_MARKER_END = "# <<< headroom persistent env <<<"
+_ENV_PATTERN = re.compile(
+    re.escape(_ENV_MARKER_START) + r".*?" + re.escape(_ENV_MARKER_END),
+    re.DOTALL,
+)
+
+
+def _merge_marker_block(file_path: Path, block: str, pattern: re.Pattern[str], marker: str) -> str:
+    if file_path.exists():
+        existing = file_path.read_text()
+        if marker in existing:
+            return pattern.sub(block, existing)
+        return existing.rstrip() + "\n\n" + block + "\n"
+    return block + "\n"
+
+
+def _env_block(values: dict[str, str]) -> str:
+    lines = [_ENV_MARKER_START]
+    for name, value in values.items():
+        lines.append(f'export {name}="{value}"')
+    lines.append(_ENV_MARKER_END)
+    return "\n".join(lines)
+
+
+def _powershell_literal(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def _unix_scope_values(manifest: DeploymentManifest) -> dict[str, str]:
+    merged = dict(manifest.base_env)
+    for env_map in manifest.tool_envs.values():
+        merged.update(env_map)
+    return merged
+
+
+def _apply_unix_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:
+    values = _unix_scope_values(manifest)
+    block = _env_block(values)
+    if manifest.scope == ConfigScope.USER.value:
+        targets = unix_user_env_targets()
+    else:
+        targets = unix_system_env_targets()
+    mutations: list[ManagedMutation] = []
+    for path in targets:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        merged = _merge_marker_block(path, block, _ENV_PATTERN, _ENV_MARKER_START)
+        path.write_text(merged)
+        mutations.append(ManagedMutation(target="env", kind="shell-block", path=str(path)))
+    return mutations
+
+
+def _remove_unix_env_scope(mutations: list[ManagedMutation]) -> None:
+    for mutation in mutations:
+        if mutation.kind != "shell-block" or not mutation.path:
+            continue
+        path = Path(mutation.path)
+        if not path.exists():
+            continue
+        content = path.read_text()
+        if _ENV_MARKER_START not in content:
+            continue
+        path.write_text(_ENV_PATTERN.sub("", content).strip() + "\n")
+
+
+def _apply_windows_env_scope(manifest: DeploymentManifest) -> list[ManagedMutation]:
+    scope_name = "Machine" if manifest.scope == ConfigScope.SYSTEM.value else "User"
+    merged = _unix_scope_values(manifest)
+    mutations: list[ManagedMutation] = []
+    for name, value in merged.items():
+        previous = subprocess.run(
+            [
+                "powershell",
+                "-NoProfile",
+                "-Command",
+                f"$value = [Environment]::GetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(scope_name)}); "
+                "if ($null -eq $value) { '__HEADROOM_UNSET__' } else { $value }",
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        command = [
+            "powershell",
+            "-NoProfile",
+            "-Command",
+            f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{_powershell_literal(value)},{_powershell_literal(scope_name)})",
+        ]
+        subprocess.run(command, check=True)
+        mutations.append(
+            ManagedMutation(
+                target="env",
+                kind="windows-env",
+                data={
+                    "name": name,
+                    "scope": scope_name,
+                    "previous": None if previous == "__HEADROOM_UNSET__" else previous,
+                },
+            )
+        )
+    return mutations
+
+
+def _remove_windows_env_scope(mutations: list[ManagedMutation]) -> None:
+    for mutation in mutations:
+        if mutation.kind != "windows-env":
+            continue
+        name = mutation.data.get("name")
+        if not isinstance(name, str):
+            raise ValueError("Windows environment mutation is missing a variable name")
+        scope_name = mutation.data.get("scope", "User")
+        if not isinstance(scope_name, str):
+            raise ValueError("Windows environment mutation is missing a valid scope")
+        previous = mutation.data.get("previous")
+        if previous is None:
+            value_literal = "$null"
+        else:
+            value_literal = _powershell_literal(previous)
+        command = [
+            "powershell",
+            "-NoProfile",
+            "-Command",
+            f"[Environment]::SetEnvironmentVariable({_powershell_literal(name)},{value_literal},{_powershell_literal(scope_name)})",
+        ]
+        subprocess.run(command, check=True)
+
+
+def apply_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
+    """Apply provider/user/system configuration for a deployment."""
+
+    mutations: list[ManagedMutation] = []
+    if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:
+        if os.name == "nt":
+            mutations.extend(_apply_windows_env_scope(manifest))
+        else:
+            mutations.extend(_apply_unix_env_scope(manifest))
+        mutations.extend(apply_provider_scope_mutations(manifest))
+        return mutations
+
+    return [*mutations, *apply_provider_scope_mutations(manifest)]
+
+
+def revert_mutations(manifest: DeploymentManifest) -> None:
+    """Undo the stored mutations for a deployment."""
+
+    if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:
+        shell_mutations = [m for m in manifest.mutations if m.target == "env"]
+        if os.name == "nt":
+            _remove_windows_env_scope(shell_mutations)
+        else:
+            _remove_unix_env_scope(shell_mutations)
+
+    for mutation in manifest.mutations:
+        revert_provider_scope_mutation(manifest, mutation)
diff --git a/headroom/install/runtime.py b/headroom/install/runtime.py
index de7cb8fcdc1874f6fc68fe7a64fdf8c2095cde52..d285197c6e0a696e22f26483f30113ef3b9d6b35 100644
--- a/headroom/install/runtime.py
+++ b/headroom/install/runtime.py
@@ -1,279 +1,279 @@
-"""Runtime helpers for persistent deployments."""
-
-from __future__ import annotations
-
-import os
-import shutil
-import signal
-import subprocess
-import sys
-import time
-from pathlib import Path
-from typing import Any
-
-from .health import probe_ready
-from .models import DeploymentManifest, InstallPreset, RuntimeKind
-from .paths import log_path, pid_path
-
-PASSTHROUGH_ENV_PREFIXES = (
-    "HEADROOM_",
-    "ANTHROPIC_",
-    "OPENAI_",
-    "GEMINI_",
-    "AWS_",
-    "AZURE_",
-    "VERTEX_",
-    "GOOGLE_",
-    "GOOGLE_CLOUD_",
-    "MISTRAL_",
-    "GROQ_",
-    "OPENROUTER_",
-    "XAI_",
-    "TOGETHER_",
-    "COHERE_",
-    "OLLAMA_",
-    "LITELLM_",
-    "OTEL_",
-    "SUPABASE_",
-    "QDRANT_",
-    "NEO4J_",
-    "LANGSMITH_",
-)
-
-
-def _is_windows() -> bool:
-    return sys.platform.startswith("win")
-
-
-def _deployment_env(manifest: DeploymentManifest) -> dict[str, str]:
-    return {
-        "HEADROOM_DEPLOYMENT_PROFILE": manifest.profile,
-        "HEADROOM_DEPLOYMENT_PRESET": manifest.preset,
-        "HEADROOM_DEPLOYMENT_RUNTIME": manifest.runtime_kind,
-        "HEADROOM_DEPLOYMENT_SUPERVISOR": manifest.supervisor_kind,
-        "HEADROOM_DEPLOYMENT_SCOPE": manifest.scope,
-    }
-
-
-def resolve_headroom_command() -> list[str]:
-    """Resolve the most reliable command to invoke headroom."""
-
-    headroom_bin = shutil.which("headroom")
-    if headroom_bin:
-        return [headroom_bin]
-    return [sys.executable, "-m", "headroom.cli"]
-
-
-def _runtime_env(manifest: DeploymentManifest) -> dict[str, str]:
-    env = os.environ.copy()
-    env.update(manifest.base_env)
-    env.update(_deployment_env(manifest))
-    return env
-
-
-def _ensure_host_dirs() -> None:
-    for subdir in (".headroom", ".claude", ".codex", ".gemini"):
-        (Path.home() / subdir).mkdir(parents=True, exist_ok=True)
-
-
-def _mount_source(home: str, subdir: str) -> str:
-    if _is_windows():
-        return f"{home}\\{subdir}"
-    return f"{home}/{subdir}"
-
-
-def build_runtime_command(manifest: DeploymentManifest) -> list[str]:
-    """Build the raw foreground command that runs the proxy."""
-
-    if manifest.runtime_kind == RuntimeKind.PYTHON.value:
-        return [sys.executable, "-m", "headroom.cli", "proxy", *manifest.proxy_args]
-
-    _ensure_host_dirs()
-    home = str(Path.home())
-    container_home = "/tmp/headroom-home"
-    command = [
-        "docker",
-        "run",
-        "--rm",
-        "--name",
-        manifest.container_name,
-        "-p",
-        f"127.0.0.1:{manifest.port}:{manifest.port}",
-        "--workdir",
-        container_home,
-        "--env",
-        f"HOME={container_home}",
-        "--env",
-        "PYTHONUNBUFFERED=1",
-        # Canonical Headroom filesystem contract (issue #175).
-        "--env",
-        f"HEADROOM_WORKSPACE_DIR={container_home}/.headroom",
-        "--env",
-        f"HEADROOM_CONFIG_DIR={container_home}/.headroom/config",
-        "--volume",
-        f"{_mount_source(home, '.headroom')}:{container_home}/.headroom",
-        "--volume",
-        f"{_mount_source(home, '.claude')}:{container_home}/.claude",
-        "--volume",
-        f"{_mount_source(home, '.codex')}:{container_home}/.codex",
-        "--volume",
-        f"{_mount_source(home, '.gemini')}:{container_home}/.gemini",
-    ]
-    if not _is_windows():
-        getuid = getattr(os, "getuid", None)
-        getgid = getattr(os, "getgid", None)
-        if callable(getuid) and callable(getgid):
-            command.extend(["--user", f"{getuid()}:{getgid()}"])
-    runtime_env = {**manifest.base_env, **_deployment_env(manifest)}
-    for name, value in runtime_env.items():
-        command.extend(["--env", f"{name}={value}"])
-    for name in sorted(os.environ):
-        if name.startswith(PASSTHROUGH_ENV_PREFIXES):
-            command.extend(["--env", name])
-    command.extend(
-        [
-            manifest.image,
-            "headroom",
-            "proxy",
-            "--host",
-            "0.0.0.0",
-            *manifest.proxy_args[2:],
-        ]
-    )
-    return command
-
-
-def _write_pid(profile: str, pid: int) -> None:
-    path = pid_path(profile)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(str(pid))
-
-
-def _read_pid(profile: str) -> int | None:
-    path = pid_path(profile)
-    if not path.exists():
-        return None
-    try:
-        return int(path.read_text().strip())
-    except ValueError:
-        return None
-
-
-def _clear_pid(profile: str) -> None:
-    path = pid_path(profile)
-    if path.exists():
-        path.unlink()
-
-
-def run_foreground(manifest: DeploymentManifest) -> int:
-    """Run the raw runtime command in the foreground."""
-
-    command = build_runtime_command(manifest)
-    env = _runtime_env(manifest)
-    log_file_path = log_path(manifest.profile)
-    log_file_path.parent.mkdir(parents=True, exist_ok=True)
-
-    with open(log_file_path, "a", encoding="utf-8", errors="replace") as log_file:
-        proc = subprocess.Popen(command, env=env, stdout=log_file, stderr=log_file)
-        _write_pid(manifest.profile, proc.pid)
-
-        def _cleanup(signum: int | None = None, frame: Any = None) -> None:
-            if proc.poll() is None:
-                proc.terminate()
-                try:
-                    proc.wait(timeout=10)
-                except subprocess.TimeoutExpired:
-                    proc.kill()
-
-        signal.signal(signal.SIGINT, _cleanup)
-        signal.signal(signal.SIGTERM, _cleanup)
-        try:
-            return proc.wait()
-        finally:
-            _clear_pid(manifest.profile)
-
-
-def start_detached_agent(profile: str) -> subprocess.Popen[str]:
-    """Start `headroom install agent run` detached for the given profile."""
-
-    command = [*resolve_headroom_command(), "install", "agent", "run", "--profile", profile]
-    log_file_path = log_path(profile)
-    log_file_path.parent.mkdir(parents=True, exist_ok=True)
-    log_file = open(log_file_path, "a", encoding="utf-8", errors="replace")  # noqa: SIM115
-
-    kwargs: dict[str, Any] = {"stdout": log_file, "stderr": log_file}
-    if _is_windows():
-        kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(
-            subprocess, "CREATE_NEW_PROCESS_GROUP", 0
-        )
-    else:
-        kwargs["start_new_session"] = True
-    return subprocess.Popen(command, **kwargs)
-
-
-def start_persistent_docker(manifest: DeploymentManifest) -> None:
-    """Start a persistent Docker container with restart policy."""
-
-    command = build_runtime_command(manifest)
-    docker_cmd = [
-        "docker",
-        "run",
-        "-d",
-        "--restart",
-        "unless-stopped",
-        "--name",
-        manifest.container_name,
-        *command[5:],  # drop initial `docker run --rm --name ...`
-    ]
-    subprocess.run(["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True)
-    subprocess.run(docker_cmd, check=True)
-
-
-def stop_runtime(manifest: DeploymentManifest) -> None:
-    """Stop the raw runtime for the deployment."""
-
-    if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
-        subprocess.run(["docker", "stop", manifest.container_name], capture_output=True, text=True)
-        subprocess.run(
-            ["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True
-        )
-        return
-
-    pid = _read_pid(manifest.profile)
-    if pid is None:
-        return
-    try:
-        os.kill(pid, signal.SIGTERM)
-    except OSError:
-        pass
-    _clear_pid(manifest.profile)
-
-
-def wait_ready(manifest: DeploymentManifest, timeout_seconds: int = 30) -> bool:
-    """Wait for the deployment to report ready."""
-
-    for _ in range(timeout_seconds):
-        if probe_ready(manifest.health_url):
-            return True
-        time.sleep(1)
-    return False
-
-
-def runtime_status(manifest: DeploymentManifest) -> str:
-    """Return a short status string for the deployment runtime."""
-
-    if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
-        result = subprocess.run(
-            ["docker", "ps", "--format", "{{.Names}}"], capture_output=True, text=True
-        )
-        if manifest.container_name in result.stdout.splitlines():
-            return "running"
-        return "stopped"
-    pid = _read_pid(manifest.profile)
-    if pid is None:
-        return "stopped"
-    try:
-        os.kill(pid, 0)
-    except OSError:
-        return "stopped"
-    return "running"
+"""Runtime helpers for persistent deployments."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from .health import probe_ready
+from .models import DeploymentManifest, InstallPreset, RuntimeKind
+from .paths import log_path, pid_path
+
+PASSTHROUGH_ENV_PREFIXES = (
+    "HEADROOM_",
+    "ANTHROPIC_",
+    "OPENAI_",
+    "GEMINI_",
+    "AWS_",
+    "AZURE_",
+    "VERTEX_",
+    "GOOGLE_",
+    "GOOGLE_CLOUD_",
+    "MISTRAL_",
+    "GROQ_",
+    "OPENROUTER_",
+    "XAI_",
+    "TOGETHER_",
+    "COHERE_",
+    "OLLAMA_",
+    "LITELLM_",
+    "OTEL_",
+    "SUPABASE_",
+    "QDRANT_",
+    "NEO4J_",
+    "LANGSMITH_",
+)
+
+
+def _is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
+def _deployment_env(manifest: DeploymentManifest) -> dict[str, str]:
+    return {
+        "HEADROOM_DEPLOYMENT_PROFILE": manifest.profile,
+        "HEADROOM_DEPLOYMENT_PRESET": manifest.preset,
+        "HEADROOM_DEPLOYMENT_RUNTIME": manifest.runtime_kind,
+        "HEADROOM_DEPLOYMENT_SUPERVISOR": manifest.supervisor_kind,
+        "HEADROOM_DEPLOYMENT_SCOPE": manifest.scope,
+    }
+
+
+def resolve_headroom_command() -> list[str]:
+    """Resolve the most reliable command to invoke headroom."""
+
+    headroom_bin = shutil.which("headroom")
+    if headroom_bin:
+        return [headroom_bin]
+    return [sys.executable, "-m", "headroom.cli"]
+
+
+def _runtime_env(manifest: DeploymentManifest) -> dict[str, str]:
+    env = os.environ.copy()
+    env.update(manifest.base_env)
+    env.update(_deployment_env(manifest))
+    return env
+
+
+def _ensure_host_dirs() -> None:
+    for subdir in (".headroom", ".claude", ".codex", ".gemini"):
+        (Path.home() / subdir).mkdir(parents=True, exist_ok=True)
+
+
+def _mount_source(home: str, subdir: str) -> str:
+    if _is_windows():
+        return f"{home}\\{subdir}"
+    return f"{home}/{subdir}"
+
+
+def build_runtime_command(manifest: DeploymentManifest) -> list[str]:
+    """Build the raw foreground command that runs the proxy."""
+
+    if manifest.runtime_kind == RuntimeKind.PYTHON.value:
+        return [sys.executable, "-m", "headroom.cli", "proxy", *manifest.proxy_args]
+
+    _ensure_host_dirs()
+    home = str(Path.home())
+    container_home = "/tmp/headroom-home"
+    command = [
+        "docker",
+        "run",
+        "--rm",
+        "--name",
+        manifest.container_name,
+        "-p",
+        f"127.0.0.1:{manifest.port}:{manifest.port}",
+        "--workdir",
+        container_home,
+        "--env",
+        f"HOME={container_home}",
+        "--env",
+        "PYTHONUNBUFFERED=1",
+        # Canonical Headroom filesystem contract (issue #175).
+        "--env",
+        f"HEADROOM_WORKSPACE_DIR={container_home}/.headroom",
+        "--env",
+        f"HEADROOM_CONFIG_DIR={container_home}/.headroom/config",
+        "--volume",
+        f"{_mount_source(home, '.headroom')}:{container_home}/.headroom",
+        "--volume",
+        f"{_mount_source(home, '.claude')}:{container_home}/.claude",
+        "--volume",
+        f"{_mount_source(home, '.codex')}:{container_home}/.codex",
+        "--volume",
+        f"{_mount_source(home, '.gemini')}:{container_home}/.gemini",
+    ]
+    if not _is_windows():
+        getuid = getattr(os, "getuid", None)
+        getgid = getattr(os, "getgid", None)
+        if callable(getuid) and callable(getgid):
+            command.extend(["--user", f"{getuid()}:{getgid()}"])
+    runtime_env = {**manifest.base_env, **_deployment_env(manifest)}
+    for name, value in runtime_env.items():
+        command.extend(["--env", f"{name}={value}"])
+    for name in sorted(os.environ):
+        if name.startswith(PASSTHROUGH_ENV_PREFIXES):
+            command.extend(["--env", name])
+    command.extend(
+        [
+            manifest.image,
+            "headroom",
+            "proxy",
+            "--host",
+            "0.0.0.0",
+            *manifest.proxy_args[2:],
+        ]
+    )
+    return command
+
+
+def _write_pid(profile: str, pid: int) -> None:
+    path = pid_path(profile)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(str(pid))
+
+
+def _read_pid(profile: str) -> int | None:
+    path = pid_path(profile)
+    if not path.exists():
+        return None
+    try:
+        return int(path.read_text().strip())
+    except ValueError:
+        return None
+
+
+def _clear_pid(profile: str) -> None:
+    path = pid_path(profile)
+    if path.exists():
+        path.unlink()
+
+
+def run_foreground(manifest: DeploymentManifest) -> int:
+    """Run the raw runtime command in the foreground."""
+
+    command = build_runtime_command(manifest)
+    env = _runtime_env(manifest)
+    log_file_path = log_path(manifest.profile)
+    log_file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(log_file_path, "a", encoding="utf-8", errors="replace") as log_file:
+        proc = subprocess.Popen(command, env=env, stdout=log_file, stderr=log_file)
+        _write_pid(manifest.profile, proc.pid)
+
+        def _cleanup(signum: int | None = None, frame: Any = None) -> None:
+            if proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=10)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+
+        signal.signal(signal.SIGINT, _cleanup)
+        signal.signal(signal.SIGTERM, _cleanup)
+        try:
+            return proc.wait()
+        finally:
+            _clear_pid(manifest.profile)
+
+
+def start_detached_agent(profile: str) -> subprocess.Popen[str]:
+    """Start `headroom install agent run` detached for the given profile."""
+
+    command = [*resolve_headroom_command(), "install", "agent", "run", "--profile", profile]
+    log_file_path = log_path(profile)
+    log_file_path.parent.mkdir(parents=True, exist_ok=True)
+    log_file = open(log_file_path, "a", encoding="utf-8", errors="replace")  # noqa: SIM115
+
+    kwargs: dict[str, Any] = {"stdout": log_file, "stderr": log_file}
+    if _is_windows():
+        kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(
+            subprocess, "CREATE_NEW_PROCESS_GROUP", 0
+        )
+    else:
+        kwargs["start_new_session"] = True
+    return subprocess.Popen(command, **kwargs)
+
+
+def start_persistent_docker(manifest: DeploymentManifest) -> None:
+    """Start a persistent Docker container with restart policy."""
+
+    command = build_runtime_command(manifest)
+    docker_cmd = [
+        "docker",
+        "run",
+        "-d",
+        "--restart",
+        "unless-stopped",
+        "--name",
+        manifest.container_name,
+        *command[5:],  # drop initial `docker run --rm --name ...`
+    ]
+    subprocess.run(["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True)
+    subprocess.run(docker_cmd, check=True)
+
+
+def stop_runtime(manifest: DeploymentManifest) -> None:
+    """Stop the raw runtime for the deployment."""
+
+    if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
+        subprocess.run(["docker", "stop", manifest.container_name], capture_output=True, text=True)
+        subprocess.run(
+            ["docker", "rm", "-f", manifest.container_name], capture_output=True, text=True
+        )
+        return
+
+    pid = _read_pid(manifest.profile)
+    if pid is None:
+        return
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except OSError:
+        pass
+    _clear_pid(manifest.profile)
+
+
+def wait_ready(manifest: DeploymentManifest, timeout_seconds: int = 30) -> bool:
+    """Wait for the deployment to report ready."""
+
+    for _ in range(timeout_seconds):
+        if probe_ready(manifest.health_url):
+            return True
+        time.sleep(1)
+    return False
+
+
+def runtime_status(manifest: DeploymentManifest) -> str:
+    """Return a short status string for the deployment runtime."""
+
+    if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value:
+        result = subprocess.run(
+            ["docker", "ps", "--format", "{{.Names}}"], capture_output=True, text=True
+        )
+        if manifest.container_name in result.stdout.splitlines():
+            return "running"
+        return "stopped"
+    pid = _read_pid(manifest.profile)
+    if pid is None:
+        return "stopped"
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return "stopped"
+    return "running"
diff --git a/headroom/providers/aider/install.py b/headroom/providers/aider/install.py
index ceb326129745e125827a4b3bf45f860aacf7f707..5e177d1c1398881adc13ef334f05d67e3fafe6c9 100644
--- a/headroom/providers/aider/install.py
+++ b/headroom/providers/aider/install.py
@@ -1,12 +1,12 @@
-"""Aider install-time helpers."""
-
-from __future__ import annotations
-
-from .runtime import build_launch_env
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Aider."""
-    del backend
-    env, _lines = build_launch_env(port=port, environ={})
-    return {key: env[key] for key in ("OPENAI_API_BASE", "ANTHROPIC_BASE_URL")}
+"""Aider install-time helpers."""
+
+from __future__ import annotations
+
+from .runtime import build_launch_env
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Aider."""
+    del backend
+    env, _lines = build_launch_env(port=port, environ={})
+    return {key: env[key] for key in ("OPENAI_API_BASE", "ANTHROPIC_BASE_URL")}
diff --git a/headroom/providers/claude/install.py b/headroom/providers/claude/install.py
index db5d03059603f55bf96d8d4d0fdae1793729e6cf..97f166018aa75979e474adaf485bf9e7dbebb29e 100644
--- a/headroom/providers/claude/install.py
+++ b/headroom/providers/claude/install.py
@@ -1,63 +1,63 @@
-"""Claude install-time helpers."""
-
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget
-from headroom.install.paths import claude_settings_path
-
-from .runtime import proxy_base_url
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Claude."""
-    del backend
-    return {"ANTHROPIC_BASE_URL": proxy_base_url(port)}
-
-
-def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:
-    """Apply Claude provider-scope configuration when requested."""
-    if manifest.scope != ConfigScope.PROVIDER.value:
-        return None
-
-    path = claude_settings_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    payload: dict[str, object] = {}
-    if path.exists():
-        payload = json.loads(path.read_text())
-    env = payload.get("env")
-    env_map = dict(env) if isinstance(env, dict) else {}
-    values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})
-    previous = {name: env_map.get(name) for name in values}
-    env_map.update(values)
-    payload["env"] = env_map
-    path.write_text(json.dumps(payload, indent=2) + "\n")
-    return ManagedMutation(
-        target=ToolTarget.CLAUDE.value,
-        kind="json-env",
-        path=str(path),
-        data={"previous": previous},
-    )
-
-
-def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
-    """Revert Claude provider-scope configuration."""
-    if not mutation.path:
-        return
-    path = Path(mutation.path)
-    if not path.exists():
-        return
-    payload = json.loads(path.read_text())
-    env = payload.get("env")
-    env_map = dict(env) if isinstance(env, dict) else {}
-    previous: dict[str, object] = mutation.data.get("previous", {})
-    values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})
-    for name in values:
-        if previous.get(name) is None:
-            env_map.pop(name, None)
-        else:
-            env_map[name] = previous[name]
-    payload["env"] = env_map
-    path.write_text(json.dumps(payload, indent=2) + "\n")
+"""Claude install-time helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget
+from headroom.install.paths import claude_settings_path
+
+from .runtime import proxy_base_url
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Claude."""
+    del backend
+    return {"ANTHROPIC_BASE_URL": proxy_base_url(port)}
+
+
+def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:
+    """Apply Claude provider-scope configuration when requested."""
+    if manifest.scope != ConfigScope.PROVIDER.value:
+        return None
+
+    path = claude_settings_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload: dict[str, object] = {}
+    if path.exists():
+        payload = json.loads(path.read_text())
+    env = payload.get("env")
+    env_map = dict(env) if isinstance(env, dict) else {}
+    values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})
+    previous = {name: env_map.get(name) for name in values}
+    env_map.update(values)
+    payload["env"] = env_map
+    path.write_text(json.dumps(payload, indent=2) + "\n")
+    return ManagedMutation(
+        target=ToolTarget.CLAUDE.value,
+        kind="json-env",
+        path=str(path),
+        data={"previous": previous},
+    )
+
+
+def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
+    """Revert Claude provider-scope configuration."""
+    if not mutation.path:
+        return
+    path = Path(mutation.path)
+    if not path.exists():
+        return
+    payload = json.loads(path.read_text())
+    env = payload.get("env")
+    env_map = dict(env) if isinstance(env, dict) else {}
+    previous: dict[str, object] = mutation.data.get("previous", {})
+    values = manifest.tool_envs.get(ToolTarget.CLAUDE.value, {})
+    for name in values:
+        if previous.get(name) is None:
+            env_map.pop(name, None)
+        else:
+            env_map[name] = previous[name]
+    payload["env"] = env_map
+    path.write_text(json.dumps(payload, indent=2) + "\n")
diff --git a/headroom/providers/codex/install.py b/headroom/providers/codex/install.py
index 0bdbbbc20abf5c69615f3dafff856e79270964ae..b8f71860221c66c2b769f268ddd106d922c4fc9a 100644
--- a/headroom/providers/codex/install.py
+++ b/headroom/providers/codex/install.py
@@ -1,68 +1,68 @@
-"""Codex install-time helpers."""
-
-from __future__ import annotations
-
-import re
-from pathlib import Path
-
-from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget
-from headroom.install.paths import codex_config_path
-
-from .runtime import proxy_base_url
-
-_CODEX_MARKER_START = "# --- Headroom persistent provider ---"
-_CODEX_MARKER_END = "# --- end Headroom persistent provider ---"
-_CODEX_PATTERN = re.compile(
-    re.escape(_CODEX_MARKER_START) + r".*?" + re.escape(_CODEX_MARKER_END),
-    re.DOTALL,
-)
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Codex."""
-    del backend
-    return {"OPENAI_BASE_URL": proxy_base_url(port)}
-
-
-def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:
-    """Apply Codex provider-scope configuration when requested."""
-    if manifest.scope != ConfigScope.PROVIDER.value:
-        return None
-
-    path = codex_config_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    section = (
-        f"{_CODEX_MARKER_START}\n"
-        'model_provider = "headroom"\n\n'
-        "[model_providers.headroom]\n"
-        'name = "Headroom persistent proxy"\n'
-        f'base_url = "{proxy_base_url(manifest.port)}"\n'
-        'env_key = "OPENAI_API_KEY"\n'
-        "requires_openai_auth = true\n"
-        "supports_websockets = true\n"
-        f"{_CODEX_MARKER_END}\n"
-    )
-    if path.exists():
-        existing = path.read_text()
-        if _CODEX_MARKER_START in existing:
-            merged = _CODEX_PATTERN.sub(section, existing)
-        else:
-            merged = existing.rstrip() + "\n\n" + section + "\n"
-    else:
-        merged = section + "\n"
-    path.write_text(merged)
-    return ManagedMutation(target=ToolTarget.CODEX.value, kind="toml-block", path=str(path))
-
-
-def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
-    """Revert Codex provider-scope configuration."""
-    del manifest
-    if not mutation.path:
-        return
-    path = Path(mutation.path)
-    if not path.exists():
-        return
-    content = path.read_text()
-    if _CODEX_MARKER_START not in content:
-        return
-    path.write_text(_CODEX_PATTERN.sub("", content).strip() + "\n")
+"""Codex install-time helpers."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTarget
+from headroom.install.paths import codex_config_path
+
+from .runtime import proxy_base_url
+
+_CODEX_MARKER_START = "# --- Headroom persistent provider ---"
+_CODEX_MARKER_END = "# --- end Headroom persistent provider ---"
+_CODEX_PATTERN = re.compile(
+    re.escape(_CODEX_MARKER_START) + r".*?" + re.escape(_CODEX_MARKER_END),
+    re.DOTALL,
+)
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Codex."""
+    del backend
+    return {"OPENAI_BASE_URL": proxy_base_url(port)}
+
+
+def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:
+    """Apply Codex provider-scope configuration when requested."""
+    if manifest.scope != ConfigScope.PROVIDER.value:
+        return None
+
+    path = codex_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    section = (
+        f"{_CODEX_MARKER_START}\n"
+        'model_provider = "headroom"\n\n'
+        "[model_providers.headroom]\n"
+        'name = "Headroom persistent proxy"\n'
+        f'base_url = "{proxy_base_url(manifest.port)}"\n'
+        'env_key = "OPENAI_API_KEY"\n'
+        "requires_openai_auth = true\n"
+        "supports_websockets = true\n"
+        f"{_CODEX_MARKER_END}\n"
+    )
+    if path.exists():
+        existing = path.read_text()
+        if _CODEX_MARKER_START in existing:
+            merged = _CODEX_PATTERN.sub(section, existing)
+        else:
+            merged = existing.rstrip() + "\n\n" + section + "\n"
+    else:
+        merged = section + "\n"
+    path.write_text(merged)
+    return ManagedMutation(target=ToolTarget.CODEX.value, kind="toml-block", path=str(path))
+
+
+def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
+    """Revert Codex provider-scope configuration."""
+    del manifest
+    if not mutation.path:
+        return
+    path = Path(mutation.path)
+    if not path.exists():
+        return
+    content = path.read_text()
+    if _CODEX_MARKER_START not in content:
+        return
+    path.write_text(_CODEX_PATTERN.sub("", content).strip() + "\n")
diff --git a/headroom/providers/copilot/install.py b/headroom/providers/copilot/install.py
index 5b0df8e3216f3b1c0a3ab8bcdebfe0b65f8bf9f9..24c7ec941fc23a98598b926ef3e6a3a9cef3c6a7 100644
--- a/headroom/providers/copilot/install.py
+++ b/headroom/providers/copilot/install.py
@@ -1,25 +1,25 @@
-"""Copilot install-time helpers."""
-
-from __future__ import annotations
-
-from .wrap import build_launch_env, resolve_provider_type
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Copilot."""
-    provider_type = resolve_provider_type(backend, "auto", {"HEADROOM_BACKEND": backend})
-    env, _lines = build_launch_env(
-        port=port,
-        provider_type=provider_type,
-        wire_api=None,
-        environ={},
-    )
-    return {
-        key: env[key]
-        for key in (
-            "COPILOT_PROVIDER_TYPE",
-            "COPILOT_PROVIDER_BASE_URL",
-            "COPILOT_PROVIDER_WIRE_API",
-        )
-        if key in env
-    }
+"""Copilot install-time helpers."""
+
+from __future__ import annotations
+
+from .wrap import build_launch_env, resolve_provider_type
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Copilot."""
+    provider_type = resolve_provider_type(backend, "auto", {"HEADROOM_BACKEND": backend})
+    env, _lines = build_launch_env(
+        port=port,
+        provider_type=provider_type,
+        wire_api=None,
+        environ={},
+    )
+    return {
+        key: env[key]
+        for key in (
+            "COPILOT_PROVIDER_TYPE",
+            "COPILOT_PROVIDER_BASE_URL",
+            "COPILOT_PROVIDER_WIRE_API",
+        )
+        if key in env
+    }
diff --git a/headroom/providers/cursor/install.py b/headroom/providers/cursor/install.py
index 6724f496ffb01136a17f835c83d19172b49dacf1..181fcbdf0a0cf1c5a4b0d2c80bdce21fd2d533ae 100644
--- a/headroom/providers/cursor/install.py
+++ b/headroom/providers/cursor/install.py
@@ -1,15 +1,15 @@
-"""Cursor install-time helpers."""
-
-from __future__ import annotations
-
-from .runtime import build_proxy_targets
-
-
-def build_install_env(*, port: int, backend: str) -> dict[str, str]:
-    """Build the persistent install environment for Cursor."""
-    del backend
-    targets = build_proxy_targets(port)
-    return {
-        "OPENAI_BASE_URL": targets.openai_base_url,
-        "ANTHROPIC_BASE_URL": targets.anthropic_base_url,
-    }
+"""Cursor install-time helpers."""
+
+from __future__ import annotations
+
+from .runtime import build_proxy_targets
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+    """Build the persistent install environment for Cursor."""
+    del backend
+    targets = build_proxy_targets(port)
+    return {
+        "OPENAI_BASE_URL": targets.openai_base_url,
+        "ANTHROPIC_BASE_URL": targets.anthropic_base_url,
+    }
diff --git a/headroom/providers/install_registry.py b/headroom/providers/install_registry.py
index 4160466559fc1b5c20bd85b9aec92bc03892e82e..99526435e552e395b8514132d5a47be782185d92 100644
--- a/headroom/providers/install_registry.py
+++ b/headroom/providers/install_registry.py
@@ -1,86 +1,86 @@
-"""Install-time provider registry helpers."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-
-from headroom.install.models import DeploymentManifest, ManagedMutation
-from headroom.providers.aider.install import build_install_env as _build_aider_install_env
-from headroom.providers.claude.install import (
-    apply_provider_scope as _apply_claude_provider_scope,
-)
-from headroom.providers.claude.install import (
-    build_install_env as _build_claude_install_env,
-)
-from headroom.providers.claude.install import (
-    revert_provider_scope as _revert_claude_provider_scope,
-)
-from headroom.providers.codex.install import (
-    apply_provider_scope as _apply_codex_provider_scope,
-)
-from headroom.providers.codex.install import build_install_env as _build_codex_install_env
-from headroom.providers.codex.install import (
-    revert_provider_scope as _revert_codex_provider_scope,
-)
-from headroom.providers.copilot.install import (
-    build_install_env as _build_copilot_install_env,
-)
-from headroom.providers.cursor.install import build_install_env as _build_cursor_install_env
-from headroom.providers.openclaw.install import (
-    apply_provider_scope as _apply_openclaw_provider_scope,
-)
-from headroom.providers.openclaw.install import (
-    revert_provider_scope as _revert_openclaw_provider_scope,
-)
-
-_InstallEnvBuilder = Callable[..., dict[str, str]]
-_ProviderScopeApplier = Callable[[DeploymentManifest], ManagedMutation | None]
-_ProviderScopeReverter = Callable[[ManagedMutation, DeploymentManifest], None]
-
-_ENV_BUILDERS: dict[str, _InstallEnvBuilder] = {
-    "claude": _build_claude_install_env,
-    "copilot": _build_copilot_install_env,
-    "codex": _build_codex_install_env,
-    "aider": _build_aider_install_env,
-    "cursor": _build_cursor_install_env,
-}
-
-_PROVIDER_SCOPE_HANDLERS: dict[str, tuple[_ProviderScopeApplier, _ProviderScopeReverter]] = {
-    "claude": (_apply_claude_provider_scope, _revert_claude_provider_scope),
-    "codex": (_apply_codex_provider_scope, _revert_codex_provider_scope),
-    "openclaw": (_apply_openclaw_provider_scope, _revert_openclaw_provider_scope),
-}
-
-
-def build_install_target_envs(
-    port: int, backend: str, targets: list[str]
-) -> dict[str, dict[str, str]]:
-    """Build per-target install environment values via provider slices."""
-    target_envs: dict[str, dict[str, str]] = {}
-    for target in targets:
-        builder = _ENV_BUILDERS.get(target)
-        if builder is None:
-            continue
-        target_envs[target] = builder(port=port, backend=backend)
-    return target_envs
-
-
-def apply_provider_scope_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
-    """Apply provider-scope mutations owned by provider slices."""
-    mutations: list[ManagedMutation] = []
-    for target in manifest.targets:
-        handlers = _PROVIDER_SCOPE_HANDLERS.get(target)
-        if handlers is None:
-            continue
-        mutation = handlers[0](manifest)
-        if mutation is not None:
-            mutations.append(mutation)
-    return mutations
-
-
-def revert_provider_scope_mutation(manifest: DeploymentManifest, mutation: ManagedMutation) -> None:
-    """Revert a provider-scope mutation via the owning provider slice."""
-    handlers = _PROVIDER_SCOPE_HANDLERS.get(mutation.target)
-    if handlers is None:
-        return
-    handlers[1](mutation, manifest)
+"""Install-time provider registry helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from headroom.install.models import DeploymentManifest, ManagedMutation
+from headroom.providers.aider.install import build_install_env as _build_aider_install_env
+from headroom.providers.claude.install import (
+    apply_provider_scope as _apply_claude_provider_scope,
+)
+from headroom.providers.claude.install import (
+    build_install_env as _build_claude_install_env,
+)
+from headroom.providers.claude.install import (
+    revert_provider_scope as _revert_claude_provider_scope,
+)
+from headroom.providers.codex.install import (
+    apply_provider_scope as _apply_codex_provider_scope,
+)
+from headroom.providers.codex.install import build_install_env as _build_codex_install_env
+from headroom.providers.codex.install import (
+    revert_provider_scope as _revert_codex_provider_scope,
+)
+from headroom.providers.copilot.install import (
+    build_install_env as _build_copilot_install_env,
+)
+from headroom.providers.cursor.install import build_install_env as _build_cursor_install_env
+from headroom.providers.openclaw.install import (
+    apply_provider_scope as _apply_openclaw_provider_scope,
+)
+from headroom.providers.openclaw.install import (
+    revert_provider_scope as _revert_openclaw_provider_scope,
+)
+
+_InstallEnvBuilder = Callable[..., dict[str, str]]
+_ProviderScopeApplier = Callable[[DeploymentManifest], ManagedMutation | None]
+_ProviderScopeReverter = Callable[[ManagedMutation, DeploymentManifest], None]
+
+_ENV_BUILDERS: dict[str, _InstallEnvBuilder] = {
+    "claude": _build_claude_install_env,
+    "copilot": _build_copilot_install_env,
+    "codex": _build_codex_install_env,
+    "aider": _build_aider_install_env,
+    "cursor": _build_cursor_install_env,
+}
+
+_PROVIDER_SCOPE_HANDLERS: dict[str, tuple[_ProviderScopeApplier, _ProviderScopeReverter]] = {
+    "claude": (_apply_claude_provider_scope, _revert_claude_provider_scope),
+    "codex": (_apply_codex_provider_scope, _revert_codex_provider_scope),
+    "openclaw": (_apply_openclaw_provider_scope, _revert_openclaw_provider_scope),
+}
+
+
+def build_install_target_envs(
+    port: int, backend: str, targets: list[str]
+) -> dict[str, dict[str, str]]:
+    """Build per-target install environment values via provider slices."""
+    target_envs: dict[str, dict[str, str]] = {}
+    for target in targets:
+        builder = _ENV_BUILDERS.get(target)
+        if builder is None:
+            continue
+        target_envs[target] = builder(port=port, backend=backend)
+    return target_envs
+
+
+def apply_provider_scope_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
+    """Apply provider-scope mutations owned by provider slices."""
+    mutations: list[ManagedMutation] = []
+    for target in manifest.targets:
+        handlers = _PROVIDER_SCOPE_HANDLERS.get(target)
+        if handlers is None:
+            continue
+        mutation = handlers[0](manifest)
+        if mutation is not None:
+            mutations.append(mutation)
+    return mutations
+
+
+def revert_provider_scope_mutation(manifest: DeploymentManifest, mutation: ManagedMutation) -> None:
+    """Revert a provider-scope mutation via the owning provider slice."""
+    handlers = _PROVIDER_SCOPE_HANDLERS.get(mutation.target)
+    if handlers is None:
+        return
+    handlers[1](mutation, manifest)
diff --git a/headroom/providers/openclaw/install.py b/headroom/providers/openclaw/install.py
index e7e2b6f59ee3b11956d7b117895d3cd11fd8ec4c..97a3b1494f2203ff5c67138e15a6cb13deb29bc1 100644
--- a/headroom/providers/openclaw/install.py
+++ b/headroom/providers/openclaw/install.py
@@ -1,50 +1,50 @@
-"""OpenClaw install-time helpers."""
-
-from __future__ import annotations
-
-import click
-
-from headroom.install.models import DeploymentManifest, ManagedMutation, ToolTarget
-from headroom.install.paths import openclaw_config_path
-from headroom.install.runtime import resolve_headroom_command
-
-
-def shutil_which(name: str) -> str | None:
-    from shutil import which
-
-    return which(name)
-
-
-def _invoke_openclaw(command: list[str]) -> None:
-    import subprocess
-
-    subprocess.run(command, check=True)
-
-
-def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation:
-    """Configure OpenClaw to route through the persistent proxy."""
-    if not shutil_which("openclaw"):
-        raise click.ClickException("openclaw not found in PATH; cannot apply provider scope.")
-    command = [
-        *resolve_headroom_command(),
-        "wrap",
-        "openclaw",
-        "--no-auto-start",
-        "--proxy-port",
-        str(manifest.port),
-    ]
-    _invoke_openclaw(command)
-    return ManagedMutation(
-        target=ToolTarget.OPENCLAW.value,
-        kind="openclaw-wrap",
-        path=str(openclaw_config_path()),
-    )
-
-
-def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
-    """Undo OpenClaw persistent proxy configuration."""
-    del mutation, manifest
-    if not shutil_which("openclaw"):
-        return
-    command = [*resolve_headroom_command(), "unwrap", "openclaw"]
-    _invoke_openclaw(command)
+"""OpenClaw install-time helpers."""
+
+from __future__ import annotations
+
+import click
+
+from headroom.install.models import DeploymentManifest, ManagedMutation, ToolTarget
+from headroom.install.paths import openclaw_config_path
+from headroom.install.runtime import resolve_headroom_command
+
+
+def shutil_which(name: str) -> str | None:
+    from shutil import which
+
+    return which(name)
+
+
+def _invoke_openclaw(command: list[str]) -> None:
+    import subprocess
+
+    subprocess.run(command, check=True)
+
+
+def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation:
+    """Configure OpenClaw to route through the persistent proxy."""
+    if not shutil_which("openclaw"):
+        raise click.ClickException("openclaw not found in PATH; cannot apply provider scope.")
+    command = [
+        *resolve_headroom_command(),
+        "wrap",
+        "openclaw",
+        "--no-auto-start",
+        "--proxy-port",
+        str(manifest.port),
+    ]
+    _invoke_openclaw(command)
+    return ManagedMutation(
+        target=ToolTarget.OPENCLAW.value,
+        kind="openclaw-wrap",
+        path=str(openclaw_config_path()),
+    )
+
+
+def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
+    """Undo OpenClaw persistent proxy configuration."""
+    del mutation, manifest
+    if not shutil_which("openclaw"):
+        return
+    command = [*resolve_headroom_command(), "unwrap", "openclaw"]
+    _invoke_openclaw(command)
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 73207bfc6d5677d1858603ac66f596addbf81ac1..877258a895b970ca87b1dd611d21a02ed889212e 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -1,2746 +1,2746 @@
-"""OpenAI handler mixin for HeadroomProxy.
-
-Contains all OpenAI Chat Completions, Responses API, and passthrough handlers.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import base64
-import contextlib
-import copy
-import json
-import logging
-import os
-import time
-import uuid
-from datetime import datetime
-from typing import TYPE_CHECKING, Any
-
-from headroom.proxy.helpers import jitter_delay_ms
-from headroom.proxy.stage_timer import StageTimer, emit_stage_timings_log
-from headroom.proxy.ws_session_registry import (
-    TerminationCause,
-    WebSocketSessionRegistry,
-    WSSessionHandle,
-)
-
-if TYPE_CHECKING:
-    from fastapi import Request, WebSocket
-    from fastapi.responses import JSONResponse, Response, StreamingResponse
-
-import httpx
-
-from headroom.copilot_auth import apply_copilot_api_auth, build_copilot_upstream_url
-from headroom.pipeline import PipelineStage, summarize_routing_markers
-
-logger = logging.getLogger("headroom.proxy")
-
-
-# Interactive Responses turns are latency-sensitive. Fail open quickly rather
-# than holding the session hostage on memory lookup.
-RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS = 2.0
-
-# Cap the wait for the first client frame after the WS handshake completes.
-# A zombie or malicious client that accepts the upgrade but never sends the
-# first response.create frame would otherwise hold a slot indefinitely and
-# starve the session registry. 60 s is generous for real clients (Codex
-# typically sends the first frame within a few hundred milliseconds of the
-# accept) but short enough to bound the damage from a hung peer.
-WS_FIRST_FRAME_TIMEOUT_SECONDS = 60.0
-
-
-def _decode_openai_bearer_payload(headers: dict[str, str]) -> dict[str, Any] | None:
-    """Best-effort decode of an OpenAI OAuth bearer token payload.
-
-    OpenClaw's Codex OAuth flow may forward only the bearer token after the
-    provider base URL is overridden. In that case the explicit
-    ``ChatGPT-Account-ID`` header can be missing even though the JWT still
-    carries the account id we need to route to the ChatGPT Codex backend.
-    """
-    auth = headers.get("authorization") or headers.get("Authorization")
-    if not auth:
-        return None
-
-    scheme, _, token = auth.partition(" ")
-    if scheme.lower() != "bearer" or token.count(".") < 2:
-        return None
-
-    payload = token.split(".", 2)[1]
-    payload += "=" * (-len(payload) % 4)
-    # Intentionally no signature verification here: this is only a best-effort
-    # routing hint extractor. Upstream still performs the actual auth/authz checks.
-    try:
-        decoded = base64.urlsafe_b64decode(payload.encode("ascii"))
-        data = json.loads(decoded.decode("utf-8"))
-    except (ValueError, UnicodeDecodeError):
-        return None
-
-    return data if isinstance(data, dict) else None
-
-
-def _resolve_codex_routing_headers(headers: dict[str, str]) -> tuple[dict[str, str], bool]:
-    """Resolve ChatGPT Codex routing hints from explicit headers or OAuth JWT."""
-    resolved = dict(headers)
-    lower_lookup = {k.lower(): k for k in resolved}
-
-    if "chatgpt-account-id" in lower_lookup:
-        return resolved, True
-
-    payload = _decode_openai_bearer_payload(resolved)
-    auth_claims = payload.get("https://api.openai.com/auth") if isinstance(payload, dict) else None
-    account_id = auth_claims.get("chatgpt_account_id") if isinstance(auth_claims, dict) else None
-    if isinstance(account_id, str) and account_id.strip():
-        resolved["ChatGPT-Account-ID"] = account_id.strip()
-        return resolved, True
-
-    return resolved, False
-
-
-class OpenAIHandlerMixin:
-    """Mixin providing OpenAI API handler methods for HeadroomProxy."""
-
-    @staticmethod
-    def _strict_previous_turn_frozen_count(
-        messages: list[dict[str, Any]],
-        base_frozen_count: int,
-    ) -> int:
-        """Freeze all prior turns in cache mode; only final user turn is mutable."""
-        if not messages:
-            return base_frozen_count
-        final_idx = len(messages) - 1
-        if messages[final_idx].get("role") == "user":
-            return max(base_frozen_count, final_idx)
-        return len(messages)
-
-    @staticmethod
-    def _restore_frozen_prefix(
-        original_messages: list[dict[str, Any]],
-        candidate_messages: list[dict[str, Any]],
-        *,
-        frozen_message_count: int,
-    ) -> tuple[list[dict[str, Any]], int]:
-        """Force frozen prefix bytes to match original request exactly."""
-        if frozen_message_count <= 0 or not original_messages:
-            return candidate_messages, 0
-
-        frozen = min(frozen_message_count, len(original_messages))
-        restored = list(candidate_messages)
-
-        if len(restored) < frozen:
-            return list(original_messages[:frozen]) + restored, frozen
-
-        changed = 0
-        for idx in range(frozen):
-            if restored[idx] != original_messages[idx]:
-                restored[idx] = original_messages[idx]
-                changed += 1
-        return restored, changed
-
-    async def handle_openai_chat(
-        self,
-        request: Request,
-    ) -> Response | StreamingResponse:
-        """Handle OpenAI /v1/chat/completions endpoint."""
-        if not hasattr(self, "pipeline_extensions"):
-            from headroom.pipeline import PipelineExtensionManager
-
-            self.pipeline_extensions = PipelineExtensionManager(discover=False)
-
-        from fastapi import HTTPException
-        from fastapi.responses import JSONResponse, Response
-
-        from headroom.ccr import CCRToolInjector
-        from headroom.proxy.helpers import (
-            COMPRESSION_TIMEOUT_SECONDS,
-            MAX_MESSAGE_ARRAY_LENGTH,
-            MAX_REQUEST_BODY_SIZE,
-            _read_request_json,
-        )
-        from headroom.proxy.modes import is_cache_mode, is_token_mode
-        from headroom.tokenizers import get_tokenizer
-        from headroom.utils import extract_user_query
-
-        start_time = time.time()
-        request_id = await self._next_request_id()
-
-        # Check request body size
-        content_length = request.headers.get("content-length")
-        if content_length and int(content_length) > MAX_REQUEST_BODY_SIZE:
-            return JSONResponse(
-                status_code=413,
-                content={
-                    "error": {
-                        "message": f"Request body too large. Maximum size is {MAX_REQUEST_BODY_SIZE // (1024 * 1024)}MB",
-                        "type": "invalid_request_error",
-                        "code": "request_too_large",
-                    }
-                },
-            )
-
-        # Parse request
-        try:
-            body = await _read_request_json(request)
-        except (json.JSONDecodeError, ValueError) as e:
-            return JSONResponse(
-                status_code=400,
-                content={
-                    "error": {
-                        "message": f"Invalid request body: {e!s}",
-                        "type": "invalid_request_error",
-                        "code": "invalid_json",
-                    }
-                },
-            )
-        model = body.get("model", "unknown")
-        messages = body.get("messages", [])
-        original_client_messages = copy.deepcopy(messages)
-        input_event = self.pipeline_extensions.emit(
-            PipelineStage.INPUT_RECEIVED,
-            operation="proxy.request",
-            request_id=request_id,
-            provider="openai",
-            model=model,
-            messages=messages,
-            tools=body.get("tools"),
-            metadata={"path": "/v1/chat/completions", "stream": body.get("stream", False)},
-        )
-        if input_event.messages is not None:
-            messages = input_event.messages
-            original_client_messages = copy.deepcopy(messages)
-        if input_event.tools is not None:
-            body["tools"] = input_event.tools
-
-        # Validate message array size
-        if len(messages) > MAX_MESSAGE_ARRAY_LENGTH:
-            return JSONResponse(
-                status_code=400,
-                content={
-                    "error": {
-                        "message": f"Message array too large ({len(messages)} messages). "
-                        f"Maximum is {MAX_MESSAGE_ARRAY_LENGTH}.",
-                        "type": "invalid_request_error",
-                        "code": "invalid_request",
-                    }
-                },
-            )
-
-        stream = body.get("stream", False)
-
-        # Bypass: skip ALL compression for explicit opt-out
-        _bypass = (
-            request.headers.get("x-headroom-bypass", "").lower() == "true"
-            or request.headers.get("x-headroom-mode", "").lower() == "passthrough"
-        )
-        if _bypass:
-            logger.info(f"[{request_id}] Bypass: skipping compression (header)")
-
-        # Image compression: tile alignment + ML-based technique routing
-        if self.config.image_optimize and messages and not _bypass:
-            from headroom.proxy.helpers import _get_image_compressor
-
-            compressor = _get_image_compressor()
-            if compressor and compressor.has_images(messages):
-                messages = compressor.compress(messages, provider="openai")
-                if compressor.last_result:
-                    logger.info(
-                        f"[{request_id}] Image: {compressor.last_result.technique.value} "
-                        f"({compressor.last_result.savings_percent:.0f}% saved, "
-                        f"{compressor.last_result.original_tokens} → "
-                        f"{compressor.last_result.compressed_tokens} tokens)"
-                    )
-
-        headers = dict(request.headers.items())
-        headers.pop("host", None)
-        headers.pop("content-length", None)
-        # Strip accept-encoding so httpx negotiates its own encoding.
-        # Cloudflare Workers forward "br, zstd" which OpenAI may honor;
-        # if httpx lacks brotli support the response body is undecipherable → 502.
-        headers.pop("accept-encoding", None)
-        tags = self._extract_tags(headers)
-
-        # Memory: Get user ID when memory is enabled
-        memory_user_id: str | None = None
-        if self.memory_handler:
-            memory_user_id = headers.get(
-                "x-headroom-user-id",
-                os.environ.get("USER", os.environ.get("USERNAME", "default")),
-            )
-
-        # Rate limiting
-        if self.rate_limiter:
-            rate_key = headers.get("authorization", "default")[:20]
-            allowed, wait_seconds = await self.rate_limiter.check_request(rate_key)
-            if not allowed:
-                await self.metrics.record_rate_limited(provider="openai")
-                raise HTTPException(
-                    status_code=429,
-                    detail=f"Rate limited. Retry after {wait_seconds:.1f}s",
-                )
-
-        # Check cache
-        if self.cache and not stream:
-            cached = await self.cache.get(messages, model)
-            if cached:
-                self.pipeline_extensions.emit(
-                    PipelineStage.INPUT_CACHED,
-                    operation="proxy.request",
-                    request_id=request_id,
-                    provider="openai",
-                    model=model,
-                    messages=messages,
-                    metadata={"cache_hit": True, "path": "/v1/chat/completions"},
-                )
-                await self.metrics.record_request(
-                    provider="openai",
-                    model=model,
-                    input_tokens=0,
-                    output_tokens=0,
-                    tokens_saved=0,  # Savings already counted when response was cached
-                    latency_ms=(time.time() - start_time) * 1000,
-                    cached=True,
-                )
-
-                # Remove compression headers from cached response
-                response_headers = dict(cached.response_headers)
-                response_headers.pop("content-encoding", None)
-                response_headers.pop("content-length", None)
-
-                return Response(content=cached.response_body, headers=response_headers)
-
-        # Token counting
-        tokenizer = get_tokenizer(model)
-        original_tokens = tokenizer.count_messages(messages)
-
-        # Hook: pre_compress
-        _hook_biases = None
-        if self.config.hooks:
-            from headroom.hooks import CompressContext
-
-            _hook_ctx = CompressContext(model=model, provider="openai")
-            try:
-                messages = self.config.hooks.pre_compress(messages, _hook_ctx)
-                _hook_biases = self.config.hooks.compute_biases(messages, _hook_ctx)
-            except Exception as e:
-                logger.debug(f"[{request_id}] Hook error: {e}")
-
-        # Optimization
-        transforms_applied = []
-        pipeline_timing: dict[str, float] = {}
-        waste_signals_dict: dict[str, int] | None = None
-        optimized_messages = messages
-        optimized_tokens = original_tokens
-
-        # Get prefix cache tracker for this session
-        openai_session_id = self.session_tracker_store.compute_session_id(request, model, messages)
-        openai_prefix_tracker = self.session_tracker_store.get_or_create(
-            openai_session_id, "openai"
-        )
-        openai_frozen_count = openai_prefix_tracker.get_frozen_message_count()
-        if is_cache_mode(self.config.mode):
-            openai_frozen_count = self._strict_previous_turn_frozen_count(
-                original_client_messages,
-                openai_frozen_count,
-            )
-
-        _compression_failed = False
-        original_messages = messages  # Preserve for 400-retry fallback
-        _license_ok = self.usage_reporter.should_compress if self.usage_reporter else True
-        if self.config.optimize and messages and not _bypass and _license_ok:
-            try:
-                context_limit = self.openai_provider.get_context_limit(model)
-
-                if is_token_mode(self.config.mode):
-                    comp_cache = self._get_compression_cache(openai_session_id)
-
-                    # Zone 1: Swap cached compressed versions
-                    working_messages = comp_cache.apply_cached(messages)
-
-                    # Re-freeze boundary
-                    openai_frozen_count = comp_cache.compute_frozen_count(messages)
-
-                    result = await asyncio.wait_for(
-                        asyncio.to_thread(
-                            lambda: self.openai_pipeline.apply(
-                                messages=working_messages,
-                                model=model,
-                                model_limit=context_limit,
-                                context=extract_user_query(working_messages),
-                                frozen_message_count=openai_frozen_count,
-                                biases=_hook_biases,
-                            )
-                        ),
-                        timeout=COMPRESSION_TIMEOUT_SECONDS,
-                    )
-
-                    if result.messages != working_messages:
-                        comp_cache.update_from_result(messages, result.messages)
-
-                    # Always use pipeline result in token mode
-                    optimized_messages = result.messages
-                    transforms_applied = result.transforms_applied
-                    pipeline_timing = result.timing
-                    # Keep original_tokens as the REAL original (pre-Zone-1-swap)
-                    # so tokens_saved captures both Zone 1 + Zone 2 savings.
-                    optimized_tokens = result.tokens_after
-                else:
-                    result = await asyncio.wait_for(
-                        asyncio.to_thread(
-                            lambda: self.openai_pipeline.apply(
-                                messages=messages,
-                                model=model,
-                                model_limit=context_limit,
-                                context=extract_user_query(messages),
-                                frozen_message_count=openai_frozen_count,
-                                biases=_hook_biases,
-                            )
-                        ),
-                        timeout=COMPRESSION_TIMEOUT_SECONDS,
-                    )
-
-                    if result.messages != messages:
-                        optimized_messages = result.messages
-                        transforms_applied = result.transforms_applied
-                        pipeline_timing = result.timing
-                        original_tokens = result.tokens_before
-                        optimized_tokens = result.tokens_after
-
-                if result.waste_signals:
-                    waste_signals_dict = result.waste_signals.to_dict()
-            except Exception as e:
-                logger.warning(f"Optimization failed: {e}")
-                # Flag compression failure for observability
-                _compression_failed = True
-
-        # Guard: if "optimization" inflated tokens, revert to originals
-        if optimized_tokens > original_tokens:
-            logger.warning(
-                f"[{request_id}] Optimization inflated tokens "
-                f"({original_tokens} -> {optimized_tokens}), reverting to original messages"
-            )
-            optimized_messages = original_messages
-            optimized_tokens = original_tokens
-            transforms_applied = []
-
-        tokens_saved = original_tokens - optimized_tokens
-        optimization_latency = (time.time() - start_time) * 1000
-
-        routing_markers = summarize_routing_markers(transforms_applied)
-        if routing_markers:
-            routed_event = self.pipeline_extensions.emit(
-                PipelineStage.INPUT_ROUTED,
-                operation="proxy.request",
-                request_id=request_id,
-                provider="openai",
-                model=model,
-                messages=optimized_messages,
-                metadata={
-                    "routing_markers": routing_markers,
-                    "transforms_applied": transforms_applied,
-                },
-            )
-            if routed_event.messages is not None:
-                optimized_messages = routed_event.messages
-                optimized_tokens = tokenizer.count_messages(optimized_messages)
-                tokens_saved = original_tokens - optimized_tokens
-
-        compressed_event = self.pipeline_extensions.emit(
-            PipelineStage.INPUT_COMPRESSED,
-            operation="proxy.request",
-            request_id=request_id,
-            provider="openai",
-            model=model,
-            messages=optimized_messages,
-            metadata={
-                "tokens_before": original_tokens,
-                "tokens_after": optimized_tokens,
-                "transforms_applied": transforms_applied,
-            },
-        )
-        if compressed_event.messages is not None:
-            optimized_messages = compressed_event.messages
-            optimized_tokens = tokenizer.count_messages(optimized_messages)
-            tokens_saved = original_tokens - optimized_tokens
-
-        # Hook: post_compress
-        if self.config.hooks and tokens_saved > 0:
-            from headroom.hooks import CompressEvent
-
-            try:
-                self.config.hooks.post_compress(
-                    CompressEvent(
-                        tokens_before=original_tokens,
-                        tokens_after=optimized_tokens,
-                        tokens_saved=tokens_saved,
-                        compression_ratio=tokens_saved / original_tokens
-                        if original_tokens > 0
-                        else 0,
-                        transforms_applied=transforms_applied,
-                        model=model,
-                        provider="openai",
-                    )
-                )
-            except Exception as e:
-                logger.debug(f"[{request_id}] post_compress hook error: {e}")
-
-        # CCR Tool Injection: Inject retrieval tool if compression occurred
-        tools = body.get("tools")
-        _original_tools = tools  # Preserve for diagnostic / future retry
-        if (
-            self.config.ccr_inject_tool or self.config.ccr_inject_system_instructions
-        ) and not _bypass:
-            injector = CCRToolInjector(
-                provider="openai",
-                inject_tool=self.config.ccr_inject_tool,
-                inject_system_instructions=self.config.ccr_inject_system_instructions,
-            )
-            optimized_messages, tools, was_injected = injector.process_request(
-                optimized_messages, tools
-            )
-
-            if injector.has_compressed_content:
-                if was_injected:
-                    logger.debug(
-                        f"[{request_id}] CCR: Injected retrieval tool for hashes: {injector.detected_hashes}"
-                    )
-                else:
-                    logger.debug(
-                        f"[{request_id}] CCR: Tool already present (MCP?), skipped injection for hashes: {injector.detected_hashes}"
-                    )
-
-        # Query Echo: disabled — hurts prefix caching in long conversations.
-        if is_cache_mode(self.config.mode):
-            optimized_messages, restored_count = self._restore_frozen_prefix(
-                original_client_messages,
-                optimized_messages,
-                frozen_message_count=openai_frozen_count,
-            )
-            if restored_count > 0:
-                logger.warning(
-                    f"[{request_id}] Restored {restored_count} frozen prefix message(s) "
-                    "to preserve cache stability (openai)"
-                )
-
-        # Memory: inject context and tools for OpenAI requests
-        memory_context_injected = False
-        memory_tools_injected = False
-        if self.memory_handler and memory_user_id:
-            try:
-                # Inject memory context (search similar memories, add as system message)
-                if self.memory_handler.config.inject_context:
-                    memory_context = await self.memory_handler.search_and_format_context(
-                        memory_user_id, optimized_messages
-                    )
-                    if memory_context:
-                        # Prepend as system message for OpenAI format
-                        optimized_messages = [
-                            {"role": "system", "content": memory_context},
-                            *optimized_messages,
-                        ]
-                        memory_context_injected = True
-                        logger.info(
-                            f"[{request_id}] Memory: Injected {len(memory_context)} chars "
-                            f"of context for user {memory_user_id}"
-                        )
-
-                # Inject memory tools
-                if self.memory_handler.config.inject_tools:
-                    tools, mem_tools_injected = self.memory_handler.inject_tools(tools, "openai")
-                    if mem_tools_injected:
-                        memory_tools_injected = True
-                        logger.info(f"[{request_id}] Memory: Injected memory tools (openai)")
-            except Exception as e:
-                logger.warning(f"[{request_id}] Memory injection failed: {e}")
-
-        if memory_context_injected or memory_tools_injected:
-            remembered_event = self.pipeline_extensions.emit(
-                PipelineStage.INPUT_REMEMBERED,
-                operation="proxy.request",
-                request_id=request_id,
-                provider="openai",
-                model=model,
-                messages=optimized_messages,
-                tools=tools,
-                metadata={
-                    "memory_context_injected": memory_context_injected,
-                    "memory_tools_injected": memory_tools_injected,
-                },
-            )
-            if remembered_event.messages is not None:
-                optimized_messages = remembered_event.messages
-            if remembered_event.tools is not None:
-                tools = remembered_event.tools
-
-        body["messages"] = optimized_messages
-        if tools is not None:
-            body["tools"] = tools
-
-        presend_event = self.pipeline_extensions.emit(
-            PipelineStage.PRE_SEND,
-            operation="proxy.request",
-            request_id=request_id,
-            provider="openai",
-            model=model,
-            messages=optimized_messages,
-            tools=tools,
-            headers=headers,
-            metadata={"path": "/v1/chat/completions", "stream": stream},
-        )
-        if presend_event.messages is not None:
-            optimized_messages = presend_event.messages
-            body["messages"] = optimized_messages
-        if presend_event.tools is not None:
-            tools = presend_event.tools
-            body["tools"] = tools
-        if presend_event.headers is not None:
-            headers = presend_event.headers
-        optimized_tokens = tokenizer.count_messages(body["messages"])
-        tokens_saved = original_tokens - optimized_tokens
-
-        # Route through LiteLLM/any-llm backend if configured
-        if self.anthropic_backend is not None:
-            try:
-                if stream:
-                    self.pipeline_extensions.emit(
-                        PipelineStage.POST_SEND,
-                        operation="proxy.request",
-                        request_id=request_id,
-                        provider="openai",
-                        model=model,
-                        messages=body["messages"],
-                        tools=tools,
-                        metadata={"path": "/v1/chat/completions", "stream": True},
-                    )
-                    # Streaming: use stream_openai_message() → SSE events
-                    return await self._stream_openai_via_backend(
-                        body,
-                        headers,
-                        model,
-                        request_id,
-                        start_time,
-                        original_tokens,
-                        optimized_tokens,
-                        tokens_saved,
-                        transforms_applied,
-                        tags,
-                        optimization_latency,
-                        pipeline_timing=pipeline_timing,
-                    )
-                else:
-                    # Non-streaming: use send_openai_message() → JSON
-                    backend_response = await self.anthropic_backend.send_openai_message(
-                        body, headers
-                    )
-                    self.pipeline_extensions.emit(
-                        PipelineStage.POST_SEND,
-                        operation="proxy.request",
-                        request_id=request_id,
-                        provider="openai",
-                        model=model,
-                        messages=body["messages"],
-                        tools=tools,
-                        response=backend_response.body,
-                        metadata={
-                            "path": "/v1/chat/completions",
-                            "stream": False,
-                            "status_code": backend_response.status_code,
-                        },
-                    )
-                    self.pipeline_extensions.emit(
-                        PipelineStage.RESPONSE_RECEIVED,
-                        operation="proxy.request",
-                        request_id=request_id,
-                        provider="openai",
-                        model=model,
-                        response=backend_response.body,
-                        metadata={
-                            "path": "/v1/chat/completions",
-                            "stream": False,
-                            "status_code": backend_response.status_code,
-                        },
-                    )
-
-                    if backend_response.error:
-                        return JSONResponse(
-                            status_code=backend_response.status_code,
-                            content=backend_response.body,
-                        )
-
-                    # Track metrics
-                    total_latency = (time.time() - start_time) * 1000
-                    usage = backend_response.body.get("usage", {})
-                    output_tokens = usage.get("completion_tokens", 0)
-                    total_input_tokens = usage.get("prompt_tokens", optimized_tokens)
-
-                    await self.metrics.record_request(
-                        provider=self.anthropic_backend.name,
-                        model=model,
-                        input_tokens=total_input_tokens,
-                        output_tokens=output_tokens,
-                        tokens_saved=tokens_saved,
-                        latency_ms=total_latency,
-                        cached=False,
-                        overhead_ms=optimization_latency,
-                        pipeline_timing=pipeline_timing,
-                    )
-
-                    if tokens_saved > 0:
-                        logger.info(
-                            f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "
-                            f"(saved {tokens_saved:,} tokens) via {self.anthropic_backend.name}"
-                        )
-
-                    return JSONResponse(
-                        status_code=backend_response.status_code,
-                        content=backend_response.body,
-                    )
-            except Exception as e:
-                logger.error(f"[{request_id}] Backend error: {e}")
-                return JSONResponse(
-                    status_code=500,
-                    content={
-                        "error": {
-                            "message": str(e),
-                            "type": "api_error",
-                            "code": "backend_error",
-                        }
-                    },
-                )
-
-        # Direct OpenAI API (no backend configured)
-        url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/chat/completions")
-
-        try:
-            if stream:
-                # Inject stream_options to get usage stats in streaming response
-                # This allows accurate token counting instead of byte-based estimation
-                if "stream_options" not in body:
-                    body["stream_options"] = {"include_usage": True}
-                elif isinstance(body.get("stream_options"), dict):
-                    body["stream_options"]["include_usage"] = True
-
-                self.pipeline_extensions.emit(
-                    PipelineStage.POST_SEND,
-                    operation="proxy.request",
-                    request_id=request_id,
-                    provider="openai",
-                    model=model,
-                    messages=body["messages"],
-                    tools=tools,
-                    metadata={"path": "/v1/chat/completions", "stream": True},
-                )
-                return await self._stream_response(
-                    url,
-                    headers,
-                    body,
-                    "openai",
-                    model,
-                    request_id,
-                    original_tokens,
-                    optimized_tokens,
-                    tokens_saved,
-                    transforms_applied,
-                    tags,
-                    optimization_latency,
-                    pipeline_timing=pipeline_timing,
-                    prefix_tracker=openai_prefix_tracker,
-                )
-            else:
-                headers = await apply_copilot_api_auth(headers, url=url)
-                response = await self._retry_request("POST", url, headers, body)
-                self.pipeline_extensions.emit(
-                    PipelineStage.POST_SEND,
-                    operation="proxy.request",
-                    request_id=request_id,
-                    provider="openai",
-                    model=model,
-                    messages=body["messages"],
-                    tools=tools,
-                    response=response,
-                    metadata={
-                        "path": "/v1/chat/completions",
-                        "stream": False,
-                        "status_code": response.status_code,
-                    },
-                )
-                self.pipeline_extensions.emit(
-                    PipelineStage.RESPONSE_RECEIVED,
-                    operation="proxy.request",
-                    request_id=request_id,
-                    provider="openai",
-                    model=model,
-                    response=response,
-                    metadata={
-                        "path": "/v1/chat/completions",
-                        "stream": False,
-                        "status_code": response.status_code,
-                    },
-                )
-
-                # Full diagnostic dump on upstream errors (OpenAI handler)
-                if response.status_code >= 400:
-                    try:
-                        err_body = response.json()
-                        err_msg = err_body.get("error", {}).get("message", "")
-                        err_type = err_body.get("error", {}).get("type", "")
-                    except Exception:
-                        err_body = {"raw": response.text[:2000]}
-                        err_msg = str(response.text[:500])
-                        err_type = "parse_error"
-
-                    logger.warning(
-                        f"[{request_id}] UPSTREAM_ERROR "
-                        f"status={response.status_code} "
-                        f"error_type={err_type} "
-                        f"error_msg={err_msg!r} "
-                        f"model={model} "
-                        f"compressed={'yes' if transforms_applied else 'no'} "
-                        f"transforms={transforms_applied} "
-                        f"original_tokens={original_tokens} "
-                        f"optimized_tokens={optimized_tokens} "
-                        f"message_count={len(body.get('messages', []))} "
-                        f"stream={stream}"
-                    )
-
-                    try:
-                        from headroom import paths as _hr_paths
-
-                        debug_dir = _hr_paths.debug_400_dir()
-                        debug_dir.mkdir(parents=True, exist_ok=True)
-                        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
-                        debug_file = debug_dir / f"{ts}_{request_id}.json"
-
-                        safe_headers = {}
-                        for k, v in headers.items():
-                            if k.lower() in ("x-api-key", "authorization"):
-                                safe_headers[k] = v[:12] + "..." if v else ""
-                            else:
-                                safe_headers[k] = v
-
-                        debug_payload = {
-                            "request_id": request_id,
-                            "timestamp": datetime.now().isoformat(),
-                            "status_code": response.status_code,
-                            "error_response": err_body,
-                            "model": model,
-                            "stream": stream,
-                            "headers": safe_headers,
-                            "compression": {
-                                "was_compressed": bool(transforms_applied),
-                                "transforms": transforms_applied,
-                                "original_tokens": original_tokens,
-                                "optimized_tokens": optimized_tokens,
-                                "tokens_saved": tokens_saved,
-                                "compression_failed": _compression_failed,
-                            },
-                            "tools_sent": body.get("tools"),
-                            "tool_count": len(body.get("tools") or []),
-                            "original_tool_count": len(_original_tools or []),
-                            "messages_sent": body.get("messages"),
-                            "message_count": len(body.get("messages", [])),
-                            "original_messages": (
-                                original_messages
-                                if original_messages is not body.get("messages")
-                                else "__same_as_sent__"
-                            ),
-                            "original_message_count": len(original_messages),
-                            "system_prompt": body.get("system"),
-                        }
-
-                        with open(debug_file, "w") as f:
-                            json.dump(debug_payload, f, indent=2, default=str)
-
-                        logger.warning(f"[{request_id}] Full debug dump: {debug_file}")
-                    except Exception as dump_err:
-                        logger.error(f"[{request_id}] Failed to write debug dump: {dump_err}")
-
-                total_latency = (time.time() - start_time) * 1000
-
-                total_input_tokens = optimized_tokens  # fallback
-                output_tokens = 0
-                cache_read_tokens = 0
-                resp_json = None
-                try:
-                    resp_json = response.json()
-                    usage = resp_json.get("usage", {})
-                    total_input_tokens = usage.get("prompt_tokens", optimized_tokens)
-                    output_tokens = usage.get("completion_tokens", 0)
-                    # OpenAI returns cached_tokens in prompt_tokens_details
-                    # These are charged at 50% of the input price
-                    prompt_details = usage.get("prompt_tokens_details") or {}
-                    cache_read_tokens = prompt_details.get("cached_tokens", 0)
-                except (KeyError, TypeError, AttributeError) as e:
-                    logger.debug(
-                        f"[{request_id}] Failed to extract cached tokens from OpenAI response: {e}"
-                    )
-
-                # Update prefix cache tracker for next turn
-                openai_prefix_tracker.update_from_response(
-                    cache_read_tokens=cache_read_tokens,
-                    cache_write_tokens=0,  # OpenAI doesn't report write tokens
-                    messages=optimized_messages,
-                )
-
-                # OpenAI has no write penalty — uncached = total - cached
-                uncached_input_tokens = max(0, total_input_tokens - cache_read_tokens)
-
-                if self.cost_tracker:
-                    self.cost_tracker.record_tokens(
-                        model,
-                        tokens_saved,
-                        optimized_tokens,
-                        cache_read_tokens=cache_read_tokens,
-                        uncached_tokens=uncached_input_tokens,
-                    )
-
-                # Memory: handle memory tool calls in OpenAI Chat Completions response.
-                # After executing tools, send a continuation request so the model
-                # can produce a final user-facing response (not just tool_calls).
-                if (
-                    self.memory_handler
-                    and memory_user_id
-                    and resp_json
-                    and response.status_code == 200
-                    and self.memory_handler.has_memory_tool_calls(resp_json, "openai")
-                ):
-                    try:
-                        tool_results = await self.memory_handler.handle_memory_tool_calls(
-                            resp_json, memory_user_id, "openai"
-                        )
-                        if tool_results:
-                            # Build continuation: original messages + assistant tool_calls + tool results
-                            assistant_msg = resp_json.get("choices", [{}])[0].get("message", {})
-                            continuation_messages = list(optimized_messages)
-                            continuation_messages.append(assistant_msg)
-                            continuation_messages.extend(tool_results)
-
-                            continuation_body = {
-                                **body,
-                                "messages": continuation_messages,
-                            }
-
-                            cont_response = await self._retry_request(
-                                "POST", url, headers, continuation_body
-                            )
-                            if cont_response.status_code == 200:
-                                resp_json = cont_response.json()
-                                response = cont_response
-
-                            logger.info(
-                                f"[{request_id}] Memory: Handled {len(tool_results)} "
-                                f"tool call(s) with continuation for user {memory_user_id}"
-                            )
-                    except Exception as e:
-                        logger.warning(f"[{request_id}] Memory tool handling failed: {e}")
-
-                # Cache
-                if self.cache and response.status_code == 200:
-                    await self.cache.set(
-                        messages,
-                        model,
-                        response.content,
-                        dict(response.headers),
-                        tokens_saved,
-                    )
-
-                # Capture Codex rate-limit window data from response headers
-                from headroom.subscription.codex_rate_limits import (
-                    get_codex_rate_limit_state,
-                )
-
-                get_codex_rate_limit_state().update_from_headers(dict(response.headers))
-
-                await self.metrics.record_request(
-                    provider="openai",
-                    model=model,
-                    input_tokens=total_input_tokens,
-                    output_tokens=output_tokens,
-                    tokens_saved=tokens_saved,
-                    latency_ms=total_latency,
-                    overhead_ms=optimization_latency,
-                    pipeline_timing=pipeline_timing,
-                    waste_signals=waste_signals_dict,
-                    cache_read_tokens=cache_read_tokens,
-                    uncached_input_tokens=uncached_input_tokens,
-                )
-
-                if tokens_saved > 0:
-                    logger.info(
-                        f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "
-                        f"(saved {tokens_saved:,} tokens)"
-                    )
-
-                # Remove compression headers since httpx already decompressed the response
-                response_headers = dict(response.headers)
-                response_headers.pop("content-encoding", None)
-                response_headers.pop("content-length", None)  # Length changed after decompression
-
-                # Inject Headroom compression metrics (for SaaS metering)
-                response_headers["x-headroom-tokens-before"] = str(original_tokens)
-                response_headers["x-headroom-tokens-after"] = str(optimized_tokens)
-                response_headers["x-headroom-tokens-saved"] = str(tokens_saved)
-                response_headers["x-headroom-model"] = model
-                if transforms_applied:
-                    response_headers["x-headroom-transforms"] = ",".join(transforms_applied)
-                if cache_read_tokens > 0:
-                    response_headers["x-headroom-cached"] = "true"
-                if _compression_failed:
-                    response_headers["x-headroom-compression-failed"] = "true"
-
-                return Response(
-                    content=response.content,
-                    status_code=response.status_code,
-                    headers=response_headers,
-                )
-        except Exception as e:
-            await self.metrics.record_failed(provider="openai")
-            # Log full error details internally for debugging
-            logger.error(f"[{request_id}] OpenAI request failed: {type(e).__name__}: {e}")
-            # Return sanitized error message to client (don't expose internal details)
-            return JSONResponse(
-                status_code=502,
-                content={
-                    "error": {
-                        "message": "An error occurred while processing your request. Please try again.",
-                        "type": "server_error",
-                        "code": "proxy_error",
-                    }
-                },
-            )
-
-    async def handle_openai_responses(
-        self,
-        request: Request,
-    ) -> Response | StreamingResponse:
-        """Handle OpenAI /v1/responses endpoint (new Responses API).
-
-        The Responses API differs from /v1/chat/completions:
-        - Input: `input` (string or array) instead of `messages`
-        - System: `instructions` instead of system message
-        - Output: `output[]` array instead of `choices[].message`
-        - State: `previous_response_id` for multi-turn
-        - Built-in tools: web_search, file_search, code_interpreter
-        """
-        from fastapi import HTTPException
-        from fastapi.responses import JSONResponse, Response
-
-        from headroom.proxy.helpers import (
-            COMPRESSION_TIMEOUT_SECONDS,
-            MAX_REQUEST_BODY_SIZE,
-            _read_request_json,
-        )
-        from headroom.proxy.responses_converter import (
-            messages_to_responses_items,
-            responses_items_to_messages,
-        )
-        from headroom.tokenizers import get_tokenizer
-        from headroom.utils import extract_user_query
-
-        start_time = time.time()
-        request_id = await self._next_request_id()
-
-        # Check request body size
-        content_length = request.headers.get("content-length")
-        if content_length and int(content_length) > MAX_REQUEST_BODY_SIZE:
-            return JSONResponse(
-                status_code=413,
-                content={
-                    "error": {
-                        "message": f"Request body too large. Maximum size is {MAX_REQUEST_BODY_SIZE // (1024 * 1024)}MB",
-                        "type": "invalid_request_error",
-                        "code": "request_too_large",
-                    }
-                },
-            )
-
-        # Parse request
-        try:
-            body = await _read_request_json(request)
-        except (json.JSONDecodeError, ValueError) as e:
-            return JSONResponse(
-                status_code=400,
-                content={
-                    "error": {
-                        "message": f"Invalid request body: {e!s}",
-                        "type": "invalid_request_error",
-                        "code": "invalid_json",
-                    }
-                },
-            )
-
-        model = body.get("model", "unknown")
-        stream = body.get("stream", False)
-
-        # Convert Responses API input to messages format for optimization.
-        # The Responses API uses a different item model (function_call,
-        # function_call_output, reasoning as top-level items) — we convert to
-        # Chat Completions messages for the pipeline, then convert back.
-
-        input_data = body.get("input", "")
-        instructions = body.get("instructions")
-        previous_response_id = body.get("previous_response_id")
-
-        messages: list[dict[str, Any]] = []
-        original_items: list[dict[str, Any]] | None = None
-        preserved_indices: list[int] = []
-
-        if instructions:
-            messages.append({"role": "system", "content": instructions})
-
-        if isinstance(input_data, str):
-            messages.append({"role": "user", "content": input_data})
-        elif isinstance(input_data, list):
-            original_items = input_data
-            converted, preserved_indices = responses_items_to_messages(input_data)
-            messages.extend(converted)
-
-        headers = dict(request.headers.items())
-        headers.pop("host", None)
-        headers.pop("content-length", None)
-        # Strip accept-encoding so httpx negotiates its own encoding.
-        # Cloudflare Workers forward "br, zstd" which OpenAI may honor;
-        # if httpx lacks brotli support the response body is undecipherable → 502.
-        headers.pop("accept-encoding", None)
-        tags = self._extract_tags(headers)
-
-        # Memory: Get user ID when memory is enabled
-        memory_user_id: str | None = None
-        if self.memory_handler:
-            memory_user_id = headers.get(
-                "x-headroom-user-id",
-                os.environ.get("USER", os.environ.get("USERNAME", "default")),
-            )
-
-        # Rate limiting
-        if self.rate_limiter:
-            rate_key = headers.get("authorization", "default")[:20]
-            allowed, wait_seconds = await self.rate_limiter.check_request(rate_key)
-            if not allowed:
-                await self.metrics.record_rate_limited(provider="openai")
-                raise HTTPException(
-                    status_code=429,
-                    detail=f"Rate limited. Retry after {wait_seconds:.1f}s",
-                )
-
-        # Token counting on converted messages
-        tokenizer = get_tokenizer(model)
-        original_tokens = tokenizer.count_messages(messages)
-
-        # Optimize: convert items → compress → convert back
-        tokens_saved = 0
-        transforms_applied: list[str] = []
-        optimized_messages = messages
-        optimized_tokens = original_tokens
-
-        _bypass = (
-            request.headers.get("x-headroom-bypass", "").lower() == "true"
-            or request.headers.get("x-headroom-mode", "").lower() == "passthrough"
-        )
-        _should_compress = (
-            self.config.optimize
-            and original_items is not None
-            and not previous_response_id
-            and not _bypass
-            and len(messages) > 1
-        )
-        _license_ok = self.usage_reporter.should_compress if self.usage_reporter else True
-
-        if _should_compress and _license_ok:
-            try:
-                context_limit = self.openai_provider.get_context_limit(model)
-                result = await asyncio.wait_for(
-                    asyncio.to_thread(
-                        lambda: self.openai_pipeline.apply(
-                            messages=messages,
-                            model=model,
-                            model_limit=context_limit,
-                            context=extract_user_query(messages),
-                        )
-                    ),
-                    timeout=COMPRESSION_TIMEOUT_SECONDS,
-                )
-                if result.messages != messages:
-                    optimized_messages = result.messages
-                    transforms_applied = result.transforms_applied
-                    original_tokens = result.tokens_before
-                    optimized_tokens = result.tokens_after
-            except Exception as e:
-                logger.warning(f"[{request_id}] Responses API optimization failed: {e}")
-
-        # Guard: if "optimization" inflated tokens, revert to originals
-        if optimized_tokens > original_tokens:
-            logger.warning(
-                f"[{request_id}] Optimization inflated tokens "
-                f"({original_tokens} -> {optimized_tokens}), reverting to original messages"
-            )
-            optimized_messages = messages
-            optimized_tokens = original_tokens
-            transforms_applied = []
-
-        tokens_saved = original_tokens - optimized_tokens
-        optimization_latency = (time.time() - start_time) * 1000
-
-        # Convert compressed messages back to Responses API items
-        if optimized_messages is not messages and original_items is not None:
-            opt_msgs = optimized_messages
-            # Strip system message (instructions) — it's separate in Responses API
-            if instructions and opt_msgs and opt_msgs[0].get("role") == "system":
-                body["instructions"] = opt_msgs[0]["content"]
-                opt_msgs = opt_msgs[1:]
-
-            body["input"] = messages_to_responses_items(opt_msgs, original_items, preserved_indices)
-
-        # Memory: inject context and tools for Responses API requests
-        if self.memory_handler and memory_user_id:
-            try:
-                # Inject memory context into instructions (Responses API system prompt)
-                if self.memory_handler.config.inject_context:
-                    try:
-                        memory_context = await asyncio.wait_for(
-                            self.memory_handler.search_and_format_context(
-                                memory_user_id, optimized_messages
-                            ),
-                            timeout=RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS,
-                        )
-                    except asyncio.TimeoutError:
-                        memory_context = None
-                        logger.info(
-                            f"[{request_id}] Memory context lookup exceeded "
-                            f"{RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS:.1f}s; continuing without it"
-                        )
-                    if memory_context:
-                        existing_instructions = body.get("instructions") or ""
-                        if existing_instructions:
-                            body["instructions"] = f"{existing_instructions}\n\n{memory_context}"
-                        else:
-                            body["instructions"] = memory_context
-                        logger.info(
-                            f"[{request_id}] Memory: Injected {len(memory_context)} chars "
-                            f"of context into instructions for user {memory_user_id}"
-                        )
-
-                # Inject memory tools (Responses API format)
-                if self.memory_handler.config.inject_tools:
-                    resp_tools = body.get("tools") or []
-                    resp_tools, mem_tools_injected = self.memory_handler.inject_tools(
-                        resp_tools, "openai"
-                    )
-                    if mem_tools_injected:
-                        # Convert Chat Completions format to Responses API format
-                        converted_tools = []
-                        for t in resp_tools:
-                            if t.get("type") == "function" and "function" in t:
-                                fn = t["function"]
-                                converted_tools.append(
-                                    {
-                                        "type": "function",
-                                        "name": fn.get("name"),
-                                        "description": fn.get("description", ""),
-                                        "parameters": fn.get("parameters", {}),
-                                    }
-                                )
-                            else:
-                                converted_tools.append(t)
-                        body["tools"] = converted_tools
-                        logger.info(
-                            f"[{request_id}] Memory: Injected memory tools (openai/responses)"
-                        )
-            except Exception as e:
-                logger.warning(f"[{request_id}] Memory injection failed (responses): {e}")
-
-        # /v1/responses is OpenAI-specific (Codex) — always routes direct.
-        # LiteLLM/AnyLLM backends use /v1/chat/completions or /v1/messages.
-        if self.anthropic_backend is not None:
-            logger.debug(
-                f"[{request_id}] /v1/responses always routes to OpenAI direct "
-                f"(backend '{self.anthropic_backend.name}' not used for Responses API)"
-            )
-
-        headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)
-
-        # Route to correct endpoint based on auth mode.
-        # ChatGPT session auth (codex login) uses chatgpt.com, not api.openai.com.
-        if is_chatgpt_auth:
-            url = "https://chatgpt.com/backend-api/codex/responses"
-        else:
-            url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/responses")
-
-        try:
-            if stream:
-                # Streaming for Responses API uses semantic events
-                return await self._stream_response(
-                    url,
-                    headers,
-                    body,
-                    "openai",
-                    model,
-                    request_id,
-                    original_tokens,
-                    optimized_tokens,
-                    tokens_saved,
-                    transforms_applied,
-                    tags,
-                    optimization_latency,
-                    memory_user_id=memory_user_id,
-                )
-            else:
-                headers = await apply_copilot_api_auth(headers, url=url)
-                response = await self._retry_request("POST", url, headers, body)
-                total_latency = (time.time() - start_time) * 1000
-
-                total_input_tokens = original_tokens  # fallback
-                output_tokens = 0
-                try:
-                    resp_json = response.json()
-                    usage = resp_json.get("usage", {})
-                    total_input_tokens = usage.get("input_tokens", original_tokens)
-                    output_tokens = usage.get("output_tokens", 0)
-                except (KeyError, TypeError, AttributeError) as e:
-                    logger.debug(
-                        f"[{request_id}] Failed to extract cached tokens from OpenAI passthrough response: {e}"
-                    )
-
-                # Memory: handle memory tool calls in Responses API response
-                if (
-                    self.memory_handler
-                    and memory_user_id
-                    and resp_json
-                    and response.status_code == 200
-                    and self.memory_handler.has_memory_tool_calls(resp_json, "openai")
-                ):
-                    try:
-                        # Extract function_call items from output
-                        from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES
-
-                        output_items = resp_json.get("output", [])
-                        memory_fc_items = [
-                            item
-                            for item in output_items
-                            if isinstance(item, dict)
-                            and item.get("type") == "function_call"
-                            and item.get("name") in MEMORY_TOOL_NAMES
-                        ]
-
-                        # Execute memory tool calls
-                        tool_outputs: list[dict[str, Any]] = []
-                        for fc in memory_fc_items:
-                            call_id = fc.get("call_id", fc.get("id", ""))
-                            name = fc.get("name", "")
-                            args_str = fc.get("arguments", "{}")
-                            try:
-                                args = json.loads(args_str)
-                            except json.JSONDecodeError:
-                                args = {}
-
-                            await self.memory_handler._ensure_initialized()
-                            if self.memory_handler._backend:
-                                result = await self.memory_handler._execute_memory_tool(
-                                    name, args, memory_user_id, "openai"
-                                )
-                            else:
-                                result = json.dumps({"error": "Memory backend not initialized"})
-
-                            tool_outputs.append(
-                                {
-                                    "type": "function_call_output",
-                                    "call_id": call_id,
-                                    "output": result,
-                                }
-                            )
-
-                        if tool_outputs:
-                            # Make continuation request with tool results
-                            response_id = resp_json.get("id")
-                            continuation_body = {
-                                "model": model,
-                                "input": tool_outputs,
-                            }
-                            if response_id:
-                                continuation_body["previous_response_id"] = response_id
-                            existing_tools = body.get("tools")
-                            if existing_tools:
-                                continuation_body["tools"] = existing_tools
-
-                            cont_response = await self._retry_request(
-                                "POST", url, headers, continuation_body
-                            )
-                            resp_json = cont_response.json()
-                            response = cont_response
-                            logger.info(
-                                f"[{request_id}] Memory: Handled {len(tool_outputs)} "
-                                f"tool call(s) with continuation for user {memory_user_id} (responses)"
-                            )
-                    except Exception as e:
-                        logger.warning(
-                            f"[{request_id}] Memory tool handling failed (responses): {e}"
-                        )
-
-                if self.cost_tracker:
-                    self.cost_tracker.record_tokens(model, tokens_saved, total_input_tokens)
-
-                await self.metrics.record_request(
-                    provider="openai",
-                    model=model,
-                    input_tokens=total_input_tokens,
-                    output_tokens=output_tokens,
-                    tokens_saved=tokens_saved,
-                    latency_ms=total_latency,
-                    overhead_ms=optimization_latency,
-                )
-
-                logger.info(f"[{request_id}] /v1/responses {model}: {total_input_tokens:,} tokens")
-
-                # Capture Codex rate-limit window data from response headers
-                from headroom.subscription.codex_rate_limits import (
-                    get_codex_rate_limit_state,
-                )
-
-                get_codex_rate_limit_state().update_from_headers(dict(response.headers))
-
-                # Remove compression headers
-                response_headers = dict(response.headers)
-                response_headers.pop("content-encoding", None)
-                response_headers.pop("content-length", None)
-
-                return Response(
-                    content=response.content,
-                    status_code=response.status_code,
-                    headers=response_headers,
-                )
-        except Exception as e:
-            await self.metrics.record_failed(provider="openai")
-            logger.error(f"[{request_id}] OpenAI responses request failed: {type(e).__name__}: {e}")
-            return JSONResponse(
-                status_code=502,
-                content={
-                    "error": {
-                        "message": "An error occurred while processing your request. Please try again.",
-                        "type": "server_error",
-                        "code": "proxy_error",
-                    }
-                },
-            )
-
-    async def handle_openai_responses_ws(self, websocket: WebSocket) -> None:
-        """WebSocket proxy for /v1/responses (Codex gpt-5.4+).
-
-        Newer Codex versions use WebSocket instead of HTTP POST for the
-        Responses API.  This handler:
-        1. Accepts the client WebSocket
-        2. Receives the first message (``response.create`` request)
-        3. Compresses the ``input`` array using the existing pipeline
-        4. Opens an upstream WebSocket to OpenAI
-        5. Sends the compressed request upstream
-        6. Relays all subsequent messages bidirectionally
-        """
-        from headroom.proxy.helpers import COMPRESSION_TIMEOUT_SECONDS
-        from headroom.tokenizers import get_tokenizer
-        from headroom.utils import extract_user_query
-
-        try:
-            import websockets
-        except ImportError:
-            await websocket.accept()
-            await websocket.close(
-                code=1011,
-                reason="websockets package not installed. pip install websockets",
-            )
-            return
-
-        request_id = await self._next_request_id()
-        session_id = uuid.uuid4().hex
-
-        # Stage-timer — captures per-stage durations for the structured
-        # log emitted on session close. Unit 2 instrumentation.
-        stage_timer = StageTimer()
-        session_started_at = time.perf_counter()
-
-        # Unit 3: initialize registry variables *before* accept so the
-        # outermost ``finally`` can rely on them existing even if
-        # registration itself fails for some reason.
-        ws_sessions: WebSocketSessionRegistry | None = getattr(self, "ws_sessions", None)
-        session_handle: WSSessionHandle | None = None
-        termination_cause: TerminationCause = "unknown"
-
-        # Forward client headers to upstream, adding required OpenAI-Beta header
-        ws_headers = dict(websocket.headers)
-
-        # Extract subprotocol from client — this is an application-level negotiation
-        # that MUST be forwarded end-to-end (unlike sec-websocket-key which is per-connection).
-        # Codex and OpenAI negotiate a subprotocol; stripping it causes OpenAI to return 500.
-        client_subprotocols: list[str] = []
-        raw_protocol = ws_headers.get("sec-websocket-protocol", "")
-        if raw_protocol:
-            client_subprotocols = [p.strip() for p in raw_protocol.split(",") if p.strip()]
-
-        # Accept client connection with the requested subprotocol
-        async with stage_timer.measure("accept"):
-            if client_subprotocols:
-                await websocket.accept(subprotocol=client_subprotocols[0])
-            else:
-                await websocket.accept()
-
-        # --- Unit 3: register the session as soon as accept succeeds ---
-        client_addr: str | None = None
-        client_info = getattr(websocket, "client", None)
-        if client_info is not None:
-            host = getattr(client_info, "host", None)
-            port = getattr(client_info, "port", None)
-            if host is not None and port is not None:
-                client_addr = f"{host}:{port}"
-            elif host is not None:
-                client_addr = str(host)
-        if ws_sessions is not None:
-            session_handle = WSSessionHandle(
-                session_id=session_id,
-                request_id=request_id,
-                client_addr=client_addr,
-                upstream_url=None,  # set below once upstream_url is computed
-            )
-            ws_sessions.register(session_handle)
-            metrics = getattr(self, "metrics", None)
-            if metrics is not None and hasattr(metrics, "inc_active_ws_sessions"):
-                try:
-                    metrics.inc_active_ws_sessions()
-                except Exception:  # pragma: no cover - defensive
-                    pass
-
-        # Forward all client headers except hop-by-hop / per-connection headers.
-        # These are WebSocket handshake mechanics that the `websockets` library
-        # generates fresh for the upstream connection — forwarding them would conflict.
-        # Everything else (auth, org, beta, user-agent, custom headers) is forwarded as-is.
-        _skip_headers = frozenset(
-            {
-                "host",  # must match upstream, not local proxy
-                "connection",  # hop-by-hop
-                "upgrade",  # hop-by-hop
-                "sec-websocket-key",  # per-connection cryptographic nonce
-                "sec-websocket-version",  # protocol version (websockets lib sets this)
-                "sec-websocket-extensions",  # per-connection negotiation
-                "sec-websocket-accept",  # server-side only
-                "sec-websocket-protocol",  # handled via subprotocols param below
-                "content-length",  # hop-by-hop
-                "transfer-encoding",  # hop-by-hop
-            }
-        )
-        upstream_headers: dict[str, str] = {}
-        for k, v in ws_headers.items():
-            if k.lower() not in _skip_headers:
-                upstream_headers[k] = v
-
-        upstream_headers, is_chatgpt_auth = _resolve_codex_routing_headers(upstream_headers)
-        _lower_headers = {k.lower(): v for k, v in upstream_headers.items()}
-
-        # Build upstream WebSocket URL based on auth mode
-        if is_chatgpt_auth:
-            # ChatGPT session auth → route to chatgpt.com backend
-            upstream_url = "wss://chatgpt.com/backend-api/codex/responses"
-            logger.debug(
-                f"[{request_id}] WS: ChatGPT session auth detected, routing to chatgpt.com"
-            )
-        else:
-            # API key auth → route to configured OpenAI API URL
-            base = self.OPENAI_API_URL
-            ws_base = base.replace("https://", "wss://").replace("http://", "ws://")
-            upstream_url = build_copilot_upstream_url(ws_base, "/v1/responses")
-
-        # Unit 3: attach the resolved upstream URL to the session handle.
-        if session_handle is not None:
-            session_handle.upstream_url = upstream_url
-
-        # Ensure Authorization header is present — fall back to OPENAI_API_KEY env var.
-        # Safety net for clients that don't forward auth headers via WebSocket upgrade.
-        if "authorization" not in _lower_headers:
-            api_key = os.environ.get("OPENAI_API_KEY")
-            if api_key:
-                upstream_headers["Authorization"] = f"Bearer {api_key}"
-                logger.debug(f"[{request_id}] WS: injected Authorization from OPENAI_API_KEY env")
-            else:
-                logger.warning(
-                    f"[{request_id}] WS: no Authorization header from client and "
-                    f"OPENAI_API_KEY not set — upstream will likely reject"
-                )
-
-        upstream_headers = await apply_copilot_api_auth(upstream_headers, url=upstream_url)
-
-        # Ensure the required beta header is present — OpenAI returns 500 without it.
-        # Codex sends `responses_websockets=2026-02-06`; only inject if missing entirely.
-        if "openai-beta" not in _lower_headers:
-            upstream_headers["OpenAI-Beta"] = "responses_websockets=2026-02-06"
-
-        logger.debug(
-            f"[{request_id}] WS upstream headers: "
-            f"{[k for k in upstream_headers if k.lower() != 'authorization']}, "
-            f"subprotocols={client_subprotocols}"
-        )
-
-        try:
-            # Receive the first message from client (the response.create request).
-            # Bound the wait with WS_FIRST_FRAME_TIMEOUT_SECONDS so a zombie
-            # client that opens the WS but never sends a frame cannot hold a
-            # session slot indefinitely. The StageTimer measurement still
-            # captures the elapsed time up to the timeout so operators can
-            # see the slow-client pattern in the stage-timings log.
-            try:
-                async with stage_timer.measure("first_client_frame"):
-                    first_msg_raw = await asyncio.wait_for(
-                        websocket.receive_text(),
-                        timeout=WS_FIRST_FRAME_TIMEOUT_SECONDS,
-                    )
-            except asyncio.TimeoutError:
-                logger.info(
-                    f"[{request_id}] WS first-frame timeout after "
-                    f"{WS_FIRST_FRAME_TIMEOUT_SECONDS:.0f}s; closing session "
-                    f"{session_id} (no client data)"
-                )
-                termination_cause = "client_timeout"
-                with contextlib.suppress(Exception):
-                    # 1001 (going away): server is cleanly terminating a slow
-                    # client, not an internal error.
-                    await websocket.close(code=1001, reason="first-frame timeout")
-                # Exit the outer try so the session-lifecycle ``finally`` runs
-                # deregister / metrics / stage-timings emission as usual.
-                return
-
-            # --- Optional: compress the input in the first message ---
-            body: dict[str, Any] = {}
-            try:
-                body = json.loads(first_msg_raw)
-                tokens_saved = 0
-                ws_request_body = body.get("response", body)
-                input_data = (
-                    ws_request_body.get("input") if isinstance(ws_request_body, dict) else None
-                )
-
-                should_compress = (
-                    self.config.optimize
-                    and isinstance(input_data, list)
-                    and len(input_data) > 1
-                    and not (
-                        ws_request_body.get("previous_response_id")
-                        if isinstance(ws_request_body, dict)
-                        else None
-                    )
-                )
-                if should_compress:
-                    try:
-                        from headroom.proxy.responses_converter import (
-                            messages_to_responses_items,
-                            responses_items_to_messages,
-                        )
-
-                        model = ws_request_body.get("model", "gpt-4o")
-                        converted, preserved = responses_items_to_messages(input_data)
-
-                        messages: list[dict[str, Any]] = []
-                        instructions = ws_request_body.get("instructions")
-                        if instructions:
-                            messages.append({"role": "system", "content": instructions})
-                        messages.extend(converted)
-
-                        tokenizer = get_tokenizer(model)
-                        original_tokens = tokenizer.count_messages(messages)
-
-                        context_limit = self.openai_provider.get_context_limit(model)
-                        async with stage_timer.measure("compression"):
-                            result = await asyncio.wait_for(
-                                asyncio.to_thread(
-                                    lambda: self.openai_pipeline.apply(
-                                        messages=messages,
-                                        model=model,
-                                        model_limit=context_limit,
-                                        context=extract_user_query(messages),
-                                    )
-                                ),
-                                timeout=COMPRESSION_TIMEOUT_SECONDS,
-                            )
-
-                        if result.messages != messages:
-                            opt = result.messages
-                            if instructions and opt and opt[0].get("role") == "system":
-                                ws_request_body["instructions"] = opt[0]["content"]
-                                opt = opt[1:]
-                            if result.tokens_after <= original_tokens:
-                                ws_request_body["input"] = messages_to_responses_items(
-                                    opt, input_data, preserved
-                                )
-                            else:
-                                logger.warning(
-                                    f"[{request_id}] WS optimization inflated tokens "
-                                    f"({original_tokens} -> {result.tokens_after}), reverting"
-                                )
-                            tokens_saved = max(0, original_tokens - result.tokens_after)
-                            if "response" in body and isinstance(body["response"], dict):
-                                body["response"] = ws_request_body
-                            else:
-                                body = ws_request_body
-                            first_msg_raw = json.dumps(body)
-                            logger.info(
-                                f"[{request_id}] WS /v1/responses compressed: "
-                                f"saved {tokens_saved} tokens"
-                            )
-                    except Exception as e:
-                        logger.warning(f"[{request_id}] WS compression failed: {e}")
-
-            except json.JSONDecodeError:
-                # Not JSON — pass through as-is
-                tokens_saved = 0
-
-            # --- Memory: inject context, tools, and instructions ---
-            memory_user_id: str | None = None
-            if self.memory_handler and body:
-                memory_user_id = ws_headers.get(
-                    "x-headroom-user-id",
-                    os.environ.get("USER", os.environ.get("USERNAME", "default")),
-                )
-                try:
-                    # Unwrap response.create envelope to access the response body
-                    ws_response_body = body.get("response", body)
-
-                    # Debug: log what Codex sends so we can see the full tool list
-                    existing_tool_names = [
-                        t.get("name") or t.get("function", {}).get("name", "?")
-                        for t in (ws_response_body.get("tools") or [])
-                    ]
-                    instr_preview = (ws_response_body.get("instructions") or "")[:200]
-                    logger.info(
-                        f"[{request_id}] WS Memory: Codex tools={existing_tool_names}, "
-                        f"instructions_len={len(ws_response_body.get('instructions') or '')}, "
-                        f"instructions_preview={instr_preview!r}"
-                    )
-
-                    # Inject memory context into instructions
-                    if self.memory_handler.config.inject_context:
-                        ws_input = ws_response_body.get("input", "")
-                        ws_instructions = ws_response_body.get("instructions")
-                        ws_msgs: list[dict[str, Any]] = []
-                        if ws_instructions:
-                            ws_msgs.append({"role": "system", "content": ws_instructions})
-                        if isinstance(ws_input, str) and ws_input:
-                            ws_msgs.append({"role": "user", "content": ws_input})
-                        elif isinstance(ws_input, list):
-                            from headroom.proxy.responses_converter import (
-                                responses_items_to_messages,
-                            )
-
-                            converted_msgs, _ = responses_items_to_messages(ws_input)
-                            ws_msgs.extend(converted_msgs)
-
-                        try:
-                            async with stage_timer.measure("memory_context"):
-                                memory_context = await asyncio.wait_for(
-                                    self.memory_handler.search_and_format_context(
-                                        memory_user_id, ws_msgs
-                                    ),
-                                    timeout=RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS,
-                                )
-                        except asyncio.TimeoutError:
-                            memory_context = None
-                            logger.info(
-                                f"[{request_id}] WS Memory: Context lookup exceeded "
-                                f"{RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS:.1f}s; "
-                                f"continuing without it"
-                            )
-                        if memory_context:
-                            existing = ws_response_body.get("instructions") or ""
-                            if existing:
-                                ws_response_body["instructions"] = f"{existing}\n\n{memory_context}"
-                            else:
-                                ws_response_body["instructions"] = memory_context
-                            logger.info(
-                                f"[{request_id}] WS Memory: Injected {len(memory_context)} chars "
-                                f"of context into instructions"
-                            )
-
-                    # Inject memory tools (Responses API format)
-                    if self.memory_handler.config.inject_tools:
-                        ws_tools = ws_response_body.get("tools") or []
-                        ws_tools, mem_injected = self.memory_handler.inject_tools(
-                            ws_tools, "openai"
-                        )
-                        if mem_injected:
-                            converted_tools = []
-                            for t in ws_tools:
-                                if t.get("type") == "function" and "function" in t:
-                                    fn = t["function"]
-                                    converted_tools.append(
-                                        {
-                                            "type": "function",
-                                            "name": fn.get("name"),
-                                            "description": fn.get("description", ""),
-                                            "parameters": fn.get("parameters", {}),
-                                        }
-                                    )
-                                else:
-                                    converted_tools.append(t)
-                            ws_response_body["tools"] = converted_tools
-
-                            # Add memory instruction so the model uses
-                            # memory tools as persistent cross-session knowledge.
-                            mem_instruction = (
-                                "\n\n## Memory\n"
-                                "You have persistent memory via memory_search and "
-                                "memory_save tools. Memory stores knowledge across "
-                                "sessions — user info, project details, org context, "
-                                "decisions, architecture, conventions, anything worth "
-                                "remembering.\n\n"
-                                "- ALWAYS call memory_search BEFORE searching files "
-                                "when the user asks a question that could be answered "
-                                "from prior knowledge.\n"
-                                "- Call memory_save to store important facts, decisions, "
-                                "or context that would be useful in future sessions.\n"
-                                "- Memory is your first source of truth for anything "
-                                "not visible in the current conversation."
-                            )
-                            existing_instr = ws_response_body.get("instructions") or ""
-                            ws_response_body["instructions"] = existing_instr + mem_instruction
-                            logger.info(
-                                f"[{request_id}] WS Memory: Injected memory tools + instruction"
-                            )
-
-                    # Write back into envelope if it was wrapped
-                    if "response" in body and isinstance(body["response"], dict):
-                        body["response"] = ws_response_body
-                    else:
-                        body = ws_response_body
-
-                    first_msg_raw = json.dumps(body)
-                except Exception as e:
-                    logger.warning(f"[{request_id}] WS Memory injection failed: {e}")
-
-            # --- Connect to upstream OpenAI WebSocket ---
-            logger.info(f"[{request_id}] WS /v1/responses connecting to {upstream_url}")
-
-            # Use ssl=True to let the websockets library handle SSL natively.
-            # Manual ssl.create_default_context() + certifi doesn't load the
-            # Windows system cert store, causing HTTP 500 on wss:// connections.
-            use_ssl: bool | None = True if upstream_url.startswith("wss://") else None
-
-            ws_connected = False
-            ws_connect_attempts = max(1, getattr(self.config, "retry_max_attempts", 3))
-            ws_last_err: Exception | None = None
-            _upstream_connect_started = time.perf_counter()
-            _upstream_connect_recorded = False
-            _upstream_first_event_started: float | None = None
-
-            for ws_attempt in range(ws_connect_attempts):
-                try:
-                    async with websockets.connect(
-                        upstream_url,
-                        additional_headers=upstream_headers,
-                        subprotocols=(
-                            [websockets.Subprotocol(p) for p in client_subprotocols]
-                            if client_subprotocols and hasattr(websockets, "Subprotocol")
-                            else client_subprotocols or None
-                        ),
-                        ssl=use_ssl,
-                        open_timeout=max(30, self.config.connect_timeout_seconds * 3),
-                        close_timeout=10,
-                        ping_interval=20,
-                        ping_timeout=20,
-                    ) as upstream:
-                        ws_connected = True
-                        if not _upstream_connect_recorded:
-                            stage_timer.record(
-                                "upstream_connect",
-                                (time.perf_counter() - _upstream_connect_started) * 1000.0,
-                            )
-                            _upstream_connect_recorded = True
-                            _upstream_first_event_started = time.perf_counter()
-                        await upstream.send(first_msg_raw)
-
-                        # Unit 3: flag the upstream side flips on seeing
-                        # ``response.completed`` so the outer cause
-                        # classifier can prefer it over the raw
-                        # "upstream iterator ended" default.
-                        response_completed_seen = False
-                        # Captures the first exception surfaced by the
-                        # inner relay ``except`` blocks so the outer
-                        # classifier can still tell ``upstream_error``
-                        # from ``upstream_disconnect`` / ``response_completed``
-                        # even though the halves swallow and log.
-                        upstream_relay_error: BaseException | None = None
-                        client_relay_error: BaseException | None = None
-
-                        async def _client_to_upstream() -> None:
-                            nonlocal client_relay_error
-                            try:
-                                while True:
-                                    msg = await websocket.receive_text()
-                                    await upstream.send(msg)
-                            except asyncio.CancelledError:
-                                # Explicit cancel from the outer
-                                # orchestrator — re-raise so
-                                # ``t.cancelled()`` and ``t.exception()``
-                                # behave correctly in the caller.
-                                raise
-                            except Exception as relay_err:
-                                # Surface real errors to the classifier
-                                # without re-raising (existing fork
-                                # behavior: log and return so the
-                                # partner task can be cancelled
-                                # deterministically).
-                                if "WebSocketDisconnect" not in type(relay_err).__name__:
-                                    client_relay_error = relay_err
-                                    logger.debug(
-                                        f"[{request_id}] WS client→upstream relay ended: {relay_err}"
-                                    )
-                                with contextlib.suppress(Exception):
-                                    await upstream.close()
-
-                        async def _upstream_to_client() -> None:
-                            """Relay upstream→client with transparent memory tool handling.
-
-                            Uses a buffer-then-decide approach:
-                            1. Buffer events until first output item arrives
-                            2. If first output is a memory tool → suppress entire response,
-                               execute tools silently, send continuation upstream
-                            3. If first output is non-memory → flush buffer, stream normally
-                            4. Continuation response events are relayed to Codex seamlessly
-
-                            This prevents orphaned response.created events from confusing Codex.
-                            """
-                            from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES
-
-                            # Unit 3: surface response.completed observation
-                            # to the outer scope so the termination-cause
-                            # classifier can prefer ``response_completed``
-                            # over ``upstream_disconnect``.
-                            nonlocal response_completed_seen
-                            nonlocal upstream_relay_error
-
-                            memory_enabled = bool(self.memory_handler and memory_user_id)
-
-                            # Per-response state (reset after each response.completed)
-                            event_buffer: list[str] = []
-                            decided = False
-                            suppress_response = False
-                            pending_fcs: list[dict[str, Any]] = []
-                            resp_id: str | None = None
-
-                            def _reset() -> None:
-                                nonlocal decided, suppress_response, resp_id
-                                event_buffer.clear()
-                                decided = False
-                                suppress_response = False
-                                pending_fcs.clear()
-                                resp_id = None
-
-                            # The retry-loop variable is safe to close over here:
-                            # ``_upstream_to_client`` is defined and awaited within
-                            # a single iteration and never escapes.
-                            _first_event_started_at = _upstream_first_event_started  # noqa: B023
-
-                            try:
-                                async for msg in upstream:
-                                    if (
-                                        _first_event_started_at is not None
-                                        and "upstream_first_event" not in stage_timer
-                                    ):
-                                        stage_timer.record(
-                                            "upstream_first_event",
-                                            (time.perf_counter() - _first_event_started_at)
-                                            * 1000.0,
-                                        )
-                                    if isinstance(msg, bytes):
-                                        await websocket.send_bytes(msg)
-                                        continue
-                                    msg_str = msg if isinstance(msg, str) else str(msg)
-
-                                    if not memory_enabled:
-                                        await websocket.send_text(msg_str)
-                                        continue
-
-                                    # Parse event
-                                    try:
-                                        event = json.loads(msg_str)
-                                    except (json.JSONDecodeError, TypeError):
-                                        await websocket.send_text(msg_str)
-                                        continue
-
-                                    event_type = event.get("type", "")
-
-                                    # --- Phase 1: Buffer until first output item ---
-                                    if not decided:
-                                        event_buffer.append(msg_str)
-
-                                        if event_type == "response.output_item.added":
-                                            item = event.get("item", {})
-                                            if (
-                                                item.get("type") == "function_call"
-                                                and item.get("name") in MEMORY_TOOL_NAMES
-                                            ):
-                                                # Memory tool first → suppress entire response
-                                                suppress_response = True
-                                                decided = True
-                                                event_buffer.clear()
-                                                logger.info(
-                                                    f"[{request_id}] WS Memory: Detected "
-                                                    f"{item.get('name')} — suppressing response"
-                                                )
-                                            else:
-                                                # Non-memory first → flush buffer, pass through
-                                                decided = True
-                                                for buf in event_buffer:
-                                                    await websocket.send_text(buf)
-                                                event_buffer.clear()
-
-                                        elif event_type == "response.completed":
-                                            # No output items at all — flush
-                                            decided = True
-                                            for buf in event_buffer:
-                                                await websocket.send_text(buf)
-                                            event_buffer.clear()
-                                            _reset()
-                                            response_completed_seen = True
-
-                                        continue
-
-                                    # --- Phase 2a: Suppress mode (memory response) ---
-                                    if suppress_response:
-                                        if event_type == "response.output_item.done":
-                                            item = event.get("item", {})
-                                            if (
-                                                item.get("type") == "function_call"
-                                                and item.get("name") in MEMORY_TOOL_NAMES
-                                            ):
-                                                pending_fcs.append(item)
-
-                                        elif event_type == "response.completed":
-                                            response_completed_seen = True
-                                            resp = event.get("response", {})
-                                            resp_id = resp.get("id")
-
-                                            if pending_fcs:
-                                                logger.info(
-                                                    f"[{request_id}] WS Memory: Executing "
-                                                    f"{len(pending_fcs)} tool(s) transparently"
-                                                )
-
-                                                # Execute memory tool calls
-                                                tool_outputs: list[dict[str, Any]] = []
-                                                for fc in pending_fcs:
-                                                    call_id = fc.get("call_id", fc.get("id", ""))
-                                                    fc_name = fc.get("name", "")
-                                                    args_str = fc.get("arguments", "{}")
-                                                    try:
-                                                        fc_args = json.loads(args_str)
-                                                    except json.JSONDecodeError:
-                                                        fc_args = {}
-
-                                                    await self.memory_handler._ensure_initialized()
-                                                    if self.memory_handler._backend:
-                                                        result = await self.memory_handler._execute_memory_tool(
-                                                            fc_name,
-                                                            fc_args,
-                                                            memory_user_id,
-                                                            "openai",
-                                                        )
-                                                    else:
-                                                        result = json.dumps(
-                                                            {"error": "backend not ready"}
-                                                        )
-
-                                                    tool_outputs.append(
-                                                        {
-                                                            "type": "function_call_output",
-                                                            "call_id": call_id,
-                                                            "output": result,
-                                                        }
-                                                    )
-                                                    logger.info(
-                                                        f"[{request_id}] WS Memory: Executed "
-                                                        f"{fc_name} for user {memory_user_id}"
-                                                    )
-
-                                                # Send continuation upstream
-                                                cont: dict[str, Any] = {
-                                                    "type": "response.create",
-                                                    "response": {"input": tool_outputs},
-                                                }
-                                                if resp_id:
-                                                    cont["response"]["previous_response_id"] = (
-                                                        resp_id
-                                                    )
-                                                await upstream.send(json.dumps(cont))
-                                                logger.info(
-                                                    f"[{request_id}] WS Memory: Sent continuation "
-                                                    f"with {len(tool_outputs)} result(s)"
-                                                )
-
-                                            _reset()
-                                        # All events suppressed in this mode
-                                        continue
-
-                                    # --- Phase 2b: Pass-through mode ---
-                                    await websocket.send_text(msg_str)
-
-                            except asyncio.CancelledError:
-                                raise
-                            except Exception as relay_err:
-                                if "WebSocketDisconnect" not in type(relay_err).__name__:
-                                    # Capture for the outer classifier
-                                    # so ``upstream_error`` can be
-                                    # distinguished from a clean
-                                    # upstream disconnect.
-                                    upstream_relay_error = relay_err
-                                    logger.debug(
-                                        f"[{request_id}] WS upstream→client relay ended: {relay_err}"
-                                    )
-                            finally:
-                                with contextlib.suppress(Exception):
-                                    await websocket.close()
-
-                        # --- Unit 3: deterministic relay-task cancellation ---
-                        # Spawn each half as a named task so we can:
-                        #   (a) attach them to the session registry for
-                        #       ``/debug/ws-sessions``,
-                        #   (b) cancel the survivor explicitly when the
-                        #       first one exits, and
-                        #   (c) classify the termination cause for the
-                        #       duration histogram.
-                        client_task = asyncio.create_task(
-                            _client_to_upstream(),
-                            name=f"codex-ws-c2u-{session_id}",
-                        )
-                        upstream_task = asyncio.create_task(
-                            _upstream_to_client(),
-                            name=f"codex-ws-u2c-{session_id}",
-                        )
-                        relay_tasks = [client_task, upstream_task]
-                        if ws_sessions is not None:
-                            ws_sessions.attach_tasks(session_id, relay_tasks)
-                            metrics_for_tasks = getattr(self, "metrics", None)
-                            if metrics_for_tasks is not None and hasattr(
-                                metrics_for_tasks, "inc_active_relay_tasks"
-                            ):
-                                try:
-                                    metrics_for_tasks.inc_active_relay_tasks(len(relay_tasks))
-                                except Exception:  # pragma: no cover - defensive
-                                    pass
-
-                        try:
-                            done, pending = await asyncio.wait(
-                                {client_task, upstream_task},
-                                return_when=asyncio.FIRST_COMPLETED,
-                            )
-                            # Cancel the survivor so we don't leak the
-                            # partner task. Suppress the CancelledError
-                            # we just raised ourselves — any *other*
-                            # exception from the cancelled task is
-                            # already logged inside its own try/except.
-                            for t in pending:
-                                t.cancel()
-                            if pending:
-                                with contextlib.suppress(asyncio.CancelledError):
-                                    await asyncio.gather(*pending, return_exceptions=True)
-
-                            # Classify termination cause from whichever
-                            # task completed first. ``CancelledError``
-                            # can show up on the "done" side if the
-                            # handler itself was cancelled from outside
-                            # (e.g. server shutdown).
-                            for t in done:
-                                exc = None
-                                # Cancelled tasks raise CancelledError from
-                                # .exception(); surface it explicitly so the
-                                # downstream ``isinstance(exc, CancelledError)``
-                                # branches actually run. For any other
-                                # unexpected state (``InvalidStateError`` if
-                                # the task somehow isn't done — shouldn't
-                                # happen post-gather but defensive), we
-                                # suppress and leave ``exc`` as ``None``.
-                                if t.cancelled():
-                                    exc = asyncio.CancelledError()
-                                else:
-                                    with contextlib.suppress(asyncio.InvalidStateError):
-                                        exc = t.exception()
-                                task_name = t.get_name() or ""
-                                if t is client_task:
-                                    if client_relay_error is not None:
-                                        termination_cause = "client_error"
-                                    elif exc is None:
-                                        termination_cause = "client_disconnect"
-                                    elif isinstance(exc, asyncio.CancelledError):
-                                        termination_cause = "client_disconnect"
-                                    else:
-                                        # Distinguish legitimate client
-                                        # disconnect exceptions from
-                                        # real errors: WebSocketDisconnect
-                                        # is a normal client exit.
-                                        if "WebSocketDisconnect" in type(exc).__name__:
-                                            termination_cause = "client_disconnect"
-                                        else:
-                                            termination_cause = "client_error"
-                                elif t is upstream_task:
-                                    if upstream_relay_error is not None:
-                                        termination_cause = "upstream_error"
-                                        logger.debug(
-                                            f"[{request_id}] WS relay {task_name} "
-                                            f"raised: {upstream_relay_error!r}"
-                                        )
-                                    elif exc is None:
-                                        termination_cause = (
-                                            "response_completed"
-                                            if response_completed_seen
-                                            else "upstream_disconnect"
-                                        )
-                                    elif isinstance(exc, asyncio.CancelledError):
-                                        termination_cause = "upstream_disconnect"
-                                    else:
-                                        termination_cause = "upstream_error"
-                                        logger.debug(
-                                            f"[{request_id}] WS relay {task_name} raised: {exc!r}"
-                                        )
-                        finally:
-                            # In case anything above raised before the
-                            # cancel-and-await loop ran.
-                            for t in relay_tasks:
-                                if not t.done():
-                                    t.cancel()
-                            with contextlib.suppress(asyncio.CancelledError):
-                                await asyncio.gather(*relay_tasks, return_exceptions=True)
-
-                        logger.info(
-                            f"[{request_id}] WS /v1/responses completed "
-                            f"(tokens_saved={tokens_saved}, cause={termination_cause})"
-                        )
-                    break
-                except Exception as ws_err:
-                    if ws_connected:
-                        # WS was established but broke mid-stream — re-raise
-                        raise
-
-                    ws_last_err = ws_err
-                    if ws_attempt >= ws_connect_attempts - 1:
-                        break
-
-                    delay_with_jitter = jitter_delay_ms(
-                        self.config.retry_base_delay_ms,
-                        self.config.retry_max_delay_ms,
-                        ws_attempt,
-                    )
-                    logger.warning(
-                        f"[{request_id}] WS upstream connect failed "
-                        f"(attempt {ws_attempt + 1}/{ws_connect_attempts}): {ws_err}; "
-                        f"retrying in {delay_with_jitter:.0f}ms"
-                    )
-                    await asyncio.sleep(delay_with_jitter / 1000)
-
-            if not ws_connected:
-                # WS upgrade failed (HTTP 500 from OpenAI is common).
-                # Fall back to HTTP POST streaming and relay SSE events
-                # back over the client WebSocket transparently.
-                ws_err = ws_last_err or RuntimeError("unknown websocket connect failure")
-                _ws_detail = str(ws_err)
-                if hasattr(ws_err, "response"):
-                    resp_body = getattr(getattr(ws_err, "response", None), "body", b"")
-                    if resp_body:
-                        _ws_detail += f" | {resp_body[:300].decode('utf-8', errors='replace')}"
-                logger.warning(
-                    f"[{request_id}] WS upstream failed ({_ws_detail}), "
-                    f"falling back to HTTP POST streaming"
-                )
-                await self._ws_http_fallback(
-                    websocket, body, first_msg_raw, upstream_headers, request_id
-                )
-
-            # Record metrics
-            if tokens_saved > 0:
-                model_name = body.get("model", "unknown") if isinstance(body, dict) else "unknown"
-                await self.metrics.record_request(
-                    provider="openai",
-                    model=model_name,
-                    input_tokens=0,
-                    output_tokens=0,
-                    tokens_saved=tokens_saved,
-                    latency_ms=0,
-                )
-
-        except Exception as e:
-            if "WebSocketDisconnect" in type(e).__name__:
-                # Unit 3: client dropped the socket before or during
-                # relay. The registry classifier may already have set
-                # ``client_disconnect`` via the relay task exit path;
-                # preserve that, otherwise set it here.
-                if termination_cause == "unknown":
-                    termination_cause = "client_disconnect"
-            else:
-                # Extract response body from websockets InvalidStatus for better debugging
-                error_detail = str(e)
-                if hasattr(e, "response"):
-                    try:
-                        resp = e.response
-                        body_bytes = getattr(resp, "body", None) or b""
-                        if body_bytes:
-                            error_detail += (
-                                f" | body: {body_bytes[:500].decode('utf-8', errors='replace')}"
-                            )
-                    except Exception:
-                        pass
-                logger.error(f"[{request_id}] WS proxy error: {error_detail}")
-                if termination_cause == "unknown":
-                    termination_cause = "client_error"
-            with contextlib.suppress(Exception):
-                await websocket.close(code=1011, reason=str(e)[:120])
-        finally:
-            # Unit 2: emit structured per-session stage timings.
-            stage_timer.record(
-                "total_session",
-                (time.perf_counter() - session_started_at) * 1000.0,
-            )
-            # Unit 3: deregister the session before (or independently
-            # of) the stage-timings log so a failure there cannot leak
-            # the registry entry. ``deregister`` is idempotent, so a
-            # session that never registered is a no-op.
-            if ws_sessions is not None and session_handle is not None:
-                # Use deregister_and_count so the handle pop and the
-                # relay-task count are read atomically inside the
-                # registry. Capturing ``len(session_handle.relay_tasks)``
-                # separately before ``deregister`` would risk drift if
-                # the registry's bookkeeping ever changes.
-                _deregistered, released_tasks = ws_sessions.deregister_and_count(
-                    session_id, cause=termination_cause
-                )
-                session_duration_ms = (time.perf_counter() - session_started_at) * 1000.0
-                metrics_for_close = getattr(self, "metrics", None)
-                if metrics_for_close is not None:
-                    with contextlib.suppress(Exception):
-                        if hasattr(metrics_for_close, "dec_active_ws_sessions"):
-                            metrics_for_close.dec_active_ws_sessions()
-                        if released_tasks and hasattr(metrics_for_close, "dec_active_relay_tasks"):
-                            metrics_for_close.dec_active_relay_tasks(released_tasks)
-                        if hasattr(metrics_for_close, "record_ws_session_duration"):
-                            metrics_for_close.record_ws_session_duration(
-                                session_duration_ms, termination_cause
-                            )
-            await emit_stage_timings_log(
-                path="openai_responses_ws",
-                request_id=request_id,
-                session_id=session_id,
-                stage_timer=stage_timer,
-                expected_stages=(
-                    "accept",
-                    "first_client_frame",
-                    "upstream_connect",
-                    "upstream_first_event",
-                    "memory_context",
-                    "compression",
-                    "total_session",
-                ),
-                metrics=getattr(self, "metrics", None),
-            )
-
-    async def _ws_http_fallback(
-        self,
-        websocket: WebSocket,
-        body: dict[str, Any],
-        first_msg_raw: str,
-        upstream_headers: dict[str, str],
-        request_id: str,
-    ) -> None:
-        """Fall back to HTTP POST streaming when upstream WS fails.
-
-        Converts the WS ``response.create`` message to an HTTP POST to
-        ``/v1/responses?stream=true``, reads SSE events, and relays each
-        ``data:`` line as a WS text message to the client.  This makes
-        Codex work immediately instead of exhausting its WS retry budget.
-        """
-        # Route to correct endpoint based on auth mode
-        _lower = {k.lower() for k in upstream_headers}
-        if "chatgpt-account-id" in _lower:
-            http_url = "https://chatgpt.com/backend-api/codex/responses"
-        else:
-            http_url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/responses")
-
-        # Build HTTP body from the WS response.create payload.
-        # WS messages use {"type": "response.create", "response": {...}} wrapper.
-        # The HTTP POST endpoint expects the inner response object directly.
-        http_body: dict[str, Any]
-        try:
-            parsed = json.loads(first_msg_raw) if isinstance(first_msg_raw, str) else body
-        except (json.JSONDecodeError, TypeError):
-            parsed = body
-
-        # Normalize WebSocket response.create payload into the HTTP request body.
-        # Codex may send either:
-        # 1. {"type":"response.create","response":{...}}
-        # 2. {"type":"response.create", ...response fields...}
-        if isinstance(parsed, dict) and isinstance(parsed.get("response"), dict):
-            http_body = dict(parsed["response"])
-        elif isinstance(parsed, dict):
-            http_body = dict(parsed)
-            if http_body.get("type") == "response.create":
-                http_body.pop("type", None)
-        else:
-            http_body = body if isinstance(body, dict) else {}
-
-        # Some clients include response-ish metadata that the HTTP endpoint rejects.
-        if http_body.get("type") in {"response.create", "response"}:
-            http_body.pop("type", None)
-
-        # Ensure streaming is enabled so we get SSE events
-        http_body["stream"] = True
-
-        # Build HTTP headers from the upstream headers (already stripped of WS
-        # hop-by-hop headers by the caller).
-        http_headers = dict(upstream_headers)
-        http_headers["content-type"] = "application/json"
-
-        logger.debug(f"[{request_id}] WS→HTTP fallback POST to {http_url}")
-
-        try:
-            retry_attempts = max(1, getattr(self.config, "retry_max_attempts", 3))
-            for http_attempt in range(retry_attempts):
-                try:
-                    async with self.http_client.stream(
-                        "POST",
-                        http_url,
-                        headers=http_headers,
-                        json=http_body,
-                        timeout=120.0,
-                    ) as response:
-                        if response.status_code != 200:
-                            error_body = b""
-                            async for chunk in response.aiter_bytes():
-                                error_body += chunk
-                                if len(error_body) > 2000:
-                                    break
-                            error_text = error_body.decode("utf-8", errors="replace")
-                            logger.error(
-                                f"[{request_id}] WS→HTTP fallback got {response.status_code}: "
-                                f"{error_text[:500]}"
-                            )
-                            # Send error as WS message so client sees it
-                            error_event = {
-                                "type": "error",
-                                "error": {
-                                    "type": "server_error",
-                                    "message": f"Upstream returned {response.status_code}",
-                                },
-                            }
-                            await websocket.send_text(json.dumps(error_event))
-                            return
-
-                        # Relay SSE events as WS text messages
-                        buffer = ""
-                        async for chunk in response.aiter_text():
-                            buffer += chunk
-                            while "\n" in buffer:
-                                line, buffer = buffer.split("\n", 1)
-                                line = line.strip()
-                                if not line:
-                                    continue
-                                if line.startswith("data: "):
-                                    data = line[6:]
-                                    if data == "[DONE]":
-                                        continue
-                                    try:
-                                        await websocket.send_text(data)
-                                    except Exception:
-                                        return
-                                elif line.startswith("event: "):
-                                    # SSE event type — skip, the data line contains the type
-                                    continue
-
-                        # Flush any remaining data in buffer
-                        for line in buffer.strip().splitlines():
-                            line = line.strip()
-                            if line.startswith("data: ") and line[6:] != "[DONE]":
-                                with contextlib.suppress(Exception):
-                                    await websocket.send_text(line[6:])
-                        return
-                except (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) as http_err:
-                    if http_attempt >= retry_attempts - 1:
-                        raise
-
-                    delay_with_jitter = jitter_delay_ms(
-                        self.config.retry_base_delay_ms,
-                        self.config.retry_max_delay_ms,
-                        http_attempt,
-                    )
-                    logger.warning(
-                        f"[{request_id}] WS→HTTP fallback connect failed "
-                        f"(attempt {http_attempt + 1}/{retry_attempts}): {http_err}; "
-                        f"retrying in {delay_with_jitter:.0f}ms"
-                    )
-                    await asyncio.sleep(delay_with_jitter / 1000)
-
-        except Exception as http_err:
-            logger.error(f"[{request_id}] WS→HTTP fallback failed: {http_err}")
-            error_event = {
-                "type": "error",
-                "error": {
-                    "type": "server_error",
-                    "message": f"HTTP fallback failed: {http_err!s}"[:200],
-                },
-            }
-            with contextlib.suppress(Exception):
-                await websocket.send_text(json.dumps(error_event))
-        finally:
-            with contextlib.suppress(Exception):
-                await websocket.close()
-
-    async def handle_compress(self, request: Request) -> JSONResponse:
-        """Compress messages without calling an LLM.
-
-        POST /v1/compress
-        Body: {"messages": [...], "model": "...", "config": {}}
-        Returns compressed messages + metrics.
-        """
-        from fastapi.responses import JSONResponse
-
-        from headroom.proxy.helpers import _read_request_json
-
-        # Check bypass header
-        if request.headers.get("x-headroom-bypass", "").lower() == "true":
-            try:
-                body = await _read_request_json(request)
-            except (json.JSONDecodeError, ValueError) as e:
-                return JSONResponse(
-                    status_code=400,
-                    content={"error": f"Invalid request body: {e!s}"},
-                )
-            messages = body.get("messages", [])
-            return JSONResponse(
-                {
-                    "messages": messages,
-                    "tokens_before": 0,
-                    "tokens_after": 0,
-                    "tokens_saved": 0,
-                    "compression_ratio": 1.0,
-                    "transforms_applied": [],
-                    "ccr_hashes": [],
-                }
-            )
-
-        try:
-            body = await _read_request_json(request)
-        except Exception:
-            return JSONResponse(
-                status_code=400,
-                content={
-                    "error": {
-                        "type": "invalid_request",
-                        "message": "Invalid JSON in request body.",
-                    }
-                },
-            )
-
-        messages = body.get("messages")
-        model = body.get("model")
-
-        if messages is None:
-            return JSONResponse(
-                status_code=400,
-                content={
-                    "error": {
-                        "type": "invalid_request",
-                        "message": "Missing required field: messages",
-                    }
-                },
-            )
-
-        if model is None:
-            return JSONResponse(
-                status_code=400,
-                content={
-                    "error": {
-                        "type": "invalid_request",
-                        "message": "Missing required field: model",
-                    }
-                },
-            )
-
-        if not messages:
-            return JSONResponse(
-                {
-                    "messages": [],
-                    "tokens_before": 0,
-                    "tokens_after": 0,
-                    "tokens_saved": 0,
-                    "compression_ratio": 1.0,
-                    "transforms_applied": [],
-                    "ccr_hashes": [],
-                }
-            )
-
-        try:
-            # Use OpenAI pipeline (messages are in OpenAI format from TS SDK)
-            # Allow optional token_budget to override model's context limit
-            # (used by OpenClaw compact() and other callers that need tighter budgets)
-            token_budget = body.get("token_budget")
-            context_limit = (
-                token_budget
-                if token_budget and isinstance(token_budget, int)
-                else self.openai_provider.get_context_limit(model)
-            )
-            # Extract CompressConfig options from request body
-            compress_config = body.get("config", {})
-            compress_user_messages = compress_config.get("compress_user_messages", False)
-            target_ratio = compress_config.get("target_ratio")
-            protect_recent = compress_config.get("protect_recent")
-            protect_analysis_context = compress_config.get("protect_analysis_context")
-
-            pipeline_kwargs: dict = {"model_limit": context_limit}
-            if compress_user_messages:
-                pipeline_kwargs["compress_user_messages"] = True
-            if target_ratio is not None:
-                pipeline_kwargs["target_ratio"] = float(target_ratio)
-            if protect_recent is not None:
-                pipeline_kwargs["protect_recent"] = int(protect_recent)
-            if protect_analysis_context is not None:
-                pipeline_kwargs["protect_analysis_context"] = bool(protect_analysis_context)
-
-            result = self.openai_pipeline.apply(
-                messages=messages,
-                model=model,
-                **pipeline_kwargs,
-            )
-
-            return JSONResponse(
-                {
-                    "messages": result.messages,
-                    "tokens_before": result.tokens_before,
-                    "tokens_after": result.tokens_after,
-                    "tokens_saved": result.tokens_before - result.tokens_after,
-                    "compression_ratio": (
-                        result.tokens_after / result.tokens_before
-                        if result.tokens_before > 0
-                        else 1.0
-                    ),
-                    "transforms_applied": result.transforms_applied,
-                    "transforms_summary": result.transforms_summary,
-                    "ccr_hashes": result.markers_inserted,
-                }
-            )
-        except Exception as e:
-            logger.exception("Compression failed: %s", e)
-            return JSONResponse(
-                status_code=503,
-                content={
-                    "error": {
-                        "type": "compression_error",
-                        "message": str(e),
-                    }
-                },
-            )
-
-    async def handle_passthrough(
-        self,
-        request: Request,
-        base_url: str,
-        endpoint_name: str | None = None,
-        provider: str | None = None,
-    ) -> Response:
-        """Pass through request unchanged.
-
-        Args:
-            request: The incoming request
-            base_url: The upstream API base URL
-            endpoint_name: Optional name for stats tracking (e.g., "models", "embeddings")
-            provider: Optional provider name for stats (e.g., "openai", "anthropic", "gemini")
-        """
-        from fastapi.responses import Response
-
-        start_time = time.time()
-        path = request.url.path
-        url = build_copilot_upstream_url(base_url, path)
-
-        # Preserve query string parameters
-        if request.url.query:
-            url = f"{url}?{request.url.query}"
-
-        headers = dict(request.headers.items())
-        headers.pop("host", None)
-        headers.pop("accept-encoding", None)
-
-        body = await request.body()
-
-        headers = await apply_copilot_api_auth(headers, url=url)
-        response = await self.http_client.request(  # type: ignore[union-attr]
-            method=request.method,
-            url=url,
-            headers=headers,
-            content=body,
-        )
-
-        # Remove compression headers since httpx already decompressed the response
-        response_headers = dict(response.headers)
-        response_headers.pop("content-encoding", None)
-        response_headers.pop("content-length", None)  # Length changed after decompression
-
-        # Track stats for passthrough requests
-        if endpoint_name and provider:
-            latency_ms = (time.time() - start_time) * 1000
-            await self.metrics.record_request(
-                provider=provider,
-                model=f"passthrough:{endpoint_name}",
-                input_tokens=0,
-                output_tokens=0,
-                tokens_saved=0,
-                latency_ms=latency_ms,
-                cached=False,
-            )
-
-        return Response(
-            content=response.content,
-            status_code=response.status_code,
-            headers=response_headers,
-        )
-
-    async def handle_databricks_invocations(
-        self,
-        request: Request,
-        model: str,
-    ) -> Response | StreamingResponse:
-        """Handle Databricks native /serving-endpoints/{model}/invocations endpoint.
-
-        This enables using the Databricks CLI directly with Headroom:
-            databricks serving-endpoints query <model> --profile HEADROOM --json '{"messages": [...]}'
-
-        The request/response format is identical to OpenAI chat completions,
-        so we inject the model from the path and delegate to handle_openai_chat.
-        """
-        from fastapi.responses import JSONResponse
-
-        from headroom.proxy.helpers import _read_request_json
-
-        request_id = await self._next_request_id()
-
-        try:
-            body = await _read_request_json(request)
-        except Exception as e:
-            logger.error(f"[{request_id}] Failed to parse Databricks request body: {e}")
-            return JSONResponse(
-                status_code=400,
-                content={
-                    "error": {
-                        "message": f"Invalid JSON: {e}",
-                        "type": "invalid_request_error",
-                    }
-                },
-            )
-
-        # Inject model from path into body (Databricks CLI passes model in URL, not body)
-        body["model"] = model
-
-        logger.info(f"[{request_id}] Databricks invocation: model={model}")
-
-        # Create a new request with the modified body
-        # We reuse the OpenAI chat handler since the format is identical
-        from starlette.requests import Request as StarletteRequest
-
-        # Build new scope with the body already parsed
-        scope = dict(request.scope)
-
-        # Create a simple receive function that returns our modified body
-        body_bytes = json.dumps(body).encode()
-
-        async def receive():
-            return {"type": "http.request", "body": body_bytes}
-
-        modified_request = StarletteRequest(scope, receive)
-
-        # Delegate to the OpenAI chat handler (same format)
-        return await self.handle_openai_chat(modified_request)
+"""OpenAI handler mixin for HeadroomProxy.
+
+Contains all OpenAI Chat Completions, Responses API, and passthrough handlers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import contextlib
+import copy
+import json
+import logging
+import os
+import time
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from headroom.proxy.helpers import jitter_delay_ms
+from headroom.proxy.stage_timer import StageTimer, emit_stage_timings_log
+from headroom.proxy.ws_session_registry import (
+    TerminationCause,
+    WebSocketSessionRegistry,
+    WSSessionHandle,
+)
+
+if TYPE_CHECKING:
+    from fastapi import Request, WebSocket
+    from fastapi.responses import JSONResponse, Response, StreamingResponse
+
+import httpx
+
+from headroom.copilot_auth import apply_copilot_api_auth, build_copilot_upstream_url
+from headroom.pipeline import PipelineStage, summarize_routing_markers
+
+logger = logging.getLogger("headroom.proxy")
+
+
+# Interactive Responses turns are latency-sensitive. Fail open quickly rather
+# than holding the session hostage on memory lookup.
+RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS = 2.0
+
+# Cap the wait for the first client frame after the WS handshake completes.
+# A zombie or malicious client that accepts the upgrade but never sends the
+# first response.create frame would otherwise hold a slot indefinitely and
+# starve the session registry. 60 s is generous for real clients (Codex
+# typically sends the first frame within a few hundred milliseconds of the
+# accept) but short enough to bound the damage from a hung peer.
+WS_FIRST_FRAME_TIMEOUT_SECONDS = 60.0
+
+
+def _decode_openai_bearer_payload(headers: dict[str, str]) -> dict[str, Any] | None:
+    """Best-effort decode of an OpenAI OAuth bearer token payload.
+
+    OpenClaw's Codex OAuth flow may forward only the bearer token after the
+    provider base URL is overridden. In that case the explicit
+    ``ChatGPT-Account-ID`` header can be missing even though the JWT still
+    carries the account id we need to route to the ChatGPT Codex backend.
+    """
+    auth = headers.get("authorization") or headers.get("Authorization")
+    if not auth:
+        return None
+
+    scheme, _, token = auth.partition(" ")
+    if scheme.lower() != "bearer" or token.count(".") < 2:
+        return None
+
+    payload = token.split(".", 2)[1]
+    payload += "=" * (-len(payload) % 4)
+    # Intentionally no signature verification here: this is only a best-effort
+    # routing hint extractor. Upstream still performs the actual auth/authz checks.
+    try:
+        decoded = base64.urlsafe_b64decode(payload.encode("ascii"))
+        data = json.loads(decoded.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return None
+
+    return data if isinstance(data, dict) else None
+
+
+def _resolve_codex_routing_headers(headers: dict[str, str]) -> tuple[dict[str, str], bool]:
+    """Resolve ChatGPT Codex routing hints from explicit headers or OAuth JWT."""
+    resolved = dict(headers)
+    lower_lookup = {k.lower(): k for k in resolved}
+
+    if "chatgpt-account-id" in lower_lookup:
+        return resolved, True
+
+    payload = _decode_openai_bearer_payload(resolved)
+    auth_claims = payload.get("https://api.openai.com/auth") if isinstance(payload, dict) else None
+    account_id = auth_claims.get("chatgpt_account_id") if isinstance(auth_claims, dict) else None
+    if isinstance(account_id, str) and account_id.strip():
+        resolved["ChatGPT-Account-ID"] = account_id.strip()
+        return resolved, True
+
+    return resolved, False
+
+
+class OpenAIHandlerMixin:
+    """Mixin providing OpenAI API handler methods for HeadroomProxy."""
+
+    @staticmethod
+    def _strict_previous_turn_frozen_count(
+        messages: list[dict[str, Any]],
+        base_frozen_count: int,
+    ) -> int:
+        """Freeze all prior turns in cache mode; only final user turn is mutable."""
+        if not messages:
+            return base_frozen_count
+        final_idx = len(messages) - 1
+        if messages[final_idx].get("role") == "user":
+            return max(base_frozen_count, final_idx)
+        return len(messages)
+
+    @staticmethod
+    def _restore_frozen_prefix(
+        original_messages: list[dict[str, Any]],
+        candidate_messages: list[dict[str, Any]],
+        *,
+        frozen_message_count: int,
+    ) -> tuple[list[dict[str, Any]], int]:
+        """Force frozen prefix bytes to match original request exactly."""
+        if frozen_message_count <= 0 or not original_messages:
+            return candidate_messages, 0
+
+        frozen = min(frozen_message_count, len(original_messages))
+        restored = list(candidate_messages)
+
+        if len(restored) < frozen:
+            return list(original_messages[:frozen]) + restored, frozen
+
+        changed = 0
+        for idx in range(frozen):
+            if restored[idx] != original_messages[idx]:
+                restored[idx] = original_messages[idx]
+                changed += 1
+        return restored, changed
+
+    async def handle_openai_chat(
+        self,
+        request: Request,
+    ) -> Response | StreamingResponse:
+        """Handle OpenAI /v1/chat/completions endpoint."""
+        if not hasattr(self, "pipeline_extensions"):
+            from headroom.pipeline import PipelineExtensionManager
+
+            self.pipeline_extensions = PipelineExtensionManager(discover=False)
+
+        from fastapi import HTTPException
+        from fastapi.responses import JSONResponse, Response
+
+        from headroom.ccr import CCRToolInjector
+        from headroom.proxy.helpers import (
+            COMPRESSION_TIMEOUT_SECONDS,
+            MAX_MESSAGE_ARRAY_LENGTH,
+            MAX_REQUEST_BODY_SIZE,
+            _read_request_json,
+        )
+        from headroom.proxy.modes import is_cache_mode, is_token_mode
+        from headroom.tokenizers import get_tokenizer
+        from headroom.utils import extract_user_query
+
+        start_time = time.time()
+        request_id = await self._next_request_id()
+
+        # Check request body size
+        content_length = request.headers.get("content-length")
+        if content_length and int(content_length) > MAX_REQUEST_BODY_SIZE:
+            return JSONResponse(
+                status_code=413,
+                content={
+                    "error": {
+                        "message": f"Request body too large. Maximum size is {MAX_REQUEST_BODY_SIZE // (1024 * 1024)}MB",
+                        "type": "invalid_request_error",
+                        "code": "request_too_large",
+                    }
+                },
+            )
+
+        # Parse request
+        try:
+            body = await _read_request_json(request)
+        except (json.JSONDecodeError, ValueError) as e:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": {
+                        "message": f"Invalid request body: {e!s}",
+                        "type": "invalid_request_error",
+                        "code": "invalid_json",
+                    }
+                },
+            )
+        model = body.get("model", "unknown")
+        messages = body.get("messages", [])
+        original_client_messages = copy.deepcopy(messages)
+        input_event = self.pipeline_extensions.emit(
+            PipelineStage.INPUT_RECEIVED,
+            operation="proxy.request",
+            request_id=request_id,
+            provider="openai",
+            model=model,
+            messages=messages,
+            tools=body.get("tools"),
+            metadata={"path": "/v1/chat/completions", "stream": body.get("stream", False)},
+        )
+        if input_event.messages is not None:
+            messages = input_event.messages
+            original_client_messages = copy.deepcopy(messages)
+        if input_event.tools is not None:
+            body["tools"] = input_event.tools
+
+        # Validate message array size
+        if len(messages) > MAX_MESSAGE_ARRAY_LENGTH:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": {
+                        "message": f"Message array too large ({len(messages)} messages). "
+                        f"Maximum is {MAX_MESSAGE_ARRAY_LENGTH}.",
+                        "type": "invalid_request_error",
+                        "code": "invalid_request",
+                    }
+                },
+            )
+
+        stream = body.get("stream", False)
+
+        # Bypass: skip ALL compression for explicit opt-out
+        _bypass = (
+            request.headers.get("x-headroom-bypass", "").lower() == "true"
+            or request.headers.get("x-headroom-mode", "").lower() == "passthrough"
+        )
+        if _bypass:
+            logger.info(f"[{request_id}] Bypass: skipping compression (header)")
+
+        # Image compression: tile alignment + ML-based technique routing
+        if self.config.image_optimize and messages and not _bypass:
+            from headroom.proxy.helpers import _get_image_compressor
+
+            compressor = _get_image_compressor()
+            if compressor and compressor.has_images(messages):
+                messages = compressor.compress(messages, provider="openai")
+                if compressor.last_result:
+                    logger.info(
+                        f"[{request_id}] Image: {compressor.last_result.technique.value} "
+                        f"({compressor.last_result.savings_percent:.0f}% saved, "
+                        f"{compressor.last_result.original_tokens} → "
+                        f"{compressor.last_result.compressed_tokens} tokens)"
+                    )
+
+        headers = dict(request.headers.items())
+        headers.pop("host", None)
+        headers.pop("content-length", None)
+        # Strip accept-encoding so httpx negotiates its own encoding.
+        # Cloudflare Workers forward "br, zstd" which OpenAI may honor;
+        # if httpx lacks brotli support the response body is undecipherable → 502.
+        headers.pop("accept-encoding", None)
+        tags = self._extract_tags(headers)
+
+        # Memory: Get user ID when memory is enabled
+        memory_user_id: str | None = None
+        if self.memory_handler:
+            memory_user_id = headers.get(
+                "x-headroom-user-id",
+                os.environ.get("USER", os.environ.get("USERNAME", "default")),
+            )
+
+        # Rate limiting
+        if self.rate_limiter:
+            rate_key = headers.get("authorization", "default")[:20]
+            allowed, wait_seconds = await self.rate_limiter.check_request(rate_key)
+            if not allowed:
+                await self.metrics.record_rate_limited(provider="openai")
+                raise HTTPException(
+                    status_code=429,
+                    detail=f"Rate limited. Retry after {wait_seconds:.1f}s",
+                )
+
+        # Check cache
+        if self.cache and not stream:
+            cached = await self.cache.get(messages, model)
+            if cached:
+                self.pipeline_extensions.emit(
+                    PipelineStage.INPUT_CACHED,
+                    operation="proxy.request",
+                    request_id=request_id,
+                    provider="openai",
+                    model=model,
+                    messages=messages,
+                    metadata={"cache_hit": True, "path": "/v1/chat/completions"},
+                )
+                await self.metrics.record_request(
+                    provider="openai",
+                    model=model,
+                    input_tokens=0,
+                    output_tokens=0,
+                    tokens_saved=0,  # Savings already counted when response was cached
+                    latency_ms=(time.time() - start_time) * 1000,
+                    cached=True,
+                )
+
+                # Remove compression headers from cached response
+                response_headers = dict(cached.response_headers)
+                response_headers.pop("content-encoding", None)
+                response_headers.pop("content-length", None)
+
+                return Response(content=cached.response_body, headers=response_headers)
+
+        # Token counting
+        tokenizer = get_tokenizer(model)
+        original_tokens = tokenizer.count_messages(messages)
+
+        # Hook: pre_compress
+        _hook_biases = None
+        if self.config.hooks:
+            from headroom.hooks import CompressContext
+
+            _hook_ctx = CompressContext(model=model, provider="openai")
+            try:
+                messages = self.config.hooks.pre_compress(messages, _hook_ctx)
+                _hook_biases = self.config.hooks.compute_biases(messages, _hook_ctx)
+            except Exception as e:
+                logger.debug(f"[{request_id}] Hook error: {e}")
+
+        # Optimization
+        transforms_applied = []
+        pipeline_timing: dict[str, float] = {}
+        waste_signals_dict: dict[str, int] | None = None
+        optimized_messages = messages
+        optimized_tokens = original_tokens
+
+        # Get prefix cache tracker for this session
+        openai_session_id = self.session_tracker_store.compute_session_id(request, model, messages)
+        openai_prefix_tracker = self.session_tracker_store.get_or_create(
+            openai_session_id, "openai"
+        )
+        openai_frozen_count = openai_prefix_tracker.get_frozen_message_count()
+        if is_cache_mode(self.config.mode):
+            openai_frozen_count = self._strict_previous_turn_frozen_count(
+                original_client_messages,
+                openai_frozen_count,
+            )
+
+        _compression_failed = False
+        original_messages = messages  # Preserve for 400-retry fallback
+        _license_ok = self.usage_reporter.should_compress if self.usage_reporter else True
+        if self.config.optimize and messages and not _bypass and _license_ok:
+            try:
+                context_limit = self.openai_provider.get_context_limit(model)
+
+                if is_token_mode(self.config.mode):
+                    comp_cache = self._get_compression_cache(openai_session_id)
+
+                    # Zone 1: Swap cached compressed versions
+                    working_messages = comp_cache.apply_cached(messages)
+
+                    # Re-freeze boundary
+                    openai_frozen_count = comp_cache.compute_frozen_count(messages)
+
+                    result = await asyncio.wait_for(
+                        asyncio.to_thread(
+                            lambda: self.openai_pipeline.apply(
+                                messages=working_messages,
+                                model=model,
+                                model_limit=context_limit,
+                                context=extract_user_query(working_messages),
+                                frozen_message_count=openai_frozen_count,
+                                biases=_hook_biases,
+                            )
+                        ),
+                        timeout=COMPRESSION_TIMEOUT_SECONDS,
+                    )
+
+                    if result.messages != working_messages:
+                        comp_cache.update_from_result(messages, result.messages)
+
+                    # Always use pipeline result in token mode
+                    optimized_messages = result.messages
+                    transforms_applied = result.transforms_applied
+                    pipeline_timing = result.timing
+                    # Keep original_tokens as the REAL original (pre-Zone-1-swap)
+                    # so tokens_saved captures both Zone 1 + Zone 2 savings.
+                    optimized_tokens = result.tokens_after
+                else:
+                    result = await asyncio.wait_for(
+                        asyncio.to_thread(
+                            lambda: self.openai_pipeline.apply(
+                                messages=messages,
+                                model=model,
+                                model_limit=context_limit,
+                                context=extract_user_query(messages),
+                                frozen_message_count=openai_frozen_count,
+                                biases=_hook_biases,
+                            )
+                        ),
+                        timeout=COMPRESSION_TIMEOUT_SECONDS,
+                    )
+
+                    if result.messages != messages:
+                        optimized_messages = result.messages
+                        transforms_applied = result.transforms_applied
+                        pipeline_timing = result.timing
+                        original_tokens = result.tokens_before
+                        optimized_tokens = result.tokens_after
+
+                if result.waste_signals:
+                    waste_signals_dict = result.waste_signals.to_dict()
+            except Exception as e:
+                logger.warning(f"Optimization failed: {e}")
+                # Flag compression failure for observability
+                _compression_failed = True
+
+        # Guard: if "optimization" inflated tokens, revert to originals
+        if optimized_tokens > original_tokens:
+            logger.warning(
+                f"[{request_id}] Optimization inflated tokens "
+                f"({original_tokens} -> {optimized_tokens}), reverting to original messages"
+            )
+            optimized_messages = original_messages
+            optimized_tokens = original_tokens
+            transforms_applied = []
+
+        tokens_saved = original_tokens - optimized_tokens
+        optimization_latency = (time.time() - start_time) * 1000
+
+        routing_markers = summarize_routing_markers(transforms_applied)
+        if routing_markers:
+            routed_event = self.pipeline_extensions.emit(
+                PipelineStage.INPUT_ROUTED,
+                operation="proxy.request",
+                request_id=request_id,
+                provider="openai",
+                model=model,
+                messages=optimized_messages,
+                metadata={
+                    "routing_markers": routing_markers,
+                    "transforms_applied": transforms_applied,
+                },
+            )
+            if routed_event.messages is not None:
+                optimized_messages = routed_event.messages
+                optimized_tokens = tokenizer.count_messages(optimized_messages)
+                tokens_saved = original_tokens - optimized_tokens
+
+        compressed_event = self.pipeline_extensions.emit(
+            PipelineStage.INPUT_COMPRESSED,
+            operation="proxy.request",
+            request_id=request_id,
+            provider="openai",
+            model=model,
+            messages=optimized_messages,
+            metadata={
+                "tokens_before": original_tokens,
+                "tokens_after": optimized_tokens,
+                "transforms_applied": transforms_applied,
+            },
+        )
+        if compressed_event.messages is not None:
+            optimized_messages = compressed_event.messages
+            optimized_tokens = tokenizer.count_messages(optimized_messages)
+            tokens_saved = original_tokens - optimized_tokens
+
+        # Hook: post_compress
+        if self.config.hooks and tokens_saved > 0:
+            from headroom.hooks import CompressEvent
+
+            try:
+                self.config.hooks.post_compress(
+                    CompressEvent(
+                        tokens_before=original_tokens,
+                        tokens_after=optimized_tokens,
+                        tokens_saved=tokens_saved,
+                        compression_ratio=tokens_saved / original_tokens
+                        if original_tokens > 0
+                        else 0,
+                        transforms_applied=transforms_applied,
+                        model=model,
+                        provider="openai",
+                    )
+                )
+            except Exception as e:
+                logger.debug(f"[{request_id}] post_compress hook error: {e}")
+
+        # CCR Tool Injection: Inject retrieval tool if compression occurred
+        tools = body.get("tools")
+        _original_tools = tools  # Preserve for diagnostic / future retry
+        if (
+            self.config.ccr_inject_tool or self.config.ccr_inject_system_instructions
+        ) and not _bypass:
+            injector = CCRToolInjector(
+                provider="openai",
+                inject_tool=self.config.ccr_inject_tool,
+                inject_system_instructions=self.config.ccr_inject_system_instructions,
+            )
+            optimized_messages, tools, was_injected = injector.process_request(
+                optimized_messages, tools
+            )
+
+            if injector.has_compressed_content:
+                if was_injected:
+                    logger.debug(
+                        f"[{request_id}] CCR: Injected retrieval tool for hashes: {injector.detected_hashes}"
+                    )
+                else:
+                    logger.debug(
+                        f"[{request_id}] CCR: Tool already present (MCP?), skipped injection for hashes: {injector.detected_hashes}"
+                    )
+
+        # Query Echo: disabled — hurts prefix caching in long conversations.
+        if is_cache_mode(self.config.mode):
+            optimized_messages, restored_count = self._restore_frozen_prefix(
+                original_client_messages,
+                optimized_messages,
+                frozen_message_count=openai_frozen_count,
+            )
+            if restored_count > 0:
+                logger.warning(
+                    f"[{request_id}] Restored {restored_count} frozen prefix message(s) "
+                    "to preserve cache stability (openai)"
+                )
+
+        # Memory: inject context and tools for OpenAI requests
+        memory_context_injected = False
+        memory_tools_injected = False
+        if self.memory_handler and memory_user_id:
+            try:
+                # Inject memory context (search similar memories, add as system message)
+                if self.memory_handler.config.inject_context:
+                    memory_context = await self.memory_handler.search_and_format_context(
+                        memory_user_id, optimized_messages
+                    )
+                    if memory_context:
+                        # Prepend as system message for OpenAI format
+                        optimized_messages = [
+                            {"role": "system", "content": memory_context},
+                            *optimized_messages,
+                        ]
+                        memory_context_injected = True
+                        logger.info(
+                            f"[{request_id}] Memory: Injected {len(memory_context)} chars "
+                            f"of context for user {memory_user_id}"
+                        )
+
+                # Inject memory tools
+                if self.memory_handler.config.inject_tools:
+                    tools, mem_tools_injected = self.memory_handler.inject_tools(tools, "openai")
+                    if mem_tools_injected:
+                        memory_tools_injected = True
+                        logger.info(f"[{request_id}] Memory: Injected memory tools (openai)")
+            except Exception as e:
+                logger.warning(f"[{request_id}] Memory injection failed: {e}")
+
+        if memory_context_injected or memory_tools_injected:
+            remembered_event = self.pipeline_extensions.emit(
+                PipelineStage.INPUT_REMEMBERED,
+                operation="proxy.request",
+                request_id=request_id,
+                provider="openai",
+                model=model,
+                messages=optimized_messages,
+                tools=tools,
+                metadata={
+                    "memory_context_injected": memory_context_injected,
+                    "memory_tools_injected": memory_tools_injected,
+                },
+            )
+            if remembered_event.messages is not None:
+                optimized_messages = remembered_event.messages
+            if remembered_event.tools is not None:
+                tools = remembered_event.tools
+
+        body["messages"] = optimized_messages
+        if tools is not None:
+            body["tools"] = tools
+
+        presend_event = self.pipeline_extensions.emit(
+            PipelineStage.PRE_SEND,
+            operation="proxy.request",
+            request_id=request_id,
+            provider="openai",
+            model=model,
+            messages=optimized_messages,
+            tools=tools,
+            headers=headers,
+            metadata={"path": "/v1/chat/completions", "stream": stream},
+        )
+        if presend_event.messages is not None:
+            optimized_messages = presend_event.messages
+            body["messages"] = optimized_messages
+        if presend_event.tools is not None:
+            tools = presend_event.tools
+            body["tools"] = tools
+        if presend_event.headers is not None:
+            headers = presend_event.headers
+        optimized_tokens = tokenizer.count_messages(body["messages"])
+        tokens_saved = original_tokens - optimized_tokens
+
+        # Route through LiteLLM/any-llm backend if configured
+        if self.anthropic_backend is not None:
+            try:
+                if stream:
+                    self.pipeline_extensions.emit(
+                        PipelineStage.POST_SEND,
+                        operation="proxy.request",
+                        request_id=request_id,
+                        provider="openai",
+                        model=model,
+                        messages=body["messages"],
+                        tools=tools,
+                        metadata={"path": "/v1/chat/completions", "stream": True},
+                    )
+                    # Streaming: use stream_openai_message() → SSE events
+                    return await self._stream_openai_via_backend(
+                        body,
+                        headers,
+                        model,
+                        request_id,
+                        start_time,
+                        original_tokens,
+                        optimized_tokens,
+                        tokens_saved,
+                        transforms_applied,
+                        tags,
+                        optimization_latency,
+                        pipeline_timing=pipeline_timing,
+                    )
+                else:
+                    # Non-streaming: use send_openai_message() → JSON
+                    backend_response = await self.anthropic_backend.send_openai_message(
+                        body, headers
+                    )
+                    self.pipeline_extensions.emit(
+                        PipelineStage.POST_SEND,
+                        operation="proxy.request",
+                        request_id=request_id,
+                        provider="openai",
+                        model=model,
+                        messages=body["messages"],
+                        tools=tools,
+                        response=backend_response.body,
+                        metadata={
+                            "path": "/v1/chat/completions",
+                            "stream": False,
+                            "status_code": backend_response.status_code,
+                        },
+                    )
+                    self.pipeline_extensions.emit(
+                        PipelineStage.RESPONSE_RECEIVED,
+                        operation="proxy.request",
+                        request_id=request_id,
+                        provider="openai",
+                        model=model,
+                        response=backend_response.body,
+                        metadata={
+                            "path": "/v1/chat/completions",
+                            "stream": False,
+                            "status_code": backend_response.status_code,
+                        },
+                    )
+
+                    if backend_response.error:
+                        return JSONResponse(
+                            status_code=backend_response.status_code,
+                            content=backend_response.body,
+                        )
+
+                    # Track metrics
+                    total_latency = (time.time() - start_time) * 1000
+                    usage = backend_response.body.get("usage", {})
+                    output_tokens = usage.get("completion_tokens", 0)
+                    total_input_tokens = usage.get("prompt_tokens", optimized_tokens)
+
+                    await self.metrics.record_request(
+                        provider=self.anthropic_backend.name,
+                        model=model,
+                        input_tokens=total_input_tokens,
+                        output_tokens=output_tokens,
+                        tokens_saved=tokens_saved,
+                        latency_ms=total_latency,
+                        cached=False,
+                        overhead_ms=optimization_latency,
+                        pipeline_timing=pipeline_timing,
+                    )
+
+                    if tokens_saved > 0:
+                        logger.info(
+                            f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "
+                            f"(saved {tokens_saved:,} tokens) via {self.anthropic_backend.name}"
+                        )
+
+                    return JSONResponse(
+                        status_code=backend_response.status_code,
+                        content=backend_response.body,
+                    )
+            except Exception as e:
+                logger.error(f"[{request_id}] Backend error: {e}")
+                return JSONResponse(
+                    status_code=500,
+                    content={
+                        "error": {
+                            "message": str(e),
+                            "type": "api_error",
+                            "code": "backend_error",
+                        }
+                    },
+                )
+
+        # Direct OpenAI API (no backend configured)
+        url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/chat/completions")
+
+        try:
+            if stream:
+                # Inject stream_options to get usage stats in streaming response
+                # This allows accurate token counting instead of byte-based estimation
+                if "stream_options" not in body:
+                    body["stream_options"] = {"include_usage": True}
+                elif isinstance(body.get("stream_options"), dict):
+                    body["stream_options"]["include_usage"] = True
+
+                self.pipeline_extensions.emit(
+                    PipelineStage.POST_SEND,
+                    operation="proxy.request",
+                    request_id=request_id,
+                    provider="openai",
+                    model=model,
+                    messages=body["messages"],
+                    tools=tools,
+                    metadata={"path": "/v1/chat/completions", "stream": True},
+                )
+                return await self._stream_response(
+                    url,
+                    headers,
+                    body,
+                    "openai",
+                    model,
+                    request_id,
+                    original_tokens,
+                    optimized_tokens,
+                    tokens_saved,
+                    transforms_applied,
+                    tags,
+                    optimization_latency,
+                    pipeline_timing=pipeline_timing,
+                    prefix_tracker=openai_prefix_tracker,
+                )
+            else:
+                headers = await apply_copilot_api_auth(headers, url=url)
+                response = await self._retry_request("POST", url, headers, body)
+                self.pipeline_extensions.emit(
+                    PipelineStage.POST_SEND,
+                    operation="proxy.request",
+                    request_id=request_id,
+                    provider="openai",
+                    model=model,
+                    messages=body["messages"],
+                    tools=tools,
+                    response=response,
+                    metadata={
+                        "path": "/v1/chat/completions",
+                        "stream": False,
+                        "status_code": response.status_code,
+                    },
+                )
+                self.pipeline_extensions.emit(
+                    PipelineStage.RESPONSE_RECEIVED,
+                    operation="proxy.request",
+                    request_id=request_id,
+                    provider="openai",
+                    model=model,
+                    response=response,
+                    metadata={
+                        "path": "/v1/chat/completions",
+                        "stream": False,
+                        "status_code": response.status_code,
+                    },
+                )
+
+                # Full diagnostic dump on upstream errors (OpenAI handler)
+                if response.status_code >= 400:
+                    try:
+                        err_body = response.json()
+                        err_msg = err_body.get("error", {}).get("message", "")
+                        err_type = err_body.get("error", {}).get("type", "")
+                    except Exception:
+                        err_body = {"raw": response.text[:2000]}
+                        err_msg = str(response.text[:500])
+                        err_type = "parse_error"
+
+                    logger.warning(
+                        f"[{request_id}] UPSTREAM_ERROR "
+                        f"status={response.status_code} "
+                        f"error_type={err_type} "
+                        f"error_msg={err_msg!r} "
+                        f"model={model} "
+                        f"compressed={'yes' if transforms_applied else 'no'} "
+                        f"transforms={transforms_applied} "
+                        f"original_tokens={original_tokens} "
+                        f"optimized_tokens={optimized_tokens} "
+                        f"message_count={len(body.get('messages', []))} "
+                        f"stream={stream}"
+                    )
+
+                    try:
+                        from headroom import paths as _hr_paths
+
+                        debug_dir = _hr_paths.debug_400_dir()
+                        debug_dir.mkdir(parents=True, exist_ok=True)
+                        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+                        debug_file = debug_dir / f"{ts}_{request_id}.json"
+
+                        safe_headers = {}
+                        for k, v in headers.items():
+                            if k.lower() in ("x-api-key", "authorization"):
+                                safe_headers[k] = v[:12] + "..." if v else ""
+                            else:
+                                safe_headers[k] = v
+
+                        debug_payload = {
+                            "request_id": request_id,
+                            "timestamp": datetime.now().isoformat(),
+                            "status_code": response.status_code,
+                            "error_response": err_body,
+                            "model": model,
+                            "stream": stream,
+                            "headers": safe_headers,
+                            "compression": {
+                                "was_compressed": bool(transforms_applied),
+                                "transforms": transforms_applied,
+                                "original_tokens": original_tokens,
+                                "optimized_tokens": optimized_tokens,
+                                "tokens_saved": tokens_saved,
+                                "compression_failed": _compression_failed,
+                            },
+                            "tools_sent": body.get("tools"),
+                            "tool_count": len(body.get("tools") or []),
+                            "original_tool_count": len(_original_tools or []),
+                            "messages_sent": body.get("messages"),
+                            "message_count": len(body.get("messages", [])),
+                            "original_messages": (
+                                original_messages
+                                if original_messages is not body.get("messages")
+                                else "__same_as_sent__"
+                            ),
+                            "original_message_count": len(original_messages),
+                            "system_prompt": body.get("system"),
+                        }
+
+                        with open(debug_file, "w") as f:
+                            json.dump(debug_payload, f, indent=2, default=str)
+
+                        logger.warning(f"[{request_id}] Full debug dump: {debug_file}")
+                    except Exception as dump_err:
+                        logger.error(f"[{request_id}] Failed to write debug dump: {dump_err}")
+
+                total_latency = (time.time() - start_time) * 1000
+
+                total_input_tokens = optimized_tokens  # fallback
+                output_tokens = 0
+                cache_read_tokens = 0
+                resp_json = None
+                try:
+                    resp_json = response.json()
+                    usage = resp_json.get("usage", {})
+                    total_input_tokens = usage.get("prompt_tokens", optimized_tokens)
+                    output_tokens = usage.get("completion_tokens", 0)
+                    # OpenAI returns cached_tokens in prompt_tokens_details
+                    # These are charged at 50% of the input price
+                    prompt_details = usage.get("prompt_tokens_details") or {}
+                    cache_read_tokens = prompt_details.get("cached_tokens", 0)
+                except (KeyError, TypeError, AttributeError) as e:
+                    logger.debug(
+                        f"[{request_id}] Failed to extract cached tokens from OpenAI response: {e}"
+                    )
+
+                # Update prefix cache tracker for next turn
+                openai_prefix_tracker.update_from_response(
+                    cache_read_tokens=cache_read_tokens,
+                    cache_write_tokens=0,  # OpenAI doesn't report write tokens
+                    messages=optimized_messages,
+                )
+
+                # OpenAI has no write penalty — uncached = total - cached
+                uncached_input_tokens = max(0, total_input_tokens - cache_read_tokens)
+
+                if self.cost_tracker:
+                    self.cost_tracker.record_tokens(
+                        model,
+                        tokens_saved,
+                        optimized_tokens,
+                        cache_read_tokens=cache_read_tokens,
+                        uncached_tokens=uncached_input_tokens,
+                    )
+
+                # Memory: handle memory tool calls in OpenAI Chat Completions response.
+                # After executing tools, send a continuation request so the model
+                # can produce a final user-facing response (not just tool_calls).
+                if (
+                    self.memory_handler
+                    and memory_user_id
+                    and resp_json
+                    and response.status_code == 200
+                    and self.memory_handler.has_memory_tool_calls(resp_json, "openai")
+                ):
+                    try:
+                        tool_results = await self.memory_handler.handle_memory_tool_calls(
+                            resp_json, memory_user_id, "openai"
+                        )
+                        if tool_results:
+                            # Build continuation: original messages + assistant tool_calls + tool results
+                            assistant_msg = resp_json.get("choices", [{}])[0].get("message", {})
+                            continuation_messages = list(optimized_messages)
+                            continuation_messages.append(assistant_msg)
+                            continuation_messages.extend(tool_results)
+
+                            continuation_body = {
+                                **body,
+                                "messages": continuation_messages,
+                            }
+
+                            cont_response = await self._retry_request(
+                                "POST", url, headers, continuation_body
+                            )
+                            if cont_response.status_code == 200:
+                                resp_json = cont_response.json()
+                                response = cont_response
+
+                            logger.info(
+                                f"[{request_id}] Memory: Handled {len(tool_results)} "
+                                f"tool call(s) with continuation for user {memory_user_id}"
+                            )
+                    except Exception as e:
+                        logger.warning(f"[{request_id}] Memory tool handling failed: {e}")
+
+                # Cache
+                if self.cache and response.status_code == 200:
+                    await self.cache.set(
+                        messages,
+                        model,
+                        response.content,
+                        dict(response.headers),
+                        tokens_saved,
+                    )
+
+                # Capture Codex rate-limit window data from response headers
+                from headroom.subscription.codex_rate_limits import (
+                    get_codex_rate_limit_state,
+                )
+
+                get_codex_rate_limit_state().update_from_headers(dict(response.headers))
+
+                await self.metrics.record_request(
+                    provider="openai",
+                    model=model,
+                    input_tokens=total_input_tokens,
+                    output_tokens=output_tokens,
+                    tokens_saved=tokens_saved,
+                    latency_ms=total_latency,
+                    overhead_ms=optimization_latency,
+                    pipeline_timing=pipeline_timing,
+                    waste_signals=waste_signals_dict,
+                    cache_read_tokens=cache_read_tokens,
+                    uncached_input_tokens=uncached_input_tokens,
+                )
+
+                if tokens_saved > 0:
+                    logger.info(
+                        f"[{request_id}] {model}: {original_tokens:,} → {optimized_tokens:,} "
+                        f"(saved {tokens_saved:,} tokens)"
+                    )
+
+                # Remove compression headers since httpx already decompressed the response
+                response_headers = dict(response.headers)
+                response_headers.pop("content-encoding", None)
+                response_headers.pop("content-length", None)  # Length changed after decompression
+
+                # Inject Headroom compression metrics (for SaaS metering)
+                response_headers["x-headroom-tokens-before"] = str(original_tokens)
+                response_headers["x-headroom-tokens-after"] = str(optimized_tokens)
+                response_headers["x-headroom-tokens-saved"] = str(tokens_saved)
+                response_headers["x-headroom-model"] = model
+                if transforms_applied:
+                    response_headers["x-headroom-transforms"] = ",".join(transforms_applied)
+                if cache_read_tokens > 0:
+                    response_headers["x-headroom-cached"] = "true"
+                if _compression_failed:
+                    response_headers["x-headroom-compression-failed"] = "true"
+
+                return Response(
+                    content=response.content,
+                    status_code=response.status_code,
+                    headers=response_headers,
+                )
+        except Exception as e:
+            await self.metrics.record_failed(provider="openai")
+            # Log full error details internally for debugging
+            logger.error(f"[{request_id}] OpenAI request failed: {type(e).__name__}: {e}")
+            # Return sanitized error message to client (don't expose internal details)
+            return JSONResponse(
+                status_code=502,
+                content={
+                    "error": {
+                        "message": "An error occurred while processing your request. Please try again.",
+                        "type": "server_error",
+                        "code": "proxy_error",
+                    }
+                },
+            )
+
+    async def handle_openai_responses(
+        self,
+        request: Request,
+    ) -> Response | StreamingResponse:
+        """Handle OpenAI /v1/responses endpoint (new Responses API).
+
+        The Responses API differs from /v1/chat/completions:
+        - Input: `input` (string or array) instead of `messages`
+        - System: `instructions` instead of system message
+        - Output: `output[]` array instead of `choices[].message`
+        - State: `previous_response_id` for multi-turn
+        - Built-in tools: web_search, file_search, code_interpreter
+        """
+        from fastapi import HTTPException
+        from fastapi.responses import JSONResponse, Response
+
+        from headroom.proxy.helpers import (
+            COMPRESSION_TIMEOUT_SECONDS,
+            MAX_REQUEST_BODY_SIZE,
+            _read_request_json,
+        )
+        from headroom.proxy.responses_converter import (
+            messages_to_responses_items,
+            responses_items_to_messages,
+        )
+        from headroom.tokenizers import get_tokenizer
+        from headroom.utils import extract_user_query
+
+        start_time = time.time()
+        request_id = await self._next_request_id()
+
+        # Check request body size
+        content_length = request.headers.get("content-length")
+        if content_length and int(content_length) > MAX_REQUEST_BODY_SIZE:
+            return JSONResponse(
+                status_code=413,
+                content={
+                    "error": {
+                        "message": f"Request body too large. Maximum size is {MAX_REQUEST_BODY_SIZE // (1024 * 1024)}MB",
+                        "type": "invalid_request_error",
+                        "code": "request_too_large",
+                    }
+                },
+            )
+
+        # Parse request
+        try:
+            body = await _read_request_json(request)
+        except (json.JSONDecodeError, ValueError) as e:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": {
+                        "message": f"Invalid request body: {e!s}",
+                        "type": "invalid_request_error",
+                        "code": "invalid_json",
+                    }
+                },
+            )
+
+        model = body.get("model", "unknown")
+        stream = body.get("stream", False)
+
+        # Convert Responses API input to messages format for optimization.
+        # The Responses API uses a different item model (function_call,
+        # function_call_output, reasoning as top-level items) — we convert to
+        # Chat Completions messages for the pipeline, then convert back.
+
+        input_data = body.get("input", "")
+        instructions = body.get("instructions")
+        previous_response_id = body.get("previous_response_id")
+
+        messages: list[dict[str, Any]] = []
+        original_items: list[dict[str, Any]] | None = None
+        preserved_indices: list[int] = []
+
+        if instructions:
+            messages.append({"role": "system", "content": instructions})
+
+        if isinstance(input_data, str):
+            messages.append({"role": "user", "content": input_data})
+        elif isinstance(input_data, list):
+            original_items = input_data
+            converted, preserved_indices = responses_items_to_messages(input_data)
+            messages.extend(converted)
+
+        headers = dict(request.headers.items())
+        headers.pop("host", None)
+        headers.pop("content-length", None)
+        # Strip accept-encoding so httpx negotiates its own encoding.
+        # Cloudflare Workers forward "br, zstd" which OpenAI may honor;
+        # if httpx lacks brotli support the response body is undecipherable → 502.
+        headers.pop("accept-encoding", None)
+        tags = self._extract_tags(headers)
+
+        # Memory: Get user ID when memory is enabled
+        memory_user_id: str | None = None
+        if self.memory_handler:
+            memory_user_id = headers.get(
+                "x-headroom-user-id",
+                os.environ.get("USER", os.environ.get("USERNAME", "default")),
+            )
+
+        # Rate limiting
+        if self.rate_limiter:
+            rate_key = headers.get("authorization", "default")[:20]
+            allowed, wait_seconds = await self.rate_limiter.check_request(rate_key)
+            if not allowed:
+                await self.metrics.record_rate_limited(provider="openai")
+                raise HTTPException(
+                    status_code=429,
+                    detail=f"Rate limited. Retry after {wait_seconds:.1f}s",
+                )
+
+        # Token counting on converted messages
+        tokenizer = get_tokenizer(model)
+        original_tokens = tokenizer.count_messages(messages)
+
+        # Optimize: convert items → compress → convert back
+        tokens_saved = 0
+        transforms_applied: list[str] = []
+        optimized_messages = messages
+        optimized_tokens = original_tokens
+
+        _bypass = (
+            request.headers.get("x-headroom-bypass", "").lower() == "true"
+            or request.headers.get("x-headroom-mode", "").lower() == "passthrough"
+        )
+        _should_compress = (
+            self.config.optimize
+            and original_items is not None
+            and not previous_response_id
+            and not _bypass
+            and len(messages) > 1
+        )
+        _license_ok = self.usage_reporter.should_compress if self.usage_reporter else True
+
+        if _should_compress and _license_ok:
+            try:
+                context_limit = self.openai_provider.get_context_limit(model)
+                result = await asyncio.wait_for(
+                    asyncio.to_thread(
+                        lambda: self.openai_pipeline.apply(
+                            messages=messages,
+                            model=model,
+                            model_limit=context_limit,
+                            context=extract_user_query(messages),
+                        )
+                    ),
+                    timeout=COMPRESSION_TIMEOUT_SECONDS,
+                )
+                if result.messages != messages:
+                    optimized_messages = result.messages
+                    transforms_applied = result.transforms_applied
+                    original_tokens = result.tokens_before
+                    optimized_tokens = result.tokens_after
+            except Exception as e:
+                logger.warning(f"[{request_id}] Responses API optimization failed: {e}")
+
+        # Guard: if "optimization" inflated tokens, revert to originals
+        if optimized_tokens > original_tokens:
+            logger.warning(
+                f"[{request_id}] Optimization inflated tokens "
+                f"({original_tokens} -> {optimized_tokens}), reverting to original messages"
+            )
+            optimized_messages = messages
+            optimized_tokens = original_tokens
+            transforms_applied = []
+
+        tokens_saved = original_tokens - optimized_tokens
+        optimization_latency = (time.time() - start_time) * 1000
+
+        # Convert compressed messages back to Responses API items
+        if optimized_messages is not messages and original_items is not None:
+            opt_msgs = optimized_messages
+            # Strip system message (instructions) — it's separate in Responses API
+            if instructions and opt_msgs and opt_msgs[0].get("role") == "system":
+                body["instructions"] = opt_msgs[0]["content"]
+                opt_msgs = opt_msgs[1:]
+
+            body["input"] = messages_to_responses_items(opt_msgs, original_items, preserved_indices)
+
+        # Memory: inject context and tools for Responses API requests
+        if self.memory_handler and memory_user_id:
+            try:
+                # Inject memory context into instructions (Responses API system prompt)
+                if self.memory_handler.config.inject_context:
+                    try:
+                        memory_context = await asyncio.wait_for(
+                            self.memory_handler.search_and_format_context(
+                                memory_user_id, optimized_messages
+                            ),
+                            timeout=RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS,
+                        )
+                    except asyncio.TimeoutError:
+                        memory_context = None
+                        logger.info(
+                            f"[{request_id}] Memory context lookup exceeded "
+                            f"{RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS:.1f}s; continuing without it"
+                        )
+                    if memory_context:
+                        existing_instructions = body.get("instructions") or ""
+                        if existing_instructions:
+                            body["instructions"] = f"{existing_instructions}\n\n{memory_context}"
+                        else:
+                            body["instructions"] = memory_context
+                        logger.info(
+                            f"[{request_id}] Memory: Injected {len(memory_context)} chars "
+                            f"of context into instructions for user {memory_user_id}"
+                        )
+
+                # Inject memory tools (Responses API format)
+                if self.memory_handler.config.inject_tools:
+                    resp_tools = body.get("tools") or []
+                    resp_tools, mem_tools_injected = self.memory_handler.inject_tools(
+                        resp_tools, "openai"
+                    )
+                    if mem_tools_injected:
+                        # Convert Chat Completions format to Responses API format
+                        converted_tools = []
+                        for t in resp_tools:
+                            if t.get("type") == "function" and "function" in t:
+                                fn = t["function"]
+                                converted_tools.append(
+                                    {
+                                        "type": "function",
+                                        "name": fn.get("name"),
+                                        "description": fn.get("description", ""),
+                                        "parameters": fn.get("parameters", {}),
+                                    }
+                                )
+                            else:
+                                converted_tools.append(t)
+                        body["tools"] = converted_tools
+                        logger.info(
+                            f"[{request_id}] Memory: Injected memory tools (openai/responses)"
+                        )
+            except Exception as e:
+                logger.warning(f"[{request_id}] Memory injection failed (responses): {e}")
+
+        # /v1/responses is OpenAI-specific (Codex) — always routes direct.
+        # LiteLLM/AnyLLM backends use /v1/chat/completions or /v1/messages.
+        if self.anthropic_backend is not None:
+            logger.debug(
+                f"[{request_id}] /v1/responses always routes to OpenAI direct "
+                f"(backend '{self.anthropic_backend.name}' not used for Responses API)"
+            )
+
+        headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)
+
+        # Route to correct endpoint based on auth mode.
+        # ChatGPT session auth (codex login) uses chatgpt.com, not api.openai.com.
+        if is_chatgpt_auth:
+            url = "https://chatgpt.com/backend-api/codex/responses"
+        else:
+            url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/responses")
+
+        try:
+            if stream:
+                # Streaming for Responses API uses semantic events
+                return await self._stream_response(
+                    url,
+                    headers,
+                    body,
+                    "openai",
+                    model,
+                    request_id,
+                    original_tokens,
+                    optimized_tokens,
+                    tokens_saved,
+                    transforms_applied,
+                    tags,
+                    optimization_latency,
+                    memory_user_id=memory_user_id,
+                )
+            else:
+                headers = await apply_copilot_api_auth(headers, url=url)
+                response = await self._retry_request("POST", url, headers, body)
+                total_latency = (time.time() - start_time) * 1000
+
+                total_input_tokens = original_tokens  # fallback
+                output_tokens = 0
+                try:
+                    resp_json = response.json()
+                    usage = resp_json.get("usage", {})
+                    total_input_tokens = usage.get("input_tokens", original_tokens)
+                    output_tokens = usage.get("output_tokens", 0)
+                except (KeyError, TypeError, AttributeError) as e:
+                    logger.debug(
+                        f"[{request_id}] Failed to extract cached tokens from OpenAI passthrough response: {e}"
+                    )
+
+                # Memory: handle memory tool calls in Responses API response
+                if (
+                    self.memory_handler
+                    and memory_user_id
+                    and resp_json
+                    and response.status_code == 200
+                    and self.memory_handler.has_memory_tool_calls(resp_json, "openai")
+                ):
+                    try:
+                        # Extract function_call items from output
+                        from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES
+
+                        output_items = resp_json.get("output", [])
+                        memory_fc_items = [
+                            item
+                            for item in output_items
+                            if isinstance(item, dict)
+                            and item.get("type") == "function_call"
+                            and item.get("name") in MEMORY_TOOL_NAMES
+                        ]
+
+                        # Execute memory tool calls
+                        tool_outputs: list[dict[str, Any]] = []
+                        for fc in memory_fc_items:
+                            call_id = fc.get("call_id", fc.get("id", ""))
+                            name = fc.get("name", "")
+                            args_str = fc.get("arguments", "{}")
+                            try:
+                                args = json.loads(args_str)
+                            except json.JSONDecodeError:
+                                args = {}
+
+                            await self.memory_handler._ensure_initialized()
+                            if self.memory_handler._backend:
+                                result = await self.memory_handler._execute_memory_tool(
+                                    name, args, memory_user_id, "openai"
+                                )
+                            else:
+                                result = json.dumps({"error": "Memory backend not initialized"})
+
+                            tool_outputs.append(
+                                {
+                                    "type": "function_call_output",
+                                    "call_id": call_id,
+                                    "output": result,
+                                }
+                            )
+
+                        if tool_outputs:
+                            # Make continuation request with tool results
+                            response_id = resp_json.get("id")
+                            continuation_body = {
+                                "model": model,
+                                "input": tool_outputs,
+                            }
+                            if response_id:
+                                continuation_body["previous_response_id"] = response_id
+                            existing_tools = body.get("tools")
+                            if existing_tools:
+                                continuation_body["tools"] = existing_tools
+
+                            cont_response = await self._retry_request(
+                                "POST", url, headers, continuation_body
+                            )
+                            resp_json = cont_response.json()
+                            response = cont_response
+                            logger.info(
+                                f"[{request_id}] Memory: Handled {len(tool_outputs)} "
+                                f"tool call(s) with continuation for user {memory_user_id} (responses)"
+                            )
+                    except Exception as e:
+                        logger.warning(
+                            f"[{request_id}] Memory tool handling failed (responses): {e}"
+                        )
+
+                if self.cost_tracker:
+                    self.cost_tracker.record_tokens(model, tokens_saved, total_input_tokens)
+
+                await self.metrics.record_request(
+                    provider="openai",
+                    model=model,
+                    input_tokens=total_input_tokens,
+                    output_tokens=output_tokens,
+                    tokens_saved=tokens_saved,
+                    latency_ms=total_latency,
+                    overhead_ms=optimization_latency,
+                )
+
+                logger.info(f"[{request_id}] /v1/responses {model}: {total_input_tokens:,} tokens")
+
+                # Capture Codex rate-limit window data from response headers
+                from headroom.subscription.codex_rate_limits import (
+                    get_codex_rate_limit_state,
+                )
+
+                get_codex_rate_limit_state().update_from_headers(dict(response.headers))
+
+                # Remove compression headers
+                response_headers = dict(response.headers)
+                response_headers.pop("content-encoding", None)
+                response_headers.pop("content-length", None)
+
+                return Response(
+                    content=response.content,
+                    status_code=response.status_code,
+                    headers=response_headers,
+                )
+        except Exception as e:
+            await self.metrics.record_failed(provider="openai")
+            logger.error(f"[{request_id}] OpenAI responses request failed: {type(e).__name__}: {e}")
+            return JSONResponse(
+                status_code=502,
+                content={
+                    "error": {
+                        "message": "An error occurred while processing your request. Please try again.",
+                        "type": "server_error",
+                        "code": "proxy_error",
+                    }
+                },
+            )
+
+    async def handle_openai_responses_ws(self, websocket: WebSocket) -> None:
+        """WebSocket proxy for /v1/responses (Codex gpt-5.4+).
+
+        Newer Codex versions use WebSocket instead of HTTP POST for the
+        Responses API.  This handler:
+        1. Accepts the client WebSocket
+        2. Receives the first message (``response.create`` request)
+        3. Compresses the ``input`` array using the existing pipeline
+        4. Opens an upstream WebSocket to OpenAI
+        5. Sends the compressed request upstream
+        6. Relays all subsequent messages bidirectionally
+        """
+        from headroom.proxy.helpers import COMPRESSION_TIMEOUT_SECONDS
+        from headroom.tokenizers import get_tokenizer
+        from headroom.utils import extract_user_query
+
+        try:
+            import websockets
+        except ImportError:
+            await websocket.accept()
+            await websocket.close(
+                code=1011,
+                reason="websockets package not installed. pip install websockets",
+            )
+            return
+
+        request_id = await self._next_request_id()
+        session_id = uuid.uuid4().hex
+
+        # Stage-timer — captures per-stage durations for the structured
+        # log emitted on session close. Unit 2 instrumentation.
+        stage_timer = StageTimer()
+        session_started_at = time.perf_counter()
+
+        # Unit 3: initialize registry variables *before* accept so the
+        # outermost ``finally`` can rely on them existing even if
+        # registration itself fails for some reason.
+        ws_sessions: WebSocketSessionRegistry | None = getattr(self, "ws_sessions", None)
+        session_handle: WSSessionHandle | None = None
+        termination_cause: TerminationCause = "unknown"
+
+        # Forward client headers to upstream, adding required OpenAI-Beta header
+        ws_headers = dict(websocket.headers)
+
+        # Extract subprotocol from client — this is an application-level negotiation
+        # that MUST be forwarded end-to-end (unlike sec-websocket-key which is per-connection).
+        # Codex and OpenAI negotiate a subprotocol; stripping it causes OpenAI to return 500.
+        client_subprotocols: list[str] = []
+        raw_protocol = ws_headers.get("sec-websocket-protocol", "")
+        if raw_protocol:
+            client_subprotocols = [p.strip() for p in raw_protocol.split(",") if p.strip()]
+
+        # Accept client connection with the requested subprotocol
+        async with stage_timer.measure("accept"):
+            if client_subprotocols:
+                await websocket.accept(subprotocol=client_subprotocols[0])
+            else:
+                await websocket.accept()
+
+        # --- Unit 3: register the session as soon as accept succeeds ---
+        client_addr: str | None = None
+        client_info = getattr(websocket, "client", None)
+        if client_info is not None:
+            host = getattr(client_info, "host", None)
+            port = getattr(client_info, "port", None)
+            if host is not None and port is not None:
+                client_addr = f"{host}:{port}"
+            elif host is not None:
+                client_addr = str(host)
+        if ws_sessions is not None:
+            session_handle = WSSessionHandle(
+                session_id=session_id,
+                request_id=request_id,
+                client_addr=client_addr,
+                upstream_url=None,  # set below once upstream_url is computed
+            )
+            ws_sessions.register(session_handle)
+            metrics = getattr(self, "metrics", None)
+            if metrics is not None and hasattr(metrics, "inc_active_ws_sessions"):
+                try:
+                    metrics.inc_active_ws_sessions()
+                except Exception:  # pragma: no cover - defensive
+                    pass
+
+        # Forward all client headers except hop-by-hop / per-connection headers.
+        # These are WebSocket handshake mechanics that the `websockets` library
+        # generates fresh for the upstream connection — forwarding them would conflict.
+        # Everything else (auth, org, beta, user-agent, custom headers) is forwarded as-is.
+        _skip_headers = frozenset(
+            {
+                "host",  # must match upstream, not local proxy
+                "connection",  # hop-by-hop
+                "upgrade",  # hop-by-hop
+                "sec-websocket-key",  # per-connection cryptographic nonce
+                "sec-websocket-version",  # protocol version (websockets lib sets this)
+                "sec-websocket-extensions",  # per-connection negotiation
+                "sec-websocket-accept",  # server-side only
+                "sec-websocket-protocol",  # handled via subprotocols param below
+                "content-length",  # hop-by-hop
+                "transfer-encoding",  # hop-by-hop
+            }
+        )
+        upstream_headers: dict[str, str] = {}
+        for k, v in ws_headers.items():
+            if k.lower() not in _skip_headers:
+                upstream_headers[k] = v
+
+        upstream_headers, is_chatgpt_auth = _resolve_codex_routing_headers(upstream_headers)
+        _lower_headers = {k.lower(): v for k, v in upstream_headers.items()}
+
+        # Build upstream WebSocket URL based on auth mode
+        if is_chatgpt_auth:
+            # ChatGPT session auth → route to chatgpt.com backend
+            upstream_url = "wss://chatgpt.com/backend-api/codex/responses"
+            logger.debug(
+                f"[{request_id}] WS: ChatGPT session auth detected, routing to chatgpt.com"
+            )
+        else:
+            # API key auth → route to configured OpenAI API URL
+            base = self.OPENAI_API_URL
+            ws_base = base.replace("https://", "wss://").replace("http://", "ws://")
+            upstream_url = build_copilot_upstream_url(ws_base, "/v1/responses")
+
+        # Unit 3: attach the resolved upstream URL to the session handle.
+        if session_handle is not None:
+            session_handle.upstream_url = upstream_url
+
+        # Ensure Authorization header is present — fall back to OPENAI_API_KEY env var.
+        # Safety net for clients that don't forward auth headers via WebSocket upgrade.
+        if "authorization" not in _lower_headers:
+            api_key = os.environ.get("OPENAI_API_KEY")
+            if api_key:
+                upstream_headers["Authorization"] = f"Bearer {api_key}"
+                logger.debug(f"[{request_id}] WS: injected Authorization from OPENAI_API_KEY env")
+            else:
+                logger.warning(
+                    f"[{request_id}] WS: no Authorization header from client and "
+                    f"OPENAI_API_KEY not set — upstream will likely reject"
+                )
+
+        upstream_headers = await apply_copilot_api_auth(upstream_headers, url=upstream_url)
+
+        # Ensure the required beta header is present — OpenAI returns 500 without it.
+        # Codex sends `responses_websockets=2026-02-06`; only inject if missing entirely.
+        if "openai-beta" not in _lower_headers:
+            upstream_headers["OpenAI-Beta"] = "responses_websockets=2026-02-06"
+
+        logger.debug(
+            f"[{request_id}] WS upstream headers: "
+            f"{[k for k in upstream_headers if k.lower() != 'authorization']}, "
+            f"subprotocols={client_subprotocols}"
+        )
+
+        try:
+            # Receive the first message from client (the response.create request).
+            # Bound the wait with WS_FIRST_FRAME_TIMEOUT_SECONDS so a zombie
+            # client that opens the WS but never sends a frame cannot hold a
+            # session slot indefinitely. The StageTimer measurement still
+            # captures the elapsed time up to the timeout so operators can
+            # see the slow-client pattern in the stage-timings log.
+            try:
+                async with stage_timer.measure("first_client_frame"):
+                    first_msg_raw = await asyncio.wait_for(
+                        websocket.receive_text(),
+                        timeout=WS_FIRST_FRAME_TIMEOUT_SECONDS,
+                    )
+            except asyncio.TimeoutError:
+                logger.info(
+                    f"[{request_id}] WS first-frame timeout after "
+                    f"{WS_FIRST_FRAME_TIMEOUT_SECONDS:.0f}s; closing session "
+                    f"{session_id} (no client data)"
+                )
+                termination_cause = "client_timeout"
+                with contextlib.suppress(Exception):
+                    # 1001 (going away): server is cleanly terminating a slow
+                    # client, not an internal error.
+                    await websocket.close(code=1001, reason="first-frame timeout")
+                # Exit the outer try so the session-lifecycle ``finally`` runs
+                # deregister / metrics / stage-timings emission as usual.
+                return
+
+            # --- Optional: compress the input in the first message ---
+            body: dict[str, Any] = {}
+            try:
+                body = json.loads(first_msg_raw)
+                tokens_saved = 0
+                ws_request_body = body.get("response", body)
+                input_data = (
+                    ws_request_body.get("input") if isinstance(ws_request_body, dict) else None
+                )
+
+                should_compress = (
+                    self.config.optimize
+                    and isinstance(input_data, list)
+                    and len(input_data) > 1
+                    and not (
+                        ws_request_body.get("previous_response_id")
+                        if isinstance(ws_request_body, dict)
+                        else None
+                    )
+                )
+                if should_compress:
+                    try:
+                        from headroom.proxy.responses_converter import (
+                            messages_to_responses_items,
+                            responses_items_to_messages,
+                        )
+
+                        model = ws_request_body.get("model", "gpt-4o")
+                        converted, preserved = responses_items_to_messages(input_data)
+
+                        messages: list[dict[str, Any]] = []
+                        instructions = ws_request_body.get("instructions")
+                        if instructions:
+                            messages.append({"role": "system", "content": instructions})
+                        messages.extend(converted)
+
+                        tokenizer = get_tokenizer(model)
+                        original_tokens = tokenizer.count_messages(messages)
+
+                        context_limit = self.openai_provider.get_context_limit(model)
+                        async with stage_timer.measure("compression"):
+                            result = await asyncio.wait_for(
+                                asyncio.to_thread(
+                                    lambda: self.openai_pipeline.apply(
+                                        messages=messages,
+                                        model=model,
+                                        model_limit=context_limit,
+                                        context=extract_user_query(messages),
+                                    )
+                                ),
+                                timeout=COMPRESSION_TIMEOUT_SECONDS,
+                            )
+
+                        if result.messages != messages:
+                            opt = result.messages
+                            if instructions and opt and opt[0].get("role") == "system":
+                                ws_request_body["instructions"] = opt[0]["content"]
+                                opt = opt[1:]
+                            if result.tokens_after <= original_tokens:
+                                ws_request_body["input"] = messages_to_responses_items(
+                                    opt, input_data, preserved
+                                )
+                            else:
+                                logger.warning(
+                                    f"[{request_id}] WS optimization inflated tokens "
+                                    f"({original_tokens} -> {result.tokens_after}), reverting"
+                                )
+                            tokens_saved = max(0, original_tokens - result.tokens_after)
+                            if "response" in body and isinstance(body["response"], dict):
+                                body["response"] = ws_request_body
+                            else:
+                                body = ws_request_body
+                            first_msg_raw = json.dumps(body)
+                            logger.info(
+                                f"[{request_id}] WS /v1/responses compressed: "
+                                f"saved {tokens_saved} tokens"
+                            )
+                    except Exception as e:
+                        logger.warning(f"[{request_id}] WS compression failed: {e}")
+
+            except json.JSONDecodeError:
+                # Not JSON — pass through as-is
+                tokens_saved = 0
+
+            # --- Memory: inject context, tools, and instructions ---
+            memory_user_id: str | None = None
+            if self.memory_handler and body:
+                memory_user_id = ws_headers.get(
+                    "x-headroom-user-id",
+                    os.environ.get("USER", os.environ.get("USERNAME", "default")),
+                )
+                try:
+                    # Unwrap response.create envelope to access the response body
+                    ws_response_body = body.get("response", body)
+
+                    # Debug: log what Codex sends so we can see the full tool list
+                    existing_tool_names = [
+                        t.get("name") or t.get("function", {}).get("name", "?")
+                        for t in (ws_response_body.get("tools") or [])
+                    ]
+                    instr_preview = (ws_response_body.get("instructions") or "")[:200]
+                    logger.info(
+                        f"[{request_id}] WS Memory: Codex tools={existing_tool_names}, "
+                        f"instructions_len={len(ws_response_body.get('instructions') or '')}, "
+                        f"instructions_preview={instr_preview!r}"
+                    )
+
+                    # Inject memory context into instructions
+                    if self.memory_handler.config.inject_context:
+                        ws_input = ws_response_body.get("input", "")
+                        ws_instructions = ws_response_body.get("instructions")
+                        ws_msgs: list[dict[str, Any]] = []
+                        if ws_instructions:
+                            ws_msgs.append({"role": "system", "content": ws_instructions})
+                        if isinstance(ws_input, str) and ws_input:
+                            ws_msgs.append({"role": "user", "content": ws_input})
+                        elif isinstance(ws_input, list):
+                            from headroom.proxy.responses_converter import (
+                                responses_items_to_messages,
+                            )
+
+                            converted_msgs, _ = responses_items_to_messages(ws_input)
+                            ws_msgs.extend(converted_msgs)
+
+                        try:
+                            async with stage_timer.measure("memory_context"):
+                                memory_context = await asyncio.wait_for(
+                                    self.memory_handler.search_and_format_context(
+                                        memory_user_id, ws_msgs
+                                    ),
+                                    timeout=RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS,
+                                )
+                        except asyncio.TimeoutError:
+                            memory_context = None
+                            logger.info(
+                                f"[{request_id}] WS Memory: Context lookup exceeded "
+                                f"{RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS:.1f}s; "
+                                f"continuing without it"
+                            )
+                        if memory_context:
+                            existing = ws_response_body.get("instructions") or ""
+                            if existing:
+                                ws_response_body["instructions"] = f"{existing}\n\n{memory_context}"
+                            else:
+                                ws_response_body["instructions"] = memory_context
+                            logger.info(
+                                f"[{request_id}] WS Memory: Injected {len(memory_context)} chars "
+                                f"of context into instructions"
+                            )
+
+                    # Inject memory tools (Responses API format)
+                    if self.memory_handler.config.inject_tools:
+                        ws_tools = ws_response_body.get("tools") or []
+                        ws_tools, mem_injected = self.memory_handler.inject_tools(
+                            ws_tools, "openai"
+                        )
+                        if mem_injected:
+                            converted_tools = []
+                            for t in ws_tools:
+                                if t.get("type") == "function" and "function" in t:
+                                    fn = t["function"]
+                                    converted_tools.append(
+                                        {
+                                            "type": "function",
+                                            "name": fn.get("name"),
+                                            "description": fn.get("description", ""),
+                                            "parameters": fn.get("parameters", {}),
+                                        }
+                                    )
+                                else:
+                                    converted_tools.append(t)
+                            ws_response_body["tools"] = converted_tools
+
+                            # Add memory instruction so the model uses
+                            # memory tools as persistent cross-session knowledge.
+                            mem_instruction = (
+                                "\n\n## Memory\n"
+                                "You have persistent memory via memory_search and "
+                                "memory_save tools. Memory stores knowledge across "
+                                "sessions — user info, project details, org context, "
+                                "decisions, architecture, conventions, anything worth "
+                                "remembering.\n\n"
+                                "- ALWAYS call memory_search BEFORE searching files "
+                                "when the user asks a question that could be answered "
+                                "from prior knowledge.\n"
+                                "- Call memory_save to store important facts, decisions, "
+                                "or context that would be useful in future sessions.\n"
+                                "- Memory is your first source of truth for anything "
+                                "not visible in the current conversation."
+                            )
+                            existing_instr = ws_response_body.get("instructions") or ""
+                            ws_response_body["instructions"] = existing_instr + mem_instruction
+                            logger.info(
+                                f"[{request_id}] WS Memory: Injected memory tools + instruction"
+                            )
+
+                    # Write back into envelope if it was wrapped
+                    if "response" in body and isinstance(body["response"], dict):
+                        body["response"] = ws_response_body
+                    else:
+                        body = ws_response_body
+
+                    first_msg_raw = json.dumps(body)
+                except Exception as e:
+                    logger.warning(f"[{request_id}] WS Memory injection failed: {e}")
+
+            # --- Connect to upstream OpenAI WebSocket ---
+            logger.info(f"[{request_id}] WS /v1/responses connecting to {upstream_url}")
+
+            # Use ssl=True to let the websockets library handle SSL natively.
+            # Manual ssl.create_default_context() + certifi doesn't load the
+            # Windows system cert store, causing HTTP 500 on wss:// connections.
+            use_ssl: bool | None = True if upstream_url.startswith("wss://") else None
+
+            ws_connected = False
+            ws_connect_attempts = max(1, getattr(self.config, "retry_max_attempts", 3))
+            ws_last_err: Exception | None = None
+            _upstream_connect_started = time.perf_counter()
+            _upstream_connect_recorded = False
+            _upstream_first_event_started: float | None = None
+
+            for ws_attempt in range(ws_connect_attempts):
+                try:
+                    async with websockets.connect(
+                        upstream_url,
+                        additional_headers=upstream_headers,
+                        subprotocols=(
+                            [websockets.Subprotocol(p) for p in client_subprotocols]
+                            if client_subprotocols and hasattr(websockets, "Subprotocol")
+                            else client_subprotocols or None
+                        ),
+                        ssl=use_ssl,
+                        open_timeout=max(30, self.config.connect_timeout_seconds * 3),
+                        close_timeout=10,
+                        ping_interval=20,
+                        ping_timeout=20,
+                    ) as upstream:
+                        ws_connected = True
+                        if not _upstream_connect_recorded:
+                            stage_timer.record(
+                                "upstream_connect",
+                                (time.perf_counter() - _upstream_connect_started) * 1000.0,
+                            )
+                            _upstream_connect_recorded = True
+                            _upstream_first_event_started = time.perf_counter()
+                        await upstream.send(first_msg_raw)
+
+                        # Unit 3: flag the upstream side flips on seeing
+                        # ``response.completed`` so the outer cause
+                        # classifier can prefer it over the raw
+                        # "upstream iterator ended" default.
+                        response_completed_seen = False
+                        # Captures the first exception surfaced by the
+                        # inner relay ``except`` blocks so the outer
+                        # classifier can still tell ``upstream_error``
+                        # from ``upstream_disconnect`` / ``response_completed``
+                        # even though the halves swallow and log.
+                        upstream_relay_error: BaseException | None = None
+                        client_relay_error: BaseException | None = None
+
+                        async def _client_to_upstream() -> None:
+                            nonlocal client_relay_error
+                            try:
+                                while True:
+                                    msg = await websocket.receive_text()
+                                    await upstream.send(msg)
+                            except asyncio.CancelledError:
+                                # Explicit cancel from the outer
+                                # orchestrator — re-raise so
+                                # ``t.cancelled()`` and ``t.exception()``
+                                # behave correctly in the caller.
+                                raise
+                            except Exception as relay_err:
+                                # Surface real errors to the classifier
+                                # without re-raising (existing fork
+                                # behavior: log and return so the
+                                # partner task can be cancelled
+                                # deterministically).
+                                if "WebSocketDisconnect" not in type(relay_err).__name__:
+                                    client_relay_error = relay_err
+                                    logger.debug(
+                                        f"[{request_id}] WS client→upstream relay ended: {relay_err}"
+                                    )
+                                with contextlib.suppress(Exception):
+                                    await upstream.close()
+
+                        async def _upstream_to_client() -> None:
+                            """Relay upstream→client with transparent memory tool handling.
+
+                            Uses a buffer-then-decide approach:
+                            1. Buffer events until first output item arrives
+                            2. If first output is a memory tool → suppress entire response,
+                               execute tools silently, send continuation upstream
+                            3. If first output is non-memory → flush buffer, stream normally
+                            4. Continuation response events are relayed to Codex seamlessly
+
+                            This prevents orphaned response.created events from confusing Codex.
+                            """
+                            from headroom.proxy.memory_handler import MEMORY_TOOL_NAMES
+
+                            # Unit 3: surface response.completed observation
+                            # to the outer scope so the termination-cause
+                            # classifier can prefer ``response_completed``
+                            # over ``upstream_disconnect``.
+                            nonlocal response_completed_seen
+                            nonlocal upstream_relay_error
+
+                            memory_enabled = bool(self.memory_handler and memory_user_id)
+
+                            # Per-response state (reset after each response.completed)
+                            event_buffer: list[str] = []
+                            decided = False
+                            suppress_response = False
+                            pending_fcs: list[dict[str, Any]] = []
+                            resp_id: str | None = None
+
+                            def _reset() -> None:
+                                nonlocal decided, suppress_response, resp_id
+                                event_buffer.clear()
+                                decided = False
+                                suppress_response = False
+                                pending_fcs.clear()
+                                resp_id = None
+
+                            # The retry-loop variable is safe to close over here:
+                            # ``_upstream_to_client`` is defined and awaited within
+                            # a single iteration and never escapes.
+                            _first_event_started_at = _upstream_first_event_started  # noqa: B023
+
+                            try:
+                                async for msg in upstream:
+                                    if (
+                                        _first_event_started_at is not None
+                                        and "upstream_first_event" not in stage_timer
+                                    ):
+                                        stage_timer.record(
+                                            "upstream_first_event",
+                                            (time.perf_counter() - _first_event_started_at)
+                                            * 1000.0,
+                                        )
+                                    if isinstance(msg, bytes):
+                                        await websocket.send_bytes(msg)
+                                        continue
+                                    msg_str = msg if isinstance(msg, str) else str(msg)
+
+                                    if not memory_enabled:
+                                        await websocket.send_text(msg_str)
+                                        continue
+
+                                    # Parse event
+                                    try:
+                                        event = json.loads(msg_str)
+                                    except (json.JSONDecodeError, TypeError):
+                                        await websocket.send_text(msg_str)
+                                        continue
+
+                                    event_type = event.get("type", "")
+
+                                    # --- Phase 1: Buffer until first output item ---
+                                    if not decided:
+                                        event_buffer.append(msg_str)
+
+                                        if event_type == "response.output_item.added":
+                                            item = event.get("item", {})
+                                            if (
+                                                item.get("type") == "function_call"
+                                                and item.get("name") in MEMORY_TOOL_NAMES
+                                            ):
+                                                # Memory tool first → suppress entire response
+                                                suppress_response = True
+                                                decided = True
+                                                event_buffer.clear()
+                                                logger.info(
+                                                    f"[{request_id}] WS Memory: Detected "
+                                                    f"{item.get('name')} — suppressing response"
+                                                )
+                                            else:
+                                                # Non-memory first → flush buffer, pass through
+                                                decided = True
+                                                for buf in event_buffer:
+                                                    await websocket.send_text(buf)
+                                                event_buffer.clear()
+
+                                        elif event_type == "response.completed":
+                                            # No output items at all — flush
+                                            decided = True
+                                            for buf in event_buffer:
+                                                await websocket.send_text(buf)
+                                            event_buffer.clear()
+                                            _reset()
+                                            response_completed_seen = True
+
+                                        continue
+
+                                    # --- Phase 2a: Suppress mode (memory response) ---
+                                    if suppress_response:
+                                        if event_type == "response.output_item.done":
+                                            item = event.get("item", {})
+                                            if (
+                                                item.get("type") == "function_call"
+                                                and item.get("name") in MEMORY_TOOL_NAMES
+                                            ):
+                                                pending_fcs.append(item)
+
+                                        elif event_type == "response.completed":
+                                            response_completed_seen = True
+                                            resp = event.get("response", {})
+                                            resp_id = resp.get("id")
+
+                                            if pending_fcs:
+                                                logger.info(
+                                                    f"[{request_id}] WS Memory: Executing "
+                                                    f"{len(pending_fcs)} tool(s) transparently"
+                                                )
+
+                                                # Execute memory tool calls
+                                                tool_outputs: list[dict[str, Any]] = []
+                                                for fc in pending_fcs:
+                                                    call_id = fc.get("call_id", fc.get("id", ""))
+                                                    fc_name = fc.get("name", "")
+                                                    args_str = fc.get("arguments", "{}")
+                                                    try:
+                                                        fc_args = json.loads(args_str)
+                                                    except json.JSONDecodeError:
+                                                        fc_args = {}
+
+                                                    await self.memory_handler._ensure_initialized()
+                                                    if self.memory_handler._backend:
+                                                        result = await self.memory_handler._execute_memory_tool(
+                                                            fc_name,
+                                                            fc_args,
+                                                            memory_user_id,
+                                                            "openai",
+                                                        )
+                                                    else:
+                                                        result = json.dumps(
+                                                            {"error": "backend not ready"}
+                                                        )
+
+                                                    tool_outputs.append(
+                                                        {
+                                                            "type": "function_call_output",
+                                                            "call_id": call_id,
+                                                            "output": result,
+                                                        }
+                                                    )
+                                                    logger.info(
+                                                        f"[{request_id}] WS Memory: Executed "
+                                                        f"{fc_name} for user {memory_user_id}"
+                                                    )
+
+                                                # Send continuation upstream
+                                                cont: dict[str, Any] = {
+                                                    "type": "response.create",
+                                                    "response": {"input": tool_outputs},
+                                                }
+                                                if resp_id:
+                                                    cont["response"]["previous_response_id"] = (
+                                                        resp_id
+                                                    )
+                                                await upstream.send(json.dumps(cont))
+                                                logger.info(
+                                                    f"[{request_id}] WS Memory: Sent continuation "
+                                                    f"with {len(tool_outputs)} result(s)"
+                                                )
+
+                                            _reset()
+                                        # All events suppressed in this mode
+                                        continue
+
+                                    # --- Phase 2b: Pass-through mode ---
+                                    await websocket.send_text(msg_str)
+
+                            except asyncio.CancelledError:
+                                raise
+                            except Exception as relay_err:
+                                if "WebSocketDisconnect" not in type(relay_err).__name__:
+                                    # Capture for the outer classifier
+                                    # so ``upstream_error`` can be
+                                    # distinguished from a clean
+                                    # upstream disconnect.
+                                    upstream_relay_error = relay_err
+                                    logger.debug(
+                                        f"[{request_id}] WS upstream→client relay ended: {relay_err}"
+                                    )
+                            finally:
+                                with contextlib.suppress(Exception):
+                                    await websocket.close()
+
+                        # --- Unit 3: deterministic relay-task cancellation ---
+                        # Spawn each half as a named task so we can:
+                        #   (a) attach them to the session registry for
+                        #       ``/debug/ws-sessions``,
+                        #   (b) cancel the survivor explicitly when the
+                        #       first one exits, and
+                        #   (c) classify the termination cause for the
+                        #       duration histogram.
+                        client_task = asyncio.create_task(
+                            _client_to_upstream(),
+                            name=f"codex-ws-c2u-{session_id}",
+                        )
+                        upstream_task = asyncio.create_task(
+                            _upstream_to_client(),
+                            name=f"codex-ws-u2c-{session_id}",
+                        )
+                        relay_tasks = [client_task, upstream_task]
+                        if ws_sessions is not None:
+                            ws_sessions.attach_tasks(session_id, relay_tasks)
+                            metrics_for_tasks = getattr(self, "metrics", None)
+                            if metrics_for_tasks is not None and hasattr(
+                                metrics_for_tasks, "inc_active_relay_tasks"
+                            ):
+                                try:
+                                    metrics_for_tasks.inc_active_relay_tasks(len(relay_tasks))
+                                except Exception:  # pragma: no cover - defensive
+                                    pass
+
+                        try:
+                            done, pending = await asyncio.wait(
+                                {client_task, upstream_task},
+                                return_when=asyncio.FIRST_COMPLETED,
+                            )
+                            # Cancel the survivor so we don't leak the
+                            # partner task. Suppress the CancelledError
+                            # we just raised ourselves — any *other*
+                            # exception from the cancelled task is
+                            # already logged inside its own try/except.
+                            for t in pending:
+                                t.cancel()
+                            if pending:
+                                with contextlib.suppress(asyncio.CancelledError):
+                                    await asyncio.gather(*pending, return_exceptions=True)
+
+                            # Classify termination cause from whichever
+                            # task completed first. ``CancelledError``
+                            # can show up on the "done" side if the
+                            # handler itself was cancelled from outside
+                            # (e.g. server shutdown).
+                            for t in done:
+                                exc = None
+                                # Cancelled tasks raise CancelledError from
+                                # .exception(); surface it explicitly so the
+                                # downstream ``isinstance(exc, CancelledError)``
+                                # branches actually run. For any other
+                                # unexpected state (``InvalidStateError`` if
+                                # the task somehow isn't done — shouldn't
+                                # happen post-gather but defensive), we
+                                # suppress and leave ``exc`` as ``None``.
+                                if t.cancelled():
+                                    exc = asyncio.CancelledError()
+                                else:
+                                    with contextlib.suppress(asyncio.InvalidStateError):
+                                        exc = t.exception()
+                                task_name = t.get_name() or ""
+                                if t is client_task:
+                                    if client_relay_error is not None:
+                                        termination_cause = "client_error"
+                                    elif exc is None:
+                                        termination_cause = "client_disconnect"
+                                    elif isinstance(exc, asyncio.CancelledError):
+                                        termination_cause = "client_disconnect"
+                                    else:
+                                        # Distinguish legitimate client
+                                        # disconnect exceptions from
+                                        # real errors: WebSocketDisconnect
+                                        # is a normal client exit.
+                                        if "WebSocketDisconnect" in type(exc).__name__:
+                                            termination_cause = "client_disconnect"
+                                        else:
+                                            termination_cause = "client_error"
+                                elif t is upstream_task:
+                                    if upstream_relay_error is not None:
+                                        termination_cause = "upstream_error"
+                                        logger.debug(
+                                            f"[{request_id}] WS relay {task_name} "
+                                            f"raised: {upstream_relay_error!r}"
+                                        )
+                                    elif exc is None:
+                                        termination_cause = (
+                                            "response_completed"
+                                            if response_completed_seen
+                                            else "upstream_disconnect"
+                                        )
+                                    elif isinstance(exc, asyncio.CancelledError):
+                                        termination_cause = "upstream_disconnect"
+                                    else:
+                                        termination_cause = "upstream_error"
+                                        logger.debug(
+                                            f"[{request_id}] WS relay {task_name} raised: {exc!r}"
+                                        )
+                        finally:
+                            # In case anything above raised before the
+                            # cancel-and-await loop ran.
+                            for t in relay_tasks:
+                                if not t.done():
+                                    t.cancel()
+                            with contextlib.suppress(asyncio.CancelledError):
+                                await asyncio.gather(*relay_tasks, return_exceptions=True)
+
+                        logger.info(
+                            f"[{request_id}] WS /v1/responses completed "
+                            f"(tokens_saved={tokens_saved}, cause={termination_cause})"
+                        )
+                    break
+                except Exception as ws_err:
+                    if ws_connected:
+                        # WS was established but broke mid-stream — re-raise
+                        raise
+
+                    ws_last_err = ws_err
+                    if ws_attempt >= ws_connect_attempts - 1:
+                        break
+
+                    delay_with_jitter = jitter_delay_ms(
+                        self.config.retry_base_delay_ms,
+                        self.config.retry_max_delay_ms,
+                        ws_attempt,
+                    )
+                    logger.warning(
+                        f"[{request_id}] WS upstream connect failed "
+                        f"(attempt {ws_attempt + 1}/{ws_connect_attempts}): {ws_err}; "
+                        f"retrying in {delay_with_jitter:.0f}ms"
+                    )
+                    await asyncio.sleep(delay_with_jitter / 1000)
+
+            if not ws_connected:
+                # WS upgrade failed (HTTP 500 from OpenAI is common).
+                # Fall back to HTTP POST streaming and relay SSE events
+                # back over the client WebSocket transparently.
+                ws_err = ws_last_err or RuntimeError("unknown websocket connect failure")
+                _ws_detail = str(ws_err)
+                if hasattr(ws_err, "response"):
+                    resp_body = getattr(getattr(ws_err, "response", None), "body", b"")
+                    if resp_body:
+                        _ws_detail += f" | {resp_body[:300].decode('utf-8', errors='replace')}"
+                logger.warning(
+                    f"[{request_id}] WS upstream failed ({_ws_detail}), "
+                    f"falling back to HTTP POST streaming"
+                )
+                await self._ws_http_fallback(
+                    websocket, body, first_msg_raw, upstream_headers, request_id
+                )
+
+            # Record metrics
+            if tokens_saved > 0:
+                model_name = body.get("model", "unknown") if isinstance(body, dict) else "unknown"
+                await self.metrics.record_request(
+                    provider="openai",
+                    model=model_name,
+                    input_tokens=0,
+                    output_tokens=0,
+                    tokens_saved=tokens_saved,
+                    latency_ms=0,
+                )
+
+        except Exception as e:
+            if "WebSocketDisconnect" in type(e).__name__:
+                # Unit 3: client dropped the socket before or during
+                # relay. The registry classifier may already have set
+                # ``client_disconnect`` via the relay task exit path;
+                # preserve that, otherwise set it here.
+                if termination_cause == "unknown":
+                    termination_cause = "client_disconnect"
+            else:
+                # Extract response body from websockets InvalidStatus for better debugging
+                error_detail = str(e)
+                if hasattr(e, "response"):
+                    try:
+                        resp = e.response
+                        body_bytes = getattr(resp, "body", None) or b""
+                        if body_bytes:
+                            error_detail += (
+                                f" | body: {body_bytes[:500].decode('utf-8', errors='replace')}"
+                            )
+                    except Exception:
+                        pass
+                logger.error(f"[{request_id}] WS proxy error: {error_detail}")
+                if termination_cause == "unknown":
+                    termination_cause = "client_error"
+            with contextlib.suppress(Exception):
+                await websocket.close(code=1011, reason=str(e)[:120])
+        finally:
+            # Unit 2: emit structured per-session stage timings.
+            stage_timer.record(
+                "total_session",
+                (time.perf_counter() - session_started_at) * 1000.0,
+            )
+            # Unit 3: deregister the session before (or independently
+            # of) the stage-timings log so a failure there cannot leak
+            # the registry entry. ``deregister`` is idempotent, so a
+            # session that never registered is a no-op.
+            if ws_sessions is not None and session_handle is not None:
+                # Use deregister_and_count so the handle pop and the
+                # relay-task count are read atomically inside the
+                # registry. Capturing ``len(session_handle.relay_tasks)``
+                # separately before ``deregister`` would risk drift if
+                # the registry's bookkeeping ever changes.
+                _deregistered, released_tasks = ws_sessions.deregister_and_count(
+                    session_id, cause=termination_cause
+                )
+                session_duration_ms = (time.perf_counter() - session_started_at) * 1000.0
+                metrics_for_close = getattr(self, "metrics", None)
+                if metrics_for_close is not None:
+                    with contextlib.suppress(Exception):
+                        if hasattr(metrics_for_close, "dec_active_ws_sessions"):
+                            metrics_for_close.dec_active_ws_sessions()
+                        if released_tasks and hasattr(metrics_for_close, "dec_active_relay_tasks"):
+                            metrics_for_close.dec_active_relay_tasks(released_tasks)
+                        if hasattr(metrics_for_close, "record_ws_session_duration"):
+                            metrics_for_close.record_ws_session_duration(
+                                session_duration_ms, termination_cause
+                            )
+            await emit_stage_timings_log(
+                path="openai_responses_ws",
+                request_id=request_id,
+                session_id=session_id,
+                stage_timer=stage_timer,
+                expected_stages=(
+                    "accept",
+                    "first_client_frame",
+                    "upstream_connect",
+                    "upstream_first_event",
+                    "memory_context",
+                    "compression",
+                    "total_session",
+                ),
+                metrics=getattr(self, "metrics", None),
+            )
+
+    async def _ws_http_fallback(
+        self,
+        websocket: WebSocket,
+        body: dict[str, Any],
+        first_msg_raw: str,
+        upstream_headers: dict[str, str],
+        request_id: str,
+    ) -> None:
+        """Fall back to HTTP POST streaming when upstream WS fails.
+
+        Converts the WS ``response.create`` message to an HTTP POST to
+        ``/v1/responses?stream=true``, reads SSE events, and relays each
+        ``data:`` line as a WS text message to the client.  This makes
+        Codex work immediately instead of exhausting its WS retry budget.
+        """
+        # Route to correct endpoint based on auth mode
+        _lower = {k.lower() for k in upstream_headers}
+        if "chatgpt-account-id" in _lower:
+            http_url = "https://chatgpt.com/backend-api/codex/responses"
+        else:
+            http_url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/responses")
+
+        # Build HTTP body from the WS response.create payload.
+        # WS messages use {"type": "response.create", "response": {...}} wrapper.
+        # The HTTP POST endpoint expects the inner response object directly.
+        http_body: dict[str, Any]
+        try:
+            parsed = json.loads(first_msg_raw) if isinstance(first_msg_raw, str) else body
+        except (json.JSONDecodeError, TypeError):
+            parsed = body
+
+        # Normalize WebSocket response.create payload into the HTTP request body.
+        # Codex may send either:
+        # 1. {"type":"response.create","response":{...}}
+        # 2. {"type":"response.create", ...response fields...}
+        if isinstance(parsed, dict) and isinstance(parsed.get("response"), dict):
+            http_body = dict(parsed["response"])
+        elif isinstance(parsed, dict):
+            http_body = dict(parsed)
+            if http_body.get("type") == "response.create":
+                http_body.pop("type", None)
+        else:
+            http_body = body if isinstance(body, dict) else {}
+
+        # Some clients include response-ish metadata that the HTTP endpoint rejects.
+        if http_body.get("type") in {"response.create", "response"}:
+            http_body.pop("type", None)
+
+        # Ensure streaming is enabled so we get SSE events
+        http_body["stream"] = True
+
+        # Build HTTP headers from the upstream headers (already stripped of WS
+        # hop-by-hop headers by the caller).
+        http_headers = dict(upstream_headers)
+        http_headers["content-type"] = "application/json"
+
+        logger.debug(f"[{request_id}] WS→HTTP fallback POST to {http_url}")
+
+        try:
+            retry_attempts = max(1, getattr(self.config, "retry_max_attempts", 3))
+            for http_attempt in range(retry_attempts):
+                try:
+                    async with self.http_client.stream(
+                        "POST",
+                        http_url,
+                        headers=http_headers,
+                        json=http_body,
+                        timeout=120.0,
+                    ) as response:
+                        if response.status_code != 200:
+                            error_body = b""
+                            async for chunk in response.aiter_bytes():
+                                error_body += chunk
+                                if len(error_body) > 2000:
+                                    break
+                            error_text = error_body.decode("utf-8", errors="replace")
+                            logger.error(
+                                f"[{request_id}] WS→HTTP fallback got {response.status_code}: "
+                                f"{error_text[:500]}"
+                            )
+                            # Send error as WS message so client sees it
+                            error_event = {
+                                "type": "error",
+                                "error": {
+                                    "type": "server_error",
+                                    "message": f"Upstream returned {response.status_code}",
+                                },
+                            }
+                            await websocket.send_text(json.dumps(error_event))
+                            return
+
+                        # Relay SSE events as WS text messages
+                        buffer = ""
+                        async for chunk in response.aiter_text():
+                            buffer += chunk
+                            while "\n" in buffer:
+                                line, buffer = buffer.split("\n", 1)
+                                line = line.strip()
+                                if not line:
+                                    continue
+                                if line.startswith("data: "):
+                                    data = line[6:]
+                                    if data == "[DONE]":
+                                        continue
+                                    try:
+                                        await websocket.send_text(data)
+                                    except Exception:
+                                        return
+                                elif line.startswith("event: "):
+                                    # SSE event type — skip, the data line contains the type
+                                    continue
+
+                        # Flush any remaining data in buffer
+                        for line in buffer.strip().splitlines():
+                            line = line.strip()
+                            if line.startswith("data: ") and line[6:] != "[DONE]":
+                                with contextlib.suppress(Exception):
+                                    await websocket.send_text(line[6:])
+                        return
+                except (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) as http_err:
+                    if http_attempt >= retry_attempts - 1:
+                        raise
+
+                    delay_with_jitter = jitter_delay_ms(
+                        self.config.retry_base_delay_ms,
+                        self.config.retry_max_delay_ms,
+                        http_attempt,
+                    )
+                    logger.warning(
+                        f"[{request_id}] WS→HTTP fallback connect failed "
+                        f"(attempt {http_attempt + 1}/{retry_attempts}): {http_err}; "
+                        f"retrying in {delay_with_jitter:.0f}ms"
+                    )
+                    await asyncio.sleep(delay_with_jitter / 1000)
+
+        except Exception as http_err:
+            logger.error(f"[{request_id}] WS→HTTP fallback failed: {http_err}")
+            error_event = {
+                "type": "error",
+                "error": {
+                    "type": "server_error",
+                    "message": f"HTTP fallback failed: {http_err!s}"[:200],
+                },
+            }
+            with contextlib.suppress(Exception):
+                await websocket.send_text(json.dumps(error_event))
+        finally:
+            with contextlib.suppress(Exception):
+                await websocket.close()
+
+    async def handle_compress(self, request: Request) -> JSONResponse:
+        """Compress messages without calling an LLM.
+
+        POST /v1/compress
+        Body: {"messages": [...], "model": "...", "config": {}}
+        Returns compressed messages + metrics.
+        """
+        from fastapi.responses import JSONResponse
+
+        from headroom.proxy.helpers import _read_request_json
+
+        # Check bypass header
+        if request.headers.get("x-headroom-bypass", "").lower() == "true":
+            try:
+                body = await _read_request_json(request)
+            except (json.JSONDecodeError, ValueError) as e:
+                return JSONResponse(
+                    status_code=400,
+                    content={"error": f"Invalid request body: {e!s}"},
+                )
+            messages = body.get("messages", [])
+            return JSONResponse(
+                {
+                    "messages": messages,
+                    "tokens_before": 0,
+                    "tokens_after": 0,
+                    "tokens_saved": 0,
+                    "compression_ratio": 1.0,
+                    "transforms_applied": [],
+                    "ccr_hashes": [],
+                }
+            )
+
+        try:
+            body = await _read_request_json(request)
+        except Exception:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": {
+                        "type": "invalid_request",
+                        "message": "Invalid JSON in request body.",
+                    }
+                },
+            )
+
+        messages = body.get("messages")
+        model = body.get("model")
+
+        if messages is None:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": {
+                        "type": "invalid_request",
+                        "message": "Missing required field: messages",
+                    }
+                },
+            )
+
+        if model is None:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": {
+                        "type": "invalid_request",
+                        "message": "Missing required field: model",
+                    }
+                },
+            )
+
+        if not messages:
+            return JSONResponse(
+                {
+                    "messages": [],
+                    "tokens_before": 0,
+                    "tokens_after": 0,
+                    "tokens_saved": 0,
+                    "compression_ratio": 1.0,
+                    "transforms_applied": [],
+                    "ccr_hashes": [],
+                }
+            )
+
+        try:
+            # Use OpenAI pipeline (messages are in OpenAI format from TS SDK)
+            # Allow optional token_budget to override model's context limit
+            # (used by OpenClaw compact() and other callers that need tighter budgets)
+            token_budget = body.get("token_budget")
+            context_limit = (
+                token_budget
+                if token_budget and isinstance(token_budget, int)
+                else self.openai_provider.get_context_limit(model)
+            )
+            # Extract CompressConfig options from request body
+            compress_config = body.get("config", {})
+            compress_user_messages = compress_config.get("compress_user_messages", False)
+            target_ratio = compress_config.get("target_ratio")
+            protect_recent = compress_config.get("protect_recent")
+            protect_analysis_context = compress_config.get("protect_analysis_context")
+
+            pipeline_kwargs: dict = {"model_limit": context_limit}
+            if compress_user_messages:
+                pipeline_kwargs["compress_user_messages"] = True
+            if target_ratio is not None:
+                pipeline_kwargs["target_ratio"] = float(target_ratio)
+            if protect_recent is not None:
+                pipeline_kwargs["protect_recent"] = int(protect_recent)
+            if protect_analysis_context is not None:
+                pipeline_kwargs["protect_analysis_context"] = bool(protect_analysis_context)
+
+            result = self.openai_pipeline.apply(
+                messages=messages,
+                model=model,
+                **pipeline_kwargs,
+            )
+
+            return JSONResponse(
+                {
+                    "messages": result.messages,
+                    "tokens_before": result.tokens_before,
+                    "tokens_after": result.tokens_after,
+                    "tokens_saved": result.tokens_before - result.tokens_after,
+                    "compression_ratio": (
+                        result.tokens_after / result.tokens_before
+                        if result.tokens_before > 0
+                        else 1.0
+                    ),
+                    "transforms_applied": result.transforms_applied,
+                    "transforms_summary": result.transforms_summary,
+                    "ccr_hashes": result.markers_inserted,
+                }
+            )
+        except Exception as e:
+            logger.exception("Compression failed: %s", e)
+            return JSONResponse(
+                status_code=503,
+                content={
+                    "error": {
+                        "type": "compression_error",
+                        "message": str(e),
+                    }
+                },
+            )
+
+    async def handle_passthrough(
+        self,
+        request: Request,
+        base_url: str,
+        endpoint_name: str | None = None,
+        provider: str | None = None,
+    ) -> Response:
+        """Pass through request unchanged.
+
+        Args:
+            request: The incoming request
+            base_url: The upstream API base URL
+            endpoint_name: Optional name for stats tracking (e.g., "models", "embeddings")
+            provider: Optional provider name for stats (e.g., "openai", "anthropic", "gemini")
+        """
+        from fastapi.responses import Response
+
+        start_time = time.time()
+        path = request.url.path
+        url = build_copilot_upstream_url(base_url, path)
+
+        # Preserve query string parameters
+        if request.url.query:
+            url = f"{url}?{request.url.query}"
+
+        headers = dict(request.headers.items())
+        headers.pop("host", None)
+        headers.pop("accept-encoding", None)
+
+        body = await request.body()
+
+        headers = await apply_copilot_api_auth(headers, url=url)
+        response = await self.http_client.request(  # type: ignore[union-attr]
+            method=request.method,
+            url=url,
+            headers=headers,
+            content=body,
+        )
+
+        # Remove compression headers since httpx already decompressed the response
+        response_headers = dict(response.headers)
+        response_headers.pop("content-encoding", None)
+        response_headers.pop("content-length", None)  # Length changed after decompression
+
+        # Track stats for passthrough requests
+        if endpoint_name and provider:
+            latency_ms = (time.time() - start_time) * 1000
+            await self.metrics.record_request(
+                provider=provider,
+                model=f"passthrough:{endpoint_name}",
+                input_tokens=0,
+                output_tokens=0,
+                tokens_saved=0,
+                latency_ms=latency_ms,
+                cached=False,
+            )
+
+        return Response(
+            content=response.content,
+            status_code=response.status_code,
+            headers=response_headers,
+        )
+
+    async def handle_databricks_invocations(
+        self,
+        request: Request,
+        model: str,
+    ) -> Response | StreamingResponse:
+        """Handle Databricks native /serving-endpoints/{model}/invocations endpoint.
+
+        This enables using the Databricks CLI directly with Headroom:
+            databricks serving-endpoints query <model> --profile HEADROOM --json '{"messages": [...]}'
+
+        The request/response format is identical to OpenAI chat completions,
+        so we inject the model from the path and delegate to handle_openai_chat.
+        """
+        from fastapi.responses import JSONResponse
+
+        from headroom.proxy.helpers import _read_request_json
+
+        request_id = await self._next_request_id()
+
+        try:
+            body = await _read_request_json(request)
+        except Exception as e:
+            logger.error(f"[{request_id}] Failed to parse Databricks request body: {e}")
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": {
+                        "message": f"Invalid JSON: {e}",
+                        "type": "invalid_request_error",
+                    }
+                },
+            )
+
+        # Inject model from path into body (Databricks CLI passes model in URL, not body)
+        body["model"] = model
+
+        logger.info(f"[{request_id}] Databricks invocation: model={model}")
+
+        # Create a new request with the modified body
+        # We reuse the OpenAI chat handler since the format is identical
+        from starlette.requests import Request as StarletteRequest
+
+        # Build new scope with the body already parsed
+        scope = dict(request.scope)
+
+        # Create a simple receive function that returns our modified body
+        body_bytes = json.dumps(body).encode()
+
+        async def receive():
+            return {"type": "http.request", "body": body_bytes}
+
+        modified_request = StarletteRequest(scope, receive)
+
+        # Delegate to the OpenAI chat handler (same format)
+        return await self.handle_openai_chat(modified_request)
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 8cdcbe7145cbd02e5fc9ec860ca8a7bffd7829cf..256776c70f94f178900fc9b624f26d9a939d7fd2 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -1,2620 +1,2620 @@
-"""Headroom Proxy Server - Production Ready.
-
-A full-featured LLM proxy with optimization, caching, rate limiting,
-and observability.
-
-Features:
-- Context optimization (SmartCrusher, CacheAligner, RollingWindow)
-- Semantic caching (save costs on repeated queries)
-- Rate limiting (token bucket)
-- Retry with exponential backoff
-- Cost tracking and budgets
-- Request tagging and metadata
-- Provider fallback
-- Prometheus metrics
-- Full request/response logging
-
-Usage:
-    python -m headroom.proxy.server --port 8787
-
-    # With Claude Code:
-    ANTHROPIC_BASE_URL=http://localhost:8787 claude
-"""
-
-from __future__ import annotations
-
-import argparse
-import asyncio
-import json
-import logging
-import os
-import sys
-import time
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, cast
-
-if TYPE_CHECKING:
-    from ..backends.base import Backend
-    from ..cache.compression_cache import CompressionCache
-    from ..memory.tracker import MemoryTracker
-
-
-import httpx
-
-try:
-    import uvicorn
-    from fastapi import Depends, FastAPI, HTTPException, Request, Response
-    from fastapi.middleware.cors import CORSMiddleware
-    from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
-
-    FASTAPI_AVAILABLE = True
-except ImportError:
-    FASTAPI_AVAILABLE = False
-
-# Add parent to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent.parent))
-
-from headroom._version import __version__
-from headroom.cache.compression_feedback import get_compression_feedback
-from headroom.cache.compression_store import get_compression_store
-from headroom.ccr import (
-    CCR_TOOL_NAME,
-    # Batch processing
-    CCRResponseHandler,
-    CCRToolInjector,
-    ContextTracker,
-    ContextTrackerConfig,
-    ResponseHandlerConfig,
-    parse_tool_call,
-)
-from headroom.config import (
-    CacheAlignerConfig,
-    CCRConfig,
-    IntelligentContextConfig,
-    ReadLifecycleConfig,
-    RollingWindowConfig,
-    SmartCrusherConfig,
-)
-from headroom.dashboard import get_dashboard_html
-from headroom.observability import (
-    LangfuseTracingConfig,
-    OTelMetricsConfig,
-    configure_langfuse_tracing,
-    configure_otel_metrics,
-    get_langfuse_tracing_status,
-    get_otel_metrics_status,
-    shutdown_headroom_tracing,
-    shutdown_otel_metrics,
-)
-from headroom.pipeline import PipelineExtensionManager, PipelineStage
-from headroom.providers.proxy_routes import register_provider_routes
-from headroom.providers.registry import (
-    DEFAULT_ANTHROPIC_API_URL,
-    DEFAULT_CLOUDCODE_API_URL,
-    DEFAULT_GEMINI_API_URL,
-    DEFAULT_OPENAI_API_URL,
-    build_proxy_provider_runtime,
-    create_proxy_backend,
-    format_backend_status,
-)
-
-# =============================================================================
-# Extracted modules (re-exported for backward compatibility)
-# =============================================================================
-from headroom.proxy.cost import (
-    _CACHE_ECONOMICS,  # noqa: F401
-    CostTracker,  # noqa: F401
-    _summarize_transforms,  # noqa: F401
-    build_prefix_cache_stats,  # noqa: F401
-    build_session_summary,  # noqa: F401
-    merge_cost_stats,  # noqa: F401
-)
-from headroom.proxy.helpers import (
-    COMPRESSION_TIMEOUT_SECONDS,  # noqa: F401
-    MAX_COMPRESSION_CACHE_SESSIONS,  # noqa: F401
-    MAX_MESSAGE_ARRAY_LENGTH,  # noqa: F401
-    MAX_REQUEST_BODY_SIZE,  # noqa: F401
-    MAX_SSE_BUFFER_SIZE,  # noqa: F401
-    _get_image_compressor,  # noqa: F401
-    _get_rtk_stats,  # noqa: F401
-    _read_request_json,  # noqa: F401
-    _setup_file_logging,  # noqa: F401
-    is_anthropic_auth,  # noqa: F401
-    jitter_delay_ms,
-)
-from headroom.proxy.memory_handler import MemoryConfig, MemoryHandler
-
-# Data models (extracted to headroom/proxy/models.py for maintainability)
-from headroom.proxy.models import CacheEntry, ProxyConfig, RateLimitState, RequestLog  # noqa: F401
-from headroom.proxy.modes import (
-    PROXY_MODE_CACHE,
-    PROXY_MODE_TOKEN,
-    is_token_mode,
-    normalize_proxy_mode,
-)
-from headroom.proxy.prometheus_metrics import PrometheusMetrics  # noqa: F401
-from headroom.proxy.rate_limiter import TokenBucketRateLimiter  # noqa: F401
-from headroom.proxy.request_logger import RequestLogger  # noqa: F401
-from headroom.proxy.semantic_cache import SemanticCache  # noqa: F401
-from headroom.proxy.warmup import WarmupRegistry
-from headroom.proxy.ws_session_registry import WebSocketSessionRegistry
-from headroom.subscription.base import get_quota_registry, reset_quota_registry
-from headroom.subscription.codex_rate_limits import get_codex_rate_limit_state
-from headroom.subscription.copilot_quota import get_copilot_quota_tracker
-from headroom.subscription.tracker import (
-    configure_subscription_tracker,
-    get_subscription_tracker,
-)
-from headroom.telemetry import get_telemetry_collector
-from headroom.telemetry.beacon import is_telemetry_enabled
-from headroom.telemetry.toin import get_toin
-from headroom.transforms import (
-    CacheAligner,
-    CodeAwareCompressor,
-    CodeCompressorConfig,
-    ContentRouter,
-    ContentRouterConfig,
-    IntelligentContextManager,
-    RollingWindow,
-    SmartCrusher,
-    Transform,
-    TransformPipeline,
-    is_tree_sitter_available,
-)
-
-AnyLLMBackend: Any = None
-LiteLLMBackend: Any = None
-
-fcntl: Any = None
-try:
-    import fcntl as _fcntl
-
-    fcntl = _fcntl
-    HAS_FCNTL = True
-except ImportError:
-    HAS_FCNTL = False
-
-_build_prefix_cache_stats = build_prefix_cache_stats
-_build_session_summary = build_session_summary
-_merge_cost_stats = merge_cost_stats
-
-
-logging.basicConfig(
-    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-)
-logger = logging.getLogger("headroom.proxy")
-
-# Always-on file logging to ~/.headroom/logs/ for `headroom perf` analysis
-_setup_file_logging()
-
-
-# Compression pipeline timeout in seconds
-
-
-from headroom.proxy.handlers import (  # noqa: E402
-    AnthropicHandlerMixin,
-    BatchHandlerMixin,
-    GeminiHandlerMixin,
-    OpenAIHandlerMixin,
-    StreamingMixin,
-)
-
-
-class HeadroomProxy(
-    StreamingMixin,
-    AnthropicHandlerMixin,
-    OpenAIHandlerMixin,
-    GeminiHandlerMixin,
-    BatchHandlerMixin,
-):
-    """Production-ready Headroom optimization proxy."""
-
-    ANTHROPIC_API_URL = DEFAULT_ANTHROPIC_API_URL
-    OPENAI_API_URL = DEFAULT_OPENAI_API_URL
-    GEMINI_API_URL = DEFAULT_GEMINI_API_URL
-    CLOUDCODE_API_URL = DEFAULT_CLOUDCODE_API_URL
-
-    def __init__(self, config: ProxyConfig):
-        self.config = config
-        self.config.mode = normalize_proxy_mode(self.config.mode)
-        self.pipeline_extensions = PipelineExtensionManager(
-            hooks=config.hooks,
-            extensions=config.pipeline_extensions,
-            discover=config.discover_pipeline_extensions,
-        )
-
-        self.provider_runtime = build_proxy_provider_runtime(config)
-        api_targets = self.provider_runtime.api_targets
-
-        # Preserve the long-standing proxy compatibility surface while keeping
-        # provider_runtime as the source of truth for resolved upstream targets.
-        HeadroomProxy.ANTHROPIC_API_URL = api_targets.anthropic
-        HeadroomProxy.OPENAI_API_URL = api_targets.openai
-        HeadroomProxy.GEMINI_API_URL = api_targets.gemini
-        HeadroomProxy.CLOUDCODE_API_URL = api_targets.cloudcode
-        self.anthropic_provider = self.provider_runtime.pipeline_provider("anthropic")
-        self.openai_provider = self.provider_runtime.pipeline_provider("openai")
-
-        # Initialize transforms based on routing mode
-        # Choose context manager: IntelligentContextManager (smart) or RollingWindow (legacy)
-        context_manager: Transform  # Can be either IntelligentContextManager or RollingWindow
-        if config.intelligent_context:
-            # Get TOIN instance for learned pattern integration
-            toin = get_toin() if config.intelligent_context_scoring else None
-            context_manager = IntelligentContextManager(
-                config=IntelligentContextConfig(
-                    enabled=True,
-                    keep_system=True,
-                    keep_last_turns=config.keep_last_turns,
-                    use_importance_scoring=config.intelligent_context_scoring,
-                    toin_integration=config.intelligent_context_scoring,
-                    compress_threshold=0.10 if config.intelligent_context_compress_first else 0.0,
-                ),
-                toin=toin,
-            )
-            self._context_manager_status = "intelligent"
-        else:
-            context_manager = RollingWindow(
-                RollingWindowConfig(
-                    enabled=True,
-                    keep_system=True,
-                    keep_last_turns=config.keep_last_turns,
-                )
-            )
-            self._context_manager_status = "rolling_window"
-
-        if config.smart_routing:
-            # Smart routing: ContentRouter handles all content types intelligently
-            # It lazy-loads compressors only when needed
-            router_config = ContentRouterConfig(
-                enable_code_aware=config.code_aware_enabled,
-                tool_profiles=config.tool_profiles,
-                read_lifecycle=ReadLifecycleConfig(enabled=config.read_lifecycle),
-            )
-            # Token mode: allow compression of older excluded-tool results
-            if is_token_mode(config.mode):
-                router_config.protect_recent_reads_fraction = 0.3
-            transforms = [
-                CacheAligner(CacheAlignerConfig(enabled=False)),
-                ContentRouter(router_config),
-                context_manager,
-            ]
-            self._code_aware_status = "lazy" if config.code_aware_enabled else "disabled"
-        else:
-            # Legacy mode: sequential pipeline
-            transforms = [
-                CacheAligner(CacheAlignerConfig(enabled=False)),
-                SmartCrusher(
-                    SmartCrusherConfig(  # type: ignore[arg-type]
-                        enabled=True,
-                        min_tokens_to_crush=config.min_tokens_to_crush,
-                        max_items_after_crush=config.max_items_after_crush,
-                    ),
-                    ccr_config=CCRConfig(
-                        enabled=config.ccr_inject_tool,
-                        inject_retrieval_marker=config.ccr_inject_tool,  # Add CCR markers
-                    ),
-                ),
-                context_manager,
-            ]
-            # Add CodeAware if enabled and available
-            self._code_aware_status = self._setup_code_aware(config, transforms)
-
-        self.anthropic_pipeline = TransformPipeline(
-            transforms=transforms,
-            provider=self.anthropic_provider,
-        )
-        self.openai_pipeline = TransformPipeline(
-            transforms=transforms,
-            provider=self.openai_provider,
-        )
-
-        # Initialize components
-        self.cache = (
-            SemanticCache(
-                max_entries=config.cache_max_entries,
-                ttl_seconds=config.cache_ttl_seconds,
-            )
-            if config.cache_enabled
-            else None
-        )
-
-        self.rate_limiter = (
-            TokenBucketRateLimiter(
-                requests_per_minute=config.rate_limit_requests_per_minute,
-                tokens_per_minute=config.rate_limit_tokens_per_minute,
-            )
-            if config.rate_limit_enabled
-            else None
-        )
-
-        self.cost_tracker = (
-            CostTracker(
-                budget_limit_usd=config.budget_limit_usd,
-                budget_period=config.budget_period,
-            )
-            if config.cost_tracking_enabled
-            else None
-        )
-
-        self.metrics = PrometheusMetrics(cost_tracker=self.cost_tracker)
-
-        # Prefix cache tracking: freeze already-cached messages to avoid
-        # invalidating the provider's prefix cache with our transforms
-        from headroom.cache.prefix_tracker import PrefixFreezeConfig, SessionTrackerStore
-
-        self.session_tracker_store = SessionTrackerStore(
-            default_config=PrefixFreezeConfig(
-                enabled=config.prefix_freeze_enabled,
-                session_ttl_seconds=config.prefix_freeze_session_ttl,
-            )
-        )
-
-        # Compression cache store for token mode (session-scoped)
-        self._compression_caches: dict[str, CompressionCache] = {}
-
-        self.logger = (
-            RequestLogger(
-                log_file=config.log_file,
-                log_full_messages=config.log_full_messages,
-            )
-            if config.log_requests
-            else None
-        )
-
-        # Enterprise security plugin (loaded dynamically if available + licensed)
-        self.security = None
-
-        # HTTP client
-        self.http_client: httpx.AsyncClient | None = None
-
-        # Shared cold-start warmup registry (populated by startup()).
-        # Holds typed slots with loaded / loading / null / error status for
-        # each preloaded heavy asset. Exposed as ``proxy.warmup`` and
-        # serialized by the /debug/warmup route (Unit 5).
-        self.warmup: WarmupRegistry = WarmupRegistry()
-        # Unit 3: live registry of Codex WS sessions. Populated by
-        # ``handle_openai_responses_ws`` on accept; drained in its
-        # outermost ``finally``. Consumed by ``/debug/ws-sessions``.
-        self.ws_sessions: WebSocketSessionRegistry = WebSocketSessionRegistry()
-
-        # Unit 4: bounded pre-upstream concurrency for the Anthropic HTTP
-        # path. Caps how many ``handle_anthropic_messages`` calls may be
-        # running deep-copy / first-stage compression / memory-context
-        # lookup / upstream connect concurrently. ``/livez``, ``/readyz``,
-        # ``/health``, ``/metrics``, ``/stats``, and the Codex WS path are
-        # intentionally NOT gated by this semaphore.
-        #
-        # A value of ``0`` or negative disables the semaphore (unbounded
-        # mode); this is useful for the Unit 6 counter-factual where we
-        # deliberately reproduce the original starvation. The default is
-        # ``max(2, min(8, os.cpu_count() or 4))``.
-        _pre_upstream_cfg = config.anthropic_pre_upstream_concurrency
-        if _pre_upstream_cfg is None:
-            _pre_upstream_resolved = max(2, min(8, os.cpu_count() or 4))
-        else:
-            _pre_upstream_resolved = _pre_upstream_cfg
-        self.anthropic_pre_upstream_concurrency: int = _pre_upstream_resolved
-        self.anthropic_pre_upstream_acquire_timeout_seconds = float(
-            config.anthropic_pre_upstream_acquire_timeout_seconds
-        )
-        self.anthropic_pre_upstream_memory_context_timeout_seconds = float(
-            config.anthropic_pre_upstream_memory_context_timeout_seconds
-        )
-        if _pre_upstream_resolved > 0:
-            self.anthropic_pre_upstream_sem: asyncio.Semaphore | None = asyncio.Semaphore(
-                _pre_upstream_resolved
-            )
-        else:
-            self.anthropic_pre_upstream_sem = None
-
-        # Backend for Anthropic API (direct, LiteLLM, or any-llm)
-        # Supports: "anthropic" (direct), "bedrock", "vertex", "litellm-<provider>", or "anyllm"
-        self.anthropic_backend: Backend | None = create_proxy_backend(
-            backend=config.backend,
-            anyllm_provider=config.anyllm_provider,
-            bedrock_region=config.bedrock_region,
-            logger=logger,
-            anyllm_backend_cls=AnyLLMBackend,
-            litellm_backend_cls=LiteLLMBackend,
-        )
-
-        # Request counter for IDs
-        self._request_counter = 0
-        self._request_counter_lock = asyncio.Lock()
-
-        # CCR tool injectors (one per provider)
-        self.anthropic_tool_injector = CCRToolInjector(
-            provider="anthropic",
-            inject_tool=config.ccr_inject_tool,
-            inject_system_instructions=config.ccr_inject_system_instructions,
-        )
-        self.openai_tool_injector = CCRToolInjector(
-            provider="openai",
-            inject_tool=config.ccr_inject_tool,
-            inject_system_instructions=config.ccr_inject_system_instructions,
-        )
-
-        # CCR Response Handler (handles CCR tool calls automatically)
-        self.ccr_response_handler = (
-            CCRResponseHandler(
-                ResponseHandlerConfig(
-                    enabled=True,
-                    max_retrieval_rounds=config.ccr_max_retrieval_rounds,
-                )
-            )
-            if config.ccr_handle_responses
-            else None
-        )
-
-        # CCR Context Tracker (tracks compressed content across turns)
-        self.ccr_context_tracker = (
-            ContextTracker(
-                ContextTrackerConfig(
-                    enabled=True,
-                    proactive_expansion=config.ccr_proactive_expansion,
-                    max_proactive_expansions=config.ccr_max_proactive_expansions,
-                )
-            )
-            if config.ccr_context_tracking
-            else None
-        )
-
-        # Turn counter for context tracking
-        self._turn_counter = 0
-
-        # Memory Handler (persistent user memory)
-        self.memory_handler: MemoryHandler | None = None
-        if config.memory_enabled:
-            # Resolve memory DB path: empty → project-scoped default
-            _mem_db_path = config.memory_db_path
-            if not _mem_db_path:
-                _mem_dir = Path.cwd() / ".headroom"
-                _mem_dir.mkdir(parents=True, exist_ok=True)
-                _mem_db_path = str(_mem_dir / "memory.db")
-                logger.info(f"Memory: Project-scoped DB at {_mem_db_path}")
-
-            memory_config = MemoryConfig(
-                enabled=True,
-                backend=config.memory_backend,
-                db_path=_mem_db_path,
-                inject_tools=config.memory_inject_tools,
-                use_native_tool=config.memory_use_native_tool,
-                inject_context=config.memory_inject_context,
-                top_k=config.memory_top_k,
-                min_similarity=config.memory_min_similarity,
-                qdrant_host=config.memory_qdrant_host,
-                qdrant_port=config.memory_qdrant_port,
-                neo4j_uri=config.memory_neo4j_uri,
-                neo4j_user=config.memory_neo4j_user,
-                neo4j_password=config.memory_neo4j_password,
-                bridge_enabled=config.memory_bridge_enabled,
-                bridge_md_paths=config.memory_bridge_md_paths,
-                bridge_md_format=config.memory_bridge_md_format,
-                bridge_auto_import=config.memory_bridge_auto_import,
-                bridge_export_path=config.memory_bridge_export_path,
-            )
-            self.memory_handler = MemoryHandler(
-                memory_config,
-                agent_type=config.traffic_learning_agent_type,
-            )
-
-        # Usage Reporter (license validation + phone-home for managed/enterprise)
-        self.usage_reporter: UsageReporter | None = None
-        if config.license_key:
-            from headroom.telemetry.reporter import UsageReporter
-
-            self.usage_reporter = UsageReporter(
-                license_key=config.license_key,
-                cloud_url=config.license_cloud_url,
-                report_interval=config.license_report_interval,
-            )
-
-        # Traffic Learner (live pattern extraction from proxy traffic)
-        # Only activates with --learn flag; requires --memory for backend
-        self.traffic_learner: TrafficLearner | None = None
-        self.traffic_learning_agent_type: str = config.traffic_learning_agent_type
-        if config.traffic_learning_enabled:
-            from headroom.memory.traffic_learner import TrafficLearner
-
-            self.traffic_learner = TrafficLearner(
-                user_id=os.environ.get("HEADROOM_USER_ID", os.environ.get("USER", "default")),
-                agent_type=config.traffic_learning_agent_type,
-            )
-
-        # Code graph file watcher (live reindex on file changes)
-        self.code_graph_watcher: CodeGraphWatcher | None = None  # type: ignore[annotation-unchecked]
-        if config.code_graph_watcher:
-            from headroom.graph.watcher import CodeGraphWatcher
-
-            self.code_graph_watcher = CodeGraphWatcher(project_dir=Path.cwd())
-            if self.code_graph_watcher.start():
-                logger.info("Code graph: file watcher started")
-            else:
-                self.code_graph_watcher = None
-
-        self.pipeline_extensions.emit(
-            PipelineStage.SETUP,
-            operation="proxy.setup",
-            metadata={
-                "mode": self.config.mode,
-                "optimize": self.config.optimize,
-                "backend": self.config.backend,
-                "memory_enabled": self.config.memory_enabled,
-            },
-        )
-
-    def _get_compression_cache(self, session_id: str) -> CompressionCache:
-        """Get or create a CompressionCache for a session."""
-        if session_id not in self._compression_caches:
-            from headroom.cache.compression_cache import CompressionCache
-
-            # Evict oldest caches if at capacity
-            if len(self._compression_caches) >= MAX_COMPRESSION_CACHE_SESSIONS:
-                # Remove oldest quarter to amortize cleanup cost
-                oldest_keys = list(self._compression_caches.keys())[
-                    : MAX_COMPRESSION_CACHE_SESSIONS // 4
-                ]
-                for key in oldest_keys:
-                    del self._compression_caches[key]
-                logger.info(
-                    "Evicted %d compression caches (exceeded %d max sessions)",
-                    len(oldest_keys),
-                    MAX_COMPRESSION_CACHE_SESSIONS,
-                )
-
-            self._compression_caches[session_id] = CompressionCache()
-        return self._compression_caches[session_id]
-
-    def _setup_code_aware(self, config: ProxyConfig, transforms: list) -> str:
-        """Set up code-aware compression if enabled.
-
-        Args:
-            config: Proxy configuration
-            transforms: Transform list to append to
-
-        Returns:
-            Status string for logging: 'enabled', 'disabled', 'available', 'unavailable'
-        """
-        if config.code_aware_enabled:
-            if is_tree_sitter_available():
-                code_config = CodeCompressorConfig(
-                    preserve_imports=True,
-                    preserve_signatures=True,
-                    preserve_type_annotations=True,
-                )
-                # Insert before RollingWindow (which should be last)
-                transforms.insert(-1, CodeAwareCompressor(code_config))
-                return "enabled"
-            else:
-                logger.warning(
-                    "Code-aware compression requested but tree-sitter not installed. "
-                    "Install with: pip install headroom-ai[code]"
-                )
-                return "unavailable"
-        else:
-            if is_tree_sitter_available():
-                return "available"  # Available but not enabled
-            return "disabled"
-
-    async def startup(self):
-        """Initialize async resources."""
-        self.pipeline_extensions.emit(
-            PipelineStage.PRE_START,
-            operation="proxy.startup",
-            metadata={"port": self.config.port, "host": self.config.host},
-        )
-        self.http_client = httpx.AsyncClient(
-            timeout=httpx.Timeout(
-                connect=self.config.connect_timeout_seconds,
-                read=self.config.request_timeout_seconds,
-                write=self.config.request_timeout_seconds,
-                pool=self.config.connect_timeout_seconds,
-            ),
-            limits=httpx.Limits(
-                max_connections=self.config.max_connections,
-                max_keepalive_connections=self.config.max_keepalive_connections,
-            ),
-            http2=self.config.http2,
-        )
-        logger.info("Headroom Proxy started")
-        logger.info(f"Optimization: {'ENABLED' if self.config.optimize else 'DISABLED'}")
-        self.config.mode = normalize_proxy_mode(self.config.mode)
-        logger.info(f"Mode: {self.config.mode}")
-        if self.config.mode == PROXY_MODE_TOKEN:
-            logger.info("  Prefix freeze: re-freeze after compression")
-            logger.info("  Read protection window: 30%% of excluded-tool messages")
-            logger.info("  CCR TTL: extended for session lifetime")
-            logger.info("  Compression cache: active")
-        if self.config.mode == PROXY_MODE_CACHE:
-            logger.info("  Prefix freeze: strict (all prior turns immutable)")
-            logger.info("  Mutations: latest turn only")
-        logger.info(f"Caching: {'ENABLED' if self.config.cache_enabled else 'DISABLED'}")
-        logger.info(f"Rate Limiting: {'ENABLED' if self.config.rate_limit_enabled else 'DISABLED'}")
-        logger.info(
-            f"Connection Pool: max_connections={self.config.max_connections}, "
-            f"max_keepalive={self.config.max_keepalive_connections}, "
-            f"http2={'ENABLED' if self.config.http2 else 'DISABLED'}"
-        )
-
-        # Unit 4 pre-upstream concurrency announcement. Report the resolved
-        # value (auto-detected vs. explicit) so operators can correlate
-        # ``pre_upstream_wait_ms`` log lines with the configured cap.
-        if self.anthropic_pre_upstream_sem is None:
-            logger.info("Anthropic pre-upstream concurrency: unbounded (explicitly disabled)")
-        else:
-            _explicit = self.config.anthropic_pre_upstream_concurrency
-            _origin = "auto-detected" if _explicit is None else "explicit"
-            logger.info(
-                "Anthropic pre-upstream concurrency: %d (%s)",
-                self.anthropic_pre_upstream_concurrency,
-                _origin,
-            )
-        logger.info(
-            "Anthropic pre-upstream timeouts: acquire=%.1fs compression=%.1fs memory_context=%.1fs",
-            self.anthropic_pre_upstream_acquire_timeout_seconds,
-            float(COMPRESSION_TIMEOUT_SECONDS),
-            self.anthropic_pre_upstream_memory_context_timeout_seconds,
-        )
-
-        # Smart routing status
-        if self.config.smart_routing:
-            logger.info("Smart Routing: ENABLED (intelligent content detection)")
-        else:
-            logger.info("Smart Routing: DISABLED (legacy sequential mode)")
-
-        # Eagerly load ALL compressors, parsers, and detectors at startup
-        # This eliminates cold-start latency spikes on first requests.
-        # Iterate BOTH pipelines (Anthropic + OpenAI) and dedupe transforms
-        # by id() so shared-transform instances never load twice. The
-        # resulting status dict is merged into ``self.warmup`` so /debug/warmup
-        # (Unit 5) and /readyz have a single source of truth.
-        self._kompress_status = "not installed"
-        eager_status: dict[str, str] = {}
-
-        if self.config.optimize:
-            logger.info("Pre-loading compressors and parsers...")
-            seen_transform_ids: set[int] = set()
-            pipelines = (self.anthropic_pipeline, self.openai_pipeline)
-            for pipeline in pipelines:
-                for transform in pipeline.transforms:
-                    if id(transform) in seen_transform_ids:
-                        continue
-                    seen_transform_ids.add(id(transform))
-                    if not hasattr(transform, "eager_load_compressors"):
-                        continue
-                    try:
-                        transform_status = transform.eager_load_compressors()
-                    except Exception as exc:
-                        logger.warning(
-                            "Eager preload failed for %s: %s",
-                            type(transform).__name__,
-                            exc,
-                        )
-                        continue
-                    if not isinstance(transform_status, dict):
-                        continue
-                    # Merge: later writers win only if the key wasn't set.
-                    # Preload a transform ONCE — if another pipeline also has
-                    # ``eager_load_compressors`` it contributes only new keys.
-                    for key, value in transform_status.items():
-                        eager_status.setdefault(key, value)
-                    self.warmup.merge_transform_status(transform_status)
-
-        # Update internal status from eager loading results
-        if eager_status.get("kompress") == "enabled":
-            self._kompress_status = "enabled"
-        if eager_status.get("code_aware") == "enabled":
-            self._code_aware_status = "enabled"
-
-        # Log component status
-        if self._kompress_status == "enabled":
-            logger.info("Kompress: ENABLED (ModernBERT token compressor)")
-        elif self.config.optimize:
-            logger.info("Kompress: not installed (pip install headroom-ai[ml] for ML compression)")
-
-        if self._code_aware_status == "enabled":
-            logger.info("Code-Aware: ENABLED (AST-based compression)")
-            if "tree_sitter" in eager_status:
-                logger.info(f"Tree-Sitter: {eager_status['tree_sitter']}")
-        elif self._code_aware_status == "lazy":
-            logger.info("Code-Aware: LAZY (will load when code content detected)")
-        elif self._code_aware_status == "available":
-            logger.info("Code-Aware: available but disabled (use --code-aware)")
-        elif self._code_aware_status == "unavailable":
-            logger.info("Code-Aware: not installed (pip install headroom-ai[code])")
-        elif self._code_aware_status == "disabled":
-            logger.info("Code-Aware: DISABLED")
-
-        if eager_status.get("magika") == "enabled":
-            logger.info("Magika: ENABLED (ML content detection)")
-
-        if self.memory_handler:
-            self.warmup.memory_backend.mark_loading()
-            try:
-                await self.memory_handler.ensure_initialized()
-            except Exception as exc:  # pragma: no cover - defensive
-                self.warmup.memory_backend.mark_error(str(exc))
-                logger.warning("Memory: backend initialization failed (startup continues): %s", exc)
-            memory_status = self.memory_handler.health_status()
-            if memory_status.get("initialized"):
-                self.warmup.memory_backend.mark_loaded(
-                    handle=self.memory_handler,
-                    backend=memory_status.get("backend"),
-                )
-                # Force one embed call so the ONNX graph is compiled now,
-                # not lazily during the first request. Best-effort — any
-                # failure is swallowed inside warmup_embedder.
-                self.warmup.memory_embedder.mark_loading()
-                warmed = await self.memory_handler.warmup_embedder()
-                if warmed:
-                    self.warmup.memory_embedder.mark_loaded()
-                else:
-                    # Not an error — e.g. qdrant-neo4j has no embedder slot
-                    # we can reach, or the backend simply exposes no handle.
-                    self.warmup.memory_embedder.mark_null()
-            else:
-                if self.warmup.memory_backend.status != "error":
-                    self.warmup.memory_backend.mark_null()
-                self.warmup.memory_embedder.mark_null()
-            logger.info(
-                "Memory: ENABLED "
-                f"(backend={memory_status['backend']}, initialized={memory_status['initialized']})"
-            )
-        else:
-            logger.info("Memory: DISABLED")
-
-        # CCR status
-        ccr_features = []
-        if self.config.ccr_inject_tool:
-            ccr_features.append("tool_injection")
-        if self.config.ccr_handle_responses:
-            ccr_features.append("response_handling")
-        if self.config.ccr_context_tracking:
-            ccr_features.append("context_tracking")
-        if self.config.ccr_proactive_expansion:
-            ccr_features.append("proactive_expansion")
-        if ccr_features:
-            logger.info(f"CCR (Compress-Cache-Retrieve): ENABLED ({', '.join(ccr_features)})")
-        else:
-            logger.info("CCR: DISABLED")
-        logger.info(f"Savings history: {self.metrics.savings_tracker.storage_path}")
-
-        # Reset and rebuild the quota tracker registry for this server instance.
-        # reset_quota_registry() ensures a clean slate when the proxy is restarted
-        # (e.g. in tests that spin up multiple app instances in the same process).
-        reset_quota_registry()
-        registry = get_quota_registry()
-        tracker = configure_subscription_tracker(
-            poll_interval_s=self.config.subscription_poll_interval_s,
-            active_window_s=self.config.subscription_active_window_s,
-            enabled=self.config.subscription_tracking_enabled,
-        )
-        registry.register(tracker)
-        registry.register(get_codex_rate_limit_state())
-        registry.register(get_copilot_quota_tracker())
-        await registry.start_all()
-
-        if self.config.subscription_tracking_enabled:
-            logger.info(
-                "Subscription tracking: ENABLED "
-                f"(poll_interval={self.config.subscription_poll_interval_s}s, "
-                f"active_window={self.config.subscription_active_window_s}s)"
-            )
-        else:
-            logger.info("Subscription tracking: DISABLED")
-
-        copilot_tracker = get_copilot_quota_tracker()
-        if copilot_tracker.is_available():
-            logger.info("GitHub Copilot quota tracking: ENABLED")
-        else:
-            logger.info(
-                "GitHub Copilot quota tracking: DISABLED "
-                "(set GITHUB_TOKEN or GITHUB_COPILOT_GITHUB_TOKEN to enable)"
-            )
-
-        # Log anonymous telemetry status so operators can see it in the log stream
-        if is_telemetry_enabled():
-            logger.info(
-                "Anonymous telemetry: ENABLED (aggregate stats only — no prompts or content). "
-                "Opt out: HEADROOM_TELEMETRY=off or --no-telemetry"
-            )
-        else:
-            logger.info("Anonymous telemetry: DISABLED")
-
-        self.pipeline_extensions.emit(
-            PipelineStage.POST_START,
-            operation="proxy.startup",
-            metadata={
-                "port": self.config.port,
-                "host": self.config.host,
-                "warmup": self.warmup.to_dict(),
-            },
-        )
-
-    async def shutdown(self):
-        """Cleanup async resources."""
-        if self.http_client:
-            await self.http_client.aclose()
-            self.http_client = None
-
-        if self.memory_handler and hasattr(self.memory_handler, "close"):
-            await self.memory_handler.close()
-
-        # Stop all quota trackers via the registry
-        await get_quota_registry().stop_all()
-
-        # Print final stats
-        self._print_summary()
-
-    def _print_summary(self):
-        """Print session summary."""
-        m = self.metrics
-        logger.info("=" * 70)
-        logger.info("HEADROOM PROXY SESSION SUMMARY")
-        logger.info("=" * 70)
-        logger.info(f"Total requests:        {m.requests_total}")
-        logger.info(f"Cached responses:      {m.requests_cached}")
-        logger.info(f"Rate limited:          {m.requests_rate_limited}")
-        logger.info(f"Failed:                {m.requests_failed}")
-        logger.info(f"Input tokens:          {m.tokens_input_total:,}")
-        logger.info(f"Output tokens:         {m.tokens_output_total:,}")
-        logger.info(f"Tokens saved:          {m.tokens_saved_total:,}")
-        if m.tokens_input_total > 0:
-            savings_pct = (
-                m.tokens_saved_total / (m.tokens_input_total + m.tokens_saved_total)
-            ) * 100
-            logger.info(f"Token savings:         {savings_pct:.1f}%")
-        if m.latency_count > 0:
-            avg_latency = m.latency_sum_ms / m.latency_count
-            logger.info(f"Avg latency:           {avg_latency:.0f}ms")
-        logger.info("=" * 70)
-
-    async def _next_request_id(self) -> str:
-        """Generate unique request ID."""
-        async with self._request_counter_lock:
-            self._request_counter += 1
-            return f"hr_{int(time.time())}_{self._request_counter:06d}"
-
-    def _extract_tags(self, headers: dict) -> dict[str, str]:
-        """Extract Headroom tags from headers."""
-        tags = {}
-        for key, value in headers.items():
-            if key.lower().startswith("x-headroom-"):
-                tag_name = key.lower().replace("x-headroom-", "")
-                tags[tag_name] = value
-        return tags
-
-    def _inject_system_context(
-        self,
-        messages: list[dict[str, Any]],
-        context: str,
-        body: dict[str, Any] | None = None,
-    ) -> list[dict[str, Any]]:
-        """Inject context into the system message/parameter.
-
-        For Anthropic API: Uses top-level 'system' parameter (not messages array).
-        For OpenAI API: Uses system role in messages array.
-
-        Args:
-            messages: The messages list.
-            context: Context to inject.
-            body: Optional request body to update system parameter (for Anthropic).
-
-        Returns:
-            Updated messages list.
-        """
-        messages = list(messages)  # Copy to avoid mutation
-
-        # For Anthropic API: use top-level 'system' parameter
-        if body is not None:
-            existing_system = body.get("system", "")
-            if isinstance(existing_system, str):
-                body["system"] = (existing_system + "\n\n" + context).strip()
-            elif isinstance(existing_system, list):
-                # system is a list of content blocks (e.g., with cache_control).
-                # Append memory context as a new text block — never overwrite.
-                body["system"] = existing_system + [{"type": "text", "text": context}]
-            else:
-                # No existing system prompt — set as string
-                body["system"] = context
-            return messages
-
-        # For OpenAI API: use system role in messages
-        for i, msg in enumerate(messages):
-            if msg.get("role") == "system":
-                content = msg.get("content", "")
-                if isinstance(content, str):
-                    messages[i] = {**msg, "content": content + "\n\n" + context}
-                return messages
-
-        # No system message found - prepend one
-        messages.insert(0, {"role": "system", "content": context})
-        return messages
-
-    async def _retry_request(
-        self,
-        method: str,
-        url: str,
-        headers: dict,
-        body: dict,
-        stream: bool = False,
-    ) -> httpx.Response:
-        """Make request with retry and exponential backoff."""
-        last_error = None
-
-        for attempt in range(self.config.retry_max_attempts):
-            try:
-                if stream:
-                    # For streaming, we return early - retry happens at higher level
-                    return await self.http_client.post(url, json=body, headers=headers)  # type: ignore[union-attr]
-                else:
-                    response = await self.http_client.post(url, json=body, headers=headers)  # type: ignore[union-attr]
-
-                    # Don't retry client errors (4xx)
-                    if 400 <= response.status_code < 500:
-                        return response
-
-                    # Retry server errors (5xx)
-                    if response.status_code >= 500:
-                        raise httpx.HTTPStatusError(
-                            f"Server error: {response.status_code}",
-                            request=response.request,
-                            response=response,
-                        )
-
-                    return response
-
-            except (httpx.ConnectError, httpx.ReadTimeout, httpx.HTTPStatusError) as e:
-                last_error = e
-
-                if not self.config.retry_enabled or attempt >= self.config.retry_max_attempts - 1:
-                    raise
-
-                # Exponential backoff with jitter
-                delay_with_jitter = jitter_delay_ms(
-                    self.config.retry_base_delay_ms,
-                    self.config.retry_max_delay_ms,
-                    attempt,
-                )
-
-                logger.warning(
-                    f"Request failed (attempt {attempt + 1}), retrying in {delay_with_jitter:.0f}ms: {e}"
-                )
-                await asyncio.sleep(delay_with_jitter / 1000)
-
-        raise last_error  # type: ignore[misc]
-
-
-async def _log_toin_stats_periodically(interval_seconds: int = 300) -> None:
-    """Background task that logs TOIN stats periodically.
-
-    Args:
-        interval_seconds: How often to log stats (default: 5 minutes).
-    """
-    while True:
-        await asyncio.sleep(interval_seconds)
-        try:
-            toin = get_toin()
-            stats = toin.get_stats()
-            total_compressions = stats.get("total_compressions", 0)
-            if total_compressions > 0:
-                patterns = stats.get("patterns_tracked", 0)
-                retrievals = stats.get("total_retrievals", 0)
-                retrieval_rate = stats.get("global_retrieval_rate", 0.0)
-                logger.info(
-                    "TOIN: %d patterns, %d compressions, %d retrievals, %.1f%% retrieval rate",
-                    patterns,
-                    total_compressions,
-                    retrievals,
-                    retrieval_rate * 100,
-                )
-        except Exception as e:
-            logger.debug("Failed to log TOIN stats: %s", e)
-
-
-def _register_memory_components(proxy: HeadroomProxy, tracker: MemoryTracker) -> None:
-    """Register all memory-tracked components with the tracker.
-
-    This function is idempotent - it checks if components are already registered.
-
-    Args:
-        proxy: The HeadroomProxy instance.
-        tracker: The MemoryTracker instance.
-    """
-    # Register compression store (global singleton)
-    if "compression_store" not in tracker.registered_components:
-        store = get_compression_store()
-        tracker.register("compression_store", store.get_memory_stats)
-
-    # Register semantic cache (instance on proxy)
-    if proxy.cache and "semantic_cache" not in tracker.registered_components:
-        tracker.register("semantic_cache", proxy.cache.get_memory_stats)
-
-    # Register request logger (instance on proxy)
-    if proxy.logger and "request_logger" not in tracker.registered_components:
-        tracker.register("request_logger", proxy.logger.get_memory_stats)
-
-    # Register batch context store (global singleton)
-    if "batch_context_store" not in tracker.registered_components:
-        try:
-            from ..ccr.batch_store import get_batch_context_store
-
-            batch_store = get_batch_context_store()
-            if hasattr(batch_store, "get_memory_stats"):
-                tracker.register("batch_context_store", batch_store.get_memory_stats)
-        except ImportError:
-            pass
-
-    # Note: graph_store and vector_index are created per-user within the
-    # LocalMemoryBackend, not as global singletons. They would need to be
-    # registered when the memory system is initialized with specific backends.
-
-
-def create_app(config: ProxyConfig | None = None) -> FastAPI:
-    """Create FastAPI application."""
-    if not FASTAPI_AVAILABLE:
-        raise ImportError("FastAPI required. Install: pip install fastapi uvicorn httpx")
-
-    from contextlib import asynccontextmanager
-
-    config = config or ProxyConfig()
-    proxy = HeadroomProxy(config)
-
-    # Telemetry beacon (anonymous aggregate stats).
-    # With uvicorn workers > 1, each worker runs the lifespan independently.
-    # We must ensure only ONE beacon runs across all workers — otherwise each
-    # worker creates its own beacon, spamming the telemetry table with N rows
-    # per cycle instead of 1 (all reading the same /stats from the same port).
-    #
-    # Strategy: use a file lock to ensure only the first worker starts the
-    # beacon. Other workers see the lock and skip.
-    from headroom.telemetry.beacon import TelemetryBeacon
-
-    _beacon = TelemetryBeacon(
-        port=config.port if hasattr(config, "port") else 8787,
-        sdk=os.environ.get("HEADROOM_SDK", "proxy").strip() or "proxy",
-        backend=config.backend if hasattr(config, "backend") else "anthropic",
-    )
-    from headroom import paths as _hr_paths
-
-    _beacon_lock_path = _hr_paths.beacon_lock_path(config.port)
-    _beacon_lock_fd: list = [None]  # mutable holder for the lock file descriptor
-    _beacon_is_owner: list = [False]
-
-    def _try_acquire_beacon_lock() -> bool:
-        """Try to acquire the beacon file lock (non-blocking).
-
-        Returns True if this process is the beacon owner.
-        """
-        if not HAS_FCNTL:
-            return True
-
-        fd = None
-        try:
-            _beacon_lock_path.parent.mkdir(parents=True, exist_ok=True)
-            fd = open(_beacon_lock_path, "w")  # noqa: SIM115
-            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
-            fd.write(str(os.getpid()))
-            fd.flush()
-            _beacon_lock_fd[0] = fd
-            return True
-        except OSError:
-            if fd is not None:
-                fd.close()
-            return False
-
-    def _release_beacon_lock() -> None:
-        """Release the beacon file lock."""
-        fd = _beacon_lock_fd[0]
-        if fd:
-            try:
-                if HAS_FCNTL:
-                    fcntl.flock(fd, fcntl.LOCK_UN)
-                fd.close()
-            except Exception:
-                pass
-            _beacon_lock_fd[0] = None
-        try:
-            _beacon_lock_path.unlink(missing_ok=True)
-        except Exception:
-            pass
-
-    @asynccontextmanager
-    async def lifespan(app: FastAPI):  # type: ignore[no-untyped-def]
-        configure_otel_metrics(OTelMetricsConfig.from_env(default_service_name="headroom-proxy"))
-        configure_langfuse_tracing(
-            LangfuseTracingConfig.from_env(default_service_name="headroom-proxy")
-        )
-
-        app.state.started_at = time.time()
-        app.state.ready = False
-        app.state.startup_error = None
-
-        try:
-            try:
-                # Startup
-                await proxy.startup()
-                asyncio.create_task(_log_toin_stats_periodically())
-                if proxy.usage_reporter:
-                    await proxy.usage_reporter.start(proxy)
-                if proxy.traffic_learner:
-                    await proxy.traffic_learner.start()
-
-                # Only start beacon if we acquire the lock (first worker wins)
-                _beacon_is_owner[0] = _try_acquire_beacon_lock()
-                if _beacon_is_owner[0]:
-                    await _beacon.start()
-                else:
-                    logger.debug("Beacon: skipping (another worker owns the lock)")
-
-                app.state.ready = True
-                yield
-            except Exception as exc:
-                app.state.startup_error = str(exc)
-                raise
-        finally:
-            app.state.ready = False
-            # Shutdown
-            if _beacon_is_owner[0]:
-                await _beacon.stop()
-                _release_beacon_lock()
-            if proxy.usage_reporter:
-                await proxy.usage_reporter.stop()
-            if proxy.traffic_learner:
-                await proxy.traffic_learner.stop()
-            if proxy.code_graph_watcher:
-                proxy.code_graph_watcher.stop()
-            await proxy.shutdown()
-            shutdown_headroom_tracing()
-            shutdown_otel_metrics()
-
-    app = FastAPI(
-        title="Headroom Proxy",
-        description="Production-ready LLM optimization proxy",
-        version=__version__,
-        lifespan=lifespan,
-    )
-    app.state.proxy = proxy
-    app.state.started_at = None
-    app.state.ready = False
-    app.state.startup_error = None
-
-    def _iso_utc_now() -> str:
-        return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-
-    def _uptime_seconds() -> float:
-        started_at = getattr(app.state, "started_at", None)
-        if not isinstance(started_at, int | float):
-            return 0.0
-        return round(max(0.0, time.time() - float(started_at)), 3)
-
-    def _component_health(
-        *,
-        enabled: bool,
-        ready: bool,
-        **details: Any,
-    ) -> dict[str, Any]:
-        status = "disabled" if not enabled else ("healthy" if ready else "unhealthy")
-        return {
-            "enabled": enabled,
-            "ready": (ready if enabled else True),
-            "status": status,
-            **details,
-        }
-
-    def _health_checks() -> dict[str, dict[str, Any]]:
-        memory_status = (
-            proxy.memory_handler.health_status()
-            if proxy.memory_handler
-            else {
-                "enabled": False,
-                "backend": None,
-                "initialized": False,
-                "native_tool": False,
-                "bridge_enabled": False,
-            }
-        )
-        memory_enabled = bool(memory_status.get("enabled", False))
-        memory_initialized = bool(memory_status.get("initialized", False))
-        return {
-            "startup": _component_health(
-                enabled=True,
-                ready=bool(getattr(app.state, "ready", False)),
-                error=getattr(app.state, "startup_error", None),
-            ),
-            "http_client": _component_health(
-                enabled=True,
-                ready=proxy.http_client is not None,
-            ),
-            "cache": _component_health(
-                enabled=config.cache_enabled,
-                ready=(proxy.cache is not None),
-            ),
-            "rate_limiter": _component_health(
-                enabled=config.rate_limit_enabled,
-                ready=(proxy.rate_limiter is not None),
-            ),
-            "memory": _component_health(
-                enabled=memory_enabled,
-                ready=memory_initialized,
-                backend=memory_status["backend"],
-                initialized=memory_initialized,
-                native_tool=bool(memory_status.get("native_tool", False)),
-                bridge_enabled=bool(memory_status.get("bridge_enabled", False)),
-            ),
-        }
-
-    def _runtime_payload() -> dict[str, Any]:
-        ws_registry = getattr(proxy, "ws_sessions", None)
-        ws_active_sessions = ws_registry.active_count() if ws_registry is not None else 0
-        ws_active_relay_tasks = (
-            ws_registry.active_relay_task_count() if ws_registry is not None else 0
-        )
-        return {
-            "anthropic_pre_upstream": {
-                "enabled": proxy.anthropic_pre_upstream_sem is not None,
-                "resolved_concurrency": proxy.anthropic_pre_upstream_concurrency,
-                "source": (
-                    "auto" if config.anthropic_pre_upstream_concurrency is None else "explicit"
-                ),
-                "acquire_timeout_seconds": proxy.anthropic_pre_upstream_acquire_timeout_seconds,
-                "compression_timeout_seconds": float(COMPRESSION_TIMEOUT_SECONDS),
-                "memory_context_timeout_seconds": (
-                    proxy.anthropic_pre_upstream_memory_context_timeout_seconds
-                ),
-                "codex_ws_gated": False,
-            },
-            "websocket_sessions": {
-                "active_sessions": ws_active_sessions,
-                "active_relay_tasks": ws_active_relay_tasks,
-            },
-        }
-
-    def _health_payload(*, include_config: bool) -> dict[str, Any]:
-        checks = _health_checks()
-        ready = all(check["ready"] for check in checks.values())
-        payload: dict[str, Any] = {
-            "service": "headroom-proxy",
-            "status": "healthy" if ready else "unhealthy",
-            "ready": ready,
-            "version": __version__,
-            "timestamp": _iso_utc_now(),
-            "uptime_seconds": _uptime_seconds(),
-            "checks": checks,
-            "runtime": _runtime_payload(),
-        }
-        deployment_profile = os.environ.get("HEADROOM_DEPLOYMENT_PROFILE")
-        if deployment_profile:
-            payload["deployment"] = {
-                "profile": deployment_profile,
-                "preset": os.environ.get("HEADROOM_DEPLOYMENT_PRESET"),
-                "runtime": os.environ.get("HEADROOM_DEPLOYMENT_RUNTIME"),
-                "supervisor": os.environ.get("HEADROOM_DEPLOYMENT_SUPERVISOR"),
-                "scope": os.environ.get("HEADROOM_DEPLOYMENT_SCOPE"),
-            }
-        if include_config:
-            payload["config"] = {
-                "backend": config.backend,
-                "optimize": config.optimize,
-                "cache": config.cache_enabled,
-                "rate_limit": config.rate_limit_enabled,
-                "memory": config.memory_enabled,
-                "learn": config.traffic_learning_enabled,
-                "code_graph": config.code_graph_watcher,
-                "pid": os.getpid(),
-            }
-        return payload
-
-    # CORS
-    app.add_middleware(
-        CORSMiddleware,
-        allow_origins=["*"],
-        allow_credentials=True,
-        allow_methods=["*"],
-        allow_headers=["*"],
-    )
-
-    # X-Headroom-Stack: SDK adapters (TS openai/anthropic/etc.) tag their
-    # requests so telemetry can segment by integration surface. Registered
-    # before extension middleware so any extension-level auth/guards run
-    # outermost and we don't count requests they reject.
-    @app.middleware("http")
-    async def _record_headroom_stack(request, call_next):
-        if request.url.path.startswith("/v1/"):
-            stack = request.headers.get("x-headroom-stack")
-            if stack:
-                try:
-                    proxy.metrics.record_stack(stack)
-                except Exception:
-                    logger.debug("record_stack failed", exc_info=True)
-        return await call_next(request)
-
-    # Third-party proxy extensions (Enterprise, custom plugins). Discovered via
-    # the `headroom.proxy_extension` entry-point group. An extension that raises
-    # from its install() is a deliberate fail-closed signal and aborts startup.
-    from headroom.proxy.extensions import install_all as _install_extensions
-
-    _install_extensions(app, config)
-
-    # Health & Metrics
-    @app.get("/livez")
-    async def livez():
-        return JSONResponse(
-            status_code=200,
-            content={
-                "service": "headroom-proxy",
-                "status": "healthy",
-                "alive": True,
-                "version": __version__,
-                "timestamp": _iso_utc_now(),
-                "uptime_seconds": _uptime_seconds(),
-            },
-        )
-
-    @app.get("/readyz")
-    async def readyz():
-        payload = _health_payload(include_config=False)
-        return JSONResponse(status_code=200 if payload["ready"] else 503, content=payload)
-
-    @app.get("/health")
-    async def health():
-        payload = _health_payload(include_config=True)
-        return JSONResponse(status_code=200, content=payload)
-
-    # Loopback-only debug introspection (Unit 5). A remote IP gets 404 —
-    # debug endpoints are invisible to external scanners.
-    from headroom.proxy.debug_introspection import (
-        collect_tasks as _collect_tasks,
-    )
-    from headroom.proxy.loopback_guard import require_loopback as _require_loopback
-
-    @app.get("/debug/tasks", dependencies=[Depends(_require_loopback)])
-    async def debug_tasks(stack: bool = False):
-        """Enumerate running asyncio tasks.
-
-        Default is cheap — ``stack_depth`` is ``null`` in every entry so
-        a storm snapshot does not walk 50+ coroutine frames synchronously.
-        Pass ``?stack=true`` to compute ``stack_depth`` for each task
-        (useful for single-shot human debugging).
-        """
-        ws_registry = getattr(proxy, "ws_sessions", None)
-        return JSONResponse(
-            status_code=200,
-            content=_collect_tasks(ws_registry, with_stack_depth=stack),
-        )
-
-    @app.get("/debug/ws-sessions", dependencies=[Depends(_require_loopback)])
-    async def debug_ws_sessions():
-        ws_registry = getattr(proxy, "ws_sessions", None)
-        snapshot = ws_registry.snapshot() if ws_registry is not None else []
-        return JSONResponse(status_code=200, content=snapshot)
-
-    @app.get("/debug/warmup", dependencies=[Depends(_require_loopback)])
-    async def debug_warmup():
-        warmup_registry = getattr(proxy, "warmup", None)
-        payload = warmup_registry.to_dict() if warmup_registry is not None else {}
-        payload["runtime"] = _runtime_payload()
-        return JSONResponse(status_code=200, content=payload)
-
-    @app.get("/dashboard", response_class=HTMLResponse)
-    async def dashboard():
-        """Serve the Headroom dashboard UI."""
-        return get_dashboard_html()
-
-    DASHBOARD_STATS_CACHE_TTL_SECONDS = 5.0
-    _stats_snapshot_lock = asyncio.Lock()
-    _stats_snapshot: dict[str, Any] = {"expires_at": 0.0, "value": None}
-
-    async def _build_stats_payload() -> dict[str, Any]:
-        """Build the full `/stats` response payload.
-
-        This is the main stats endpoint - it aggregates data from all subsystems:
-        - Request metrics (total, cached, failed, by model/provider)
-        - Token usage and savings
-        - Cost tracking
-        - Canonical persisted display_session metrics for downstream dashboards
-        - Compression (CCR) statistics
-        - Telemetry/TOIN (data flywheel) statistics
-        - Cache and rate limiter stats
-        """
-        m = proxy.metrics
-
-        # Calculate average latency
-        avg_latency_ms = round(m.latency_sum_ms / m.latency_count, 2) if m.latency_count > 0 else 0
-        min_latency_ms = (
-            round(m.latency_min_ms, 2)
-            if m.latency_count > 0 and m.latency_min_ms != float("inf")
-            else 0
-        )
-        max_latency_ms = round(m.latency_max_ms, 2) if m.latency_count > 0 else 0
-
-        # Calculate Headroom overhead (optimization time only, excludes pass-through requests)
-        avg_overhead_ms = (
-            round(m.overhead_sum_ms / m.overhead_count, 2) if m.overhead_count > 0 else 0
-        )
-        min_overhead_ms = (
-            round(m.overhead_min_ms, 2)
-            if m.overhead_count > 0 and m.overhead_min_ms != float("inf")
-            else 0
-        )
-        max_overhead_ms = round(m.overhead_max_ms, 2) if m.overhead_count > 0 else 0
-
-        # Calculate TTFB (time to first byte)
-        avg_ttfb_ms = round(m.ttfb_sum_ms / m.ttfb_count, 2) if m.ttfb_count > 0 else 0
-        min_ttfb_ms = (
-            round(m.ttfb_min_ms, 2) if m.ttfb_count > 0 and m.ttfb_min_ms != float("inf") else 0
-        )
-        max_ttfb_ms = round(m.ttfb_max_ms, 2) if m.ttfb_count > 0 else 0
-
-        # Get compression store stats
-        store = get_compression_store()
-        compression_stats = store.get_stats()
-
-        # Get telemetry/TOIN stats
-        telemetry = get_telemetry_collector()
-        telemetry_stats = telemetry.get_stats()
-
-        # Get feedback loop stats
-        feedback = get_compression_feedback()
-        feedback_stats = feedback.get_stats()
-
-        # Build prefix cache stats once (used in both prefix_cache and cost)
-        prefix_cache_stats = _build_prefix_cache_stats(m, proxy.cost_tracker)
-
-        # Fetch CLI filtering savings (rtk — tokens avoided before reaching context)
-        cli_filtering_stats = _get_rtk_stats()
-        cli_tokens_avoided = (
-            cli_filtering_stats.get("tokens_saved", 0) if cli_filtering_stats else 0
-        )
-
-        # Calculate total tokens before compression
-        total_tokens_before = m.tokens_input_total + m.tokens_saved_total
-
-        # Build human-readable summary
-        summary = _build_session_summary(
-            proxy, m, prefix_cache_stats, cli_tokens_avoided, total_tokens_before
-        )
-        # DEBUG: log the summary payload for external upsert consumers
-        try:
-            logger.debug("/stats summary data: %r", summary)
-        except Exception:
-            logger.warning("Failed to log /stats summary payload")
-
-        # Compression cache stats (token mode)
-        compression_cache_stats: dict = {}
-        if proxy.config.mode == PROXY_MODE_TOKEN and proxy._compression_caches:
-            total_entries = 0
-            total_hits = 0
-            total_misses = 0
-            total_tokens_saved = 0
-            for cache in proxy._compression_caches.values():
-                s = cache.get_stats()
-                total_entries += s.get("entries", 0)
-                total_hits += s.get("hits", 0)
-                total_misses += s.get("misses", 0)
-                total_tokens_saved += s.get("total_tokens_saved", 0)
-            compression_cache_stats = {
-                "mode": PROXY_MODE_TOKEN,
-                "active_sessions": len(proxy._compression_caches),
-                "total_entries": total_entries,
-                "total_hits": total_hits,
-                "total_misses": total_misses,
-                "hit_rate": round(total_hits / max(1, total_hits + total_misses) * 100, 1),
-                "total_tokens_saved": total_tokens_saved,
-            }
-        else:
-            compression_cache_stats = {"mode": proxy.config.mode}
-
-        # Build unified savings summary (all layers)
-        compression_tokens = m.tokens_saved_total
-        cache_net_usd = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)
-        total_tokens_all_layers = compression_tokens + cli_tokens_avoided
-        persistent_savings = m.savings_tracker.stats_preview()
-        display_session = persistent_savings.get("display_session", {})
-
-        return {
-            "summary": summary,
-            "savings": {
-                "total_tokens": total_tokens_all_layers,
-                "by_layer": {
-                    "cli_filtering": {
-                        "tokens": cli_tokens_avoided,
-                        "description": "Tokens avoided by CLI output filtering (rtk) before reaching context",
-                    },
-                    "compression": {
-                        "tokens": compression_tokens,
-                        "description": "Tokens removed by proxy compression (SmartCrusher, ContentRouter, etc.)",
-                    },
-                    "prefix_cache": {
-                        "discount_usd": round(cache_net_usd, 4),
-                        "description": (
-                            "Cost discount from provider prefix caching. "
-                            "Headroom's CacheAligner improves hit rates; "
-                            "baseline caching is provider-native."
-                        ),
-                    },
-                },
-            },
-            "requests": {
-                "total": m.requests_total,
-                "cached": m.requests_cached,
-                "rate_limited": m.requests_rate_limited,
-                "failed": m.requests_failed,
-                "by_provider": dict(m.requests_by_provider),
-                "by_model": dict(m.requests_by_model),
-                "by_stack": dict(m.requests_by_stack),
-            },
-            "tokens": {
-                "input": m.tokens_input_total,
-                "output": m.tokens_output_total,
-                "saved": m.tokens_saved_total,
-                "cli_tokens_avoided": cli_tokens_avoided,
-                "total_before_compression": total_tokens_before,
-                "savings_percent": round(
-                    (m.tokens_saved_total / total_tokens_before * 100)
-                    if total_tokens_before > 0
-                    else 0,
-                    2,
-                ),
-            },
-            "latency": {
-                "average_ms": avg_latency_ms,
-                "min_ms": min_latency_ms,
-                "max_ms": max_latency_ms,
-                "total_requests": m.latency_count,
-            },
-            "overhead": {
-                "average_ms": avg_overhead_ms,
-                "min_ms": min_overhead_ms,
-                "max_ms": max_overhead_ms,
-            },
-            "ttfb": {
-                "average_ms": avg_ttfb_ms,
-                "min_ms": min_ttfb_ms,
-                "max_ms": max_ttfb_ms,
-            },
-            "pipeline_timing": {
-                name: {
-                    "average_ms": round(
-                        m.transform_timing_sum[name] / m.transform_timing_count[name], 2
-                    ),
-                    "max_ms": round(m.transform_timing_max[name], 2),
-                    "count": m.transform_timing_count[name],
-                }
-                for name in sorted(m.transform_timing_sum.keys())
-            }
-            if m.transform_timing_sum
-            else {},
-            "waste_signals": dict(m.waste_signals_total) if m.waste_signals_total else {},
-            "savings_history": m.savings_history[-100:],  # Last 100 data points
-            "display_session": display_session,
-            "persistent_savings": persistent_savings,
-            "prefix_cache": prefix_cache_stats,
-            "cost": _merge_cost_stats(
-                proxy.cost_tracker.stats() if proxy.cost_tracker else None,
-                prefix_cache_stats,
-                cli_tokens_avoided=cli_tokens_avoided,
-            ),
-            "compression": {
-                "ccr_entries": compression_stats.get("entry_count", 0),
-                "ccr_max_entries": compression_stats.get("max_entries", 0),
-                "original_tokens_cached": compression_stats.get("total_original_tokens", 0),
-                "compressed_tokens_cached": compression_stats.get("total_compressed_tokens", 0),
-                "ccr_retrievals": compression_stats.get("total_retrievals", 0),
-            },
-            "compression_cache": compression_cache_stats,
-            "anon_telemetry_shipping": is_telemetry_enabled(),
-            "telemetry": {
-                "enabled": telemetry_stats.get("enabled", False),
-                "total_compressions": telemetry_stats.get("total_compressions", 0),
-                "total_retrievals": telemetry_stats.get("total_retrievals", 0),
-                "global_retrieval_rate": round(telemetry_stats.get("global_retrieval_rate", 0), 4),
-                "tool_signatures_tracked": telemetry_stats.get("tool_signatures_tracked", 0),
-                "avg_compression_ratio": round(telemetry_stats.get("avg_compression_ratio", 0), 4),
-                "avg_token_reduction": round(telemetry_stats.get("avg_token_reduction", 0), 4),
-            },
-            "otel": get_otel_metrics_status(),
-            "langfuse": get_langfuse_tracing_status(),
-            "feedback_loop": {
-                "tools_tracked": feedback_stats.get("tools_tracked", 0),
-                "total_compressions": feedback_stats.get("total_compressions", 0),
-                "total_retrievals": feedback_stats.get("total_retrievals", 0),
-                "global_retrieval_rate": round(feedback_stats.get("global_retrieval_rate", 0), 4),
-                "tools_with_high_retrieval": sum(
-                    1
-                    for p in feedback_stats.get("tool_patterns", {}).values()
-                    if p.get("retrieval_rate", 0) > 0.3
-                ),
-            },
-            "toin": get_toin().get_stats(),
-            "cli_filtering": cli_filtering_stats,
-            "cache": await proxy.cache.stats() if proxy.cache else None,
-            "rate_limiter": await proxy.rate_limiter.stats() if proxy.rate_limiter else None,
-            "recent_requests": proxy.logger.get_recent(10) if proxy.logger else [],
-            "log_full_messages": proxy.config.log_full_messages if proxy else False,
-            **get_quota_registry().get_all_stats(),
-        }
-
-    async def _get_cached_stats_payload() -> dict[str, Any]:
-        """Return a short-TTL cached `/stats` snapshot for dashboard polling."""
-        now = time.monotonic()
-        cached_payload = cast(dict[str, Any] | None, _stats_snapshot.get("value"))
-        if cached_payload is not None and now < float(_stats_snapshot["expires_at"]):
-            return cached_payload
-
-        async with _stats_snapshot_lock:
-            now = time.monotonic()
-            cached_payload = cast(dict[str, Any] | None, _stats_snapshot.get("value"))
-            if cached_payload is not None and now < float(_stats_snapshot["expires_at"]):
-                return cached_payload
-
-            payload = await _build_stats_payload()
-            _stats_snapshot["value"] = payload
-            _stats_snapshot["expires_at"] = time.monotonic() + DASHBOARD_STATS_CACHE_TTL_SECONDS
-            return payload
-
-    @app.get("/stats")
-    async def stats(cached: bool = False):
-        """Get comprehensive proxy statistics.
-
-        This is the main stats endpoint - it aggregates data from all subsystems:
-        - Request metrics (total, cached, failed, by model/provider)
-        - Token usage and savings
-        - Cost tracking
-        - Canonical persisted display_session metrics for downstream dashboards
-        - Compression (CCR) statistics
-        - Telemetry/TOIN (data flywheel) statistics
-        - Cache and rate limiter stats
-
-        Use ``?cached=1`` for the dashboard fast path. That returns a short-TTL
-        snapshot to avoid rebuilding the full payload on every UI poll.
-        """
-        if cached:
-            return await _get_cached_stats_payload()
-        return await _build_stats_payload()
-
-    @app.get("/stats-history")
-    async def stats_history(
-        format: Literal["json", "csv"] = "json",
-        series: Literal["history", "hourly", "daily", "weekly", "monthly"] = "history",
-        history_mode: Literal["compact", "full", "none"] = "compact",
-    ):
-        """Get durable proxy compression history plus display-session state."""
-        if format == "csv":
-            filename = f"headroom-stats-history-{series}.csv"
-            return Response(
-                content=proxy.metrics.savings_tracker.export_csv(series=series),
-                media_type="text/csv; charset=utf-8",
-                headers={"Content-Disposition": f'attachment; filename="{filename}"'},
-            )
-
-        return proxy.metrics.savings_tracker.history_response(history_mode=history_mode)
-
-    @app.get("/transformations/feed")
-    async def transformations_feed(limit: int = 20):
-        """Get recent message transformations for the live feed.
-
-        Returns empty list if log_full_messages is disabled (messages are not stored).
-        """
-        if limit > 100:
-            limit = 100
-
-        transformations = []
-        log_full_messages = proxy.config.log_full_messages if proxy else False
-
-        if proxy and proxy.logger:
-            logs = proxy.logger.get_recent_with_messages(limit)
-            for log in logs:
-                transformations.append(
-                    {
-                        "request_id": log.get("request_id"),
-                        "timestamp": log.get("timestamp"),
-                        "provider": log.get("provider"),
-                        "model": log.get("model"),
-                        "input_tokens_original": log.get("input_tokens_original"),
-                        "input_tokens_optimized": log.get("input_tokens_optimized"),
-                        "tokens_saved": log.get("tokens_saved"),
-                        "savings_percent": log.get("savings_percent"),
-                        "transforms_applied": log.get("transforms_applied", []),
-                        "request_messages": log.get("request_messages"),
-                        "response_content": log.get("response_content"),
-                        "turn_id": log.get("turn_id"),
-                    }
-                )
-
-        return {"transformations": transformations, "log_full_messages": log_full_messages}
-
-    @app.get("/subscription-window")
-    async def subscription_window():
-        """Current Anthropic subscription window utilisation and Headroom contribution."""
-        tracker = get_subscription_tracker()
-        if tracker is None:
-            return JSONResponse(
-                status_code=503,
-                content={"error": "Subscription tracking is not enabled"},
-            )
-        return JSONResponse(content=tracker.state)
-
-    @app.get("/quota")
-    async def quota():
-        """Unified quota/rate-limit stats for all registered providers (Anthropic, Codex, Copilot)."""
-        return JSONResponse(content=get_quota_registry().get_all_stats())
-
-    @app.get("/metrics")
-    async def metrics():
-        """Prometheus metrics endpoint."""
-        return PlainTextResponse(
-            await proxy.metrics.export(),
-            media_type="text/plain; version=0.0.4",
-        )
-
-    # Debug endpoints
-    @app.get("/debug/memory")
-    async def debug_memory():
-        """Get detailed memory usage statistics.
-
-        Returns memory usage for all tracked components including:
-        - Process-level memory (RSS, VMS, percent)
-        - Per-component memory usage and budgets
-        - Cache hit/miss statistics
-        - Total tracked vs target budget
-
-        This endpoint is useful for debugging memory issues and
-        monitoring memory budgets.
-        """
-        from ..memory.tracker import MemoryTracker
-
-        tracker = MemoryTracker.get()
-
-        # Register components if not already registered
-        _register_memory_components(proxy, tracker)
-
-        report = tracker.get_report()
-        return report.to_dict()
-
-    @app.post("/cache/clear")
-    async def clear_cache():
-        """Clear the response cache."""
-        if proxy.cache:
-            await proxy.cache.clear()
-            return {"status": "cleared"}
-        return {"status": "cache disabled"}
-
-    # CCR (Compress-Cache-Retrieve) endpoints
-    @app.post("/v1/retrieve")
-    async def ccr_retrieve(request: Request):
-        """Retrieve original content from CCR compression cache.
-
-        This is the "Retrieve" part of CCR (Compress-Cache-Retrieve).
-        When SmartCrusher compresses tool outputs, the original data is cached.
-        LLMs can call this endpoint to get more data if needed.
-
-        Request body:
-            hash (str): Hash key from compression marker (required)
-            query (str): Optional search query to filter results
-
-        Response:
-            Full retrieval: {"hash": "...", "original_content": "...", ...}
-            Search: {"hash": "...", "query": "...", "results": [...], "count": N}
-        """
-        data = await request.json()
-        hash_key = data.get("hash")
-        query = data.get("query")
-
-        if not hash_key:
-            raise HTTPException(status_code=400, detail="hash required")
-
-        store = get_compression_store()
-
-        if query:
-            # Search within cached content
-            results = store.search(hash_key, query)
-            return {
-                "hash": hash_key,
-                "query": query,
-                "results": results,
-                "count": len(results),
-            }
-        else:
-            # Return full original content
-            entry = store.retrieve(hash_key)
-            if entry:
-                return {
-                    "hash": hash_key,
-                    "original_content": entry.original_content,
-                    "original_tokens": entry.original_tokens,
-                    "original_item_count": entry.original_item_count,
-                    "compressed_item_count": entry.compressed_item_count,
-                    "tool_name": entry.tool_name,
-                    "retrieval_count": entry.retrieval_count,
-                }
-            raise HTTPException(
-                status_code=404, detail="Entry not found or expired (TTL: 5 minutes)"
-            )
-
-    @app.get("/v1/retrieve/stats")
-    async def ccr_stats():
-        """Get CCR compression store statistics."""
-        store = get_compression_store()
-        stats = store.get_stats()
-        events = store.get_retrieval_events(limit=20)
-        return {
-            "store": stats,
-            "recent_retrievals": [
-                {
-                    "hash": e.hash,
-                    "query": e.query,
-                    "items_retrieved": e.items_retrieved,
-                    "total_items": e.total_items,
-                    "tool_name": e.tool_name,
-                    "retrieval_type": e.retrieval_type,
-                }
-                for e in events
-            ],
-        }
-
-    @app.get("/v1/feedback")
-    async def ccr_feedback():
-        """Get CCR feedback loop statistics and learned patterns.
-
-        This endpoint exposes the feedback loop's learned patterns for monitoring
-        and debugging. It shows:
-        - Per-tool retrieval rates (high = compress less aggressively)
-        - Common search queries per tool
-        - Queried fields (suggest what to preserve)
-
-        Use this to understand how well compression is working and whether
-        the feedback loop is adjusting appropriately.
-        """
-        feedback = get_compression_feedback()
-        stats = feedback.get_stats()
-        return {
-            "feedback": stats,
-            "hints_example": {
-                tool_name: {
-                    "hints": {
-                        "max_items": hints.max_items
-                        if (hints := feedback.get_compression_hints(tool_name))
-                        else 15,
-                        "suggested_items": hints.suggested_items if hints else None,
-                        "skip_compression": hints.skip_compression if hints else False,
-                        "preserve_fields": hints.preserve_fields if hints else [],
-                        "reason": hints.reason if hints else "",
-                    }
-                }
-                for tool_name in list(stats.get("tool_patterns", {}).keys())[:5]
-            },
-        }
-
-    @app.get("/v1/feedback/{tool_name}")
-    async def ccr_feedback_for_tool(tool_name: str):
-        """Get compression hints for a specific tool.
-
-        Returns feedback-based hints that would be used for compressing
-        this tool's output.
-        """
-        feedback = get_compression_feedback()
-        hints = feedback.get_compression_hints(tool_name)
-        patterns = feedback.get_all_patterns().get(tool_name)
-
-        return {
-            "tool_name": tool_name,
-            "hints": {
-                "max_items": hints.max_items,
-                "min_items": hints.min_items,
-                "suggested_items": hints.suggested_items,
-                "aggressiveness": hints.aggressiveness,
-                "skip_compression": hints.skip_compression,
-                "preserve_fields": hints.preserve_fields,
-                "reason": hints.reason,
-            },
-            "pattern": {
-                "total_compressions": patterns.total_compressions if patterns else 0,
-                "total_retrievals": patterns.total_retrievals if patterns else 0,
-                "retrieval_rate": patterns.retrieval_rate if patterns else 0.0,
-                "full_retrieval_rate": patterns.full_retrieval_rate if patterns else 0.0,
-                "search_rate": patterns.search_rate if patterns else 0.0,
-                "common_queries": list(patterns.common_queries.keys())[:10] if patterns else [],
-                "queried_fields": list(patterns.queried_fields.keys())[:10] if patterns else [],
-            }
-            if patterns
-            else None,
-        }
-
-    # Telemetry endpoints (Data Flywheel)
-    @app.get("/v1/telemetry")
-    async def telemetry_stats():
-        """Get telemetry statistics for the data flywheel.
-
-        This endpoint exposes privacy-preserving telemetry data that powers
-        the data flywheel - learning optimal compression strategies across
-        tool types based on usage patterns.
-
-        What's collected (anonymized):
-        - Tool output structure patterns (field types, not values)
-        - Compression decisions and ratios
-        - Retrieval patterns (rate, type, not content)
-        - Strategy effectiveness
-
-        What's NOT collected:
-        - Actual data values
-        - User identifiers
-        - Queries or search terms
-        - File paths or tool names (hashed by default)
-        """
-        telemetry = get_telemetry_collector()
-        return telemetry.get_stats()
-
-    @app.get("/v1/telemetry/export")
-    async def telemetry_export():
-        """Export full telemetry data for aggregation.
-
-        This endpoint exports all telemetry data in a format suitable for
-        cross-user aggregation. The data is privacy-preserving - no actual
-        values are included, only structural patterns and statistics.
-
-        Use this for:
-        - Building a central learning service
-        - Sharing learned patterns across instances
-        - Analysis and debugging
-        """
-        telemetry = get_telemetry_collector()
-        return telemetry.export_stats()
-
-    @app.post("/v1/telemetry/import")
-    async def telemetry_import(request: Request):
-        """Import telemetry data from another source.
-
-        This allows merging telemetry from multiple sources for cross-user
-        learning. The imported data is merged with existing statistics.
-
-        Request body: Telemetry export data from /v1/telemetry/export
-        """
-        telemetry = get_telemetry_collector()
-        data = await request.json()
-        telemetry.import_stats(data)
-        return {"status": "imported", "current_stats": telemetry.get_stats()}
-
-    @app.get("/v1/telemetry/tools")
-    async def telemetry_tools():
-        """Get telemetry statistics for all tracked tool signatures.
-
-        Returns statistics per tool signature (anonymized), including:
-        - Compression ratios and strategy usage
-        - Retrieval rates (high = compression too aggressive)
-        - Learned recommendations
-        """
-        telemetry = get_telemetry_collector()
-        all_stats = telemetry.get_all_tool_stats()
-        return {
-            "tool_count": len(all_stats),
-            "tools": {sig_hash: stats.to_dict() for sig_hash, stats in all_stats.items()},
-        }
-
-    @app.get("/v1/telemetry/tools/{signature_hash}")
-    async def telemetry_tool_detail(signature_hash: str):
-        """Get detailed telemetry for a specific tool signature.
-
-        Includes learned recommendations if enough data has been collected.
-        """
-        telemetry = get_telemetry_collector()
-        stats = telemetry.get_tool_stats(signature_hash)
-        recommendations = telemetry.get_recommendations(signature_hash)
-
-        if stats is None:
-            raise HTTPException(
-                status_code=404, detail=f"No telemetry found for signature: {signature_hash}"
-            )
-
-        return {
-            "signature_hash": signature_hash,
-            "stats": stats.to_dict(),
-            "recommendations": recommendations,
-        }
-
-    # TOIN (Tool Output Intelligence Network) endpoints
-    @app.get("/v1/toin/stats")
-    async def toin_stats():
-        """Get overall TOIN statistics.
-
-        Returns aggregated statistics from the Tool Output Intelligence Network,
-        which learns optimal compression strategies across all tool types.
-
-        Response includes:
-        - enabled: Whether TOIN is enabled
-        - patterns_tracked: Number of unique tool patterns being tracked
-        - total_compressions: Total compression events recorded
-        - total_retrievals: Total retrieval events recorded
-        - global_retrieval_rate: Overall retrieval rate (high = compression too aggressive)
-        - patterns_with_recommendations: Patterns with enough data for recommendations
-        """
-        toin = get_toin()
-        return toin.get_stats()
-
-    @app.get("/v1/toin/patterns")
-    async def toin_patterns(limit: int = 20):
-        """List TOIN patterns with most samples.
-
-        Returns patterns sorted by sample_size descending. Use this to see
-        which tool types have the most data and their learned behaviors.
-
-        Query params:
-            limit: Maximum number of patterns to return (default 20)
-
-        Response includes for each pattern:
-        - hash: Truncated tool signature hash (12 chars)
-        - compressions: Total compression events
-        - retrievals: Total retrieval events
-        - retrieval_rate: Percentage of compressions that triggered retrieval
-        - confidence: Confidence level in recommendations (0.0-1.0)
-        - skip_recommended: Whether TOIN recommends skipping compression
-        - optimal_max_items: Learned optimal max_items setting
-        """
-        toin = get_toin()
-        exported = toin.export_patterns()
-        patterns_data = exported.get("patterns", {})
-
-        # Convert to list and sort by sample_size
-        patterns_list = []
-        for sig_hash, pattern_dict in patterns_data.items():
-            sample_size = pattern_dict.get("sample_size", 0)
-            total_compressions = pattern_dict.get("total_compressions", 0)
-            total_retrievals = pattern_dict.get("total_retrievals", 0)
-            retrieval_rate = (
-                total_retrievals / total_compressions if total_compressions > 0 else 0.0
-            )
-
-            patterns_list.append(
-                {
-                    "hash": sig_hash[:12],
-                    "compressions": total_compressions,
-                    "retrievals": total_retrievals,
-                    "retrieval_rate": f"{retrieval_rate:.1%}",
-                    "confidence": round(pattern_dict.get("confidence", 0.0), 3),
-                    "skip_recommended": pattern_dict.get("skip_compression_recommended", False),
-                    "optimal_max_items": pattern_dict.get("optimal_max_items", 20),
-                    "sample_size": sample_size,
-                }
-            )
-
-        # Sort by sample_size descending
-        patterns_list.sort(key=lambda p: p["sample_size"], reverse=True)
-
-        # Remove sample_size from output (used only for sorting)
-        for p in patterns_list:
-            del p["sample_size"]
-
-        return patterns_list[:limit]
-
-    @app.get("/v1/toin/pattern/{hash_prefix}")
-    async def toin_pattern_detail(hash_prefix: str):
-        """Get detailed TOIN pattern info by hash prefix.
-
-        Searches for a pattern where the tool signature hash starts with
-        the provided prefix. Returns full pattern details if found.
-
-        Path params:
-            hash_prefix: Beginning of the tool signature hash (min 4 chars recommended)
-
-        Response: Full pattern.to_dict() with all learned statistics and recommendations.
-        """
-        toin = get_toin()
-        exported = toin.export_patterns()
-        patterns_data = exported.get("patterns", {})
-
-        # Search for pattern with matching hash prefix
-        for sig_hash, pattern_dict in patterns_data.items():
-            if sig_hash.startswith(hash_prefix):
-                return pattern_dict
-
-        raise HTTPException(
-            status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}"
-        )
-
-    @app.get("/v1/retrieve/{hash_key}")
-    async def ccr_retrieve_get(hash_key: str, query: str | None = None):
-        """GET version of CCR retrieve for easier testing."""
-        store = get_compression_store()
-
-        if query:
-            results = store.search(hash_key, query)
-            return {
-                "hash": hash_key,
-                "query": query,
-                "results": results,
-                "count": len(results),
-            }
-        else:
-            entry = store.retrieve(hash_key)
-            if entry:
-                return {
-                    "hash": hash_key,
-                    "original_content": entry.original_content,
-                    "original_tokens": entry.original_tokens,
-                    "original_item_count": entry.original_item_count,
-                    "compressed_item_count": entry.compressed_item_count,
-                    "tool_name": entry.tool_name,
-                    "retrieval_count": entry.retrieval_count,
-                }
-            raise HTTPException(status_code=404, detail="Entry not found or expired")
-
-    # CCR Tool Call Handler - for agent frameworks to call when LLM uses headroom_retrieve
-    @app.post("/v1/retrieve/tool_call")
-    async def ccr_handle_tool_call(request: Request):
-        """Handle a CCR tool call from an LLM response.
-
-        This endpoint accepts tool call formats from various providers and returns
-        a properly formatted tool result. Agent frameworks can use this to handle
-        CCR tool calls without implementing the retrieval logic themselves.
-
-        Request body (Anthropic format):
-            {
-                "tool_call": {
-                    "id": "toolu_123",
-                    "name": "headroom_retrieve",
-                    "input": {"hash": "abc123", "query": "optional search"}
-                },
-                "provider": "anthropic"
-            }
-
-        Request body (OpenAI format):
-            {
-                "tool_call": {
-                    "id": "call_123",
-                    "function": {
-                        "name": "headroom_retrieve",
-                        "arguments": "{\"hash\": \"abc123\"}"
-                    }
-                },
-                "provider": "openai"
-            }
-
-        Response:
-            {
-                "tool_result": {...},  # Formatted for the provider
-                "success": true,
-                "data": {...}  # Raw retrieval data
-            }
-        """
-        data = await request.json()
-        tool_call = data.get("tool_call", {})
-        provider = data.get("provider", "anthropic")
-
-        # Parse the tool call
-        hash_key, query = parse_tool_call(tool_call, provider)
-
-        if hash_key is None:
-            raise HTTPException(
-                status_code=400, detail=f"Invalid tool call or not a {CCR_TOOL_NAME} call"
-            )
-
-        # Perform retrieval
-        store = get_compression_store()
-
-        if query:
-            results = store.search(hash_key, query)
-            retrieval_data = {
-                "hash": hash_key,
-                "query": query,
-                "results": results,
-                "count": len(results),
-            }
-        else:
-            entry = store.retrieve(hash_key)
-            if entry:
-                retrieval_data = {
-                    "hash": hash_key,
-                    "original_content": entry.original_content,
-                    "original_item_count": entry.original_item_count,
-                    "compressed_item_count": entry.compressed_item_count,
-                }
-            else:
-                retrieval_data = {
-                    "error": "Entry not found or expired (TTL: 5 minutes)",
-                    "hash": hash_key,
-                }
-
-        # Format tool result for provider
-        tool_call_id = tool_call.get("id", "")
-        result_content = json.dumps(retrieval_data, indent=2)
-
-        if provider == "anthropic":
-            tool_result = {
-                "type": "tool_result",
-                "tool_use_id": tool_call_id,
-                "content": result_content,
-            }
-        elif provider == "openai":
-            tool_result = {
-                "role": "tool",
-                "tool_call_id": tool_call_id,
-                "content": result_content,
-            }
-        else:
-            tool_result = {
-                "tool_call_id": tool_call_id,
-                "content": result_content,
-            }
-
-        return {
-            "tool_result": tool_result,
-            "success": "error" not in retrieval_data,
-            "data": retrieval_data,
-        }
-
-    # Compression-only endpoint (for TypeScript SDK and other HTTP clients)
-    @app.post("/v1/compress")
-    async def compress_messages(request: Request):
-        return await proxy.handle_compress(request)
-
-    register_provider_routes(app, proxy)
-
-    return app
-
-
-def _get_code_aware_banner_status(config: ProxyConfig) -> str:
-    """Get code-aware compression status line for banner."""
-    if config.code_aware_enabled:
-        if is_tree_sitter_available():
-            return "ENABLED  (AST-based)"
-        else:
-            return "NOT INSTALLED (pip install headroom-ai[code])"
-    else:
-        if is_tree_sitter_available():
-            return "DISABLED (remove --no-code-aware to enable)"
-        return "DISABLED"
-
-
-def run_server(
-    config: ProxyConfig | None = None,
-    workers: int = 1,
-    limit_concurrency: int = 1000,
-):
-    """Run the proxy server.
-
-    Args:
-        config: Proxy configuration
-        workers: Number of worker processes (use N for multi-core scaling)
-        limit_concurrency: Max concurrent connections before 503 response
-    """
-    if not FASTAPI_AVAILABLE:
-        print("ERROR: FastAPI required. Install: pip install fastapi uvicorn httpx")
-        sys.exit(1)
-
-    config = config or ProxyConfig()
-    app = create_app(config)
-
-    code_aware_status = _get_code_aware_banner_status(config)
-
-    # Format connection pool info
-    pool_info = f"max={config.max_connections}, keepalive={config.max_keepalive_connections}"
-    http2_status = "ENABLED" if config.http2 else "DISABLED"
-
-    backend_status = format_backend_status(
-        backend=config.backend,
-        anyllm_provider=config.anyllm_provider,
-        bedrock_region=config.bedrock_region,
-    )
-
-    print(f"""
-╔══════════════════════════════════════════════════════════════════════╗
-║                      HEADROOM PROXY SERVER                           ║
-╠══════════════════════════════════════════════════════════════════════╣
-║  Version: 1.0.0                                                      ║
-║  Listening: http://{config.host}:{config.port:<5}                                      ║
-║  Workers: {workers:<3}  Concurrency Limit: {limit_concurrency:<5}                          ║
-║  Backend: {backend_status:<59}║
-╠══════════════════════════════════════════════════════════════════════╣
-║  FEATURES:                                                           ║
-║    Optimization:    {"ENABLED " if config.optimize else "DISABLED"}                                       ║
-║    Caching:         {"ENABLED " if config.cache_enabled else "DISABLED"}   (TTL: {config.cache_ttl_seconds}s)                          ║
-║    Rate Limiting:   {"ENABLED " if config.rate_limit_enabled else "DISABLED"}   ({config.rate_limit_requests_per_minute} req/min, {config.rate_limit_tokens_per_minute:,} tok/min)       ║
-║    Retry:           {"ENABLED " if config.retry_enabled else "DISABLED"}   (max {config.retry_max_attempts} attempts)                       ║
-║    Cost Tracking:   {"ENABLED " if config.cost_tracking_enabled else "DISABLED"}   (budget: {"$" + str(config.budget_limit_usd) + "/" + config.budget_period if config.budget_limit_usd else "unlimited"})          ║
-║    Code-Aware:      {code_aware_status:<52}║
-║    HTTP/2:          {http2_status:<52}║
-║    Conn Pool:       {pool_info:<52}║
-╠══════════════════════════════════════════════════════════════════════╣
-║  USAGE:                                                              ║
-║    Claude Code:   ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude     ║
-║    Cursor:        Set base URL in settings                           ║
-╠══════════════════════════════════════════════════════════════════════╣
-║  ENDPOINTS:                                                          ║
-║    /livez                   Process liveness                         ║
-║    /readyz                  Traffic readiness                        ║
-║    /health                  Aggregate health                         ║
-║    /stats                   Detailed statistics                      ║
-║    /metrics                 Prometheus metrics                       ║
-║    /cache/clear             Clear response cache                     ║
-║    /v1/retrieve             CCR: Retrieve compressed content         ║
-║    /v1/retrieve/stats       CCR: Compression store stats             ║
-║    /v1/retrieve/tool_call   CCR: Handle LLM tool calls               ║
-║    /v1/feedback             CCR: Feedback loop stats & patterns      ║
-║    /v1/feedback/{{tool}}    CCR: Compression hints for a tool        ║
-║    /v1/telemetry            Data flywheel: Telemetry stats           ║
-║    /v1/telemetry/export     Data flywheel: Export for aggregation    ║
-║    /v1/telemetry/tools      Data flywheel: Per-tool stats            ║
-║    /v1/toin/stats           TOIN: Overall intelligence stats         ║
-║    /v1/toin/patterns        TOIN: List learned patterns              ║
-║    /v1/toin/pattern/{{hash}} TOIN: Pattern details by hash            ║
-╚══════════════════════════════════════════════════════════════════════╝
-""")
-
-    uvicorn.run(
-        app,
-        host=config.host,
-        port=config.port,
-        log_level="warning",
-        workers=workers if workers > 1 else None,  # None = single process (default)
-        limit_concurrency=limit_concurrency,
-        # Defense-in-depth: the loopback guard for /debug/* endpoints trusts
-        # request.client.host. uvicorn's ProxyHeadersMiddleware rewrites that
-        # from X-Forwarded-For when FORWARDED_ALLOW_IPS is broader than the
-        # default. Disabling proxy_headers here guarantees the guard sees the
-        # real peer address regardless of env.
-        proxy_headers=False,
-    )
-
-
-def _get_env_bool(name: str, default: bool) -> bool:
-    """Get boolean from environment variable."""
-    val = os.environ.get(name)
-    if val is None:
-        return default
-    return val.lower() in ("true", "1", "yes", "on")
-
-
-def _get_env_int(name: str, default: int) -> int:
-    """Get integer from environment variable."""
-    val = os.environ.get(name)
-    if val is None:
-        return default
-    try:
-        return int(val)
-    except ValueError:
-        return default
-
-
-def _get_env_float(name: str, default: float) -> float:
-    """Get float from environment variable."""
-    val = os.environ.get(name)
-    if val is None:
-        return default
-    try:
-        return float(val)
-    except ValueError:
-        return default
-
-
-def _get_env_str(name: str, default: str) -> str:
-    """Get string from environment variable."""
-    return os.environ.get(name, default)
-
-
-def _parse_tool_profiles(cli_profiles: list[str]) -> dict[str, Any]:
-    """Parse tool profiles from CLI args and HEADROOM_TOOL_PROFILES env var.
-
-    Format: ToolName:level (e.g., Grep:conservative, Bash:moderate)
-    Env var format: comma-separated (e.g., "Grep:conservative,Bash:moderate")
-
-    Returns:
-        Dict mapping tool names to CompressionProfile instances.
-    """
-    from headroom.config import PROFILE_PRESETS, CompressionProfile
-
-    profiles: dict[str, CompressionProfile] = {}
-    raw_entries: list[str] = list(cli_profiles)
-
-    # Also check env var
-    env_val = os.environ.get("HEADROOM_TOOL_PROFILES", "")
-    if env_val:
-        raw_entries.extend(e.strip() for e in env_val.split(",") if e.strip())
-
-    for entry in raw_entries:
-        if ":" not in entry:
-            logger.warning("Invalid tool profile format (expected ToolName:level): %s", entry)
-            continue
-        tool_name, level = entry.split(":", 1)
-        tool_name = tool_name.strip()
-        level = level.strip().lower()
-
-        if level in PROFILE_PRESETS:
-            profiles[tool_name] = PROFILE_PRESETS[level]
-        else:
-            logger.warning(
-                "Unknown profile level '%s' for tool '%s'. Use: conservative, moderate, aggressive",
-                level,
-                tool_name,
-            )
-
-    return profiles
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Headroom Proxy Server")
-
-    # Server
-    parser.add_argument("--host", default="127.0.0.1")
-    parser.add_argument("--port", type=int, default=8787)
-    parser.add_argument(
-        "--openai-api-url", help=f"Custom OpenAI API URL (default: {DEFAULT_OPENAI_API_URL})"
-    )
-    parser.add_argument(
-        "--anthropic-api-url",
-        help=f"Custom Anthropic API URL (default: {DEFAULT_ANTHROPIC_API_URL})",
-    )
-
-    # Backend (anthropic direct, bedrock, openrouter, anyllm, or litellm-<provider>)
-    parser.add_argument(
-        "--backend",
-        default="anthropic",
-        help=(
-            "Backend: 'anthropic' (direct), 'bedrock' (AWS), 'openrouter', "
-            "'anyllm' (any-llm), or 'litellm-<provider>' (e.g., litellm-hosted_vllm, litellm-vertex)"
-        ),
-    )
-    parser.add_argument(
-        "--bedrock-region",
-        default="us-west-2",
-        help="AWS region for Bedrock backend (default: us-west-2)",
-    )
-    parser.add_argument(
-        "--bedrock-profile",
-        help="AWS profile for Bedrock backend (default: use default credentials)",
-    )
-    parser.add_argument(
-        "--openrouter-api-key",
-        help="OpenRouter API key (or set OPENROUTER_API_KEY env var)",
-    )
-    parser.add_argument(
-        "--anyllm-provider",
-        default="openai",
-        help="any-llm provider: openai, anthropic, mistral, groq, ollama, bedrock, etc. (default: openai)",
-    )
-
-    # Connection pool (scalability)
-    parser.add_argument(
-        "--max-connections",
-        type=int,
-        default=500,
-        help="Max connections to upstream APIs (default: 500)",
-    )
-    parser.add_argument(
-        "--max-keepalive", type=int, default=100, help="Max keepalive connections (default: 100)"
-    )
-    parser.add_argument(
-        "--no-http2",
-        action="store_true",
-        help="Disable HTTP/2 (enabled by default for better throughput)",
-    )
-    parser.add_argument(
-        "--workers",
-        type=int,
-        default=1,
-        help="Number of worker processes (default: 1, use N for multi-core)",
-    )
-    parser.add_argument(
-        "--limit-concurrency",
-        type=int,
-        default=1000,
-        help="Max concurrent connections before 503 (default: 1000)",
-    )
-
-    # Optimization
-    parser.add_argument("--no-optimize", action="store_true", help="Disable optimization")
-    parser.add_argument("--min-tokens", type=int, default=500, help="Min tokens to crush")
-    parser.add_argument("--max-items", type=int, default=50, help="Max items after crush")
-    parser.add_argument(
-        "--tool-profile",
-        action="append",
-        default=[],
-        help="Per-tool compression profile: ToolName:level (e.g., Grep:conservative, Bash:moderate, WebFetch:aggressive). "
-        "Can be specified multiple times. Also settable via HEADROOM_TOOL_PROFILES env var.",
-    )
-
-    # Caching
-    parser.add_argument("--no-cache", action="store_true", help="Disable caching")
-    parser.add_argument("--cache-ttl", type=int, default=3600, help="Cache TTL seconds")
-
-    # Rate limiting
-    parser.add_argument("--no-rate-limit", action="store_true", help="Disable rate limiting")
-    parser.add_argument("--rpm", type=int, default=60, help="Requests per minute")
-    parser.add_argument("--tpm", type=int, default=100000, help="Tokens per minute")
-
-    # Cost
-    parser.add_argument("--budget", type=float, help="Budget limit in USD")
-    parser.add_argument("--budget-period", choices=["hourly", "daily", "monthly"], default="daily")
-
-    # Logging
-    parser.add_argument("--log-file", help="Log file path")
-    parser.add_argument("--log-messages", action="store_true", help="Log full messages")
-
-    # Smart routing (content-aware compression)
-    parser.add_argument(
-        "--no-smart-routing",
-        action="store_true",
-        help="Disable smart routing (use legacy sequential pipeline)",
-    )
-
-    # Code-aware compression
-    parser.add_argument(
-        "--code-aware",
-        action="store_true",
-        help="Enable AST-based code compression (requires: pip install headroom-ai[code])",
-    )
-    parser.add_argument(
-        "--no-code-aware",
-        action="store_true",
-        help="Disable code-aware compression",
-    )
-
-    args = parser.parse_args()
-
-    # Environment variable defaults (HEADROOM_* prefix)
-    # CLI args override env vars, env vars override ProxyConfig defaults
-    env_smart_routing = _get_env_bool("HEADROOM_SMART_ROUTING", True)
-    env_code_aware = _get_env_bool("HEADROOM_CODE_AWARE_ENABLED", True)
-    env_optimize = _get_env_bool("HEADROOM_OPTIMIZE", True)
-    env_cache = _get_env_bool("HEADROOM_CACHE_ENABLED", True)
-    env_rate_limit = _get_env_bool("HEADROOM_RATE_LIMIT_ENABLED", True)
-
-    # Determine settings: CLI flags override env vars
-    # --no-X explicitly disables, --X explicitly enables, neither uses env var
-    smart_routing = env_smart_routing if not args.no_smart_routing else False
-    code_aware_enabled = (
-        env_code_aware
-        if not (args.code_aware or args.no_code_aware)
-        else (args.code_aware or not args.no_code_aware)
-    )
-    optimize = env_optimize if not args.no_optimize else False
-    cache_enabled = env_cache if not args.no_cache else False
-    rate_limit_enabled = env_rate_limit if not args.no_rate_limit else False
-
-    # Set OpenRouter API key from CLI if provided
-    if hasattr(args, "openrouter_api_key") and args.openrouter_api_key:
-        os.environ["OPENROUTER_API_KEY"] = args.openrouter_api_key
-
-    # Parse per-tool compression profiles from CLI and env var
-    tool_profiles = _parse_tool_profiles(args.tool_profile)
-
-    config = ProxyConfig(
-        host=_get_env_str("HEADROOM_HOST", args.host),
-        port=_get_env_int("HEADROOM_PORT", args.port),
-        openai_api_url=_get_env_str("OPENAI_TARGET_API_URL", args.openai_api_url),
-        anthropic_api_url=_get_env_str("ANTHROPIC_TARGET_API_URL", args.anthropic_api_url),
-        # Backend settings
-        backend=_get_env_str("HEADROOM_BACKEND", args.backend),  # type: ignore[arg-type]
-        bedrock_region=_get_env_str("HEADROOM_BEDROCK_REGION", args.bedrock_region),
-        bedrock_profile=args.bedrock_profile or os.environ.get("AWS_PROFILE"),
-        anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", args.anyllm_provider),
-        optimize=optimize,
-        min_tokens_to_crush=_get_env_int("HEADROOM_MIN_TOKENS", args.min_tokens),
-        max_items_after_crush=_get_env_int("HEADROOM_MAX_ITEMS", args.max_items),
-        cache_enabled=cache_enabled,
-        cache_ttl_seconds=_get_env_int("HEADROOM_CACHE_TTL", args.cache_ttl),
-        rate_limit_enabled=rate_limit_enabled,
-        rate_limit_requests_per_minute=_get_env_int("HEADROOM_RPM", args.rpm),
-        rate_limit_tokens_per_minute=_get_env_int("HEADROOM_TPM", args.tpm),
-        budget_limit_usd=args.budget,
-        budget_period=args.budget_period,
-        log_file=_get_env_str("HEADROOM_LOG_FILE", args.log_file)
-        if args.log_file
-        else os.environ.get("HEADROOM_LOG_FILE"),
-        log_full_messages=args.log_messages or _get_env_bool("HEADROOM_LOG_MESSAGES", False),
-        smart_routing=smart_routing,
-        code_aware_enabled=code_aware_enabled,
-        # Connection pool settings
-        max_connections=_get_env_int("HEADROOM_MAX_CONNECTIONS", args.max_connections),
-        max_keepalive_connections=_get_env_int("HEADROOM_MAX_KEEPALIVE", args.max_keepalive),
-        http2=not args.no_http2 and _get_env_bool("HEADROOM_HTTP2", True),
-        tool_profiles=tool_profiles if tool_profiles else None,
-        mode=normalize_proxy_mode(_get_env_str("HEADROOM_MODE", PROXY_MODE_TOKEN)),
-    )
-
-    # Get worker and concurrency settings
-    workers = _get_env_int("HEADROOM_WORKERS", args.workers)
-    limit_concurrency = _get_env_int("HEADROOM_LIMIT_CONCURRENCY", args.limit_concurrency)
-
-    run_server(config, workers=workers, limit_concurrency=limit_concurrency)
+"""Headroom Proxy Server - Production Ready.
+
+A full-featured LLM proxy with optimization, caching, rate limiting,
+and observability.
+
+Features:
+- Context optimization (SmartCrusher, CacheAligner, RollingWindow)
+- Semantic caching (save costs on repeated queries)
+- Rate limiting (token bucket)
+- Retry with exponential backoff
+- Cost tracking and budgets
+- Request tagging and metadata
+- Provider fallback
+- Prometheus metrics
+- Full request/response logging
+
+Usage:
+    python -m headroom.proxy.server --port 8787
+
+    # With Claude Code:
+    ANTHROPIC_BASE_URL=http://localhost:8787 claude
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+if TYPE_CHECKING:
+    from ..backends.base import Backend
+    from ..cache.compression_cache import CompressionCache
+    from ..memory.tracker import MemoryTracker
+
+
+import httpx
+
+try:
+    import uvicorn
+    from fastapi import Depends, FastAPI, HTTPException, Request, Response
+    from fastapi.middleware.cors import CORSMiddleware
+    from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
+
+    FASTAPI_AVAILABLE = True
+except ImportError:
+    FASTAPI_AVAILABLE = False
+
+# Add parent to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from headroom._version import __version__
+from headroom.cache.compression_feedback import get_compression_feedback
+from headroom.cache.compression_store import get_compression_store
+from headroom.ccr import (
+    CCR_TOOL_NAME,
+    # Batch processing
+    CCRResponseHandler,
+    CCRToolInjector,
+    ContextTracker,
+    ContextTrackerConfig,
+    ResponseHandlerConfig,
+    parse_tool_call,
+)
+from headroom.config import (
+    CacheAlignerConfig,
+    CCRConfig,
+    IntelligentContextConfig,
+    ReadLifecycleConfig,
+    RollingWindowConfig,
+    SmartCrusherConfig,
+)
+from headroom.dashboard import get_dashboard_html
+from headroom.observability import (
+    LangfuseTracingConfig,
+    OTelMetricsConfig,
+    configure_langfuse_tracing,
+    configure_otel_metrics,
+    get_langfuse_tracing_status,
+    get_otel_metrics_status,
+    shutdown_headroom_tracing,
+    shutdown_otel_metrics,
+)
+from headroom.pipeline import PipelineExtensionManager, PipelineStage
+from headroom.providers.proxy_routes import register_provider_routes
+from headroom.providers.registry import (
+    DEFAULT_ANTHROPIC_API_URL,
+    DEFAULT_CLOUDCODE_API_URL,
+    DEFAULT_GEMINI_API_URL,
+    DEFAULT_OPENAI_API_URL,
+    build_proxy_provider_runtime,
+    create_proxy_backend,
+    format_backend_status,
+)
+
+# =============================================================================
+# Extracted modules (re-exported for backward compatibility)
+# =============================================================================
+from headroom.proxy.cost import (
+    _CACHE_ECONOMICS,  # noqa: F401
+    CostTracker,  # noqa: F401
+    _summarize_transforms,  # noqa: F401
+    build_prefix_cache_stats,  # noqa: F401
+    build_session_summary,  # noqa: F401
+    merge_cost_stats,  # noqa: F401
+)
+from headroom.proxy.helpers import (
+    COMPRESSION_TIMEOUT_SECONDS,  # noqa: F401
+    MAX_COMPRESSION_CACHE_SESSIONS,  # noqa: F401
+    MAX_MESSAGE_ARRAY_LENGTH,  # noqa: F401
+    MAX_REQUEST_BODY_SIZE,  # noqa: F401
+    MAX_SSE_BUFFER_SIZE,  # noqa: F401
+    _get_image_compressor,  # noqa: F401
+    _get_rtk_stats,  # noqa: F401
+    _read_request_json,  # noqa: F401
+    _setup_file_logging,  # noqa: F401
+    is_anthropic_auth,  # noqa: F401
+    jitter_delay_ms,
+)
+from headroom.proxy.memory_handler import MemoryConfig, MemoryHandler
+
+# Data models (extracted to headroom/proxy/models.py for maintainability)
+from headroom.proxy.models import CacheEntry, ProxyConfig, RateLimitState, RequestLog  # noqa: F401
+from headroom.proxy.modes import (
+    PROXY_MODE_CACHE,
+    PROXY_MODE_TOKEN,
+    is_token_mode,
+    normalize_proxy_mode,
+)
+from headroom.proxy.prometheus_metrics import PrometheusMetrics  # noqa: F401
+from headroom.proxy.rate_limiter import TokenBucketRateLimiter  # noqa: F401
+from headroom.proxy.request_logger import RequestLogger  # noqa: F401
+from headroom.proxy.semantic_cache import SemanticCache  # noqa: F401
+from headroom.proxy.warmup import WarmupRegistry
+from headroom.proxy.ws_session_registry import WebSocketSessionRegistry
+from headroom.subscription.base import get_quota_registry, reset_quota_registry
+from headroom.subscription.codex_rate_limits import get_codex_rate_limit_state
+from headroom.subscription.copilot_quota import get_copilot_quota_tracker
+from headroom.subscription.tracker import (
+    configure_subscription_tracker,
+    get_subscription_tracker,
+)
+from headroom.telemetry import get_telemetry_collector
+from headroom.telemetry.beacon import is_telemetry_enabled
+from headroom.telemetry.toin import get_toin
+from headroom.transforms import (
+    CacheAligner,
+    CodeAwareCompressor,
+    CodeCompressorConfig,
+    ContentRouter,
+    ContentRouterConfig,
+    IntelligentContextManager,
+    RollingWindow,
+    SmartCrusher,
+    Transform,
+    TransformPipeline,
+    is_tree_sitter_available,
+)
+
+AnyLLMBackend: Any = None
+LiteLLMBackend: Any = None
+
+fcntl: Any = None
+try:
+    import fcntl as _fcntl
+
+    fcntl = _fcntl
+    HAS_FCNTL = True
+except ImportError:
+    HAS_FCNTL = False
+
+_build_prefix_cache_stats = build_prefix_cache_stats
+_build_session_summary = build_session_summary
+_merge_cost_stats = merge_cost_stats
+
+
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger("headroom.proxy")
+
+# Always-on file logging to ~/.headroom/logs/ for `headroom perf` analysis
+_setup_file_logging()
+
+
+# Compression pipeline timeout in seconds
+
+
+from headroom.proxy.handlers import (  # noqa: E402
+    AnthropicHandlerMixin,
+    BatchHandlerMixin,
+    GeminiHandlerMixin,
+    OpenAIHandlerMixin,
+    StreamingMixin,
+)
+
+
+class HeadroomProxy(
+    StreamingMixin,
+    AnthropicHandlerMixin,
+    OpenAIHandlerMixin,
+    GeminiHandlerMixin,
+    BatchHandlerMixin,
+):
+    """Production-ready Headroom optimization proxy."""
+
+    ANTHROPIC_API_URL = DEFAULT_ANTHROPIC_API_URL
+    OPENAI_API_URL = DEFAULT_OPENAI_API_URL
+    GEMINI_API_URL = DEFAULT_GEMINI_API_URL
+    CLOUDCODE_API_URL = DEFAULT_CLOUDCODE_API_URL
+
+    def __init__(self, config: ProxyConfig):
+        self.config = config
+        self.config.mode = normalize_proxy_mode(self.config.mode)
+        self.pipeline_extensions = PipelineExtensionManager(
+            hooks=config.hooks,
+            extensions=config.pipeline_extensions,
+            discover=config.discover_pipeline_extensions,
+        )
+
+        self.provider_runtime = build_proxy_provider_runtime(config)
+        api_targets = self.provider_runtime.api_targets
+
+        # Preserve the long-standing proxy compatibility surface while keeping
+        # provider_runtime as the source of truth for resolved upstream targets.
+        HeadroomProxy.ANTHROPIC_API_URL = api_targets.anthropic
+        HeadroomProxy.OPENAI_API_URL = api_targets.openai
+        HeadroomProxy.GEMINI_API_URL = api_targets.gemini
+        HeadroomProxy.CLOUDCODE_API_URL = api_targets.cloudcode
+        self.anthropic_provider = self.provider_runtime.pipeline_provider("anthropic")
+        self.openai_provider = self.provider_runtime.pipeline_provider("openai")
+
+        # Initialize transforms based on routing mode
+        # Choose context manager: IntelligentContextManager (smart) or RollingWindow (legacy)
+        context_manager: Transform  # Can be either IntelligentContextManager or RollingWindow
+        if config.intelligent_context:
+            # Get TOIN instance for learned pattern integration
+            toin = get_toin() if config.intelligent_context_scoring else None
+            context_manager = IntelligentContextManager(
+                config=IntelligentContextConfig(
+                    enabled=True,
+                    keep_system=True,
+                    keep_last_turns=config.keep_last_turns,
+                    use_importance_scoring=config.intelligent_context_scoring,
+                    toin_integration=config.intelligent_context_scoring,
+                    compress_threshold=0.10 if config.intelligent_context_compress_first else 0.0,
+                ),
+                toin=toin,
+            )
+            self._context_manager_status = "intelligent"
+        else:
+            context_manager = RollingWindow(
+                RollingWindowConfig(
+                    enabled=True,
+                    keep_system=True,
+                    keep_last_turns=config.keep_last_turns,
+                )
+            )
+            self._context_manager_status = "rolling_window"
+
+        if config.smart_routing:
+            # Smart routing: ContentRouter handles all content types intelligently
+            # It lazy-loads compressors only when needed
+            router_config = ContentRouterConfig(
+                enable_code_aware=config.code_aware_enabled,
+                tool_profiles=config.tool_profiles,
+                read_lifecycle=ReadLifecycleConfig(enabled=config.read_lifecycle),
+            )
+            # Token mode: allow compression of older excluded-tool results
+            if is_token_mode(config.mode):
+                router_config.protect_recent_reads_fraction = 0.3
+            transforms = [
+                CacheAligner(CacheAlignerConfig(enabled=False)),
+                ContentRouter(router_config),
+                context_manager,
+            ]
+            self._code_aware_status = "lazy" if config.code_aware_enabled else "disabled"
+        else:
+            # Legacy mode: sequential pipeline
+            transforms = [
+                CacheAligner(CacheAlignerConfig(enabled=False)),
+                SmartCrusher(
+                    SmartCrusherConfig(  # type: ignore[arg-type]
+                        enabled=True,
+                        min_tokens_to_crush=config.min_tokens_to_crush,
+                        max_items_after_crush=config.max_items_after_crush,
+                    ),
+                    ccr_config=CCRConfig(
+                        enabled=config.ccr_inject_tool,
+                        inject_retrieval_marker=config.ccr_inject_tool,  # Add CCR markers
+                    ),
+                ),
+                context_manager,
+            ]
+            # Add CodeAware if enabled and available
+            self._code_aware_status = self._setup_code_aware(config, transforms)
+
+        self.anthropic_pipeline = TransformPipeline(
+            transforms=transforms,
+            provider=self.anthropic_provider,
+        )
+        self.openai_pipeline = TransformPipeline(
+            transforms=transforms,
+            provider=self.openai_provider,
+        )
+
+        # Initialize components
+        self.cache = (
+            SemanticCache(
+                max_entries=config.cache_max_entries,
+                ttl_seconds=config.cache_ttl_seconds,
+            )
+            if config.cache_enabled
+            else None
+        )
+
+        self.rate_limiter = (
+            TokenBucketRateLimiter(
+                requests_per_minute=config.rate_limit_requests_per_minute,
+                tokens_per_minute=config.rate_limit_tokens_per_minute,
+            )
+            if config.rate_limit_enabled
+            else None
+        )
+
+        self.cost_tracker = (
+            CostTracker(
+                budget_limit_usd=config.budget_limit_usd,
+                budget_period=config.budget_period,
+            )
+            if config.cost_tracking_enabled
+            else None
+        )
+
+        self.metrics = PrometheusMetrics(cost_tracker=self.cost_tracker)
+
+        # Prefix cache tracking: freeze already-cached messages to avoid
+        # invalidating the provider's prefix cache with our transforms
+        from headroom.cache.prefix_tracker import PrefixFreezeConfig, SessionTrackerStore
+
+        self.session_tracker_store = SessionTrackerStore(
+            default_config=PrefixFreezeConfig(
+                enabled=config.prefix_freeze_enabled,
+                session_ttl_seconds=config.prefix_freeze_session_ttl,
+            )
+        )
+
+        # Compression cache store for token mode (session-scoped)
+        self._compression_caches: dict[str, CompressionCache] = {}
+
+        self.logger = (
+            RequestLogger(
+                log_file=config.log_file,
+                log_full_messages=config.log_full_messages,
+            )
+            if config.log_requests
+            else None
+        )
+
+        # Enterprise security plugin (loaded dynamically if available + licensed)
+        self.security = None
+
+        # HTTP client
+        self.http_client: httpx.AsyncClient | None = None
+
+        # Shared cold-start warmup registry (populated by startup()).
+        # Holds typed slots with loaded / loading / null / error status for
+        # each preloaded heavy asset. Exposed as ``proxy.warmup`` and
+        # serialized by the /debug/warmup route (Unit 5).
+        self.warmup: WarmupRegistry = WarmupRegistry()
+        # Unit 3: live registry of Codex WS sessions. Populated by
+        # ``handle_openai_responses_ws`` on accept; drained in its
+        # outermost ``finally``. Consumed by ``/debug/ws-sessions``.
+        self.ws_sessions: WebSocketSessionRegistry = WebSocketSessionRegistry()
+
+        # Unit 4: bounded pre-upstream concurrency for the Anthropic HTTP
+        # path. Caps how many ``handle_anthropic_messages`` calls may be
+        # running deep-copy / first-stage compression / memory-context
+        # lookup / upstream connect concurrently. ``/livez``, ``/readyz``,
+        # ``/health``, ``/metrics``, ``/stats``, and the Codex WS path are
+        # intentionally NOT gated by this semaphore.
+        #
+        # A value of ``0`` or negative disables the semaphore (unbounded
+        # mode); this is useful for the Unit 6 counter-factual where we
+        # deliberately reproduce the original starvation. The default is
+        # ``max(2, min(8, os.cpu_count() or 4))``.
+        _pre_upstream_cfg = config.anthropic_pre_upstream_concurrency
+        if _pre_upstream_cfg is None:
+            _pre_upstream_resolved = max(2, min(8, os.cpu_count() or 4))
+        else:
+            _pre_upstream_resolved = _pre_upstream_cfg
+        self.anthropic_pre_upstream_concurrency: int = _pre_upstream_resolved
+        self.anthropic_pre_upstream_acquire_timeout_seconds = float(
+            config.anthropic_pre_upstream_acquire_timeout_seconds
+        )
+        self.anthropic_pre_upstream_memory_context_timeout_seconds = float(
+            config.anthropic_pre_upstream_memory_context_timeout_seconds
+        )
+        if _pre_upstream_resolved > 0:
+            self.anthropic_pre_upstream_sem: asyncio.Semaphore | None = asyncio.Semaphore(
+                _pre_upstream_resolved
+            )
+        else:
+            self.anthropic_pre_upstream_sem = None
+
+        # Backend for Anthropic API (direct, LiteLLM, or any-llm)
+        # Supports: "anthropic" (direct), "bedrock", "vertex", "litellm-<provider>", or "anyllm"
+        self.anthropic_backend: Backend | None = create_proxy_backend(
+            backend=config.backend,
+            anyllm_provider=config.anyllm_provider,
+            bedrock_region=config.bedrock_region,
+            logger=logger,
+            anyllm_backend_cls=AnyLLMBackend,
+            litellm_backend_cls=LiteLLMBackend,
+        )
+
+        # Request counter for IDs
+        self._request_counter = 0
+        self._request_counter_lock = asyncio.Lock()
+
+        # CCR tool injectors (one per provider)
+        self.anthropic_tool_injector = CCRToolInjector(
+            provider="anthropic",
+            inject_tool=config.ccr_inject_tool,
+            inject_system_instructions=config.ccr_inject_system_instructions,
+        )
+        self.openai_tool_injector = CCRToolInjector(
+            provider="openai",
+            inject_tool=config.ccr_inject_tool,
+            inject_system_instructions=config.ccr_inject_system_instructions,
+        )
+
+        # CCR Response Handler (handles CCR tool calls automatically)
+        self.ccr_response_handler = (
+            CCRResponseHandler(
+                ResponseHandlerConfig(
+                    enabled=True,
+                    max_retrieval_rounds=config.ccr_max_retrieval_rounds,
+                )
+            )
+            if config.ccr_handle_responses
+            else None
+        )
+
+        # CCR Context Tracker (tracks compressed content across turns)
+        self.ccr_context_tracker = (
+            ContextTracker(
+                ContextTrackerConfig(
+                    enabled=True,
+                    proactive_expansion=config.ccr_proactive_expansion,
+                    max_proactive_expansions=config.ccr_max_proactive_expansions,
+                )
+            )
+            if config.ccr_context_tracking
+            else None
+        )
+
+        # Turn counter for context tracking
+        self._turn_counter = 0
+
+        # Memory Handler (persistent user memory)
+        self.memory_handler: MemoryHandler | None = None
+        if config.memory_enabled:
+            # Resolve memory DB path: empty → project-scoped default
+            _mem_db_path = config.memory_db_path
+            if not _mem_db_path:
+                _mem_dir = Path.cwd() / ".headroom"
+                _mem_dir.mkdir(parents=True, exist_ok=True)
+                _mem_db_path = str(_mem_dir / "memory.db")
+                logger.info(f"Memory: Project-scoped DB at {_mem_db_path}")
+
+            memory_config = MemoryConfig(
+                enabled=True,
+                backend=config.memory_backend,
+                db_path=_mem_db_path,
+                inject_tools=config.memory_inject_tools,
+                use_native_tool=config.memory_use_native_tool,
+                inject_context=config.memory_inject_context,
+                top_k=config.memory_top_k,
+                min_similarity=config.memory_min_similarity,
+                qdrant_host=config.memory_qdrant_host,
+                qdrant_port=config.memory_qdrant_port,
+                neo4j_uri=config.memory_neo4j_uri,
+                neo4j_user=config.memory_neo4j_user,
+                neo4j_password=config.memory_neo4j_password,
+                bridge_enabled=config.memory_bridge_enabled,
+                bridge_md_paths=config.memory_bridge_md_paths,
+                bridge_md_format=config.memory_bridge_md_format,
+                bridge_auto_import=config.memory_bridge_auto_import,
+                bridge_export_path=config.memory_bridge_export_path,
+            )
+            self.memory_handler = MemoryHandler(
+                memory_config,
+                agent_type=config.traffic_learning_agent_type,
+            )
+
+        # Usage Reporter (license validation + phone-home for managed/enterprise)
+        self.usage_reporter: UsageReporter | None = None
+        if config.license_key:
+            from headroom.telemetry.reporter import UsageReporter
+
+            self.usage_reporter = UsageReporter(
+                license_key=config.license_key,
+                cloud_url=config.license_cloud_url,
+                report_interval=config.license_report_interval,
+            )
+
+        # Traffic Learner (live pattern extraction from proxy traffic)
+        # Only activates with --learn flag; requires --memory for backend
+        self.traffic_learner: TrafficLearner | None = None
+        self.traffic_learning_agent_type: str = config.traffic_learning_agent_type
+        if config.traffic_learning_enabled:
+            from headroom.memory.traffic_learner import TrafficLearner
+
+            self.traffic_learner = TrafficLearner(
+                user_id=os.environ.get("HEADROOM_USER_ID", os.environ.get("USER", "default")),
+                agent_type=config.traffic_learning_agent_type,
+            )
+
+        # Code graph file watcher (live reindex on file changes)
+        self.code_graph_watcher: CodeGraphWatcher | None = None  # type: ignore[annotation-unchecked]
+        if config.code_graph_watcher:
+            from headroom.graph.watcher import CodeGraphWatcher
+
+            self.code_graph_watcher = CodeGraphWatcher(project_dir=Path.cwd())
+            if self.code_graph_watcher.start():
+                logger.info("Code graph: file watcher started")
+            else:
+                self.code_graph_watcher = None
+
+        self.pipeline_extensions.emit(
+            PipelineStage.SETUP,
+            operation="proxy.setup",
+            metadata={
+                "mode": self.config.mode,
+                "optimize": self.config.optimize,
+                "backend": self.config.backend,
+                "memory_enabled": self.config.memory_enabled,
+            },
+        )
+
+    def _get_compression_cache(self, session_id: str) -> CompressionCache:
+        """Get or create a CompressionCache for a session."""
+        if session_id not in self._compression_caches:
+            from headroom.cache.compression_cache import CompressionCache
+
+            # Evict oldest caches if at capacity
+            if len(self._compression_caches) >= MAX_COMPRESSION_CACHE_SESSIONS:
+                # Remove oldest quarter to amortize cleanup cost
+                oldest_keys = list(self._compression_caches.keys())[
+                    : MAX_COMPRESSION_CACHE_SESSIONS // 4
+                ]
+                for key in oldest_keys:
+                    del self._compression_caches[key]
+                logger.info(
+                    "Evicted %d compression caches (exceeded %d max sessions)",
+                    len(oldest_keys),
+                    MAX_COMPRESSION_CACHE_SESSIONS,
+                )
+
+            self._compression_caches[session_id] = CompressionCache()
+        return self._compression_caches[session_id]
+
+    def _setup_code_aware(self, config: ProxyConfig, transforms: list) -> str:
+        """Set up code-aware compression if enabled.
+
+        Args:
+            config: Proxy configuration
+            transforms: Transform list to append to
+
+        Returns:
+            Status string for logging: 'enabled', 'disabled', 'available', 'unavailable'
+        """
+        if config.code_aware_enabled:
+            if is_tree_sitter_available():
+                code_config = CodeCompressorConfig(
+                    preserve_imports=True,
+                    preserve_signatures=True,
+                    preserve_type_annotations=True,
+                )
+                # Insert before RollingWindow (which should be last)
+                transforms.insert(-1, CodeAwareCompressor(code_config))
+                return "enabled"
+            else:
+                logger.warning(
+                    "Code-aware compression requested but tree-sitter not installed. "
+                    "Install with: pip install headroom-ai[code]"
+                )
+                return "unavailable"
+        else:
+            if is_tree_sitter_available():
+                return "available"  # Available but not enabled
+            return "disabled"
+
+    async def startup(self):
+        """Initialize async resources."""
+        self.pipeline_extensions.emit(
+            PipelineStage.PRE_START,
+            operation="proxy.startup",
+            metadata={"port": self.config.port, "host": self.config.host},
+        )
+        self.http_client = httpx.AsyncClient(
+            timeout=httpx.Timeout(
+                connect=self.config.connect_timeout_seconds,
+                read=self.config.request_timeout_seconds,
+                write=self.config.request_timeout_seconds,
+                pool=self.config.connect_timeout_seconds,
+            ),
+            limits=httpx.Limits(
+                max_connections=self.config.max_connections,
+                max_keepalive_connections=self.config.max_keepalive_connections,
+            ),
+            http2=self.config.http2,
+        )
+        logger.info("Headroom Proxy started")
+        logger.info(f"Optimization: {'ENABLED' if self.config.optimize else 'DISABLED'}")
+        self.config.mode = normalize_proxy_mode(self.config.mode)
+        logger.info(f"Mode: {self.config.mode}")
+        if self.config.mode == PROXY_MODE_TOKEN:
+            logger.info("  Prefix freeze: re-freeze after compression")
+            logger.info("  Read protection window: 30%% of excluded-tool messages")
+            logger.info("  CCR TTL: extended for session lifetime")
+            logger.info("  Compression cache: active")
+        if self.config.mode == PROXY_MODE_CACHE:
+            logger.info("  Prefix freeze: strict (all prior turns immutable)")
+            logger.info("  Mutations: latest turn only")
+        logger.info(f"Caching: {'ENABLED' if self.config.cache_enabled else 'DISABLED'}")
+        logger.info(f"Rate Limiting: {'ENABLED' if self.config.rate_limit_enabled else 'DISABLED'}")
+        logger.info(
+            f"Connection Pool: max_connections={self.config.max_connections}, "
+            f"max_keepalive={self.config.max_keepalive_connections}, "
+            f"http2={'ENABLED' if self.config.http2 else 'DISABLED'}"
+        )
+
+        # Unit 4 pre-upstream concurrency announcement. Report the resolved
+        # value (auto-detected vs. explicit) so operators can correlate
+        # ``pre_upstream_wait_ms`` log lines with the configured cap.
+        if self.anthropic_pre_upstream_sem is None:
+            logger.info("Anthropic pre-upstream concurrency: unbounded (explicitly disabled)")
+        else:
+            _explicit = self.config.anthropic_pre_upstream_concurrency
+            _origin = "auto-detected" if _explicit is None else "explicit"
+            logger.info(
+                "Anthropic pre-upstream concurrency: %d (%s)",
+                self.anthropic_pre_upstream_concurrency,
+                _origin,
+            )
+        logger.info(
+            "Anthropic pre-upstream timeouts: acquire=%.1fs compression=%.1fs memory_context=%.1fs",
+            self.anthropic_pre_upstream_acquire_timeout_seconds,
+            float(COMPRESSION_TIMEOUT_SECONDS),
+            self.anthropic_pre_upstream_memory_context_timeout_seconds,
+        )
+
+        # Smart routing status
+        if self.config.smart_routing:
+            logger.info("Smart Routing: ENABLED (intelligent content detection)")
+        else:
+            logger.info("Smart Routing: DISABLED (legacy sequential mode)")
+
+        # Eagerly load ALL compressors, parsers, and detectors at startup
+        # This eliminates cold-start latency spikes on first requests.
+        # Iterate BOTH pipelines (Anthropic + OpenAI) and dedupe transforms
+        # by id() so shared-transform instances never load twice. The
+        # resulting status dict is merged into ``self.warmup`` so /debug/warmup
+        # (Unit 5) and /readyz have a single source of truth.
+        self._kompress_status = "not installed"
+        eager_status: dict[str, str] = {}
+
+        if self.config.optimize:
+            logger.info("Pre-loading compressors and parsers...")
+            seen_transform_ids: set[int] = set()
+            pipelines = (self.anthropic_pipeline, self.openai_pipeline)
+            for pipeline in pipelines:
+                for transform in pipeline.transforms:
+                    if id(transform) in seen_transform_ids:
+                        continue
+                    seen_transform_ids.add(id(transform))
+                    if not hasattr(transform, "eager_load_compressors"):
+                        continue
+                    try:
+                        transform_status = transform.eager_load_compressors()
+                    except Exception as exc:
+                        logger.warning(
+                            "Eager preload failed for %s: %s",
+                            type(transform).__name__,
+                            exc,
+                        )
+                        continue
+                    if not isinstance(transform_status, dict):
+                        continue
+                    # Merge: later writers win only if the key wasn't set.
+                    # Preload a transform ONCE — if another pipeline also has
+                    # ``eager_load_compressors`` it contributes only new keys.
+                    for key, value in transform_status.items():
+                        eager_status.setdefault(key, value)
+                    self.warmup.merge_transform_status(transform_status)
+
+        # Update internal status from eager loading results
+        if eager_status.get("kompress") == "enabled":
+            self._kompress_status = "enabled"
+        if eager_status.get("code_aware") == "enabled":
+            self._code_aware_status = "enabled"
+
+        # Log component status
+        if self._kompress_status == "enabled":
+            logger.info("Kompress: ENABLED (ModernBERT token compressor)")
+        elif self.config.optimize:
+            logger.info("Kompress: not installed (pip install headroom-ai[ml] for ML compression)")
+
+        if self._code_aware_status == "enabled":
+            logger.info("Code-Aware: ENABLED (AST-based compression)")
+            if "tree_sitter" in eager_status:
+                logger.info(f"Tree-Sitter: {eager_status['tree_sitter']}")
+        elif self._code_aware_status == "lazy":
+            logger.info("Code-Aware: LAZY (will load when code content detected)")
+        elif self._code_aware_status == "available":
+            logger.info("Code-Aware: available but disabled (use --code-aware)")
+        elif self._code_aware_status == "unavailable":
+            logger.info("Code-Aware: not installed (pip install headroom-ai[code])")
+        elif self._code_aware_status == "disabled":
+            logger.info("Code-Aware: DISABLED")
+
+        if eager_status.get("magika") == "enabled":
+            logger.info("Magika: ENABLED (ML content detection)")
+
+        if self.memory_handler:
+            self.warmup.memory_backend.mark_loading()
+            try:
+                await self.memory_handler.ensure_initialized()
+            except Exception as exc:  # pragma: no cover - defensive
+                self.warmup.memory_backend.mark_error(str(exc))
+                logger.warning("Memory: backend initialization failed (startup continues): %s", exc)
+            memory_status = self.memory_handler.health_status()
+            if memory_status.get("initialized"):
+                self.warmup.memory_backend.mark_loaded(
+                    handle=self.memory_handler,
+                    backend=memory_status.get("backend"),
+                )
+                # Force one embed call so the ONNX graph is compiled now,
+                # not lazily during the first request. Best-effort — any
+                # failure is swallowed inside warmup_embedder.
+                self.warmup.memory_embedder.mark_loading()
+                warmed = await self.memory_handler.warmup_embedder()
+                if warmed:
+                    self.warmup.memory_embedder.mark_loaded()
+                else:
+                    # Not an error — e.g. qdrant-neo4j has no embedder slot
+                    # we can reach, or the backend simply exposes no handle.
+                    self.warmup.memory_embedder.mark_null()
+            else:
+                if self.warmup.memory_backend.status != "error":
+                    self.warmup.memory_backend.mark_null()
+                self.warmup.memory_embedder.mark_null()
+            logger.info(
+                "Memory: ENABLED "
+                f"(backend={memory_status['backend']}, initialized={memory_status['initialized']})"
+            )
+        else:
+            logger.info("Memory: DISABLED")
+
+        # CCR status
+        ccr_features = []
+        if self.config.ccr_inject_tool:
+            ccr_features.append("tool_injection")
+        if self.config.ccr_handle_responses:
+            ccr_features.append("response_handling")
+        if self.config.ccr_context_tracking:
+            ccr_features.append("context_tracking")
+        if self.config.ccr_proactive_expansion:
+            ccr_features.append("proactive_expansion")
+        if ccr_features:
+            logger.info(f"CCR (Compress-Cache-Retrieve): ENABLED ({', '.join(ccr_features)})")
+        else:
+            logger.info("CCR: DISABLED")
+        logger.info(f"Savings history: {self.metrics.savings_tracker.storage_path}")
+
+        # Reset and rebuild the quota tracker registry for this server instance.
+        # reset_quota_registry() ensures a clean slate when the proxy is restarted
+        # (e.g. in tests that spin up multiple app instances in the same process).
+        reset_quota_registry()
+        registry = get_quota_registry()
+        tracker = configure_subscription_tracker(
+            poll_interval_s=self.config.subscription_poll_interval_s,
+            active_window_s=self.config.subscription_active_window_s,
+            enabled=self.config.subscription_tracking_enabled,
+        )
+        registry.register(tracker)
+        registry.register(get_codex_rate_limit_state())
+        registry.register(get_copilot_quota_tracker())
+        await registry.start_all()
+
+        if self.config.subscription_tracking_enabled:
+            logger.info(
+                "Subscription tracking: ENABLED "
+                f"(poll_interval={self.config.subscription_poll_interval_s}s, "
+                f"active_window={self.config.subscription_active_window_s}s)"
+            )
+        else:
+            logger.info("Subscription tracking: DISABLED")
+
+        copilot_tracker = get_copilot_quota_tracker()
+        if copilot_tracker.is_available():
+            logger.info("GitHub Copilot quota tracking: ENABLED")
+        else:
+            logger.info(
+                "GitHub Copilot quota tracking: DISABLED "
+                "(set GITHUB_TOKEN or GITHUB_COPILOT_GITHUB_TOKEN to enable)"
+            )
+
+        # Log anonymous telemetry status so operators can see it in the log stream
+        if is_telemetry_enabled():
+            logger.info(
+                "Anonymous telemetry: ENABLED (aggregate stats only — no prompts or content). "
+                "Opt out: HEADROOM_TELEMETRY=off or --no-telemetry"
+            )
+        else:
+            logger.info("Anonymous telemetry: DISABLED")
+
+        self.pipeline_extensions.emit(
+            PipelineStage.POST_START,
+            operation="proxy.startup",
+            metadata={
+                "port": self.config.port,
+                "host": self.config.host,
+                "warmup": self.warmup.to_dict(),
+            },
+        )
+
+    async def shutdown(self):
+        """Cleanup async resources."""
+        if self.http_client:
+            await self.http_client.aclose()
+            self.http_client = None
+
+        if self.memory_handler and hasattr(self.memory_handler, "close"):
+            await self.memory_handler.close()
+
+        # Stop all quota trackers via the registry
+        await get_quota_registry().stop_all()
+
+        # Print final stats
+        self._print_summary()
+
+    def _print_summary(self):
+        """Print session summary."""
+        m = self.metrics
+        logger.info("=" * 70)
+        logger.info("HEADROOM PROXY SESSION SUMMARY")
+        logger.info("=" * 70)
+        logger.info(f"Total requests:        {m.requests_total}")
+        logger.info(f"Cached responses:      {m.requests_cached}")
+        logger.info(f"Rate limited:          {m.requests_rate_limited}")
+        logger.info(f"Failed:                {m.requests_failed}")
+        logger.info(f"Input tokens:          {m.tokens_input_total:,}")
+        logger.info(f"Output tokens:         {m.tokens_output_total:,}")
+        logger.info(f"Tokens saved:          {m.tokens_saved_total:,}")
+        if m.tokens_input_total > 0:
+            savings_pct = (
+                m.tokens_saved_total / (m.tokens_input_total + m.tokens_saved_total)
+            ) * 100
+            logger.info(f"Token savings:         {savings_pct:.1f}%")
+        if m.latency_count > 0:
+            avg_latency = m.latency_sum_ms / m.latency_count
+            logger.info(f"Avg latency:           {avg_latency:.0f}ms")
+        logger.info("=" * 70)
+
+    async def _next_request_id(self) -> str:
+        """Generate unique request ID."""
+        async with self._request_counter_lock:
+            self._request_counter += 1
+            return f"hr_{int(time.time())}_{self._request_counter:06d}"
+
+    def _extract_tags(self, headers: dict) -> dict[str, str]:
+        """Extract Headroom tags from headers."""
+        tags = {}
+        for key, value in headers.items():
+            if key.lower().startswith("x-headroom-"):
+                tag_name = key.lower().replace("x-headroom-", "")
+                tags[tag_name] = value
+        return tags
+
+    def _inject_system_context(
+        self,
+        messages: list[dict[str, Any]],
+        context: str,
+        body: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Inject context into the system message/parameter.
+
+        For Anthropic API: Uses top-level 'system' parameter (not messages array).
+        For OpenAI API: Uses system role in messages array.
+
+        Args:
+            messages: The messages list.
+            context: Context to inject.
+            body: Optional request body to update system parameter (for Anthropic).
+
+        Returns:
+            Updated messages list.
+        """
+        messages = list(messages)  # Copy to avoid mutation
+
+        # For Anthropic API: use top-level 'system' parameter
+        if body is not None:
+            existing_system = body.get("system", "")
+            if isinstance(existing_system, str):
+                body["system"] = (existing_system + "\n\n" + context).strip()
+            elif isinstance(existing_system, list):
+                # system is a list of content blocks (e.g., with cache_control).
+                # Append memory context as a new text block — never overwrite.
+                body["system"] = existing_system + [{"type": "text", "text": context}]
+            else:
+                # No existing system prompt — set as string
+                body["system"] = context
+            return messages
+
+        # For OpenAI API: use system role in messages
+        for i, msg in enumerate(messages):
+            if msg.get("role") == "system":
+                content = msg.get("content", "")
+                if isinstance(content, str):
+                    messages[i] = {**msg, "content": content + "\n\n" + context}
+                return messages
+
+        # No system message found - prepend one
+        messages.insert(0, {"role": "system", "content": context})
+        return messages
+
+    async def _retry_request(
+        self,
+        method: str,
+        url: str,
+        headers: dict,
+        body: dict,
+        stream: bool = False,
+    ) -> httpx.Response:
+        """Make request with retry and exponential backoff."""
+        last_error = None
+
+        for attempt in range(self.config.retry_max_attempts):
+            try:
+                if stream:
+                    # For streaming, we return early - retry happens at higher level
+                    return await self.http_client.post(url, json=body, headers=headers)  # type: ignore[union-attr]
+                else:
+                    response = await self.http_client.post(url, json=body, headers=headers)  # type: ignore[union-attr]
+
+                    # Don't retry client errors (4xx)
+                    if 400 <= response.status_code < 500:
+                        return response
+
+                    # Retry server errors (5xx)
+                    if response.status_code >= 500:
+                        raise httpx.HTTPStatusError(
+                            f"Server error: {response.status_code}",
+                            request=response.request,
+                            response=response,
+                        )
+
+                    return response
+
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.HTTPStatusError) as e:
+                last_error = e
+
+                if not self.config.retry_enabled or attempt >= self.config.retry_max_attempts - 1:
+                    raise
+
+                # Exponential backoff with jitter
+                delay_with_jitter = jitter_delay_ms(
+                    self.config.retry_base_delay_ms,
+                    self.config.retry_max_delay_ms,
+                    attempt,
+                )
+
+                logger.warning(
+                    f"Request failed (attempt {attempt + 1}), retrying in {delay_with_jitter:.0f}ms: {e}"
+                )
+                await asyncio.sleep(delay_with_jitter / 1000)
+
+        raise last_error  # type: ignore[misc]
+
+
+async def _log_toin_stats_periodically(interval_seconds: int = 300) -> None:
+    """Background task that logs TOIN stats periodically.
+
+    Args:
+        interval_seconds: How often to log stats (default: 5 minutes).
+    """
+    while True:
+        await asyncio.sleep(interval_seconds)
+        try:
+            toin = get_toin()
+            stats = toin.get_stats()
+            total_compressions = stats.get("total_compressions", 0)
+            if total_compressions > 0:
+                patterns = stats.get("patterns_tracked", 0)
+                retrievals = stats.get("total_retrievals", 0)
+                retrieval_rate = stats.get("global_retrieval_rate", 0.0)
+                logger.info(
+                    "TOIN: %d patterns, %d compressions, %d retrievals, %.1f%% retrieval rate",
+                    patterns,
+                    total_compressions,
+                    retrievals,
+                    retrieval_rate * 100,
+                )
+        except Exception as e:
+            logger.debug("Failed to log TOIN stats: %s", e)
+
+
+def _register_memory_components(proxy: HeadroomProxy, tracker: MemoryTracker) -> None:
+    """Register all memory-tracked components with the tracker.
+
+    This function is idempotent - it checks if components are already registered.
+
+    Args:
+        proxy: The HeadroomProxy instance.
+        tracker: The MemoryTracker instance.
+    """
+    # Register compression store (global singleton)
+    if "compression_store" not in tracker.registered_components:
+        store = get_compression_store()
+        tracker.register("compression_store", store.get_memory_stats)
+
+    # Register semantic cache (instance on proxy)
+    if proxy.cache and "semantic_cache" not in tracker.registered_components:
+        tracker.register("semantic_cache", proxy.cache.get_memory_stats)
+
+    # Register request logger (instance on proxy)
+    if proxy.logger and "request_logger" not in tracker.registered_components:
+        tracker.register("request_logger", proxy.logger.get_memory_stats)
+
+    # Register batch context store (global singleton)
+    if "batch_context_store" not in tracker.registered_components:
+        try:
+            from ..ccr.batch_store import get_batch_context_store
+
+            batch_store = get_batch_context_store()
+            if hasattr(batch_store, "get_memory_stats"):
+                tracker.register("batch_context_store", batch_store.get_memory_stats)
+        except ImportError:
+            pass
+
+    # Note: graph_store and vector_index are created per-user within the
+    # LocalMemoryBackend, not as global singletons. They would need to be
+    # registered when the memory system is initialized with specific backends.
+
+
+def create_app(config: ProxyConfig | None = None) -> FastAPI:
+    """Create FastAPI application."""
+    if not FASTAPI_AVAILABLE:
+        raise ImportError("FastAPI required. Install: pip install fastapi uvicorn httpx")
+
+    from contextlib import asynccontextmanager
+
+    config = config or ProxyConfig()
+    proxy = HeadroomProxy(config)
+
+    # Telemetry beacon (anonymous aggregate stats).
+    # With uvicorn workers > 1, each worker runs the lifespan independently.
+    # We must ensure only ONE beacon runs across all workers — otherwise each
+    # worker creates its own beacon, spamming the telemetry table with N rows
+    # per cycle instead of 1 (all reading the same /stats from the same port).
+    #
+    # Strategy: use a file lock to ensure only the first worker starts the
+    # beacon. Other workers see the lock and skip.
+    from headroom.telemetry.beacon import TelemetryBeacon
+
+    _beacon = TelemetryBeacon(
+        port=config.port if hasattr(config, "port") else 8787,
+        sdk=os.environ.get("HEADROOM_SDK", "proxy").strip() or "proxy",
+        backend=config.backend if hasattr(config, "backend") else "anthropic",
+    )
+    from headroom import paths as _hr_paths
+
+    _beacon_lock_path = _hr_paths.beacon_lock_path(config.port)
+    _beacon_lock_fd: list = [None]  # mutable holder for the lock file descriptor
+    _beacon_is_owner: list = [False]
+
+    def _try_acquire_beacon_lock() -> bool:
+        """Try to acquire the beacon file lock (non-blocking).
+
+        Returns True if this process is the beacon owner.
+        """
+        if not HAS_FCNTL:
+            return True
+
+        fd = None
+        try:
+            _beacon_lock_path.parent.mkdir(parents=True, exist_ok=True)
+            fd = open(_beacon_lock_path, "w")  # noqa: SIM115
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            fd.write(str(os.getpid()))
+            fd.flush()
+            _beacon_lock_fd[0] = fd
+            return True
+        except OSError:
+            if fd is not None:
+                fd.close()
+            return False
+
+    def _release_beacon_lock() -> None:
+        """Release the beacon file lock."""
+        fd = _beacon_lock_fd[0]
+        if fd:
+            try:
+                if HAS_FCNTL:
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+                fd.close()
+            except Exception:
+                pass
+            _beacon_lock_fd[0] = None
+        try:
+            _beacon_lock_path.unlink(missing_ok=True)
+        except Exception:
+            pass
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):  # type: ignore[no-untyped-def]
+        configure_otel_metrics(OTelMetricsConfig.from_env(default_service_name="headroom-proxy"))
+        configure_langfuse_tracing(
+            LangfuseTracingConfig.from_env(default_service_name="headroom-proxy")
+        )
+
+        app.state.started_at = time.time()
+        app.state.ready = False
+        app.state.startup_error = None
+
+        try:
+            try:
+                # Startup
+                await proxy.startup()
+                asyncio.create_task(_log_toin_stats_periodically())
+                if proxy.usage_reporter:
+                    await proxy.usage_reporter.start(proxy)
+                if proxy.traffic_learner:
+                    await proxy.traffic_learner.start()
+
+                # Only start beacon if we acquire the lock (first worker wins)
+                _beacon_is_owner[0] = _try_acquire_beacon_lock()
+                if _beacon_is_owner[0]:
+                    await _beacon.start()
+                else:
+                    logger.debug("Beacon: skipping (another worker owns the lock)")
+
+                app.state.ready = True
+                yield
+            except Exception as exc:
+                app.state.startup_error = str(exc)
+                raise
+        finally:
+            app.state.ready = False
+            # Shutdown
+            if _beacon_is_owner[0]:
+                await _beacon.stop()
+                _release_beacon_lock()
+            if proxy.usage_reporter:
+                await proxy.usage_reporter.stop()
+            if proxy.traffic_learner:
+                await proxy.traffic_learner.stop()
+            if proxy.code_graph_watcher:
+                proxy.code_graph_watcher.stop()
+            await proxy.shutdown()
+            shutdown_headroom_tracing()
+            shutdown_otel_metrics()
+
+    app = FastAPI(
+        title="Headroom Proxy",
+        description="Production-ready LLM optimization proxy",
+        version=__version__,
+        lifespan=lifespan,
+    )
+    app.state.proxy = proxy
+    app.state.started_at = None
+    app.state.ready = False
+    app.state.startup_error = None
+
+    def _iso_utc_now() -> str:
+        return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+    def _uptime_seconds() -> float:
+        started_at = getattr(app.state, "started_at", None)
+        if not isinstance(started_at, int | float):
+            return 0.0
+        return round(max(0.0, time.time() - float(started_at)), 3)
+
+    def _component_health(
+        *,
+        enabled: bool,
+        ready: bool,
+        **details: Any,
+    ) -> dict[str, Any]:
+        status = "disabled" if not enabled else ("healthy" if ready else "unhealthy")
+        return {
+            "enabled": enabled,
+            "ready": (ready if enabled else True),
+            "status": status,
+            **details,
+        }
+
+    def _health_checks() -> dict[str, dict[str, Any]]:
+        memory_status = (
+            proxy.memory_handler.health_status()
+            if proxy.memory_handler
+            else {
+                "enabled": False,
+                "backend": None,
+                "initialized": False,
+                "native_tool": False,
+                "bridge_enabled": False,
+            }
+        )
+        memory_enabled = bool(memory_status.get("enabled", False))
+        memory_initialized = bool(memory_status.get("initialized", False))
+        return {
+            "startup": _component_health(
+                enabled=True,
+                ready=bool(getattr(app.state, "ready", False)),
+                error=getattr(app.state, "startup_error", None),
+            ),
+            "http_client": _component_health(
+                enabled=True,
+                ready=proxy.http_client is not None,
+            ),
+            "cache": _component_health(
+                enabled=config.cache_enabled,
+                ready=(proxy.cache is not None),
+            ),
+            "rate_limiter": _component_health(
+                enabled=config.rate_limit_enabled,
+                ready=(proxy.rate_limiter is not None),
+            ),
+            "memory": _component_health(
+                enabled=memory_enabled,
+                ready=memory_initialized,
+                backend=memory_status["backend"],
+                initialized=memory_initialized,
+                native_tool=bool(memory_status.get("native_tool", False)),
+                bridge_enabled=bool(memory_status.get("bridge_enabled", False)),
+            ),
+        }
+
+    def _runtime_payload() -> dict[str, Any]:
+        ws_registry = getattr(proxy, "ws_sessions", None)
+        ws_active_sessions = ws_registry.active_count() if ws_registry is not None else 0
+        ws_active_relay_tasks = (
+            ws_registry.active_relay_task_count() if ws_registry is not None else 0
+        )
+        return {
+            "anthropic_pre_upstream": {
+                "enabled": proxy.anthropic_pre_upstream_sem is not None,
+                "resolved_concurrency": proxy.anthropic_pre_upstream_concurrency,
+                "source": (
+                    "auto" if config.anthropic_pre_upstream_concurrency is None else "explicit"
+                ),
+                "acquire_timeout_seconds": proxy.anthropic_pre_upstream_acquire_timeout_seconds,
+                "compression_timeout_seconds": float(COMPRESSION_TIMEOUT_SECONDS),
+                "memory_context_timeout_seconds": (
+                    proxy.anthropic_pre_upstream_memory_context_timeout_seconds
+                ),
+                "codex_ws_gated": False,
+            },
+            "websocket_sessions": {
+                "active_sessions": ws_active_sessions,
+                "active_relay_tasks": ws_active_relay_tasks,
+            },
+        }
+
+    def _health_payload(*, include_config: bool) -> dict[str, Any]:
+        checks = _health_checks()
+        ready = all(check["ready"] for check in checks.values())
+        payload: dict[str, Any] = {
+            "service": "headroom-proxy",
+            "status": "healthy" if ready else "unhealthy",
+            "ready": ready,
+            "version": __version__,
+            "timestamp": _iso_utc_now(),
+            "uptime_seconds": _uptime_seconds(),
+            "checks": checks,
+            "runtime": _runtime_payload(),
+        }
+        deployment_profile = os.environ.get("HEADROOM_DEPLOYMENT_PROFILE")
+        if deployment_profile:
+            payload["deployment"] = {
+                "profile": deployment_profile,
+                "preset": os.environ.get("HEADROOM_DEPLOYMENT_PRESET"),
+                "runtime": os.environ.get("HEADROOM_DEPLOYMENT_RUNTIME"),
+                "supervisor": os.environ.get("HEADROOM_DEPLOYMENT_SUPERVISOR"),
+                "scope": os.environ.get("HEADROOM_DEPLOYMENT_SCOPE"),
+            }
+        if include_config:
+            payload["config"] = {
+                "backend": config.backend,
+                "optimize": config.optimize,
+                "cache": config.cache_enabled,
+                "rate_limit": config.rate_limit_enabled,
+                "memory": config.memory_enabled,
+                "learn": config.traffic_learning_enabled,
+                "code_graph": config.code_graph_watcher,
+                "pid": os.getpid(),
+            }
+        return payload
+
+    # CORS
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # X-Headroom-Stack: SDK adapters (TS openai/anthropic/etc.) tag their
+    # requests so telemetry can segment by integration surface. Registered
+    # before extension middleware so any extension-level auth/guards run
+    # outermost and we don't count requests they reject.
+    @app.middleware("http")
+    async def _record_headroom_stack(request, call_next):
+        if request.url.path.startswith("/v1/"):
+            stack = request.headers.get("x-headroom-stack")
+            if stack:
+                try:
+                    proxy.metrics.record_stack(stack)
+                except Exception:
+                    logger.debug("record_stack failed", exc_info=True)
+        return await call_next(request)
+
+    # Third-party proxy extensions (Enterprise, custom plugins). Discovered via
+    # the `headroom.proxy_extension` entry-point group. An extension that raises
+    # from its install() is a deliberate fail-closed signal and aborts startup.
+    from headroom.proxy.extensions import install_all as _install_extensions
+
+    _install_extensions(app, config)
+
+    # Health & Metrics
+    @app.get("/livez")
+    async def livez():
+        return JSONResponse(
+            status_code=200,
+            content={
+                "service": "headroom-proxy",
+                "status": "healthy",
+                "alive": True,
+                "version": __version__,
+                "timestamp": _iso_utc_now(),
+                "uptime_seconds": _uptime_seconds(),
+            },
+        )
+
+    @app.get("/readyz")
+    async def readyz():
+        payload = _health_payload(include_config=False)
+        return JSONResponse(status_code=200 if payload["ready"] else 503, content=payload)
+
+    @app.get("/health")
+    async def health():
+        payload = _health_payload(include_config=True)
+        return JSONResponse(status_code=200, content=payload)
+
+    # Loopback-only debug introspection (Unit 5). A remote IP gets 404 —
+    # debug endpoints are invisible to external scanners.
+    from headroom.proxy.debug_introspection import (
+        collect_tasks as _collect_tasks,
+    )
+    from headroom.proxy.loopback_guard import require_loopback as _require_loopback
+
+    @app.get("/debug/tasks", dependencies=[Depends(_require_loopback)])
+    async def debug_tasks(stack: bool = False):
+        """Enumerate running asyncio tasks.
+
+        Default is cheap — ``stack_depth`` is ``null`` in every entry so
+        a storm snapshot does not walk 50+ coroutine frames synchronously.
+        Pass ``?stack=true`` to compute ``stack_depth`` for each task
+        (useful for single-shot human debugging).
+        """
+        ws_registry = getattr(proxy, "ws_sessions", None)
+        return JSONResponse(
+            status_code=200,
+            content=_collect_tasks(ws_registry, with_stack_depth=stack),
+        )
+
+    @app.get("/debug/ws-sessions", dependencies=[Depends(_require_loopback)])
+    async def debug_ws_sessions():
+        ws_registry = getattr(proxy, "ws_sessions", None)
+        snapshot = ws_registry.snapshot() if ws_registry is not None else []
+        return JSONResponse(status_code=200, content=snapshot)
+
+    @app.get("/debug/warmup", dependencies=[Depends(_require_loopback)])
+    async def debug_warmup():
+        warmup_registry = getattr(proxy, "warmup", None)
+        payload = warmup_registry.to_dict() if warmup_registry is not None else {}
+        payload["runtime"] = _runtime_payload()
+        return JSONResponse(status_code=200, content=payload)
+
+    @app.get("/dashboard", response_class=HTMLResponse)
+    async def dashboard():
+        """Serve the Headroom dashboard UI."""
+        return get_dashboard_html()
+
+    DASHBOARD_STATS_CACHE_TTL_SECONDS = 5.0
+    _stats_snapshot_lock = asyncio.Lock()
+    _stats_snapshot: dict[str, Any] = {"expires_at": 0.0, "value": None}
+
+    async def _build_stats_payload() -> dict[str, Any]:
+        """Build the full `/stats` response payload.
+
+        This is the main stats endpoint - it aggregates data from all subsystems:
+        - Request metrics (total, cached, failed, by model/provider)
+        - Token usage and savings
+        - Cost tracking
+        - Canonical persisted display_session metrics for downstream dashboards
+        - Compression (CCR) statistics
+        - Telemetry/TOIN (data flywheel) statistics
+        - Cache and rate limiter stats
+        """
+        m = proxy.metrics
+
+        # Calculate average latency
+        avg_latency_ms = round(m.latency_sum_ms / m.latency_count, 2) if m.latency_count > 0 else 0
+        min_latency_ms = (
+            round(m.latency_min_ms, 2)
+            if m.latency_count > 0 and m.latency_min_ms != float("inf")
+            else 0
+        )
+        max_latency_ms = round(m.latency_max_ms, 2) if m.latency_count > 0 else 0
+
+        # Calculate Headroom overhead (optimization time only, excludes pass-through requests)
+        avg_overhead_ms = (
+            round(m.overhead_sum_ms / m.overhead_count, 2) if m.overhead_count > 0 else 0
+        )
+        min_overhead_ms = (
+            round(m.overhead_min_ms, 2)
+            if m.overhead_count > 0 and m.overhead_min_ms != float("inf")
+            else 0
+        )
+        max_overhead_ms = round(m.overhead_max_ms, 2) if m.overhead_count > 0 else 0
+
+        # Calculate TTFB (time to first byte)
+        avg_ttfb_ms = round(m.ttfb_sum_ms / m.ttfb_count, 2) if m.ttfb_count > 0 else 0
+        min_ttfb_ms = (
+            round(m.ttfb_min_ms, 2) if m.ttfb_count > 0 and m.ttfb_min_ms != float("inf") else 0
+        )
+        max_ttfb_ms = round(m.ttfb_max_ms, 2) if m.ttfb_count > 0 else 0
+
+        # Get compression store stats
+        store = get_compression_store()
+        compression_stats = store.get_stats()
+
+        # Get telemetry/TOIN stats
+        telemetry = get_telemetry_collector()
+        telemetry_stats = telemetry.get_stats()
+
+        # Get feedback loop stats
+        feedback = get_compression_feedback()
+        feedback_stats = feedback.get_stats()
+
+        # Build prefix cache stats once (used in both prefix_cache and cost)
+        prefix_cache_stats = _build_prefix_cache_stats(m, proxy.cost_tracker)
+
+        # Fetch CLI filtering savings (rtk — tokens avoided before reaching context)
+        cli_filtering_stats = _get_rtk_stats()
+        cli_tokens_avoided = (
+            cli_filtering_stats.get("tokens_saved", 0) if cli_filtering_stats else 0
+        )
+
+        # Calculate total tokens before compression
+        total_tokens_before = m.tokens_input_total + m.tokens_saved_total
+
+        # Build human-readable summary
+        summary = _build_session_summary(
+            proxy, m, prefix_cache_stats, cli_tokens_avoided, total_tokens_before
+        )
+        # DEBUG: log the summary payload for external upsert consumers
+        try:
+            logger.debug("/stats summary data: %r", summary)
+        except Exception:
+            logger.warning("Failed to log /stats summary payload")
+
+        # Compression cache stats (token mode)
+        compression_cache_stats: dict = {}
+        if proxy.config.mode == PROXY_MODE_TOKEN and proxy._compression_caches:
+            total_entries = 0
+            total_hits = 0
+            total_misses = 0
+            total_tokens_saved = 0
+            for cache in proxy._compression_caches.values():
+                s = cache.get_stats()
+                total_entries += s.get("entries", 0)
+                total_hits += s.get("hits", 0)
+                total_misses += s.get("misses", 0)
+                total_tokens_saved += s.get("total_tokens_saved", 0)
+            compression_cache_stats = {
+                "mode": PROXY_MODE_TOKEN,
+                "active_sessions": len(proxy._compression_caches),
+                "total_entries": total_entries,
+                "total_hits": total_hits,
+                "total_misses": total_misses,
+                "hit_rate": round(total_hits / max(1, total_hits + total_misses) * 100, 1),
+                "total_tokens_saved": total_tokens_saved,
+            }
+        else:
+            compression_cache_stats = {"mode": proxy.config.mode}
+
+        # Build unified savings summary (all layers)
+        compression_tokens = m.tokens_saved_total
+        cache_net_usd = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)
+        total_tokens_all_layers = compression_tokens + cli_tokens_avoided
+        persistent_savings = m.savings_tracker.stats_preview()
+        display_session = persistent_savings.get("display_session", {})
+
+        return {
+            "summary": summary,
+            "savings": {
+                "total_tokens": total_tokens_all_layers,
+                "by_layer": {
+                    "cli_filtering": {
+                        "tokens": cli_tokens_avoided,
+                        "description": "Tokens avoided by CLI output filtering (rtk) before reaching context",
+                    },
+                    "compression": {
+                        "tokens": compression_tokens,
+                        "description": "Tokens removed by proxy compression (SmartCrusher, ContentRouter, etc.)",
+                    },
+                    "prefix_cache": {
+                        "discount_usd": round(cache_net_usd, 4),
+                        "description": (
+                            "Cost discount from provider prefix caching. "
+                            "Headroom's CacheAligner improves hit rates; "
+                            "baseline caching is provider-native."
+                        ),
+                    },
+                },
+            },
+            "requests": {
+                "total": m.requests_total,
+                "cached": m.requests_cached,
+                "rate_limited": m.requests_rate_limited,
+                "failed": m.requests_failed,
+                "by_provider": dict(m.requests_by_provider),
+                "by_model": dict(m.requests_by_model),
+                "by_stack": dict(m.requests_by_stack),
+            },
+            "tokens": {
+                "input": m.tokens_input_total,
+                "output": m.tokens_output_total,
+                "saved": m.tokens_saved_total,
+                "cli_tokens_avoided": cli_tokens_avoided,
+                "total_before_compression": total_tokens_before,
+                "savings_percent": round(
+                    (m.tokens_saved_total / total_tokens_before * 100)
+                    if total_tokens_before > 0
+                    else 0,
+                    2,
+                ),
+            },
+            "latency": {
+                "average_ms": avg_latency_ms,
+                "min_ms": min_latency_ms,
+                "max_ms": max_latency_ms,
+                "total_requests": m.latency_count,
+            },
+            "overhead": {
+                "average_ms": avg_overhead_ms,
+                "min_ms": min_overhead_ms,
+                "max_ms": max_overhead_ms,
+            },
+            "ttfb": {
+                "average_ms": avg_ttfb_ms,
+                "min_ms": min_ttfb_ms,
+                "max_ms": max_ttfb_ms,
+            },
+            "pipeline_timing": {
+                name: {
+                    "average_ms": round(
+                        m.transform_timing_sum[name] / m.transform_timing_count[name], 2
+                    ),
+                    "max_ms": round(m.transform_timing_max[name], 2),
+                    "count": m.transform_timing_count[name],
+                }
+                for name in sorted(m.transform_timing_sum.keys())
+            }
+            if m.transform_timing_sum
+            else {},
+            "waste_signals": dict(m.waste_signals_total) if m.waste_signals_total else {},
+            "savings_history": m.savings_history[-100:],  # Last 100 data points
+            "display_session": display_session,
+            "persistent_savings": persistent_savings,
+            "prefix_cache": prefix_cache_stats,
+            "cost": _merge_cost_stats(
+                proxy.cost_tracker.stats() if proxy.cost_tracker else None,
+                prefix_cache_stats,
+                cli_tokens_avoided=cli_tokens_avoided,
+            ),
+            "compression": {
+                "ccr_entries": compression_stats.get("entry_count", 0),
+                "ccr_max_entries": compression_stats.get("max_entries", 0),
+                "original_tokens_cached": compression_stats.get("total_original_tokens", 0),
+                "compressed_tokens_cached": compression_stats.get("total_compressed_tokens", 0),
+                "ccr_retrievals": compression_stats.get("total_retrievals", 0),
+            },
+            "compression_cache": compression_cache_stats,
+            "anon_telemetry_shipping": is_telemetry_enabled(),
+            "telemetry": {
+                "enabled": telemetry_stats.get("enabled", False),
+                "total_compressions": telemetry_stats.get("total_compressions", 0),
+                "total_retrievals": telemetry_stats.get("total_retrievals", 0),
+                "global_retrieval_rate": round(telemetry_stats.get("global_retrieval_rate", 0), 4),
+                "tool_signatures_tracked": telemetry_stats.get("tool_signatures_tracked", 0),
+                "avg_compression_ratio": round(telemetry_stats.get("avg_compression_ratio", 0), 4),
+                "avg_token_reduction": round(telemetry_stats.get("avg_token_reduction", 0), 4),
+            },
+            "otel": get_otel_metrics_status(),
+            "langfuse": get_langfuse_tracing_status(),
+            "feedback_loop": {
+                "tools_tracked": feedback_stats.get("tools_tracked", 0),
+                "total_compressions": feedback_stats.get("total_compressions", 0),
+                "total_retrievals": feedback_stats.get("total_retrievals", 0),
+                "global_retrieval_rate": round(feedback_stats.get("global_retrieval_rate", 0), 4),
+                "tools_with_high_retrieval": sum(
+                    1
+                    for p in feedback_stats.get("tool_patterns", {}).values()
+                    if p.get("retrieval_rate", 0) > 0.3
+                ),
+            },
+            "toin": get_toin().get_stats(),
+            "cli_filtering": cli_filtering_stats,
+            "cache": await proxy.cache.stats() if proxy.cache else None,
+            "rate_limiter": await proxy.rate_limiter.stats() if proxy.rate_limiter else None,
+            "recent_requests": proxy.logger.get_recent(10) if proxy.logger else [],
+            "log_full_messages": proxy.config.log_full_messages if proxy else False,
+            **get_quota_registry().get_all_stats(),
+        }
+
+    async def _get_cached_stats_payload() -> dict[str, Any]:
+        """Return a short-TTL cached `/stats` snapshot for dashboard polling."""
+        now = time.monotonic()
+        cached_payload = cast(dict[str, Any] | None, _stats_snapshot.get("value"))
+        if cached_payload is not None and now < float(_stats_snapshot["expires_at"]):
+            return cached_payload
+
+        async with _stats_snapshot_lock:
+            now = time.monotonic()
+            cached_payload = cast(dict[str, Any] | None, _stats_snapshot.get("value"))
+            if cached_payload is not None and now < float(_stats_snapshot["expires_at"]):
+                return cached_payload
+
+            payload = await _build_stats_payload()
+            _stats_snapshot["value"] = payload
+            _stats_snapshot["expires_at"] = time.monotonic() + DASHBOARD_STATS_CACHE_TTL_SECONDS
+            return payload
+
+    @app.get("/stats")
+    async def stats(cached: bool = False):
+        """Get comprehensive proxy statistics.
+
+        This is the main stats endpoint - it aggregates data from all subsystems:
+        - Request metrics (total, cached, failed, by model/provider)
+        - Token usage and savings
+        - Cost tracking
+        - Canonical persisted display_session metrics for downstream dashboards
+        - Compression (CCR) statistics
+        - Telemetry/TOIN (data flywheel) statistics
+        - Cache and rate limiter stats
+
+        Use ``?cached=1`` for the dashboard fast path. That returns a short-TTL
+        snapshot to avoid rebuilding the full payload on every UI poll.
+        """
+        if cached:
+            return await _get_cached_stats_payload()
+        return await _build_stats_payload()
+
+    @app.get("/stats-history")
+    async def stats_history(
+        format: Literal["json", "csv"] = "json",
+        series: Literal["history", "hourly", "daily", "weekly", "monthly"] = "history",
+        history_mode: Literal["compact", "full", "none"] = "compact",
+    ):
+        """Get durable proxy compression history plus display-session state."""
+        if format == "csv":
+            filename = f"headroom-stats-history-{series}.csv"
+            return Response(
+                content=proxy.metrics.savings_tracker.export_csv(series=series),
+                media_type="text/csv; charset=utf-8",
+                headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+            )
+
+        return proxy.metrics.savings_tracker.history_response(history_mode=history_mode)
+
+    @app.get("/transformations/feed")
+    async def transformations_feed(limit: int = 20):
+        """Get recent message transformations for the live feed.
+
+        Returns empty list if log_full_messages is disabled (messages are not stored).
+        """
+        if limit > 100:
+            limit = 100
+
+        transformations = []
+        log_full_messages = proxy.config.log_full_messages if proxy else False
+
+        if proxy and proxy.logger:
+            logs = proxy.logger.get_recent_with_messages(limit)
+            for log in logs:
+                transformations.append(
+                    {
+                        "request_id": log.get("request_id"),
+                        "timestamp": log.get("timestamp"),
+                        "provider": log.get("provider"),
+                        "model": log.get("model"),
+                        "input_tokens_original": log.get("input_tokens_original"),
+                        "input_tokens_optimized": log.get("input_tokens_optimized"),
+                        "tokens_saved": log.get("tokens_saved"),
+                        "savings_percent": log.get("savings_percent"),
+                        "transforms_applied": log.get("transforms_applied", []),
+                        "request_messages": log.get("request_messages"),
+                        "response_content": log.get("response_content"),
+                        "turn_id": log.get("turn_id"),
+                    }
+                )
+
+        return {"transformations": transformations, "log_full_messages": log_full_messages}
+
+    @app.get("/subscription-window")
+    async def subscription_window():
+        """Current Anthropic subscription window utilisation and Headroom contribution."""
+        tracker = get_subscription_tracker()
+        if tracker is None:
+            return JSONResponse(
+                status_code=503,
+                content={"error": "Subscription tracking is not enabled"},
+            )
+        return JSONResponse(content=tracker.state)
+
+    @app.get("/quota")
+    async def quota():
+        """Unified quota/rate-limit stats for all registered providers (Anthropic, Codex, Copilot)."""
+        return JSONResponse(content=get_quota_registry().get_all_stats())
+
+    @app.get("/metrics")
+    async def metrics():
+        """Prometheus metrics endpoint."""
+        return PlainTextResponse(
+            await proxy.metrics.export(),
+            media_type="text/plain; version=0.0.4",
+        )
+
+    # Debug endpoints
+    @app.get("/debug/memory")
+    async def debug_memory():
+        """Get detailed memory usage statistics.
+
+        Returns memory usage for all tracked components including:
+        - Process-level memory (RSS, VMS, percent)
+        - Per-component memory usage and budgets
+        - Cache hit/miss statistics
+        - Total tracked vs target budget
+
+        This endpoint is useful for debugging memory issues and
+        monitoring memory budgets.
+        """
+        from ..memory.tracker import MemoryTracker
+
+        tracker = MemoryTracker.get()
+
+        # Register components if not already registered
+        _register_memory_components(proxy, tracker)
+
+        report = tracker.get_report()
+        return report.to_dict()
+
+    @app.post("/cache/clear")
+    async def clear_cache():
+        """Clear the response cache."""
+        if proxy.cache:
+            await proxy.cache.clear()
+            return {"status": "cleared"}
+        return {"status": "cache disabled"}
+
+    # CCR (Compress-Cache-Retrieve) endpoints
+    @app.post("/v1/retrieve")
+    async def ccr_retrieve(request: Request):
+        """Retrieve original content from CCR compression cache.
+
+        This is the "Retrieve" part of CCR (Compress-Cache-Retrieve).
+        When SmartCrusher compresses tool outputs, the original data is cached.
+        LLMs can call this endpoint to get more data if needed.
+
+        Request body:
+            hash (str): Hash key from compression marker (required)
+            query (str): Optional search query to filter results
+
+        Response:
+            Full retrieval: {"hash": "...", "original_content": "...", ...}
+            Search: {"hash": "...", "query": "...", "results": [...], "count": N}
+        """
+        data = await request.json()
+        hash_key = data.get("hash")
+        query = data.get("query")
+
+        if not hash_key:
+            raise HTTPException(status_code=400, detail="hash required")
+
+        store = get_compression_store()
+
+        if query:
+            # Search within cached content
+            results = store.search(hash_key, query)
+            return {
+                "hash": hash_key,
+                "query": query,
+                "results": results,
+                "count": len(results),
+            }
+        else:
+            # Return full original content
+            entry = store.retrieve(hash_key)
+            if entry:
+                return {
+                    "hash": hash_key,
+                    "original_content": entry.original_content,
+                    "original_tokens": entry.original_tokens,
+                    "original_item_count": entry.original_item_count,
+                    "compressed_item_count": entry.compressed_item_count,
+                    "tool_name": entry.tool_name,
+                    "retrieval_count": entry.retrieval_count,
+                }
+            raise HTTPException(
+                status_code=404, detail="Entry not found or expired (TTL: 5 minutes)"
+            )
+
+    @app.get("/v1/retrieve/stats")
+    async def ccr_stats():
+        """Get CCR compression store statistics."""
+        store = get_compression_store()
+        stats = store.get_stats()
+        events = store.get_retrieval_events(limit=20)
+        return {
+            "store": stats,
+            "recent_retrievals": [
+                {
+                    "hash": e.hash,
+                    "query": e.query,
+                    "items_retrieved": e.items_retrieved,
+                    "total_items": e.total_items,
+                    "tool_name": e.tool_name,
+                    "retrieval_type": e.retrieval_type,
+                }
+                for e in events
+            ],
+        }
+
+    @app.get("/v1/feedback")
+    async def ccr_feedback():
+        """Get CCR feedback loop statistics and learned patterns.
+
+        This endpoint exposes the feedback loop's learned patterns for monitoring
+        and debugging. It shows:
+        - Per-tool retrieval rates (high = compress less aggressively)
+        - Common search queries per tool
+        - Queried fields (suggest what to preserve)
+
+        Use this to understand how well compression is working and whether
+        the feedback loop is adjusting appropriately.
+        """
+        feedback = get_compression_feedback()
+        stats = feedback.get_stats()
+        return {
+            "feedback": stats,
+            "hints_example": {
+                tool_name: {
+                    "hints": {
+                        "max_items": hints.max_items
+                        if (hints := feedback.get_compression_hints(tool_name))
+                        else 15,
+                        "suggested_items": hints.suggested_items if hints else None,
+                        "skip_compression": hints.skip_compression if hints else False,
+                        "preserve_fields": hints.preserve_fields if hints else [],
+                        "reason": hints.reason if hints else "",
+                    }
+                }
+                for tool_name in list(stats.get("tool_patterns", {}).keys())[:5]
+            },
+        }
+
+    @app.get("/v1/feedback/{tool_name}")
+    async def ccr_feedback_for_tool(tool_name: str):
+        """Get compression hints for a specific tool.
+
+        Returns feedback-based hints that would be used for compressing
+        this tool's output.
+        """
+        feedback = get_compression_feedback()
+        hints = feedback.get_compression_hints(tool_name)
+        patterns = feedback.get_all_patterns().get(tool_name)
+
+        return {
+            "tool_name": tool_name,
+            "hints": {
+                "max_items": hints.max_items,
+                "min_items": hints.min_items,
+                "suggested_items": hints.suggested_items,
+                "aggressiveness": hints.aggressiveness,
+                "skip_compression": hints.skip_compression,
+                "preserve_fields": hints.preserve_fields,
+                "reason": hints.reason,
+            },
+            "pattern": {
+                "total_compressions": patterns.total_compressions if patterns else 0,
+                "total_retrievals": patterns.total_retrievals if patterns else 0,
+                "retrieval_rate": patterns.retrieval_rate if patterns else 0.0,
+                "full_retrieval_rate": patterns.full_retrieval_rate if patterns else 0.0,
+                "search_rate": patterns.search_rate if patterns else 0.0,
+                "common_queries": list(patterns.common_queries.keys())[:10] if patterns else [],
+                "queried_fields": list(patterns.queried_fields.keys())[:10] if patterns else [],
+            }
+            if patterns
+            else None,
+        }
+
+    # Telemetry endpoints (Data Flywheel)
+    @app.get("/v1/telemetry")
+    async def telemetry_stats():
+        """Get telemetry statistics for the data flywheel.
+
+        This endpoint exposes privacy-preserving telemetry data that powers
+        the data flywheel - learning optimal compression strategies across
+        tool types based on usage patterns.
+
+        What's collected (anonymized):
+        - Tool output structure patterns (field types, not values)
+        - Compression decisions and ratios
+        - Retrieval patterns (rate, type, not content)
+        - Strategy effectiveness
+
+        What's NOT collected:
+        - Actual data values
+        - User identifiers
+        - Queries or search terms
+        - File paths or tool names (hashed by default)
+        """
+        telemetry = get_telemetry_collector()
+        return telemetry.get_stats()
+
+    @app.get("/v1/telemetry/export")
+    async def telemetry_export():
+        """Export full telemetry data for aggregation.
+
+        This endpoint exports all telemetry data in a format suitable for
+        cross-user aggregation. The data is privacy-preserving - no actual
+        values are included, only structural patterns and statistics.
+
+        Use this for:
+        - Building a central learning service
+        - Sharing learned patterns across instances
+        - Analysis and debugging
+        """
+        telemetry = get_telemetry_collector()
+        return telemetry.export_stats()
+
+    @app.post("/v1/telemetry/import")
+    async def telemetry_import(request: Request):
+        """Import telemetry data from another source.
+
+        This allows merging telemetry from multiple sources for cross-user
+        learning. The imported data is merged with existing statistics.
+
+        Request body: Telemetry export data from /v1/telemetry/export
+        """
+        telemetry = get_telemetry_collector()
+        data = await request.json()
+        telemetry.import_stats(data)
+        return {"status": "imported", "current_stats": telemetry.get_stats()}
+
+    @app.get("/v1/telemetry/tools")
+    async def telemetry_tools():
+        """Get telemetry statistics for all tracked tool signatures.
+
+        Returns statistics per tool signature (anonymized), including:
+        - Compression ratios and strategy usage
+        - Retrieval rates (high = compression too aggressive)
+        - Learned recommendations
+        """
+        telemetry = get_telemetry_collector()
+        all_stats = telemetry.get_all_tool_stats()
+        return {
+            "tool_count": len(all_stats),
+            "tools": {sig_hash: stats.to_dict() for sig_hash, stats in all_stats.items()},
+        }
+
+    @app.get("/v1/telemetry/tools/{signature_hash}")
+    async def telemetry_tool_detail(signature_hash: str):
+        """Get detailed telemetry for a specific tool signature.
+
+        Includes learned recommendations if enough data has been collected.
+        """
+        telemetry = get_telemetry_collector()
+        stats = telemetry.get_tool_stats(signature_hash)
+        recommendations = telemetry.get_recommendations(signature_hash)
+
+        if stats is None:
+            raise HTTPException(
+                status_code=404, detail=f"No telemetry found for signature: {signature_hash}"
+            )
+
+        return {
+            "signature_hash": signature_hash,
+            "stats": stats.to_dict(),
+            "recommendations": recommendations,
+        }
+
+    # TOIN (Tool Output Intelligence Network) endpoints
+    @app.get("/v1/toin/stats")
+    async def toin_stats():
+        """Get overall TOIN statistics.
+
+        Returns aggregated statistics from the Tool Output Intelligence Network,
+        which learns optimal compression strategies across all tool types.
+
+        Response includes:
+        - enabled: Whether TOIN is enabled
+        - patterns_tracked: Number of unique tool patterns being tracked
+        - total_compressions: Total compression events recorded
+        - total_retrievals: Total retrieval events recorded
+        - global_retrieval_rate: Overall retrieval rate (high = compression too aggressive)
+        - patterns_with_recommendations: Patterns with enough data for recommendations
+        """
+        toin = get_toin()
+        return toin.get_stats()
+
+    @app.get("/v1/toin/patterns")
+    async def toin_patterns(limit: int = 20):
+        """List TOIN patterns with most samples.
+
+        Returns patterns sorted by sample_size descending. Use this to see
+        which tool types have the most data and their learned behaviors.
+
+        Query params:
+            limit: Maximum number of patterns to return (default 20)
+
+        Response includes for each pattern:
+        - hash: Truncated tool signature hash (12 chars)
+        - compressions: Total compression events
+        - retrievals: Total retrieval events
+        - retrieval_rate: Percentage of compressions that triggered retrieval
+        - confidence: Confidence level in recommendations (0.0-1.0)
+        - skip_recommended: Whether TOIN recommends skipping compression
+        - optimal_max_items: Learned optimal max_items setting
+        """
+        toin = get_toin()
+        exported = toin.export_patterns()
+        patterns_data = exported.get("patterns", {})
+
+        # Convert to list and sort by sample_size
+        patterns_list = []
+        for sig_hash, pattern_dict in patterns_data.items():
+            sample_size = pattern_dict.get("sample_size", 0)
+            total_compressions = pattern_dict.get("total_compressions", 0)
+            total_retrievals = pattern_dict.get("total_retrievals", 0)
+            retrieval_rate = (
+                total_retrievals / total_compressions if total_compressions > 0 else 0.0
+            )
+
+            patterns_list.append(
+                {
+                    "hash": sig_hash[:12],
+                    "compressions": total_compressions,
+                    "retrievals": total_retrievals,
+                    "retrieval_rate": f"{retrieval_rate:.1%}",
+                    "confidence": round(pattern_dict.get("confidence", 0.0), 3),
+                    "skip_recommended": pattern_dict.get("skip_compression_recommended", False),
+                    "optimal_max_items": pattern_dict.get("optimal_max_items", 20),
+                    "sample_size": sample_size,
+                }
+            )
+
+        # Sort by sample_size descending
+        patterns_list.sort(key=lambda p: p["sample_size"], reverse=True)
+
+        # Remove sample_size from output (used only for sorting)
+        for p in patterns_list:
+            del p["sample_size"]
+
+        return patterns_list[:limit]
+
+    @app.get("/v1/toin/pattern/{hash_prefix}")
+    async def toin_pattern_detail(hash_prefix: str):
+        """Get detailed TOIN pattern info by hash prefix.
+
+        Searches for a pattern where the tool signature hash starts with
+        the provided prefix. Returns full pattern details if found.
+
+        Path params:
+            hash_prefix: Beginning of the tool signature hash (min 4 chars recommended)
+
+        Response: Full pattern.to_dict() with all learned statistics and recommendations.
+        """
+        toin = get_toin()
+        exported = toin.export_patterns()
+        patterns_data = exported.get("patterns", {})
+
+        # Search for pattern with matching hash prefix
+        for sig_hash, pattern_dict in patterns_data.items():
+            if sig_hash.startswith(hash_prefix):
+                return pattern_dict
+
+        raise HTTPException(
+            status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}"
+        )
+
+    @app.get("/v1/retrieve/{hash_key}")
+    async def ccr_retrieve_get(hash_key: str, query: str | None = None):
+        """GET version of CCR retrieve for easier testing."""
+        store = get_compression_store()
+
+        if query:
+            results = store.search(hash_key, query)
+            return {
+                "hash": hash_key,
+                "query": query,
+                "results": results,
+                "count": len(results),
+            }
+        else:
+            entry = store.retrieve(hash_key)
+            if entry:
+                return {
+                    "hash": hash_key,
+                    "original_content": entry.original_content,
+                    "original_tokens": entry.original_tokens,
+                    "original_item_count": entry.original_item_count,
+                    "compressed_item_count": entry.compressed_item_count,
+                    "tool_name": entry.tool_name,
+                    "retrieval_count": entry.retrieval_count,
+                }
+            raise HTTPException(status_code=404, detail="Entry not found or expired")
+
+    # CCR Tool Call Handler - for agent frameworks to call when LLM uses headroom_retrieve
+    @app.post("/v1/retrieve/tool_call")
+    async def ccr_handle_tool_call(request: Request):
+        """Handle a CCR tool call from an LLM response.
+
+        This endpoint accepts tool call formats from various providers and returns
+        a properly formatted tool result. Agent frameworks can use this to handle
+        CCR tool calls without implementing the retrieval logic themselves.
+
+        Request body (Anthropic format):
+            {
+                "tool_call": {
+                    "id": "toolu_123",
+                    "name": "headroom_retrieve",
+                    "input": {"hash": "abc123", "query": "optional search"}
+                },
+                "provider": "anthropic"
+            }
+
+        Request body (OpenAI format):
+            {
+                "tool_call": {
+                    "id": "call_123",
+                    "function": {
+                        "name": "headroom_retrieve",
+                        "arguments": "{\"hash\": \"abc123\"}"
+                    }
+                },
+                "provider": "openai"
+            }
+
+        Response:
+            {
+                "tool_result": {...},  # Formatted for the provider
+                "success": true,
+                "data": {...}  # Raw retrieval data
+            }
+        """
+        data = await request.json()
+        tool_call = data.get("tool_call", {})
+        provider = data.get("provider", "anthropic")
+
+        # Parse the tool call
+        hash_key, query = parse_tool_call(tool_call, provider)
+
+        if hash_key is None:
+            raise HTTPException(
+                status_code=400, detail=f"Invalid tool call or not a {CCR_TOOL_NAME} call"
+            )
+
+        # Perform retrieval
+        store = get_compression_store()
+
+        if query:
+            results = store.search(hash_key, query)
+            retrieval_data = {
+                "hash": hash_key,
+                "query": query,
+                "results": results,
+                "count": len(results),
+            }
+        else:
+            entry = store.retrieve(hash_key)
+            if entry:
+                retrieval_data = {
+                    "hash": hash_key,
+                    "original_content": entry.original_content,
+                    "original_item_count": entry.original_item_count,
+                    "compressed_item_count": entry.compressed_item_count,
+                }
+            else:
+                retrieval_data = {
+                    "error": "Entry not found or expired (TTL: 5 minutes)",
+                    "hash": hash_key,
+                }
+
+        # Format tool result for provider
+        tool_call_id = tool_call.get("id", "")
+        result_content = json.dumps(retrieval_data, indent=2)
+
+        if provider == "anthropic":
+            tool_result = {
+                "type": "tool_result",
+                "tool_use_id": tool_call_id,
+                "content": result_content,
+            }
+        elif provider == "openai":
+            tool_result = {
+                "role": "tool",
+                "tool_call_id": tool_call_id,
+                "content": result_content,
+            }
+        else:
+            tool_result = {
+                "tool_call_id": tool_call_id,
+                "content": result_content,
+            }
+
+        return {
+            "tool_result": tool_result,
+            "success": "error" not in retrieval_data,
+            "data": retrieval_data,
+        }
+
+    # Compression-only endpoint (for TypeScript SDK and other HTTP clients)
+    @app.post("/v1/compress")
+    async def compress_messages(request: Request):
+        return await proxy.handle_compress(request)
+
+    register_provider_routes(app, proxy)
+
+    return app
+
+
+def _get_code_aware_banner_status(config: ProxyConfig) -> str:
+    """Get code-aware compression status line for banner."""
+    if config.code_aware_enabled:
+        if is_tree_sitter_available():
+            return "ENABLED  (AST-based)"
+        else:
+            return "NOT INSTALLED (pip install headroom-ai[code])"
+    else:
+        if is_tree_sitter_available():
+            return "DISABLED (remove --no-code-aware to enable)"
+        return "DISABLED"
+
+
+def run_server(
+    config: ProxyConfig | None = None,
+    workers: int = 1,
+    limit_concurrency: int = 1000,
+):
+    """Run the proxy server.
+
+    Args:
+        config: Proxy configuration
+        workers: Number of worker processes (use N for multi-core scaling)
+        limit_concurrency: Max concurrent connections before 503 response
+    """
+    if not FASTAPI_AVAILABLE:
+        print("ERROR: FastAPI required. Install: pip install fastapi uvicorn httpx")
+        sys.exit(1)
+
+    config = config or ProxyConfig()
+    app = create_app(config)
+
+    code_aware_status = _get_code_aware_banner_status(config)
+
+    # Format connection pool info
+    pool_info = f"max={config.max_connections}, keepalive={config.max_keepalive_connections}"
+    http2_status = "ENABLED" if config.http2 else "DISABLED"
+
+    backend_status = format_backend_status(
+        backend=config.backend,
+        anyllm_provider=config.anyllm_provider,
+        bedrock_region=config.bedrock_region,
+    )
+
+    print(f"""
+╔══════════════════════════════════════════════════════════════════════╗
+║                      HEADROOM PROXY SERVER                           ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  Version: 1.0.0                                                      ║
+║  Listening: http://{config.host}:{config.port:<5}                                      ║
+║  Workers: {workers:<3}  Concurrency Limit: {limit_concurrency:<5}                          ║
+║  Backend: {backend_status:<59}║
+╠══════════════════════════════════════════════════════════════════════╣
+║  FEATURES:                                                           ║
+║    Optimization:    {"ENABLED " if config.optimize else "DISABLED"}                                       ║
+║    Caching:         {"ENABLED " if config.cache_enabled else "DISABLED"}   (TTL: {config.cache_ttl_seconds}s)                          ║
+║    Rate Limiting:   {"ENABLED " if config.rate_limit_enabled else "DISABLED"}   ({config.rate_limit_requests_per_minute} req/min, {config.rate_limit_tokens_per_minute:,} tok/min)       ║
+║    Retry:           {"ENABLED " if config.retry_enabled else "DISABLED"}   (max {config.retry_max_attempts} attempts)                       ║
+║    Cost Tracking:   {"ENABLED " if config.cost_tracking_enabled else "DISABLED"}   (budget: {"$" + str(config.budget_limit_usd) + "/" + config.budget_period if config.budget_limit_usd else "unlimited"})          ║
+║    Code-Aware:      {code_aware_status:<52}║
+║    HTTP/2:          {http2_status:<52}║
+║    Conn Pool:       {pool_info:<52}║
+╠══════════════════════════════════════════════════════════════════════╣
+║  USAGE:                                                              ║
+║    Claude Code:   ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude     ║
+║    Cursor:        Set base URL in settings                           ║
+╠══════════════════════════════════════════════════════════════════════╣
+║  ENDPOINTS:                                                          ║
+║    /livez                   Process liveness                         ║
+║    /readyz                  Traffic readiness                        ║
+║    /health                  Aggregate health                         ║
+║    /stats                   Detailed statistics                      ║
+║    /metrics                 Prometheus metrics                       ║
+║    /cache/clear             Clear response cache                     ║
+║    /v1/retrieve             CCR: Retrieve compressed content         ║
+║    /v1/retrieve/stats       CCR: Compression store stats             ║
+║    /v1/retrieve/tool_call   CCR: Handle LLM tool calls               ║
+║    /v1/feedback             CCR: Feedback loop stats & patterns      ║
+║    /v1/feedback/{{tool}}    CCR: Compression hints for a tool        ║
+║    /v1/telemetry            Data flywheel: Telemetry stats           ║
+║    /v1/telemetry/export     Data flywheel: Export for aggregation    ║
+║    /v1/telemetry/tools      Data flywheel: Per-tool stats            ║
+║    /v1/toin/stats           TOIN: Overall intelligence stats         ║
+║    /v1/toin/patterns        TOIN: List learned patterns              ║
+║    /v1/toin/pattern/{{hash}} TOIN: Pattern details by hash            ║
+╚══════════════════════════════════════════════════════════════════════╝
+""")
+
+    uvicorn.run(
+        app,
+        host=config.host,
+        port=config.port,
+        log_level="warning",
+        workers=workers if workers > 1 else None,  # None = single process (default)
+        limit_concurrency=limit_concurrency,
+        # Defense-in-depth: the loopback guard for /debug/* endpoints trusts
+        # request.client.host. uvicorn's ProxyHeadersMiddleware rewrites that
+        # from X-Forwarded-For when FORWARDED_ALLOW_IPS is broader than the
+        # default. Disabling proxy_headers here guarantees the guard sees the
+        # real peer address regardless of env.
+        proxy_headers=False,
+    )
+
+
+def _get_env_bool(name: str, default: bool) -> bool:
+    """Get boolean from environment variable."""
+    val = os.environ.get(name)
+    if val is None:
+        return default
+    return val.lower() in ("true", "1", "yes", "on")
+
+
+def _get_env_int(name: str, default: int) -> int:
+    """Get integer from environment variable."""
+    val = os.environ.get(name)
+    if val is None:
+        return default
+    try:
+        return int(val)
+    except ValueError:
+        return default
+
+
+def _get_env_float(name: str, default: float) -> float:
+    """Get float from environment variable."""
+    val = os.environ.get(name)
+    if val is None:
+        return default
+    try:
+        return float(val)
+    except ValueError:
+        return default
+
+
+def _get_env_str(name: str, default: str) -> str:
+    """Get string from environment variable."""
+    return os.environ.get(name, default)
+
+
+def _parse_tool_profiles(cli_profiles: list[str]) -> dict[str, Any]:
+    """Parse tool profiles from CLI args and HEADROOM_TOOL_PROFILES env var.
+
+    Format: ToolName:level (e.g., Grep:conservative, Bash:moderate)
+    Env var format: comma-separated (e.g., "Grep:conservative,Bash:moderate")
+
+    Returns:
+        Dict mapping tool names to CompressionProfile instances.
+    """
+    from headroom.config import PROFILE_PRESETS, CompressionProfile
+
+    profiles: dict[str, CompressionProfile] = {}
+    raw_entries: list[str] = list(cli_profiles)
+
+    # Also check env var
+    env_val = os.environ.get("HEADROOM_TOOL_PROFILES", "")
+    if env_val:
+        raw_entries.extend(e.strip() for e in env_val.split(",") if e.strip())
+
+    for entry in raw_entries:
+        if ":" not in entry:
+            logger.warning("Invalid tool profile format (expected ToolName:level): %s", entry)
+            continue
+        tool_name, level = entry.split(":", 1)
+        tool_name = tool_name.strip()
+        level = level.strip().lower()
+
+        if level in PROFILE_PRESETS:
+            profiles[tool_name] = PROFILE_PRESETS[level]
+        else:
+            logger.warning(
+                "Unknown profile level '%s' for tool '%s'. Use: conservative, moderate, aggressive",
+                level,
+                tool_name,
+            )
+
+    return profiles
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Headroom Proxy Server")
+
+    # Server
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8787)
+    parser.add_argument(
+        "--openai-api-url", help=f"Custom OpenAI API URL (default: {DEFAULT_OPENAI_API_URL})"
+    )
+    parser.add_argument(
+        "--anthropic-api-url",
+        help=f"Custom Anthropic API URL (default: {DEFAULT_ANTHROPIC_API_URL})",
+    )
+
+    # Backend (anthropic direct, bedrock, openrouter, anyllm, or litellm-<provider>)
+    parser.add_argument(
+        "--backend",
+        default="anthropic",
+        help=(
+            "Backend: 'anthropic' (direct), 'bedrock' (AWS), 'openrouter', "
+            "'anyllm' (any-llm), or 'litellm-<provider>' (e.g., litellm-hosted_vllm, litellm-vertex)"
+        ),
+    )
+    parser.add_argument(
+        "--bedrock-region",
+        default="us-west-2",
+        help="AWS region for Bedrock backend (default: us-west-2)",
+    )
+    parser.add_argument(
+        "--bedrock-profile",
+        help="AWS profile for Bedrock backend (default: use default credentials)",
+    )
+    parser.add_argument(
+        "--openrouter-api-key",
+        help="OpenRouter API key (or set OPENROUTER_API_KEY env var)",
+    )
+    parser.add_argument(
+        "--anyllm-provider",
+        default="openai",
+        help="any-llm provider: openai, anthropic, mistral, groq, ollama, bedrock, etc. (default: openai)",
+    )
+
+    # Connection pool (scalability)
+    parser.add_argument(
+        "--max-connections",
+        type=int,
+        default=500,
+        help="Max connections to upstream APIs (default: 500)",
+    )
+    parser.add_argument(
+        "--max-keepalive", type=int, default=100, help="Max keepalive connections (default: 100)"
+    )
+    parser.add_argument(
+        "--no-http2",
+        action="store_true",
+        help="Disable HTTP/2 (enabled by default for better throughput)",
+    )
+    parser.add_argument(
+        "--workers",
+        type=int,
+        default=1,
+        help="Number of worker processes (default: 1, use N for multi-core)",
+    )
+    parser.add_argument(
+        "--limit-concurrency",
+        type=int,
+        default=1000,
+        help="Max concurrent connections before 503 (default: 1000)",
+    )
+
+    # Optimization
+    parser.add_argument("--no-optimize", action="store_true", help="Disable optimization")
+    parser.add_argument("--min-tokens", type=int, default=500, help="Min tokens to crush")
+    parser.add_argument("--max-items", type=int, default=50, help="Max items after crush")
+    parser.add_argument(
+        "--tool-profile",
+        action="append",
+        default=[],
+        help="Per-tool compression profile: ToolName:level (e.g., Grep:conservative, Bash:moderate, WebFetch:aggressive). "
+        "Can be specified multiple times. Also settable via HEADROOM_TOOL_PROFILES env var.",
+    )
+
+    # Caching
+    parser.add_argument("--no-cache", action="store_true", help="Disable caching")
+    parser.add_argument("--cache-ttl", type=int, default=3600, help="Cache TTL seconds")
+
+    # Rate limiting
+    parser.add_argument("--no-rate-limit", action="store_true", help="Disable rate limiting")
+    parser.add_argument("--rpm", type=int, default=60, help="Requests per minute")
+    parser.add_argument("--tpm", type=int, default=100000, help="Tokens per minute")
+
+    # Cost
+    parser.add_argument("--budget", type=float, help="Budget limit in USD")
+    parser.add_argument("--budget-period", choices=["hourly", "daily", "monthly"], default="daily")
+
+    # Logging
+    parser.add_argument("--log-file", help="Log file path")
+    parser.add_argument("--log-messages", action="store_true", help="Log full messages")
+
+    # Smart routing (content-aware compression)
+    parser.add_argument(
+        "--no-smart-routing",
+        action="store_true",
+        help="Disable smart routing (use legacy sequential pipeline)",
+    )
+
+    # Code-aware compression
+    parser.add_argument(
+        "--code-aware",
+        action="store_true",
+        help="Enable AST-based code compression (requires: pip install headroom-ai[code])",
+    )
+    parser.add_argument(
+        "--no-code-aware",
+        action="store_true",
+        help="Disable code-aware compression",
+    )
+
+    args = parser.parse_args()
+
+    # Environment variable defaults (HEADROOM_* prefix)
+    # CLI args override env vars, env vars override ProxyConfig defaults
+    env_smart_routing = _get_env_bool("HEADROOM_SMART_ROUTING", True)
+    env_code_aware = _get_env_bool("HEADROOM_CODE_AWARE_ENABLED", True)
+    env_optimize = _get_env_bool("HEADROOM_OPTIMIZE", True)
+    env_cache = _get_env_bool("HEADROOM_CACHE_ENABLED", True)
+    env_rate_limit = _get_env_bool("HEADROOM_RATE_LIMIT_ENABLED", True)
+
+    # Determine settings: CLI flags override env vars
+    # --no-X explicitly disables, --X explicitly enables, neither uses env var
+    smart_routing = env_smart_routing if not args.no_smart_routing else False
+    code_aware_enabled = (
+        env_code_aware
+        if not (args.code_aware or args.no_code_aware)
+        else (args.code_aware or not args.no_code_aware)
+    )
+    optimize = env_optimize if not args.no_optimize else False
+    cache_enabled = env_cache if not args.no_cache else False
+    rate_limit_enabled = env_rate_limit if not args.no_rate_limit else False
+
+    # Set OpenRouter API key from CLI if provided
+    if hasattr(args, "openrouter_api_key") and args.openrouter_api_key:
+        os.environ["OPENROUTER_API_KEY"] = args.openrouter_api_key
+
+    # Parse per-tool compression profiles from CLI and env var
+    tool_profiles = _parse_tool_profiles(args.tool_profile)
+
+    config = ProxyConfig(
+        host=_get_env_str("HEADROOM_HOST", args.host),
+        port=_get_env_int("HEADROOM_PORT", args.port),
+        openai_api_url=_get_env_str("OPENAI_TARGET_API_URL", args.openai_api_url),
+        anthropic_api_url=_get_env_str("ANTHROPIC_TARGET_API_URL", args.anthropic_api_url),
+        # Backend settings
+        backend=_get_env_str("HEADROOM_BACKEND", args.backend),  # type: ignore[arg-type]
+        bedrock_region=_get_env_str("HEADROOM_BEDROCK_REGION", args.bedrock_region),
+        bedrock_profile=args.bedrock_profile or os.environ.get("AWS_PROFILE"),
+        anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", args.anyllm_provider),
+        optimize=optimize,
+        min_tokens_to_crush=_get_env_int("HEADROOM_MIN_TOKENS", args.min_tokens),
+        max_items_after_crush=_get_env_int("HEADROOM_MAX_ITEMS", args.max_items),
+        cache_enabled=cache_enabled,
+        cache_ttl_seconds=_get_env_int("HEADROOM_CACHE_TTL", args.cache_ttl),
+        rate_limit_enabled=rate_limit_enabled,
+        rate_limit_requests_per_minute=_get_env_int("HEADROOM_RPM", args.rpm),
+        rate_limit_tokens_per_minute=_get_env_int("HEADROOM_TPM", args.tpm),
+        budget_limit_usd=args.budget,
+        budget_period=args.budget_period,
+        log_file=_get_env_str("HEADROOM_LOG_FILE", args.log_file)
+        if args.log_file
+        else os.environ.get("HEADROOM_LOG_FILE"),
+        log_full_messages=args.log_messages or _get_env_bool("HEADROOM_LOG_MESSAGES", False),
+        smart_routing=smart_routing,
+        code_aware_enabled=code_aware_enabled,
+        # Connection pool settings
+        max_connections=_get_env_int("HEADROOM_MAX_CONNECTIONS", args.max_connections),
+        max_keepalive_connections=_get_env_int("HEADROOM_MAX_KEEPALIVE", args.max_keepalive),
+        http2=not args.no_http2 and _get_env_bool("HEADROOM_HTTP2", True),
+        tool_profiles=tool_profiles if tool_profiles else None,
+        mode=normalize_proxy_mode(_get_env_str("HEADROOM_MODE", PROXY_MODE_TOKEN)),
+    )
+
+    # Get worker and concurrency settings
+    workers = _get_env_int("HEADROOM_WORKERS", args.workers)
+    limit_concurrency = _get_env_int("HEADROOM_LIMIT_CONCURRENCY", args.limit_concurrency)
+
+    run_server(config, workers=workers, limit_concurrency=limit_concurrency)
diff --git a/headroom/release_version.py b/headroom/release_version.py
index 951a8bfc05a606a2e9b73ecc42234a102d460e18..cf99835c1cc96eb195bd1efde4fa9d0ac20df4d4 100644
--- a/headroom/release_version.py
+++ b/headroom/release_version.py
@@ -1,310 +1,310 @@
-"""Release version helpers for the GitHub Actions release workflow."""
-
-from __future__ import annotations
-
-import os
-import re
-import subprocess
-from collections.abc import Sequence
-from dataclasses import dataclass, replace
-from pathlib import Path
-
-SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
-RELEASE_TAG_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)(?:\.(\d+))?$")
-CONVENTIONAL_COMMIT_RE = re.compile(
-    r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"
-)
-BREAKING_CHANGE_RE = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)
-FIELD_SEP = "\x1f"
-RECORD_SEP = "\x1e"
-GIT_LOG_FORMAT = "%s%x1f%b%x1e"
-BUMP_PRIORITY = {"patch": 0, "minor": 1, "major": 2}
-
-
-@dataclass(frozen=True, order=True)
-class SemVer:
-    """Semantic version tuple with simple bump helpers."""
-
-    major: int
-    minor: int
-    patch: int
-
-    @classmethod
-    def parse(cls, value: str) -> SemVer:
-        match = SEMVER_RE.match(value)
-        if not match:
-            raise ValueError(f"Invalid semantic version: {value}")
-        return cls(*(int(part) for part in match.groups()))
-
-    def bump(self, level: str) -> SemVer:
-        if level == "major":
-            return SemVer(self.major + 1, 0, 0)
-        if level == "minor":
-            return SemVer(self.major, self.minor + 1, 0)
-        if level == "patch":
-            return SemVer(self.major, self.minor, self.patch + 1)
-        raise ValueError(f"Unsupported bump level: {level}")
-
-    def __str__(self) -> str:
-        return f"{self.major}.{self.minor}.{self.patch}"
-
-
-@dataclass(frozen=True)
-class ReleaseVersionInfo:
-    """Workflow outputs for release version calculation."""
-
-    version: str
-    npm_version: str
-    canonical: str
-    height: str
-    bump: str
-    previous_tag: str
-
-    def as_outputs(self) -> dict[str, str]:
-        return {
-            "version": self.version,
-            "npm_version": self.npm_version,
-            "canonical": self.canonical,
-            "height": self.height,
-            "bump": self.bump,
-            "previous_tag": self.previous_tag,
-        }
-
-
-@dataclass(frozen=True, order=True)
-class ReleaseTag:
-    """Parsed release tag metadata used for sorting and normalization."""
-
-    version: SemVer
-    legacy_height: int = -1
-    raw: str = ""
-
-
-@dataclass(frozen=True)
-class CommitInfo:
-    """Commit subject/body pair used for bump detection."""
-
-    subject: str
-    body: str = ""
-
-
-def parse_release_tag(tag: str) -> ReleaseTag:
-    """Parse a release tag, preserving legacy fourth-component ordering."""
-
-    match = RELEASE_TAG_RE.match(tag)
-    if not match:
-        raise ValueError(f"Invalid release tag: {tag}")
-    major, minor, patch, extra = match.groups()
-    return ReleaseTag(
-        version=SemVer(int(major), int(minor), int(patch)),
-        legacy_height=int(extra) if extra is not None else -1,
-        raw=tag,
-    )
-
-
-def normalize_release_tag(tag: str) -> SemVer:
-    """Collapse historic 4-part release tags into their base semantic version."""
-
-    return parse_release_tag(tag).version
-
-
-def find_latest_release_tag(tags: Sequence[str]) -> str | None:
-    """Return the latest release tag after normalizing legacy 4-part tags."""
-
-    candidates: list[ReleaseTag] = []
-    for tag in tags:
-        if RELEASE_TAG_RE.match(tag):
-            candidates.append(parse_release_tag(tag))
-    if not candidates:
-        return None
-    candidates.sort(reverse=True)
-    return candidates[0].raw
-
-
-def _merge_summary(subject: str, body: str) -> str:
-    """Return the first meaningful body line for merge commits."""
-
-    if not subject.startswith("Merge "):
-        return ""
-    for line in body.splitlines():
-        stripped = line.strip()
-        if stripped:
-            return stripped
-    return ""
-
-
-def classify_commit_bump(commit: CommitInfo) -> str:
-    """Classify one commit using conventional commit semantics."""
-
-    merge_summary = _merge_summary(commit.subject, commit.body)
-    candidates = [commit.subject]
-    if merge_summary:
-        candidates.insert(0, merge_summary)
-
-    has_breaking_change = bool(BREAKING_CHANGE_RE.search(commit.body))
-    for candidate in candidates:
-        match = CONVENTIONAL_COMMIT_RE.match(candidate)
-        if not match:
-            continue
-        if has_breaking_change or bool(match.group(3)):
-            return "major"
-        if match.group(1) == "feat":
-            return "minor"
-        return "patch"
-
-    if has_breaking_change:
-        return "major"
-    return "patch"
-
-
-def determine_bump_level(commits: Sequence[CommitInfo]) -> str:
-    """Return the highest required bump across a commit range."""
-
-    level = "patch"
-    for commit in commits:
-        candidate = classify_commit_bump(commit)
-        if BUMP_PRIORITY[candidate] > BUMP_PRIORITY[level]:
-            level = candidate
-    return level
-
-
-def compute_release_version(
-    canonical_version: str,
-    level: str,
-    tags: Sequence[str],
-    manual_version: str = "",
-) -> ReleaseVersionInfo:
-    """Compute the next release version from the canonical version and existing tags."""
-
-    if manual_version:
-        manual = str(SemVer.parse(manual_version))
-        return ReleaseVersionInfo(
-            version=manual,
-            npm_version=manual,
-            canonical=canonical_version,
-            height="0",
-            bump="manual",
-            previous_tag="",
-        )
-
-    canonical = SemVer.parse(canonical_version)
-    previous_tag = find_latest_release_tag(tags)
-    current = canonical
-    if previous_tag is not None:
-        current = max(current, normalize_release_tag(previous_tag))
-
-    next_version = str(current.bump(level))
-    return ReleaseVersionInfo(
-        version=next_version,
-        npm_version=next_version,
-        canonical=canonical_version,
-        height="0",
-        bump=level,
-        previous_tag=previous_tag or "",
-    )
-
-
-def get_canonical_version(root: Path) -> str:
-    """Read the canonical project version from pyproject.toml."""
-
-    try:
-        import tomllib
-    except ModuleNotFoundError:  # pragma: no cover - Python 3.10 compatibility
-        import tomli as tomllib
-
-    with open(root / "pyproject.toml", "rb") as file:
-        project = tomllib.load(file)["project"]
-    return str(project["version"])
-
-
-def list_release_tags(root: Path) -> list[str]:
-    """List release tags from the local Git checkout."""
-
-    result = subprocess.run(
-        ["git", "tag", "-l", "v*"],
-        cwd=root,
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-    return [tag.strip() for tag in result.stdout.splitlines() if tag.strip()]
-
-
-def list_release_commits(root: Path, previous_tag: str) -> list[CommitInfo]:
-    """List commit subject/body pairs since the previous release tag."""
-
-    cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]
-    if previous_tag:
-        cmd.append(f"{previous_tag}..HEAD")
-    else:
-        cmd.append("HEAD")
-
-    result = subprocess.run(
-        cmd,
-        cwd=root,
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-
-    commits: list[CommitInfo] = []
-    for raw_entry in result.stdout.split(RECORD_SEP):
-        if not raw_entry or FIELD_SEP not in raw_entry:
-            continue
-        subject, body = raw_entry.split(FIELD_SEP, 1)
-        commits.append(CommitInfo(subject=subject.strip(), body=body.strip()))
-    return commits
-
-
-def commit_height_since(root: Path, previous_tag: str) -> str:
-    """Count commits since the previous release tag for changelog/debug outputs."""
-
-    if not previous_tag:
-        return "0"
-
-    result = subprocess.run(
-        ["git", "rev-list", f"{previous_tag}..HEAD", "--count"],
-        cwd=root,
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-    return result.stdout.strip() or "0"
-
-
-def write_github_outputs(info: ReleaseVersionInfo, output_path: str) -> None:
-    """Append workflow outputs to the GitHub Actions output file."""
-
-    with open(output_path, "a", encoding="utf-8") as output_file:
-        for key, value in info.as_outputs().items():
-            output_file.write(f"{key}={value}\n")
-
-
-def main() -> None:
-    root = Path.cwd()
-    manual_version = os.environ.get("MANUAL_VER", "").strip()
-    tags = list_release_tags(root)
-    previous_tag = find_latest_release_tag(tags) or ""
-    level = os.environ.get("LEVEL", "").strip()
-    if not level:
-        level = determine_bump_level(list_release_commits(root, previous_tag))
-
-    info = compute_release_version(
-        canonical_version=get_canonical_version(root),
-        level=level,
-        tags=tags,
-        manual_version=manual_version,
-    )
-    info = replace(info, height=commit_height_since(root, info.previous_tag))
-
-    output_path = os.environ.get("GITHUB_OUTPUT", "").strip()
-    if output_path:
-        write_github_outputs(info, output_path)
-        return
-
-    for key, value in info.as_outputs().items():
-        print(f"{key}={value}")
-
-
-if __name__ == "__main__":
-    main()
+"""Release version helpers for the GitHub Actions release workflow."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+RELEASE_TAG_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)(?:\.(\d+))?$")
+CONVENTIONAL_COMMIT_RE = re.compile(
+    r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"
+)
+BREAKING_CHANGE_RE = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)
+FIELD_SEP = "\x1f"
+RECORD_SEP = "\x1e"
+GIT_LOG_FORMAT = "%s%x1f%b%x1e"
+BUMP_PRIORITY = {"patch": 0, "minor": 1, "major": 2}
+
+
+@dataclass(frozen=True, order=True)
+class SemVer:
+    """Semantic version tuple with simple bump helpers."""
+
+    major: int
+    minor: int
+    patch: int
+
+    @classmethod
+    def parse(cls, value: str) -> SemVer:
+        match = SEMVER_RE.match(value)
+        if not match:
+            raise ValueError(f"Invalid semantic version: {value}")
+        return cls(*(int(part) for part in match.groups()))
+
+    def bump(self, level: str) -> SemVer:
+        if level == "major":
+            return SemVer(self.major + 1, 0, 0)
+        if level == "minor":
+            return SemVer(self.major, self.minor + 1, 0)
+        if level == "patch":
+            return SemVer(self.major, self.minor, self.patch + 1)
+        raise ValueError(f"Unsupported bump level: {level}")
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+
+@dataclass(frozen=True)
+class ReleaseVersionInfo:
+    """Workflow outputs for release version calculation."""
+
+    version: str
+    npm_version: str
+    canonical: str
+    height: str
+    bump: str
+    previous_tag: str
+
+    def as_outputs(self) -> dict[str, str]:
+        return {
+            "version": self.version,
+            "npm_version": self.npm_version,
+            "canonical": self.canonical,
+            "height": self.height,
+            "bump": self.bump,
+            "previous_tag": self.previous_tag,
+        }
+
+
+@dataclass(frozen=True, order=True)
+class ReleaseTag:
+    """Parsed release tag metadata used for sorting and normalization."""
+
+    version: SemVer
+    legacy_height: int = -1
+    raw: str = ""
+
+
+@dataclass(frozen=True)
+class CommitInfo:
+    """Commit subject/body pair used for bump detection."""
+
+    subject: str
+    body: str = ""
+
+
+def parse_release_tag(tag: str) -> ReleaseTag:
+    """Parse a release tag, preserving legacy fourth-component ordering."""
+
+    match = RELEASE_TAG_RE.match(tag)
+    if not match:
+        raise ValueError(f"Invalid release tag: {tag}")
+    major, minor, patch, extra = match.groups()
+    return ReleaseTag(
+        version=SemVer(int(major), int(minor), int(patch)),
+        legacy_height=int(extra) if extra is not None else -1,
+        raw=tag,
+    )
+
+
+def normalize_release_tag(tag: str) -> SemVer:
+    """Collapse historic 4-part release tags into their base semantic version."""
+
+    return parse_release_tag(tag).version
+
+
+def find_latest_release_tag(tags: Sequence[str]) -> str | None:
+    """Return the latest release tag after normalizing legacy 4-part tags."""
+
+    candidates: list[ReleaseTag] = []
+    for tag in tags:
+        if RELEASE_TAG_RE.match(tag):
+            candidates.append(parse_release_tag(tag))
+    if not candidates:
+        return None
+    candidates.sort(reverse=True)
+    return candidates[0].raw
+
+
+def _merge_summary(subject: str, body: str) -> str:
+    """Return the first meaningful body line for merge commits."""
+
+    if not subject.startswith("Merge "):
+        return ""
+    for line in body.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return ""
+
+
+def classify_commit_bump(commit: CommitInfo) -> str:
+    """Classify one commit using conventional commit semantics."""
+
+    merge_summary = _merge_summary(commit.subject, commit.body)
+    candidates = [commit.subject]
+    if merge_summary:
+        candidates.insert(0, merge_summary)
+
+    has_breaking_change = bool(BREAKING_CHANGE_RE.search(commit.body))
+    for candidate in candidates:
+        match = CONVENTIONAL_COMMIT_RE.match(candidate)
+        if not match:
+            continue
+        if has_breaking_change or bool(match.group(3)):
+            return "major"
+        if match.group(1) == "feat":
+            return "minor"
+        return "patch"
+
+    if has_breaking_change:
+        return "major"
+    return "patch"
+
+
+def determine_bump_level(commits: Sequence[CommitInfo]) -> str:
+    """Return the highest required bump across a commit range."""
+
+    level = "patch"
+    for commit in commits:
+        candidate = classify_commit_bump(commit)
+        if BUMP_PRIORITY[candidate] > BUMP_PRIORITY[level]:
+            level = candidate
+    return level
+
+
+def compute_release_version(
+    canonical_version: str,
+    level: str,
+    tags: Sequence[str],
+    manual_version: str = "",
+) -> ReleaseVersionInfo:
+    """Compute the next release version from the canonical version and existing tags."""
+
+    if manual_version:
+        manual = str(SemVer.parse(manual_version))
+        return ReleaseVersionInfo(
+            version=manual,
+            npm_version=manual,
+            canonical=canonical_version,
+            height="0",
+            bump="manual",
+            previous_tag="",
+        )
+
+    canonical = SemVer.parse(canonical_version)
+    previous_tag = find_latest_release_tag(tags)
+    current = canonical
+    if previous_tag is not None:
+        current = max(current, normalize_release_tag(previous_tag))
+
+    next_version = str(current.bump(level))
+    return ReleaseVersionInfo(
+        version=next_version,
+        npm_version=next_version,
+        canonical=canonical_version,
+        height="0",
+        bump=level,
+        previous_tag=previous_tag or "",
+    )
+
+
+def get_canonical_version(root: Path) -> str:
+    """Read the canonical project version from pyproject.toml."""
+
+    try:
+        import tomllib
+    except ModuleNotFoundError:  # pragma: no cover - Python 3.10 compatibility
+        import tomli as tomllib
+
+    with open(root / "pyproject.toml", "rb") as file:
+        project = tomllib.load(file)["project"]
+    return str(project["version"])
+
+
+def list_release_tags(root: Path) -> list[str]:
+    """List release tags from the local Git checkout."""
+
+    result = subprocess.run(
+        ["git", "tag", "-l", "v*"],
+        cwd=root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return [tag.strip() for tag in result.stdout.splitlines() if tag.strip()]
+
+
+def list_release_commits(root: Path, previous_tag: str) -> list[CommitInfo]:
+    """List commit subject/body pairs since the previous release tag."""
+
+    cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]
+    if previous_tag:
+        cmd.append(f"{previous_tag}..HEAD")
+    else:
+        cmd.append("HEAD")
+
+    result = subprocess.run(
+        cmd,
+        cwd=root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    commits: list[CommitInfo] = []
+    for raw_entry in result.stdout.split(RECORD_SEP):
+        if not raw_entry or FIELD_SEP not in raw_entry:
+            continue
+        subject, body = raw_entry.split(FIELD_SEP, 1)
+        commits.append(CommitInfo(subject=subject.strip(), body=body.strip()))
+    return commits
+
+
+def commit_height_since(root: Path, previous_tag: str) -> str:
+    """Count commits since the previous release tag for changelog/debug outputs."""
+
+    if not previous_tag:
+        return "0"
+
+    result = subprocess.run(
+        ["git", "rev-list", f"{previous_tag}..HEAD", "--count"],
+        cwd=root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip() or "0"
+
+
+def write_github_outputs(info: ReleaseVersionInfo, output_path: str) -> None:
+    """Append workflow outputs to the GitHub Actions output file."""
+
+    with open(output_path, "a", encoding="utf-8") as output_file:
+        for key, value in info.as_outputs().items():
+            output_file.write(f"{key}={value}\n")
+
+
+def main() -> None:
+    root = Path.cwd()
+    manual_version = os.environ.get("MANUAL_VER", "").strip()
+    tags = list_release_tags(root)
+    previous_tag = find_latest_release_tag(tags) or ""
+    level = os.environ.get("LEVEL", "").strip()
+    if not level:
+        level = determine_bump_level(list_release_commits(root, previous_tag))
+
+    info = compute_release_version(
+        canonical_version=get_canonical_version(root),
+        level=level,
+        tags=tags,
+        manual_version=manual_version,
+    )
+    info = replace(info, height=commit_height_since(root, info.previous_tag))
+
+    output_path = os.environ.get("GITHUB_OUTPUT", "").strip()
+    if output_path:
+        write_github_outputs(info, output_path)
+        return
+
+    for key, value in info.as_outputs().items():
+        print(f"{key}={value}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/headroom/subscription/__init__.py b/headroom/subscription/__init__.py
index e4760c94260303eb5ccd5c9fa7bdf95a1d2b7856..8ab04220b9fd9262cf8b362eb7aab86b7324ab48 100644
--- a/headroom/subscription/__init__.py
+++ b/headroom/subscription/__init__.py
@@ -1,72 +1,72 @@
-"""Subscription window tracking for Anthropic Claude Code accounts and Codex rate limits."""
-
-from headroom.subscription.base import (
-    QuotaTracker,
-    QuotaTrackerRegistry,
-    get_quota_registry,
-    reset_quota_registry,
-)
-from headroom.subscription.client import SubscriptionClient, read_cached_oauth_token
-from headroom.subscription.codex_rate_limits import (
-    CodexCreditsSnapshot,
-    CodexRateLimitSnapshot,
-    CodexRateLimitState,
-    CodexRateLimitWindow,
-    get_codex_rate_limit_state,
-    parse_codex_rate_limits,
-)
-from headroom.subscription.copilot_quota import (
-    CopilotQuotaCategory,
-    CopilotQuotaSnapshot,
-    CopilotQuotaState,
-    discover_github_token,
-    get_copilot_quota_tracker,
-    parse_copilot_quota,
-)
-from headroom.subscription.models import (
-    ExtraUsage,
-    HeadroomContribution,
-    RateLimitWindow,
-    SubscriptionSnapshot,
-    SubscriptionState,
-    WindowDiscrepancy,
-    WindowTokens,
-)
-from headroom.subscription.tracker import (
-    SubscriptionTracker,
-    configure_subscription_tracker,
-    get_subscription_tracker,
-    shutdown_subscription_tracker,
-)
-
-__all__ = [
-    "CodexCreditsSnapshot",
-    "CodexRateLimitSnapshot",
-    "CodexRateLimitState",
-    "CodexRateLimitWindow",
-    "CopilotQuotaCategory",
-    "CopilotQuotaSnapshot",
-    "CopilotQuotaState",
-    "ExtraUsage",
-    "HeadroomContribution",
-    "QuotaTracker",
-    "QuotaTrackerRegistry",
-    "RateLimitWindow",
-    "SubscriptionClient",
-    "SubscriptionSnapshot",
-    "SubscriptionState",
-    "SubscriptionTracker",
-    "WindowDiscrepancy",
-    "WindowTokens",
-    "configure_subscription_tracker",
-    "discover_github_token",
-    "get_codex_rate_limit_state",
-    "get_copilot_quota_tracker",
-    "get_quota_registry",
-    "get_subscription_tracker",
-    "parse_codex_rate_limits",
-    "parse_copilot_quota",
-    "read_cached_oauth_token",
-    "reset_quota_registry",
-    "shutdown_subscription_tracker",
-]
+"""Subscription window tracking for Anthropic Claude Code accounts and Codex rate limits."""
+
+from headroom.subscription.base import (
+    QuotaTracker,
+    QuotaTrackerRegistry,
+    get_quota_registry,
+    reset_quota_registry,
+)
+from headroom.subscription.client import SubscriptionClient, read_cached_oauth_token
+from headroom.subscription.codex_rate_limits import (
+    CodexCreditsSnapshot,
+    CodexRateLimitSnapshot,
+    CodexRateLimitState,
+    CodexRateLimitWindow,
+    get_codex_rate_limit_state,
+    parse_codex_rate_limits,
+)
+from headroom.subscription.copilot_quota import (
+    CopilotQuotaCategory,
+    CopilotQuotaSnapshot,
+    CopilotQuotaState,
+    discover_github_token,
+    get_copilot_quota_tracker,
+    parse_copilot_quota,
+)
+from headroom.subscription.models import (
+    ExtraUsage,
+    HeadroomContribution,
+    RateLimitWindow,
+    SubscriptionSnapshot,
+    SubscriptionState,
+    WindowDiscrepancy,
+    WindowTokens,
+)
+from headroom.subscription.tracker import (
+    SubscriptionTracker,
+    configure_subscription_tracker,
+    get_subscription_tracker,
+    shutdown_subscription_tracker,
+)
+
+__all__ = [
+    "CodexCreditsSnapshot",
+    "CodexRateLimitSnapshot",
+    "CodexRateLimitState",
+    "CodexRateLimitWindow",
+    "CopilotQuotaCategory",
+    "CopilotQuotaSnapshot",
+    "CopilotQuotaState",
+    "ExtraUsage",
+    "HeadroomContribution",
+    "QuotaTracker",
+    "QuotaTrackerRegistry",
+    "RateLimitWindow",
+    "SubscriptionClient",
+    "SubscriptionSnapshot",
+    "SubscriptionState",
+    "SubscriptionTracker",
+    "WindowDiscrepancy",
+    "WindowTokens",
+    "configure_subscription_tracker",
+    "discover_github_token",
+    "get_codex_rate_limit_state",
+    "get_copilot_quota_tracker",
+    "get_quota_registry",
+    "get_subscription_tracker",
+    "parse_codex_rate_limits",
+    "parse_copilot_quota",
+    "read_cached_oauth_token",
+    "reset_quota_registry",
+    "shutdown_subscription_tracker",
+]
diff --git a/headroom/subscription/base.py b/headroom/subscription/base.py
index c6664f5a8ef511f138037fd1056264c3dd754980..e5847a86da3b3dd4facac61112a8fb42f510217b 100644
--- a/headroom/subscription/base.py
+++ b/headroom/subscription/base.py
@@ -1,230 +1,230 @@
-"""Base abstractions for pluggable AI-tool quota / rate-limit trackers.
-
-Every provider tracker (Anthropic, Codex, Copilot, …) inherits from
-:class:`QuotaTracker` and is registered with the process-global
-:class:`QuotaTrackerRegistry`.  ``server.py`` only interacts with the
-registry — adding a new provider requires *zero* changes to the server.
-
-Quick-start for a new provider::
-
-    from headroom.subscription.base import QuotaTracker, get_quota_registry
-
-    class GeminiQuotaTracker(QuotaTracker):
-        key   = "gemini_quota"
-        label = "Google Gemini"
-
-        def is_available(self) -> bool:
-            return bool(os.environ.get("GOOGLE_API_KEY"))
-
-        async def start(self) -> None: ...   # launch background poll
-        async def stop(self)  -> None: ...   # cancel poll task
-
-        def get_stats(self) -> dict | None:
-            return ...  # serialisable dict or None if no data yet
-
-    get_quota_registry().register(GeminiQuotaTracker())
-"""
-
-from __future__ import annotations
-
-import abc
-import logging
-from threading import Lock
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-
-class QuotaTracker(abc.ABC):
-    """Abstract base for a single AI-tool quota / rate-limit tracker.
-
-    Subclasses must define :attr:`key`, :attr:`label`, and
-    :meth:`get_stats`.  All other methods have sensible defaults.
-    """
-
-    # ------------------------------------------------------------------ #
-    # Class-level identity — subclasses should override as class attributes
-    # ------------------------------------------------------------------ #
-
-    @property
-    @abc.abstractmethod
-    def key(self) -> str:
-        """Stats key used in ``/stats`` and the dashboard.
-
-        Must be unique across all registered trackers.
-        Examples: ``"subscription_window"``, ``"codex_rate_limits"``.
-        """
-
-    @property
-    @abc.abstractmethod
-    def label(self) -> str:
-        """Human-readable name for log messages.
-
-        Example: ``"Anthropic Claude Code"``.
-        """
-
-    # ------------------------------------------------------------------ #
-    # Availability gate
-    # ------------------------------------------------------------------ #
-
-    def is_available(self) -> bool:
-        """Return ``True`` if this tracker should be activated.
-
-        Override to gate on environment variables, config flags, etc.
-        The registry calls this before :meth:`start` and skips trackers
-        that return ``False``.  Default: always available.
-        """
-        return True
-
-    # ------------------------------------------------------------------ #
-    # Lifecycle — default no-ops (suitable for passive/header-based trackers)
-    # ------------------------------------------------------------------ #
-
-    async def start(self) -> None:  # noqa: B027
-        """Start background polling.  No-op for passive trackers."""
-
-    async def stop(self) -> None:  # noqa: B027
-        """Stop background polling.  No-op for passive trackers."""
-
-    # ------------------------------------------------------------------ #
-    # Stats
-    # ------------------------------------------------------------------ #
-
-    @abc.abstractmethod
-    def get_stats(self) -> dict[str, Any] | None:
-        """Return the current snapshot as a serialisable dict, or ``None``.
-
-        ``None`` means "no data yet" and causes the key to be omitted from
-        ``/stats`` rather than appearing as ``null``.
-        """
-
-
-# --------------------------------------------------------------------------- #
-# Registry
-# --------------------------------------------------------------------------- #
-
-
-class QuotaTrackerRegistry:
-    """Process-global registry of all :class:`QuotaTracker` instances.
-
-    Typical usage::
-
-        registry = get_quota_registry()
-        registry.register(SubscriptionTracker(...))
-        registry.register(get_codex_rate_limit_state())
-        registry.register(get_copilot_quota_tracker())
-
-        # server startup
-        await registry.start_all()
-
-        # /stats assembly
-        stats.update(registry.get_all_stats())
-
-        # server shutdown
-        await registry.stop_all()
-    """
-
-    def __init__(self) -> None:
-        self._trackers: list[QuotaTracker] = []
-        self._lock = Lock()
-
-    # ------------------------------------------------------------------ #
-    # Registration
-    # ------------------------------------------------------------------ #
-
-    def register(self, tracker: QuotaTracker) -> None:
-        """Register a tracker.  Duplicate keys are rejected."""
-        with self._lock:
-            existing_keys = {t.key for t in self._trackers}
-            if tracker.key in existing_keys:
-                raise ValueError(
-                    f"A tracker with key '{tracker.key}' is already registered. "
-                    "Each tracker must have a unique key."
-                )
-            self._trackers.append(tracker)
-
-    def get(self, key: str) -> QuotaTracker | None:
-        """Return the registered tracker for *key*, or ``None``."""
-        with self._lock:
-            for t in self._trackers:
-                if t.key == key:
-                    return t
-        return None
-
-    @property
-    def trackers(self) -> list[QuotaTracker]:
-        """Read-only snapshot of the registered tracker list."""
-        with self._lock:
-            return list(self._trackers)
-
-    # ------------------------------------------------------------------ #
-    # Lifecycle
-    # ------------------------------------------------------------------ #
-
-    async def start_all(self) -> None:
-        """Start every available tracker and log its status."""
-        for tracker in self.trackers:
-            if tracker.is_available():
-                await tracker.start()
-                logger.info("%s quota tracking: ENABLED", tracker.label)
-            else:
-                logger.info("%s quota tracking: DISABLED (not available)", tracker.label)
-
-    async def stop_all(self) -> None:
-        """Stop all registered trackers (regardless of availability)."""
-        for tracker in self.trackers:
-            try:
-                await tracker.stop()
-            except Exception as exc:  # noqa: BLE001
-                logger.warning("Error stopping %s tracker: %s", tracker.label, exc)
-
-    # ------------------------------------------------------------------ #
-    # Stats
-    # ------------------------------------------------------------------ #
-
-    def get_all_stats(self) -> dict[str, dict[str, Any] | None]:
-        """Return ``{key: stats_dict}`` for every available tracker.
-
-        Trackers that are unavailable or return ``None`` are excluded.
-        """
-        result: dict[str, dict[str, Any] | None] = {}
-        for tracker in self.trackers:
-            if not tracker.is_available():
-                continue
-            stats = tracker.get_stats()
-            if stats is not None:
-                result[tracker.key] = stats
-        return result
-
-    def get_stats(self, key: str) -> dict[str, Any] | None:
-        """Return stats for a single tracker by key, or ``None``."""
-        tracker = self.get(key)
-        return tracker.get_stats() if tracker is not None else None
-
-
-# --------------------------------------------------------------------------- #
-# Process-global singleton
-# --------------------------------------------------------------------------- #
-
-_registry: QuotaTrackerRegistry | None = None
-_registry_lock = Lock()
-
-
-def get_quota_registry() -> QuotaTrackerRegistry:
-    """Return the process-global :class:`QuotaTrackerRegistry` singleton."""
-    global _registry
-    if _registry is None:
-        with _registry_lock:
-            if _registry is None:
-                _registry = QuotaTrackerRegistry()
-    return _registry
-
-
-def reset_quota_registry() -> None:
-    """Replace the global registry with a fresh empty instance.
-
-    Intended for use in tests only.
-    """
-    global _registry
-    with _registry_lock:
-        _registry = QuotaTrackerRegistry()
+"""Base abstractions for pluggable AI-tool quota / rate-limit trackers.
+
+Every provider tracker (Anthropic, Codex, Copilot, …) inherits from
+:class:`QuotaTracker` and is registered with the process-global
+:class:`QuotaTrackerRegistry`.  ``server.py`` only interacts with the
+registry — adding a new provider requires *zero* changes to the server.
+
+Quick-start for a new provider::
+
+    from headroom.subscription.base import QuotaTracker, get_quota_registry
+
+    class GeminiQuotaTracker(QuotaTracker):
+        key   = "gemini_quota"
+        label = "Google Gemini"
+
+        def is_available(self) -> bool:
+            return bool(os.environ.get("GOOGLE_API_KEY"))
+
+        async def start(self) -> None: ...   # launch background poll
+        async def stop(self)  -> None: ...   # cancel poll task
+
+        def get_stats(self) -> dict | None:
+            return ...  # serialisable dict or None if no data yet
+
+    get_quota_registry().register(GeminiQuotaTracker())
+"""
+
+from __future__ import annotations
+
+import abc
+import logging
+from threading import Lock
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class QuotaTracker(abc.ABC):
+    """Abstract base for a single AI-tool quota / rate-limit tracker.
+
+    Subclasses must define :attr:`key`, :attr:`label`, and
+    :meth:`get_stats`.  All other methods have sensible defaults.
+    """
+
+    # ------------------------------------------------------------------ #
+    # Class-level identity — subclasses should override as class attributes
+    # ------------------------------------------------------------------ #
+
+    @property
+    @abc.abstractmethod
+    def key(self) -> str:
+        """Stats key used in ``/stats`` and the dashboard.
+
+        Must be unique across all registered trackers.
+        Examples: ``"subscription_window"``, ``"codex_rate_limits"``.
+        """
+
+    @property
+    @abc.abstractmethod
+    def label(self) -> str:
+        """Human-readable name for log messages.
+
+        Example: ``"Anthropic Claude Code"``.
+        """
+
+    # ------------------------------------------------------------------ #
+    # Availability gate
+    # ------------------------------------------------------------------ #
+
+    def is_available(self) -> bool:
+        """Return ``True`` if this tracker should be activated.
+
+        Override to gate on environment variables, config flags, etc.
+        The registry calls this before :meth:`start` and skips trackers
+        that return ``False``.  Default: always available.
+        """
+        return True
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle — default no-ops (suitable for passive/header-based trackers)
+    # ------------------------------------------------------------------ #
+
+    async def start(self) -> None:  # noqa: B027
+        """Start background polling.  No-op for passive trackers."""
+
+    async def stop(self) -> None:  # noqa: B027
+        """Stop background polling.  No-op for passive trackers."""
+
+    # ------------------------------------------------------------------ #
+    # Stats
+    # ------------------------------------------------------------------ #
+
+    @abc.abstractmethod
+    def get_stats(self) -> dict[str, Any] | None:
+        """Return the current snapshot as a serialisable dict, or ``None``.
+
+        ``None`` means "no data yet" and causes the key to be omitted from
+        ``/stats`` rather than appearing as ``null``.
+        """
+
+
+# --------------------------------------------------------------------------- #
+# Registry
+# --------------------------------------------------------------------------- #
+
+
+class QuotaTrackerRegistry:
+    """Process-global registry of all :class:`QuotaTracker` instances.
+
+    Typical usage::
+
+        registry = get_quota_registry()
+        registry.register(SubscriptionTracker(...))
+        registry.register(get_codex_rate_limit_state())
+        registry.register(get_copilot_quota_tracker())
+
+        # server startup
+        await registry.start_all()
+
+        # /stats assembly
+        stats.update(registry.get_all_stats())
+
+        # server shutdown
+        await registry.stop_all()
+    """
+
+    def __init__(self) -> None:
+        self._trackers: list[QuotaTracker] = []
+        self._lock = Lock()
+
+    # ------------------------------------------------------------------ #
+    # Registration
+    # ------------------------------------------------------------------ #
+
+    def register(self, tracker: QuotaTracker) -> None:
+        """Register a tracker.  Duplicate keys are rejected."""
+        with self._lock:
+            existing_keys = {t.key for t in self._trackers}
+            if tracker.key in existing_keys:
+                raise ValueError(
+                    f"A tracker with key '{tracker.key}' is already registered. "
+                    "Each tracker must have a unique key."
+                )
+            self._trackers.append(tracker)
+
+    def get(self, key: str) -> QuotaTracker | None:
+        """Return the registered tracker for *key*, or ``None``."""
+        with self._lock:
+            for t in self._trackers:
+                if t.key == key:
+                    return t
+        return None
+
+    @property
+    def trackers(self) -> list[QuotaTracker]:
+        """Read-only snapshot of the registered tracker list."""
+        with self._lock:
+            return list(self._trackers)
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle
+    # ------------------------------------------------------------------ #
+
+    async def start_all(self) -> None:
+        """Start every available tracker and log its status."""
+        for tracker in self.trackers:
+            if tracker.is_available():
+                await tracker.start()
+                logger.info("%s quota tracking: ENABLED", tracker.label)
+            else:
+                logger.info("%s quota tracking: DISABLED (not available)", tracker.label)
+
+    async def stop_all(self) -> None:
+        """Stop all registered trackers (regardless of availability)."""
+        for tracker in self.trackers:
+            try:
+                await tracker.stop()
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Error stopping %s tracker: %s", tracker.label, exc)
+
+    # ------------------------------------------------------------------ #
+    # Stats
+    # ------------------------------------------------------------------ #
+
+    def get_all_stats(self) -> dict[str, dict[str, Any] | None]:
+        """Return ``{key: stats_dict}`` for every available tracker.
+
+        Trackers that are unavailable or return ``None`` are excluded.
+        """
+        result: dict[str, dict[str, Any] | None] = {}
+        for tracker in self.trackers:
+            if not tracker.is_available():
+                continue
+            stats = tracker.get_stats()
+            if stats is not None:
+                result[tracker.key] = stats
+        return result
+
+    def get_stats(self, key: str) -> dict[str, Any] | None:
+        """Return stats for a single tracker by key, or ``None``."""
+        tracker = self.get(key)
+        return tracker.get_stats() if tracker is not None else None
+
+
+# --------------------------------------------------------------------------- #
+# Process-global singleton
+# --------------------------------------------------------------------------- #
+
+_registry: QuotaTrackerRegistry | None = None
+_registry_lock = Lock()
+
+
+def get_quota_registry() -> QuotaTrackerRegistry:
+    """Return the process-global :class:`QuotaTrackerRegistry` singleton."""
+    global _registry
+    if _registry is None:
+        with _registry_lock:
+            if _registry is None:
+                _registry = QuotaTrackerRegistry()
+    return _registry
+
+
+def reset_quota_registry() -> None:
+    """Replace the global registry with a fresh empty instance.
+
+    Intended for use in tests only.
+    """
+    global _registry
+    with _registry_lock:
+        _registry = QuotaTrackerRegistry()
diff --git a/headroom/subscription/client.py b/headroom/subscription/client.py
index 55a7a8cbdfc08d6656c95dc724bedc1e44f1f3ea..11b6b08fa977d52ec90243b56195f717047fb980 100644
--- a/headroom/subscription/client.py
+++ b/headroom/subscription/client.py
@@ -1,131 +1,131 @@
-"""Async HTTP client for Anthropic's OAuth usage API.
-
-Endpoint: GET https://api.anthropic.com/api/oauth/usage
-Required header: anthropic-beta: oauth-2025-04-20
-Auth: Authorization: Bearer <oauth_access_token>
-
-Token resolution order (highest → lowest priority):
-  1. Explicit token passed to :meth:`fetch`
-  2. ``CLAUDE_CODE_OAUTH_TOKEN`` env-var
-  3. ``~/.claude/.credentials.json`` → ``claudeAiOauth.accessToken``
-     (respects ``CLAUDE_CONFIG_DIR`` env-var override)
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-from pathlib import Path
-from typing import Any
-
-import httpx
-
-from headroom.subscription.models import SubscriptionSnapshot
-
-logger = logging.getLogger(__name__)
-
-_USAGE_URL = "https://api.anthropic.com/api/oauth/usage"
-_BETA_HEADER = "oauth-2025-04-20"
-_TOKEN_EXPIRY_BUFFER_S = 60
-
-
-def _credentials_path() -> Path:
-    base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")
-    return Path(base) / ".credentials.json"
-
-
-def _load_credentials_file() -> dict[str, Any] | None:
-    """Load raw credentials dict from the Claude Code credentials file."""
-    path = _credentials_path()
-    try:
-        with path.open() as fh:
-            return json.load(fh)  # type: ignore[no-any-return]
-    except FileNotFoundError:
-        return None
-    except Exception as exc:
-        logger.debug("Cannot read credentials file %s: %s", path, exc)
-        return None
-
-
-def read_cached_oauth_token() -> str | None:
-    """Resolve a stored OAuth token for background polling (no request needed).
-
-    Returns the raw access token string if found and not expired, else None.
-    """
-    # 1. Env var
-    env_token = os.environ.get("CLAUDE_CODE_OAUTH_TOKEN", "").strip()
-    if env_token:
-        return env_token
-
-    # 2. Credentials file
-    creds = _load_credentials_file()
-    if not creds:
-        return None
-    oauth = creds.get("claudeAiOauth") or {}
-    token = oauth.get("accessToken") or ""
-    if not token:
-        return None
-
-    # Check expiry (Anthropic stores timestamp in milliseconds)
-    expires_at_ms = oauth.get("expiresAt")
-    if expires_at_ms is not None:
-        import time
-
-        now_ms = time.time() * 1000
-        if now_ms >= (expires_at_ms - _TOKEN_EXPIRY_BUFFER_S * 1000):
-            logger.debug("Cached OAuth token expired; skipping background poll")
-            return None
-
-    return token
-
-
-class SubscriptionClient:
-    """Thin async wrapper around the Anthropic OAuth usage endpoint."""
-
-    def __init__(self, timeout: float = 10.0) -> None:
-        self._timeout = timeout
-
-    async def fetch(self, token: str | None = None) -> SubscriptionSnapshot | None:
-        """Fetch current subscription window data.
-
-        :param token: OAuth access token.  When *None*, falls back to
-            :func:`read_cached_oauth_token`.
-        :returns: :class:`SubscriptionSnapshot` or *None* on auth failure /
-            unsupported account.
-        """
-        resolved = (token or "").strip() or read_cached_oauth_token()
-        if not resolved:
-            logger.debug("No OAuth token available for subscription polling")
-            return None
-
-        headers = {
-            "Authorization": f"Bearer {resolved}",
-            "anthropic-beta": _BETA_HEADER,
-            "Content-Type": "application/json",
-        }
-
-        try:
-            async with httpx.AsyncClient(timeout=self._timeout) as client:
-                resp = await client.get(_USAGE_URL, headers=headers)
-
-            if resp.status_code == 401:
-                logger.debug("OAuth token rejected (401) by Anthropic usage API")
-                return None
-            if resp.status_code == 404:
-                # API key accounts (non-subscription) return 404
-                logger.debug("Subscription usage API returned 404; likely API-key account")
-                return None
-            if resp.status_code != 200:
-                logger.warning("Anthropic usage API returned %s", resp.status_code)
-                return None
-
-            data: dict[str, Any] = resp.json()
-            return SubscriptionSnapshot.from_api_response(data, token=resolved)
-
-        except httpx.TimeoutException:
-            logger.debug("Timeout fetching Anthropic subscription window")
-            return None
-        except Exception as exc:
-            logger.warning("Error fetching subscription window: %s", exc)
-            return None
+"""Async HTTP client for Anthropic's OAuth usage API.
+
+Endpoint: GET https://api.anthropic.com/api/oauth/usage
+Required header: anthropic-beta: oauth-2025-04-20
+Auth: Authorization: Bearer <oauth_access_token>
+
+Token resolution order (highest → lowest priority):
+  1. Explicit token passed to :meth:`fetch`
+  2. ``CLAUDE_CODE_OAUTH_TOKEN`` env-var
+  3. ``~/.claude/.credentials.json`` → ``claudeAiOauth.accessToken``
+     (respects ``CLAUDE_CONFIG_DIR`` env-var override)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from headroom.subscription.models import SubscriptionSnapshot
+
+logger = logging.getLogger(__name__)
+
+_USAGE_URL = "https://api.anthropic.com/api/oauth/usage"
+_BETA_HEADER = "oauth-2025-04-20"
+_TOKEN_EXPIRY_BUFFER_S = 60
+
+
+def _credentials_path() -> Path:
+    base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")
+    return Path(base) / ".credentials.json"
+
+
+def _load_credentials_file() -> dict[str, Any] | None:
+    """Load raw credentials dict from the Claude Code credentials file."""
+    path = _credentials_path()
+    try:
+        with path.open() as fh:
+            return json.load(fh)  # type: ignore[no-any-return]
+    except FileNotFoundError:
+        return None
+    except Exception as exc:
+        logger.debug("Cannot read credentials file %s: %s", path, exc)
+        return None
+
+
+def read_cached_oauth_token() -> str | None:
+    """Resolve a stored OAuth token for background polling (no request needed).
+
+    Returns the raw access token string if found and not expired, else None.
+    """
+    # 1. Env var
+    env_token = os.environ.get("CLAUDE_CODE_OAUTH_TOKEN", "").strip()
+    if env_token:
+        return env_token
+
+    # 2. Credentials file
+    creds = _load_credentials_file()
+    if not creds:
+        return None
+    oauth = creds.get("claudeAiOauth") or {}
+    token = oauth.get("accessToken") or ""
+    if not token:
+        return None
+
+    # Check expiry (Anthropic stores timestamp in milliseconds)
+    expires_at_ms = oauth.get("expiresAt")
+    if expires_at_ms is not None:
+        import time
+
+        now_ms = time.time() * 1000
+        if now_ms >= (expires_at_ms - _TOKEN_EXPIRY_BUFFER_S * 1000):
+            logger.debug("Cached OAuth token expired; skipping background poll")
+            return None
+
+    return token
+
+
+class SubscriptionClient:
+    """Thin async wrapper around the Anthropic OAuth usage endpoint."""
+
+    def __init__(self, timeout: float = 10.0) -> None:
+        self._timeout = timeout
+
+    async def fetch(self, token: str | None = None) -> SubscriptionSnapshot | None:
+        """Fetch current subscription window data.
+
+        :param token: OAuth access token.  When *None*, falls back to
+            :func:`read_cached_oauth_token`.
+        :returns: :class:`SubscriptionSnapshot` or *None* on auth failure /
+            unsupported account.
+        """
+        resolved = (token or "").strip() or read_cached_oauth_token()
+        if not resolved:
+            logger.debug("No OAuth token available for subscription polling")
+            return None
+
+        headers = {
+            "Authorization": f"Bearer {resolved}",
+            "anthropic-beta": _BETA_HEADER,
+            "Content-Type": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                resp = await client.get(_USAGE_URL, headers=headers)
+
+            if resp.status_code == 401:
+                logger.debug("OAuth token rejected (401) by Anthropic usage API")
+                return None
+            if resp.status_code == 404:
+                # API key accounts (non-subscription) return 404
+                logger.debug("Subscription usage API returned 404; likely API-key account")
+                return None
+            if resp.status_code != 200:
+                logger.warning("Anthropic usage API returned %s", resp.status_code)
+                return None
+
+            data: dict[str, Any] = resp.json()
+            return SubscriptionSnapshot.from_api_response(data, token=resolved)
+
+        except httpx.TimeoutException:
+            logger.debug("Timeout fetching Anthropic subscription window")
+            return None
+        except Exception as exc:
+            logger.warning("Error fetching subscription window: %s", exc)
+            return None
diff --git a/headroom/subscription/codex_rate_limits.py b/headroom/subscription/codex_rate_limits.py
index 3934ff8b1e1dc68888d9752ffe023e17fd1928d8..f66f247804bd51066278f67cd61106ecfbe68cab 100644
--- a/headroom/subscription/codex_rate_limits.py
+++ b/headroom/subscription/codex_rate_limits.py
@@ -1,247 +1,247 @@
-"""Passive tracking of OpenAI Codex rate-limit window data from response headers.
-
-Codex (OpenAI) embeds rate-limit data directly in API response headers
-(``x-codex-primary-used-percent``, ``x-codex-primary-window-minutes``, etc.)
-rather than exposing a dedicated usage endpoint.  This module captures those
-headers from responses that headroom proxies and makes them available in
-``/stats`` and the dashboard.
-
-Header schema (parsed by codex-rs ``rate_limits.rs``):
-    x-codex-primary-used-percent      float 0-100
-    x-codex-primary-window-minutes    int   window size
-    x-codex-primary-reset-at          int   Unix timestamp (seconds)
-    x-codex-secondary-used-percent    float 0-100   (optional)
-    x-codex-secondary-window-minutes  int            (optional)
-    x-codex-secondary-reset-at        int            (optional)
-    x-codex-credits-has-credits       bool
-    x-codex-credits-unlimited         bool
-    x-codex-credits-balance           str   e.g. "$5.00"
-    x-codex-promo-message             str   server announcement
-    x-codex-limit-name                str   e.g. "gpt-5.2-codex-sonic"
-"""
-
-from __future__ import annotations
-
-import time
-from dataclasses import dataclass, field
-from threading import Lock
-
-from headroom.subscription.base import QuotaTracker
-
-
-@dataclass
-class CodexRateLimitWindow:
-    """Usage data for a single rolling rate-limit window."""
-
-    used_percent: float
-    window_minutes: int | None = None
-    resets_at: int | None = None  # Unix timestamp (seconds)
-
-    @property
-    def window_label(self) -> str:
-        if self.window_minutes is None:
-            return "unknown"
-        if self.window_minutes < 60:
-            return f"{self.window_minutes}m"
-        hours = self.window_minutes // 60
-        mins = self.window_minutes % 60
-        return f"{hours}h{mins:02d}m" if mins else f"{hours}h"
-
-    @property
-    def seconds_until_reset(self) -> int | None:
-        if self.resets_at is None:
-            return None
-        return max(0, self.resets_at - int(time.time()))
-
-    def to_dict(self) -> dict:
-        return {
-            "used_percent": self.used_percent,
-            "window_minutes": self.window_minutes,
-            "window_label": self.window_label,
-            "resets_at": self.resets_at,
-            "seconds_until_reset": self.seconds_until_reset,
-        }
-
-
-@dataclass
-class CodexCreditsSnapshot:
-    """OpenAI credits balance for Codex."""
-
-    has_credits: bool
-    unlimited: bool
-    balance: str | None = None
-
-    def to_dict(self) -> dict:
-        return {
-            "has_credits": self.has_credits,
-            "unlimited": self.unlimited,
-            "balance": self.balance,
-        }
-
-
-@dataclass
-class CodexRateLimitSnapshot:
-    """Full rate-limit snapshot parsed from a single Codex API response."""
-
-    limit_id: str = "codex"
-    limit_name: str | None = None
-    primary: CodexRateLimitWindow | None = None
-    secondary: CodexRateLimitWindow | None = None
-    credits: CodexCreditsSnapshot | None = None
-    promo_message: str | None = None
-    captured_at: float = field(default_factory=time.time)
-
-    def to_dict(self) -> dict:
-        return {
-            "limit_id": self.limit_id,
-            "limit_name": self.limit_name,
-            "primary": self.primary.to_dict() if self.primary else None,
-            "secondary": self.secondary.to_dict() if self.secondary else None,
-            "credits": self.credits.to_dict() if self.credits else None,
-            "promo_message": self.promo_message,
-            "captured_at": self.captured_at,
-        }
-
-
-# ---------------------------------------------------------------------------
-# Header parsing helpers
-# ---------------------------------------------------------------------------
-
-
-def _parse_float(headers: dict[str, str], name: str) -> float | None:
-    raw = headers.get(name)
-    if raw is None:
-        return None
-    try:
-        v = float(raw)
-        return v if v == v else None  # NaN guard
-    except (ValueError, TypeError):
-        return None
-
-
-def _parse_int(headers: dict[str, str], name: str) -> int | None:
-    raw = headers.get(name)
-    if raw is None:
-        return None
-    try:
-        return int(raw)
-    except (ValueError, TypeError):
-        return None
-
-
-def _parse_bool(headers: dict[str, str], name: str) -> bool | None:
-    raw = headers.get(name)
-    if raw is None:
-        return None
-    if raw.lower() in ("true", "1"):
-        return True
-    if raw.lower() in ("false", "0"):
-        return False
-    return None
-
-
-def _parse_window(headers: dict[str, str], prefix: str, which: str) -> CodexRateLimitWindow | None:
-    used_pct = _parse_float(headers, f"{prefix}-{which}-used-percent")
-    if used_pct is None:
-        return None
-    return CodexRateLimitWindow(
-        used_percent=used_pct,
-        window_minutes=_parse_int(headers, f"{prefix}-{which}-window-minutes"),
-        resets_at=_parse_int(headers, f"{prefix}-{which}-reset-at"),
-    )
-
-
-def _parse_credits(headers: dict[str, str]) -> CodexCreditsSnapshot | None:
-    has_credits = _parse_bool(headers, "x-codex-credits-has-credits")
-    if has_credits is None:
-        return None
-    unlimited = _parse_bool(headers, "x-codex-credits-unlimited") or False
-    raw_balance = headers.get("x-codex-credits-balance", "").strip()
-    return CodexCreditsSnapshot(
-        has_credits=has_credits,
-        unlimited=unlimited,
-        balance=raw_balance or None,
-    )
-
-
-def parse_codex_rate_limits(headers: dict[str, str]) -> CodexRateLimitSnapshot | None:
-    """Parse a :class:`CodexRateLimitSnapshot` from a dict of HTTP response headers.
-
-    Returns ``None`` when no Codex rate-limit headers are present (e.g. the
-    response came from a non-Codex OpenAI endpoint or a cached reply).
-    """
-    prefix = "x-codex"
-    primary = _parse_window(headers, prefix, "primary")
-    secondary = _parse_window(headers, prefix, "secondary")
-    credits = _parse_credits(headers)
-    raw_promo = headers.get("x-codex-promo-message", "").strip()
-    promo = raw_promo or None
-    raw_limit_name = headers.get("x-codex-limit-name", "").strip()
-    limit_name = raw_limit_name or None
-
-    if primary is None and secondary is None and credits is None and promo is None:
-        return None  # Not a Codex response with rate-limit headers
-
-    return CodexRateLimitSnapshot(
-        limit_id="codex",
-        limit_name=limit_name,
-        primary=primary,
-        secondary=secondary,
-        credits=credits,
-        promo_message=promo,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Singleton state store
-# ---------------------------------------------------------------------------
-
-
-class CodexRateLimitState(QuotaTracker):
-    """Thread-safe store for the latest Codex rate-limit snapshot.
-
-    Implements :class:`~headroom.subscription.base.QuotaTracker` so it can
-    be registered with the :class:`~headroom.subscription.base.QuotaTrackerRegistry`.
-    This tracker is *passive* — it is updated by the OpenAI proxy handler
-    each time a response containing ``x-codex-*`` headers passes through
-    headroom, so :meth:`start` and :meth:`stop` are no-ops.
-    """
-
-    # QuotaTracker identity
-    key = "codex_rate_limits"
-    label = "OpenAI Codex"
-
-    def __init__(self) -> None:
-        self._lock = Lock()
-        self._latest: CodexRateLimitSnapshot | None = None
-
-    def update_from_headers(self, headers: dict[str, str]) -> None:
-        """Update state from a response header dict (no-op if no Codex headers)."""
-        snapshot = parse_codex_rate_limits(headers)
-        if snapshot is None:
-            return
-        with self._lock:
-            self._latest = snapshot
-
-    @property
-    def latest(self) -> CodexRateLimitSnapshot | None:
-        with self._lock:
-            return self._latest
-
-    def get_stats(self) -> dict | None:
-        snap = self.latest
-        return snap.to_dict() if snap is not None else None
-
-
-_state: CodexRateLimitState | None = None
-_state_lock = Lock()
-
-
-def get_codex_rate_limit_state() -> CodexRateLimitState:
-    """Return the process-global :class:`CodexRateLimitState` singleton."""
-    global _state
-    if _state is None:
-        with _state_lock:
-            if _state is None:
-                _state = CodexRateLimitState()
-    return _state
+"""Passive tracking of OpenAI Codex rate-limit window data from response headers.
+
+Codex (OpenAI) embeds rate-limit data directly in API response headers
+(``x-codex-primary-used-percent``, ``x-codex-primary-window-minutes``, etc.)
+rather than exposing a dedicated usage endpoint.  This module captures those
+headers from responses that headroom proxies and makes them available in
+``/stats`` and the dashboard.
+
+Header schema (parsed by codex-rs ``rate_limits.rs``):
+    x-codex-primary-used-percent      float 0-100
+    x-codex-primary-window-minutes    int   window size
+    x-codex-primary-reset-at          int   Unix timestamp (seconds)
+    x-codex-secondary-used-percent    float 0-100   (optional)
+    x-codex-secondary-window-minutes  int            (optional)
+    x-codex-secondary-reset-at        int            (optional)
+    x-codex-credits-has-credits       bool
+    x-codex-credits-unlimited         bool
+    x-codex-credits-balance           str   e.g. "$5.00"
+    x-codex-promo-message             str   server announcement
+    x-codex-limit-name                str   e.g. "gpt-5.2-codex-sonic"
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from threading import Lock
+
+from headroom.subscription.base import QuotaTracker
+
+
+@dataclass
+class CodexRateLimitWindow:
+    """Usage data for a single rolling rate-limit window."""
+
+    used_percent: float
+    window_minutes: int | None = None
+    resets_at: int | None = None  # Unix timestamp (seconds)
+
+    @property
+    def window_label(self) -> str:
+        if self.window_minutes is None:
+            return "unknown"
+        if self.window_minutes < 60:
+            return f"{self.window_minutes}m"
+        hours = self.window_minutes // 60
+        mins = self.window_minutes % 60
+        return f"{hours}h{mins:02d}m" if mins else f"{hours}h"
+
+    @property
+    def seconds_until_reset(self) -> int | None:
+        if self.resets_at is None:
+            return None
+        return max(0, self.resets_at - int(time.time()))
+
+    def to_dict(self) -> dict:
+        return {
+            "used_percent": self.used_percent,
+            "window_minutes": self.window_minutes,
+            "window_label": self.window_label,
+            "resets_at": self.resets_at,
+            "seconds_until_reset": self.seconds_until_reset,
+        }
+
+
+@dataclass
+class CodexCreditsSnapshot:
+    """OpenAI credits balance for Codex."""
+
+    has_credits: bool
+    unlimited: bool
+    balance: str | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "has_credits": self.has_credits,
+            "unlimited": self.unlimited,
+            "balance": self.balance,
+        }
+
+
+@dataclass
+class CodexRateLimitSnapshot:
+    """Full rate-limit snapshot parsed from a single Codex API response."""
+
+    limit_id: str = "codex"
+    limit_name: str | None = None
+    primary: CodexRateLimitWindow | None = None
+    secondary: CodexRateLimitWindow | None = None
+    credits: CodexCreditsSnapshot | None = None
+    promo_message: str | None = None
+    captured_at: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        return {
+            "limit_id": self.limit_id,
+            "limit_name": self.limit_name,
+            "primary": self.primary.to_dict() if self.primary else None,
+            "secondary": self.secondary.to_dict() if self.secondary else None,
+            "credits": self.credits.to_dict() if self.credits else None,
+            "promo_message": self.promo_message,
+            "captured_at": self.captured_at,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Header parsing helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_float(headers: dict[str, str], name: str) -> float | None:
+    raw = headers.get(name)
+    if raw is None:
+        return None
+    try:
+        v = float(raw)
+        return v if v == v else None  # NaN guard
+    except (ValueError, TypeError):
+        return None
+
+
+def _parse_int(headers: dict[str, str], name: str) -> int | None:
+    raw = headers.get(name)
+    if raw is None:
+        return None
+    try:
+        return int(raw)
+    except (ValueError, TypeError):
+        return None
+
+
+def _parse_bool(headers: dict[str, str], name: str) -> bool | None:
+    raw = headers.get(name)
+    if raw is None:
+        return None
+    if raw.lower() in ("true", "1"):
+        return True
+    if raw.lower() in ("false", "0"):
+        return False
+    return None
+
+
+def _parse_window(headers: dict[str, str], prefix: str, which: str) -> CodexRateLimitWindow | None:
+    used_pct = _parse_float(headers, f"{prefix}-{which}-used-percent")
+    if used_pct is None:
+        return None
+    return CodexRateLimitWindow(
+        used_percent=used_pct,
+        window_minutes=_parse_int(headers, f"{prefix}-{which}-window-minutes"),
+        resets_at=_parse_int(headers, f"{prefix}-{which}-reset-at"),
+    )
+
+
+def _parse_credits(headers: dict[str, str]) -> CodexCreditsSnapshot | None:
+    has_credits = _parse_bool(headers, "x-codex-credits-has-credits")
+    if has_credits is None:
+        return None
+    unlimited = _parse_bool(headers, "x-codex-credits-unlimited") or False
+    raw_balance = headers.get("x-codex-credits-balance", "").strip()
+    return CodexCreditsSnapshot(
+        has_credits=has_credits,
+        unlimited=unlimited,
+        balance=raw_balance or None,
+    )
+
+
+def parse_codex_rate_limits(headers: dict[str, str]) -> CodexRateLimitSnapshot | None:
+    """Parse a :class:`CodexRateLimitSnapshot` from a dict of HTTP response headers.
+
+    Returns ``None`` when no Codex rate-limit headers are present (e.g. the
+    response came from a non-Codex OpenAI endpoint or a cached reply).
+    """
+    prefix = "x-codex"
+    primary = _parse_window(headers, prefix, "primary")
+    secondary = _parse_window(headers, prefix, "secondary")
+    credits = _parse_credits(headers)
+    raw_promo = headers.get("x-codex-promo-message", "").strip()
+    promo = raw_promo or None
+    raw_limit_name = headers.get("x-codex-limit-name", "").strip()
+    limit_name = raw_limit_name or None
+
+    if primary is None and secondary is None and credits is None and promo is None:
+        return None  # Not a Codex response with rate-limit headers
+
+    return CodexRateLimitSnapshot(
+        limit_id="codex",
+        limit_name=limit_name,
+        primary=primary,
+        secondary=secondary,
+        credits=credits,
+        promo_message=promo,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Singleton state store
+# ---------------------------------------------------------------------------
+
+
+class CodexRateLimitState(QuotaTracker):
+    """Thread-safe store for the latest Codex rate-limit snapshot.
+
+    Implements :class:`~headroom.subscription.base.QuotaTracker` so it can
+    be registered with the :class:`~headroom.subscription.base.QuotaTrackerRegistry`.
+    This tracker is *passive* — it is updated by the OpenAI proxy handler
+    each time a response containing ``x-codex-*`` headers passes through
+    headroom, so :meth:`start` and :meth:`stop` are no-ops.
+    """
+
+    # QuotaTracker identity
+    key = "codex_rate_limits"
+    label = "OpenAI Codex"
+
+    def __init__(self) -> None:
+        self._lock = Lock()
+        self._latest: CodexRateLimitSnapshot | None = None
+
+    def update_from_headers(self, headers: dict[str, str]) -> None:
+        """Update state from a response header dict (no-op if no Codex headers)."""
+        snapshot = parse_codex_rate_limits(headers)
+        if snapshot is None:
+            return
+        with self._lock:
+            self._latest = snapshot
+
+    @property
+    def latest(self) -> CodexRateLimitSnapshot | None:
+        with self._lock:
+            return self._latest
+
+    def get_stats(self) -> dict | None:
+        snap = self.latest
+        return snap.to_dict() if snap is not None else None
+
+
+_state: CodexRateLimitState | None = None
+_state_lock = Lock()
+
+
+def get_codex_rate_limit_state() -> CodexRateLimitState:
+    """Return the process-global :class:`CodexRateLimitState` singleton."""
+    global _state
+    if _state is None:
+        with _state_lock:
+            if _state is None:
+                _state = CodexRateLimitState()
+    return _state
diff --git a/headroom/subscription/copilot_quota.py b/headroom/subscription/copilot_quota.py
index c7b03628fd0ccf34a1480721ac29747181b1a793..acdb2995448ee5de45f27c823d2dcd8157644a3f 100644
--- a/headroom/subscription/copilot_quota.py
+++ b/headroom/subscription/copilot_quota.py
@@ -1,366 +1,366 @@
-"""GitHub Copilot monthly quota tracking via the copilot_internal/user API.
-
-GitHub Copilot exposes per-category monthly quotas (chat, completions,
-premium_interactions) at ``GET https://api.github.com/copilot_internal/user``
-authenticated with a GitHub Bearer token.
-
-Token discovery order (first non-empty wins):
-    1. GITHUB_COPILOT_GITHUB_TOKEN
-    2. GITHUB_TOKEN
-    3. COPILOT_GITHUB_TOKEN
-    4. GITHUB_COPILOT_API_TOKEN
-
-The poll is triggered every ``poll_interval_s`` seconds (default 60) as long as
-a GitHub token is available.  No proxy traffic interception is needed — tokens
-come from the environment at headroom start-up.
-
-API response schema (relevant fields from ``/copilot_internal/user``):
-    login                  str        GitHub username
-    copilot_plan           str        "free" | "individual" | "business" | "enterprise"
-    access_type_sku        str        plan SKU string
-    quota_reset_date_utc   str        ISO-8601 date when monthly quota resets
-    quota_snapshots:
-        chat / completions / premium_interactions:
-            entitlement       int  total monthly allocation
-            remaining         int  remaining uses this month
-            quota_remaining   int  (alias for remaining)
-            percent_remaining float  0-100
-            overage_count     int  uses beyond entitlement
-            overage_permitted bool whether overage is allowed
-            unlimited         bool whether this category is unlimited
-            timestamp_utc     str  when the snapshot was recorded
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import os
-import time
-from dataclasses import dataclass, field
-from threading import Lock
-from typing import Any
-
-from headroom.subscription.base import QuotaTracker
-
-logger = logging.getLogger(__name__)
-
-_GITHUB_API_BASE = "https://api.github.com"
-_TOKEN_ENV_VARS = [
-    "GITHUB_COPILOT_GITHUB_TOKEN",
-    "GITHUB_TOKEN",
-    "COPILOT_GITHUB_TOKEN",
-    "GITHUB_COPILOT_API_TOKEN",
-]
-
-# Categories surfaced by the quota_snapshots endpoint
-QUOTA_CATEGORIES = ("chat", "completions", "premium_interactions")
-
-
-# ---------------------------------------------------------------------------
-# Data classes
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class CopilotQuotaCategory:
-    """Quota data for a single Copilot usage category."""
-
-    name: str
-    entitlement: int | None = None  # total monthly allocation
-    remaining: int | None = None  # remaining uses
-    percent_remaining: float | None = None  # 0-100
-    overage_count: int = 0  # uses beyond entitlement
-    overage_permitted: bool = False
-    unlimited: bool = False
-    timestamp_utc: str | None = None
-
-    @property
-    def used(self) -> int | None:
-        if self.entitlement is not None and self.remaining is not None:
-            return max(0, self.entitlement - self.remaining)
-        return None
-
-    @property
-    def used_percent(self) -> float | None:
-        if self.unlimited:
-            return 0.0
-        if self.percent_remaining is not None:
-            return max(0.0, 100.0 - self.percent_remaining)
-        if self.entitlement and self.entitlement > 0 and self.remaining is not None:
-            return 100.0 * (self.entitlement - self.remaining) / self.entitlement
-        return None
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "name": self.name,
-            "entitlement": self.entitlement,
-            "remaining": self.remaining,
-            "used": self.used,
-            "percent_remaining": self.percent_remaining,
-            "used_percent": self.used_percent,
-            "overage_count": self.overage_count,
-            "overage_permitted": self.overage_permitted,
-            "unlimited": self.unlimited,
-            "timestamp_utc": self.timestamp_utc,
-        }
-
-
-@dataclass
-class CopilotQuotaSnapshot:
-    """Full quota snapshot from one /copilot_internal/user response."""
-
-    login: str | None = None
-    copilot_plan: str | None = None
-    access_type_sku: str | None = None
-    quota_reset_date_utc: str | None = None
-    categories: dict[str, CopilotQuotaCategory] = field(default_factory=dict)
-    fetched_at: float = field(default_factory=time.time)
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "login": self.login,
-            "copilot_plan": self.copilot_plan,
-            "access_type_sku": self.access_type_sku,
-            "quota_reset_date_utc": self.quota_reset_date_utc,
-            "categories": {k: v.to_dict() for k, v in self.categories.items()},
-            "fetched_at": self.fetched_at,
-        }
-
-
-@dataclass
-class CopilotQuotaState:
-    """Thread-safe singleton state for Copilot quota tracking."""
-
-    latest: CopilotQuotaSnapshot | None = None
-    last_error: str | None = None
-    last_updated: float | None = None
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "latest": self.latest.to_dict() if self.latest else None,
-            "last_error": self.last_error,
-            "last_updated": self.last_updated,
-        }
-
-
-# ---------------------------------------------------------------------------
-# Parsing
-# ---------------------------------------------------------------------------
-
-
-def parse_copilot_quota(data: dict[str, Any]) -> CopilotQuotaSnapshot:
-    """Parse a /copilot_internal/user response into a ``CopilotQuotaSnapshot``."""
-    snapshot = CopilotQuotaSnapshot(
-        login=data.get("login"),
-        copilot_plan=data.get("copilot_plan"),
-        access_type_sku=data.get("access_type_sku"),
-        quota_reset_date_utc=data.get("quota_reset_date_utc") or data.get("quota_reset_date"),
-    )
-
-    raw_qs = data.get("quota_snapshots") or {}
-    for cat_name in QUOTA_CATEGORIES:
-        raw = raw_qs.get(cat_name)
-        if not raw:
-            continue
-        remaining = raw.get("remaining") or raw.get("quota_remaining")
-        cat = CopilotQuotaCategory(
-            name=cat_name,
-            entitlement=raw.get("entitlement"),
-            remaining=remaining,
-            percent_remaining=raw.get("percent_remaining"),
-            overage_count=raw.get("overage_count") or 0,
-            overage_permitted=bool(raw.get("overage_permitted")),
-            unlimited=bool(raw.get("unlimited")),
-            timestamp_utc=raw.get("timestamp_utc"),
-        )
-        snapshot.categories[cat_name] = cat
-
-    return snapshot
-
-
-# ---------------------------------------------------------------------------
-# Token discovery
-# ---------------------------------------------------------------------------
-
-
-def discover_github_token() -> str | None:
-    """Return the first GitHub token found from known environment variables."""
-    for var in _TOKEN_ENV_VARS:
-        val = os.environ.get(var, "").strip()
-        if val:
-            return val
-    return None
-
-
-# ---------------------------------------------------------------------------
-# Background tracker singleton
-# ---------------------------------------------------------------------------
-
-
-class _CopilotQuotaTracker(QuotaTracker):
-    """Singleton background poller for GitHub Copilot quota.
-
-    Implements :class:`~headroom.subscription.base.QuotaTracker` so it can be
-    registered with the :class:`~headroom.subscription.base.QuotaTrackerRegistry`.
-    Availability is gated on a GitHub token being present in the environment.
-    """
-
-    # QuotaTracker identity
-    key = "copilot_quota"
-    label = "GitHub Copilot"
-
-    def __init__(self, poll_interval_s: float = 60.0) -> None:
-        self._poll_interval_s = poll_interval_s
-        self._state = CopilotQuotaState()
-        self._lock = Lock()
-        self._stop_event: asyncio.Event | None = None
-        self._task: asyncio.Task | None = None  # type: ignore[type-arg]
-
-    # ------------------------------------------------------------------
-    # QuotaTracker interface
-    # ------------------------------------------------------------------
-
-    def is_available(self) -> bool:
-        """Returns ``True`` when a GitHub token is available in the environment."""
-        return discover_github_token() is not None
-
-    def get_stats(self) -> dict[str, Any] | None:
-        """Return the latest quota state dict, or ``None`` if no data yet."""
-        data = self.state
-        if not data.get("latest"):
-            return None
-        return data
-
-    # ------------------------------------------------------------------
-    # Lifecycle
-    # ------------------------------------------------------------------
-
-    async def start(self) -> None:
-        """Start the background polling loop."""
-        if self._task is not None and not self._task.done():
-            return
-        self._stop_event = asyncio.Event()
-        self._task = asyncio.create_task(self._poll_loop())
-
-    async def stop(self) -> None:
-        """Stop the polling loop."""
-        if self._stop_event:
-            self._stop_event.set()
-        if self._task:
-            try:
-                await asyncio.wait_for(self._task, timeout=5.0)
-            except (asyncio.TimeoutError, asyncio.CancelledError):
-                # Mirror SubscriptionTracker.stop(): on timeout or outer
-                # cancellation, cancel the underlying poll task. Without
-                # this, a wedged poll task would leak past ``stop()``.
-                self._task.cancel()
-
-    # ------------------------------------------------------------------
-    # State
-    # ------------------------------------------------------------------
-
-    @property
-    def state(self) -> dict[str, Any]:
-        with self._lock:
-            return self._state.to_dict()
-
-    # ------------------------------------------------------------------
-    # Poll loop
-    # ------------------------------------------------------------------
-
-    async def _poll_loop(self) -> None:
-        assert self._stop_event is not None
-        while not self._stop_event.is_set():
-            try:
-                await self._maybe_poll()
-            except Exception as exc:
-                logger.warning("Copilot quota poll error: %s", exc)
-            try:
-                # NOTE: do NOT wrap in asyncio.shield() — shield prevents the
-                # inner Event.wait() from being cancelled when wait_for times
-                # out, leaking one Task per poll interval. See the matching
-                # note in headroom/subscription/tracker.py:_poll_loop.
-                await asyncio.wait_for(
-                    self._stop_event.wait(),
-                    timeout=self._poll_interval_s,
-                )
-                break  # stop event was set
-            except asyncio.TimeoutError:
-                pass  # normal: poll interval elapsed
-
-    async def _maybe_poll(self) -> None:
-        token = discover_github_token()
-        if not token:
-            return
-
-        try:
-            import aiohttp
-        except ImportError:
-            logger.debug("aiohttp not available; skipping Copilot quota poll")
-            return
-
-        url = f"{_GITHUB_API_BASE}/copilot_internal/user"
-        headers = {
-            "Authorization": f"Bearer {token}",
-            "Accept": "application/json",
-            "X-GitHub-Api-Version": "2022-11-28",
-        }
-
-        try:
-            async with aiohttp.ClientSession() as session:
-                async with session.get(
-                    url, headers=headers, timeout=aiohttp.ClientTimeout(total=10)
-                ) as resp:
-                    if resp.status == 401:
-                        with self._lock:
-                            self._state.last_error = "unauthorized — check GITHUB_TOKEN"
-                        return
-                    if resp.status == 404:
-                        # API-key-only account or endpoint not available
-                        with self._lock:
-                            self._state.last_error = "endpoint not found (non-Copilot account?)"
-                        return
-                    if not resp.ok:
-                        with self._lock:
-                            self._state.last_error = f"HTTP {resp.status}"
-                        return
-
-                    data = await resp.json()
-        except Exception as exc:
-            with self._lock:
-                self._state.last_error = str(exc)
-            logger.debug("Copilot quota fetch failed: %s", exc)
-            return
-
-        try:
-            snapshot = parse_copilot_quota(data)
-        except Exception as exc:
-            with self._lock:
-                self._state.last_error = f"parse error: {exc}"
-            return
-
-        with self._lock:
-            self._state.latest = snapshot
-            self._state.last_error = None
-            self._state.last_updated = time.time()
-
-        logger.debug(
-            "Copilot quota polled: plan=%s categories=%s",
-            snapshot.copilot_plan,
-            list(snapshot.categories.keys()),
-        )
-
-
-_singleton_lock = Lock()
-_singleton: _CopilotQuotaTracker | None = None
-
-
-def get_copilot_quota_tracker() -> _CopilotQuotaTracker:
-    """Return the global ``_CopilotQuotaTracker`` singleton."""
-    global _singleton
-    if _singleton is None:
-        with _singleton_lock:
-            if _singleton is None:
-                _singleton = _CopilotQuotaTracker()
-    return _singleton
+"""GitHub Copilot monthly quota tracking via the copilot_internal/user API.
+
+GitHub Copilot exposes per-category monthly quotas (chat, completions,
+premium_interactions) at ``GET https://api.github.com/copilot_internal/user``
+authenticated with a GitHub Bearer token.
+
+Token discovery order (first non-empty wins):
+    1. GITHUB_COPILOT_GITHUB_TOKEN
+    2. GITHUB_TOKEN
+    3. COPILOT_GITHUB_TOKEN
+    4. GITHUB_COPILOT_API_TOKEN
+
+The poll is triggered every ``poll_interval_s`` seconds (default 60) as long as
+a GitHub token is available.  No proxy traffic interception is needed — tokens
+come from the environment at headroom start-up.
+
+API response schema (relevant fields from ``/copilot_internal/user``):
+    login                  str        GitHub username
+    copilot_plan           str        "free" | "individual" | "business" | "enterprise"
+    access_type_sku        str        plan SKU string
+    quota_reset_date_utc   str        ISO-8601 date when monthly quota resets
+    quota_snapshots:
+        chat / completions / premium_interactions:
+            entitlement       int  total monthly allocation
+            remaining         int  remaining uses this month
+            quota_remaining   int  (alias for remaining)
+            percent_remaining float  0-100
+            overage_count     int  uses beyond entitlement
+            overage_permitted bool whether overage is allowed
+            unlimited         bool whether this category is unlimited
+            timestamp_utc     str  when the snapshot was recorded
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Any
+
+from headroom.subscription.base import QuotaTracker
+
+logger = logging.getLogger(__name__)
+
+_GITHUB_API_BASE = "https://api.github.com"
+_TOKEN_ENV_VARS = [
+    "GITHUB_COPILOT_GITHUB_TOKEN",
+    "GITHUB_TOKEN",
+    "COPILOT_GITHUB_TOKEN",
+    "GITHUB_COPILOT_API_TOKEN",
+]
+
+# Categories surfaced by the quota_snapshots endpoint
+QUOTA_CATEGORIES = ("chat", "completions", "premium_interactions")
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CopilotQuotaCategory:
+    """Quota data for a single Copilot usage category."""
+
+    name: str
+    entitlement: int | None = None  # total monthly allocation
+    remaining: int | None = None  # remaining uses
+    percent_remaining: float | None = None  # 0-100
+    overage_count: int = 0  # uses beyond entitlement
+    overage_permitted: bool = False
+    unlimited: bool = False
+    timestamp_utc: str | None = None
+
+    @property
+    def used(self) -> int | None:
+        if self.entitlement is not None and self.remaining is not None:
+            return max(0, self.entitlement - self.remaining)
+        return None
+
+    @property
+    def used_percent(self) -> float | None:
+        if self.unlimited:
+            return 0.0
+        if self.percent_remaining is not None:
+            return max(0.0, 100.0 - self.percent_remaining)
+        if self.entitlement and self.entitlement > 0 and self.remaining is not None:
+            return 100.0 * (self.entitlement - self.remaining) / self.entitlement
+        return None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "entitlement": self.entitlement,
+            "remaining": self.remaining,
+            "used": self.used,
+            "percent_remaining": self.percent_remaining,
+            "used_percent": self.used_percent,
+            "overage_count": self.overage_count,
+            "overage_permitted": self.overage_permitted,
+            "unlimited": self.unlimited,
+            "timestamp_utc": self.timestamp_utc,
+        }
+
+
+@dataclass
+class CopilotQuotaSnapshot:
+    """Full quota snapshot from one /copilot_internal/user response."""
+
+    login: str | None = None
+    copilot_plan: str | None = None
+    access_type_sku: str | None = None
+    quota_reset_date_utc: str | None = None
+    categories: dict[str, CopilotQuotaCategory] = field(default_factory=dict)
+    fetched_at: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "login": self.login,
+            "copilot_plan": self.copilot_plan,
+            "access_type_sku": self.access_type_sku,
+            "quota_reset_date_utc": self.quota_reset_date_utc,
+            "categories": {k: v.to_dict() for k, v in self.categories.items()},
+            "fetched_at": self.fetched_at,
+        }
+
+
+@dataclass
+class CopilotQuotaState:
+    """Thread-safe singleton state for Copilot quota tracking."""
+
+    latest: CopilotQuotaSnapshot | None = None
+    last_error: str | None = None
+    last_updated: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "latest": self.latest.to_dict() if self.latest else None,
+            "last_error": self.last_error,
+            "last_updated": self.last_updated,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_copilot_quota(data: dict[str, Any]) -> CopilotQuotaSnapshot:
+    """Parse a /copilot_internal/user response into a ``CopilotQuotaSnapshot``."""
+    snapshot = CopilotQuotaSnapshot(
+        login=data.get("login"),
+        copilot_plan=data.get("copilot_plan"),
+        access_type_sku=data.get("access_type_sku"),
+        quota_reset_date_utc=data.get("quota_reset_date_utc") or data.get("quota_reset_date"),
+    )
+
+    raw_qs = data.get("quota_snapshots") or {}
+    for cat_name in QUOTA_CATEGORIES:
+        raw = raw_qs.get(cat_name)
+        if not raw:
+            continue
+        remaining = raw.get("remaining") or raw.get("quota_remaining")
+        cat = CopilotQuotaCategory(
+            name=cat_name,
+            entitlement=raw.get("entitlement"),
+            remaining=remaining,
+            percent_remaining=raw.get("percent_remaining"),
+            overage_count=raw.get("overage_count") or 0,
+            overage_permitted=bool(raw.get("overage_permitted")),
+            unlimited=bool(raw.get("unlimited")),
+            timestamp_utc=raw.get("timestamp_utc"),
+        )
+        snapshot.categories[cat_name] = cat
+
+    return snapshot
+
+
+# ---------------------------------------------------------------------------
+# Token discovery
+# ---------------------------------------------------------------------------
+
+
+def discover_github_token() -> str | None:
+    """Return the first GitHub token found from known environment variables."""
+    for var in _TOKEN_ENV_VARS:
+        val = os.environ.get(var, "").strip()
+        if val:
+            return val
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Background tracker singleton
+# ---------------------------------------------------------------------------
+
+
+class _CopilotQuotaTracker(QuotaTracker):
+    """Singleton background poller for GitHub Copilot quota.
+
+    Implements :class:`~headroom.subscription.base.QuotaTracker` so it can be
+    registered with the :class:`~headroom.subscription.base.QuotaTrackerRegistry`.
+    Availability is gated on a GitHub token being present in the environment.
+    """
+
+    # QuotaTracker identity
+    key = "copilot_quota"
+    label = "GitHub Copilot"
+
+    def __init__(self, poll_interval_s: float = 60.0) -> None:
+        self._poll_interval_s = poll_interval_s
+        self._state = CopilotQuotaState()
+        self._lock = Lock()
+        self._stop_event: asyncio.Event | None = None
+        self._task: asyncio.Task | None = None  # type: ignore[type-arg]
+
+    # ------------------------------------------------------------------
+    # QuotaTracker interface
+    # ------------------------------------------------------------------
+
+    def is_available(self) -> bool:
+        """Returns ``True`` when a GitHub token is available in the environment."""
+        return discover_github_token() is not None
+
+    def get_stats(self) -> dict[str, Any] | None:
+        """Return the latest quota state dict, or ``None`` if no data yet."""
+        data = self.state
+        if not data.get("latest"):
+            return None
+        return data
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self) -> None:
+        """Start the background polling loop."""
+        if self._task is not None and not self._task.done():
+            return
+        self._stop_event = asyncio.Event()
+        self._task = asyncio.create_task(self._poll_loop())
+
+    async def stop(self) -> None:
+        """Stop the polling loop."""
+        if self._stop_event:
+            self._stop_event.set()
+        if self._task:
+            try:
+                await asyncio.wait_for(self._task, timeout=5.0)
+            except (asyncio.TimeoutError, asyncio.CancelledError):
+                # Mirror SubscriptionTracker.stop(): on timeout or outer
+                # cancellation, cancel the underlying poll task. Without
+                # this, a wedged poll task would leak past ``stop()``.
+                self._task.cancel()
+
+    # ------------------------------------------------------------------
+    # State
+    # ------------------------------------------------------------------
+
+    @property
+    def state(self) -> dict[str, Any]:
+        with self._lock:
+            return self._state.to_dict()
+
+    # ------------------------------------------------------------------
+    # Poll loop
+    # ------------------------------------------------------------------
+
+    async def _poll_loop(self) -> None:
+        assert self._stop_event is not None
+        while not self._stop_event.is_set():
+            try:
+                await self._maybe_poll()
+            except Exception as exc:
+                logger.warning("Copilot quota poll error: %s", exc)
+            try:
+                # NOTE: do NOT wrap in asyncio.shield() — shield prevents the
+                # inner Event.wait() from being cancelled when wait_for times
+                # out, leaking one Task per poll interval. See the matching
+                # note in headroom/subscription/tracker.py:_poll_loop.
+                await asyncio.wait_for(
+                    self._stop_event.wait(),
+                    timeout=self._poll_interval_s,
+                )
+                break  # stop event was set
+            except asyncio.TimeoutError:
+                pass  # normal: poll interval elapsed
+
+    async def _maybe_poll(self) -> None:
+        token = discover_github_token()
+        if not token:
+            return
+
+        try:
+            import aiohttp
+        except ImportError:
+            logger.debug("aiohttp not available; skipping Copilot quota poll")
+            return
+
+        url = f"{_GITHUB_API_BASE}/copilot_internal/user"
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    url, headers=headers, timeout=aiohttp.ClientTimeout(total=10)
+                ) as resp:
+                    if resp.status == 401:
+                        with self._lock:
+                            self._state.last_error = "unauthorized — check GITHUB_TOKEN"
+                        return
+                    if resp.status == 404:
+                        # API-key-only account or endpoint not available
+                        with self._lock:
+                            self._state.last_error = "endpoint not found (non-Copilot account?)"
+                        return
+                    if not resp.ok:
+                        with self._lock:
+                            self._state.last_error = f"HTTP {resp.status}"
+                        return
+
+                    data = await resp.json()
+        except Exception as exc:
+            with self._lock:
+                self._state.last_error = str(exc)
+            logger.debug("Copilot quota fetch failed: %s", exc)
+            return
+
+        try:
+            snapshot = parse_copilot_quota(data)
+        except Exception as exc:
+            with self._lock:
+                self._state.last_error = f"parse error: {exc}"
+            return
+
+        with self._lock:
+            self._state.latest = snapshot
+            self._state.last_error = None
+            self._state.last_updated = time.time()
+
+        logger.debug(
+            "Copilot quota polled: plan=%s categories=%s",
+            snapshot.copilot_plan,
+            list(snapshot.categories.keys()),
+        )
+
+
+_singleton_lock = Lock()
+_singleton: _CopilotQuotaTracker | None = None
+
+
+def get_copilot_quota_tracker() -> _CopilotQuotaTracker:
+    """Return the global ``_CopilotQuotaTracker`` singleton."""
+    global _singleton
+    if _singleton is None:
+        with _singleton_lock:
+            if _singleton is None:
+                _singleton = _CopilotQuotaTracker()
+    return _singleton
diff --git a/headroom/subscription/models.py b/headroom/subscription/models.py
index c621f4df05edd7bfae552d8068630cd067bcd833..136a10cda84ac1e4d69e479b2a6ee21d8c5b816f 100644
--- a/headroom/subscription/models.py
+++ b/headroom/subscription/models.py
@@ -1,395 +1,395 @@
-"""Data models for Anthropic subscription window tracking.
-
-Mirrors the Anthropic OAuth usage API response exactly, including:
-  - five_hour / seven_day rolling windows (utilization + reset times)
-  - seven_day_opus / seven_day_sonnet per-model 7-day windows
-  - extra_usage overage block (credits stored in cents by Anthropic)
-  - Headroom contribution: tokens conserved by compression, rtk, cache
-  - Window discrepancy detection (surge pricing, cache-miss anomalies)
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from typing import Any
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _utc_now() -> datetime:
-    return datetime.now(timezone.utc)
-
-
-def _to_utc_iso(dt: datetime) -> str:
-    return dt.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
-
-
-def _parse_timestamp(value: Any) -> datetime | None:
-    if not isinstance(value, str) or not value:
-        return None
-    normalized = value.replace("Z", "+00:00")
-    try:
-        dt = datetime.fromisoformat(normalized)
-    except ValueError:
-        return None
-    if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=timezone.utc)
-    return dt.astimezone(timezone.utc)
-
-
-def _safe_float(value: Any) -> float | None:
-    if value is None:
-        return None
-    try:
-        return float(value)
-    except (TypeError, ValueError):
-        return None
-
-
-def _safe_int(value: Any) -> int | None:
-    if value is None:
-        return None
-    try:
-        return int(value)
-    except (TypeError, ValueError):
-        return None
-
-
-# ---------------------------------------------------------------------------
-# Rate-limit window (five_hour / seven_day / seven_day_opus / seven_day_sonnet)
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class RateLimitWindow:
-    """A single rolling rate-limit window returned by the Anthropic usage API.
-
-    ``used`` and ``limit`` are in Anthropic's internal token-equivalent units
-    (not raw tokens; Anthropic weights tokens differently per model family).
-    ``utilization_pct`` is the authoritative 0–100 % figure from the API.
-    """
-
-    used: int = 0
-    limit: int = 0
-    utilization_pct: float = 0.0
-    resets_at: datetime | None = None
-
-    @classmethod
-    def from_api_dict(cls, data: dict[str, Any]) -> RateLimitWindow:
-        return cls(
-            used=int(data.get("used") or 0),
-            limit=int(data.get("limit") or 0),
-            utilization_pct=float(data.get("utilization") or 0.0),
-            resets_at=_parse_timestamp(data.get("resets_at")),
-        )
-
-    def seconds_to_reset(self, *, now: datetime | None = None) -> float | None:
-        if self.resets_at is None:
-            return None
-        return max((self.resets_at - (now or _utc_now())).total_seconds(), 0.0)
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "used": self.used,
-            "limit": self.limit,
-            "utilization_pct": round(self.utilization_pct, 2),
-            "resets_at": _to_utc_iso(self.resets_at) if self.resets_at else None,
-            "seconds_to_reset": self.seconds_to_reset(),
-        }
-
-
-# ---------------------------------------------------------------------------
-# Extra-usage / overage block
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class ExtraUsage:
-    """Overage / extra-usage block from the Anthropic usage API.
-
-    ``monthly_limit_cents`` and ``used_credits_cents`` are in US cents as
-    returned by the API (divide by 100 for USD).
-    """
-
-    is_enabled: bool = False
-    monthly_limit_cents: int | None = None
-    used_credits_cents: int | None = None
-    utilization_pct: float | None = None
-
-    @classmethod
-    def from_api_dict(cls, data: dict[str, Any]) -> ExtraUsage:
-        return cls(
-            is_enabled=bool(data.get("is_enabled", False)),
-            monthly_limit_cents=_safe_int(data.get("monthly_limit")),
-            used_credits_cents=_safe_int(data.get("used_credits")),
-            utilization_pct=_safe_float(data.get("utilization")),
-        )
-
-    @property
-    def monthly_limit_usd(self) -> float | None:
-        if self.monthly_limit_cents is None:
-            return None
-        return self.monthly_limit_cents / 100.0
-
-    @property
-    def used_credits_usd(self) -> float | None:
-        if self.used_credits_cents is None:
-            return None
-        return self.used_credits_cents / 100.0
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "is_enabled": self.is_enabled,
-            "monthly_limit_usd": round(self.monthly_limit_usd, 2)
-            if self.monthly_limit_usd is not None
-            else None,
-            "used_credits_usd": round(self.used_credits_usd, 4)
-            if self.used_credits_usd is not None
-            else None,
-            "utilization_pct": round(self.utilization_pct, 2)
-            if self.utilization_pct is not None
-            else None,
-        }
-
-
-# ---------------------------------------------------------------------------
-# Full snapshot from one API poll
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class SubscriptionSnapshot:
-    """One complete poll of GET /api/oauth/usage."""
-
-    five_hour: RateLimitWindow = field(default_factory=RateLimitWindow)
-    seven_day: RateLimitWindow = field(default_factory=RateLimitWindow)
-    seven_day_opus: RateLimitWindow | None = None
-    seven_day_sonnet: RateLimitWindow | None = None
-    extra_usage: ExtraUsage = field(default_factory=ExtraUsage)
-    polled_at: datetime = field(default_factory=_utc_now)
-    token_prefix: str = ""
-    """First 8 chars of the OAuth token (for multi-account detection)."""
-
-    @classmethod
-    def from_api_response(cls, data: dict[str, Any], *, token: str = "") -> SubscriptionSnapshot:
-        snap = cls(token_prefix=token[:8] if token else "")
-        if "five_hour" in data and data["five_hour"]:
-            snap.five_hour = RateLimitWindow.from_api_dict(data["five_hour"])
-        if "seven_day" in data and data["seven_day"]:
-            snap.seven_day = RateLimitWindow.from_api_dict(data["seven_day"])
-        if "seven_day_opus" in data and data["seven_day_opus"]:
-            snap.seven_day_opus = RateLimitWindow.from_api_dict(data["seven_day_opus"])
-        if "seven_day_sonnet" in data and data["seven_day_sonnet"]:
-            snap.seven_day_sonnet = RateLimitWindow.from_api_dict(data["seven_day_sonnet"])
-        if "extra_usage" in data and data["extra_usage"]:
-            snap.extra_usage = ExtraUsage.from_api_dict(data["extra_usage"])
-        return snap
-
-    def to_dict(self) -> dict[str, Any]:
-        d: dict[str, Any] = {
-            "five_hour": self.five_hour.to_dict(),
-            "seven_day": self.seven_day.to_dict(),
-            "extra_usage": self.extra_usage.to_dict(),
-            "polled_at": _to_utc_iso(self.polled_at),
-            "token_prefix": self.token_prefix,
-        }
-        if self.seven_day_opus:
-            d["seven_day_opus"] = self.seven_day_opus.to_dict()
-        if self.seven_day_sonnet:
-            d["seven_day_sonnet"] = self.seven_day_sonnet.to_dict()
-        return d
-
-
-# ---------------------------------------------------------------------------
-# Transcript-based window token breakdown
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class WindowTokens:
-    """Token breakdown from Claude transcript JSONL files for one time window."""
-
-    input: int = 0
-    output: int = 0
-    cache_reads: int = 0
-    cache_writes_5m: int = 0
-    cache_writes_1h: int = 0
-    cache_writes_total: int = 0
-    by_model: dict[str, dict[str, int]] = field(default_factory=dict)
-    weighted_token_equivalent: float = 0.0
-    """Sonnet-normalised weighted total (opus×2, sonnet×1, haiku×0.5)."""
-
-    def total_raw(self) -> int:
-        return self.input + self.output + self.cache_reads + self.cache_writes_total
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "input": self.input,
-            "output": self.output,
-            "cache_reads": self.cache_reads,
-            "cache_writes_5m": self.cache_writes_5m,
-            "cache_writes_1h": self.cache_writes_1h,
-            "cache_writes_total": self.cache_writes_total,
-            "total_raw": self.total_raw(),
-            "weighted_token_equivalent": round(self.weighted_token_equivalent, 1),
-            "by_model": self.by_model,
-        }
-
-
-# ---------------------------------------------------------------------------
-# Headroom contribution estimate
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class HeadroomContribution:
-    """Tokens conserved within the current 5h window by Headroom's layers.
-
-    These are cumulative counters reset when the 5h window rolls over.
-    """
-
-    tokens_submitted: int = 0
-    """Raw input tokens actually forwarded to Anthropic by the proxy."""
-
-    tokens_saved_compression: int = 0
-    """Input tokens removed by proxy compression."""
-
-    tokens_saved_rtk: int = 0
-    """Tokens avoided by CLI filtering (rtk) before reaching context."""
-
-    tokens_saved_cache_reads: int = 0
-    """Input tokens served from Anthropic prefix-cache (discounted reads)."""
-
-    compression_savings_usd: float = 0.0
-    cache_savings_usd: float = 0.0
-
-    def total_saved(self) -> int:
-        return self.tokens_saved_compression + self.tokens_saved_rtk + self.tokens_saved_cache_reads
-
-    def total_savings_usd(self) -> float:
-        return self.compression_savings_usd + self.cache_savings_usd
-
-    def raw_without_headroom(self) -> int:
-        return self.tokens_submitted + self.tokens_saved_compression + self.tokens_saved_rtk
-
-    def efficiency_pct(self) -> float:
-        raw = self.raw_without_headroom()
-        if raw == 0:
-            return 0.0
-        return round(self.total_saved() / raw * 100, 1)
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "tokens_submitted": self.tokens_submitted,
-            "tokens_saved": {
-                "compression": self.tokens_saved_compression,
-                "rtk": self.tokens_saved_rtk,
-                "cache_reads": self.tokens_saved_cache_reads,
-                "total": self.total_saved(),
-            },
-            "raw_without_headroom": self.raw_without_headroom(),
-            "efficiency_pct": self.efficiency_pct(),
-            "savings_usd": {
-                "compression": round(self.compression_savings_usd, 4),
-                "cache": round(self.cache_savings_usd, 4),
-                "total": round(self.total_savings_usd(), 4),
-            },
-        }
-
-
-# ---------------------------------------------------------------------------
-# Anomaly / discrepancy record
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class WindowDiscrepancy:
-    """Detected anomaly between expected and API-reported utilization."""
-
-    kind: str
-    """'surge_pricing' | 'cache_miss' | 'none'"""
-
-    description: str = ""
-    severity: str = "info"
-    """'info' | 'warning' | 'alert'"""
-
-    expected_utilization_pct: float | None = None
-    actual_utilization_pct: float | None = None
-    delta_pct: float | None = None
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "kind": self.kind,
-            "description": self.description,
-            "severity": self.severity,
-            "expected_utilization_pct": self.expected_utilization_pct,
-            "actual_utilization_pct": self.actual_utilization_pct,
-            "delta_pct": self.delta_pct,
-        }
-
-
-# ---------------------------------------------------------------------------
-# Full tracker state
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class SubscriptionState:
-    """Persistent state for the subscription tracker."""
-
-    latest: SubscriptionSnapshot | None = None
-    window_tokens: WindowTokens | None = None
-    """Transcript-derived token breakdown for the current 5h window."""
-
-    contribution: HeadroomContribution = field(default_factory=HeadroomContribution)
-    discrepancies: list[WindowDiscrepancy] = field(default_factory=list)
-    history: list[SubscriptionSnapshot] = field(default_factory=list)
-
-    poll_count: int = 0
-    poll_errors: int = 0
-    last_error: str | None = None
-    last_active_at: datetime | None = None
-
-    _MAX_HISTORY: int = field(default=100, init=False, repr=False)
-    _MAX_DISCREPANCIES: int = field(default=20, init=False, repr=False)
-
-    def add_snapshot(self, snapshot: SubscriptionSnapshot) -> None:
-        self.latest = snapshot
-        self.history.append(snapshot)
-        if len(self.history) > self._MAX_HISTORY:
-            self.history = self.history[-self._MAX_HISTORY :]
-        self.poll_count += 1
-
-    def mark_error(self, msg: str) -> None:
-        self.poll_errors += 1
-        self.last_error = msg
-
-    def add_discrepancy(self, d: WindowDiscrepancy) -> None:
-        self.discrepancies.append(d)
-        if len(self.discrepancies) > self._MAX_DISCREPANCIES:
-            self.discrepancies = self.discrepancies[-self._MAX_DISCREPANCIES :]
-
-    def is_active(self, *, active_window_s: float = 60.0) -> bool:
-        if self.last_active_at is None:
-            return False
-        return (_utc_now() - self.last_active_at).total_seconds() <= active_window_s
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "latest": self.latest.to_dict() if self.latest else None,
-            "window_tokens": self.window_tokens.to_dict() if self.window_tokens else None,
-            "contribution": self.contribution.to_dict(),
-            "discrepancies": [d.to_dict() for d in self.discrepancies[-5:]],
-            "poll_count": self.poll_count,
-            "poll_errors": self.poll_errors,
-            "last_error": self.last_error,
-            "last_active_at": _to_utc_iso(self.last_active_at) if self.last_active_at else None,
-        }
-
-    def to_persist_dict(self) -> dict[str, Any]:
-        d = self.to_dict()
-        d["history"] = [s.to_dict() for s in self.history[-20:]]
-        return d
+"""Data models for Anthropic subscription window tracking.
+
+Mirrors the Anthropic OAuth usage API response exactly, including:
+  - five_hour / seven_day rolling windows (utilization + reset times)
+  - seven_day_opus / seven_day_sonnet per-model 7-day windows
+  - extra_usage overage block (credits stored in cents by Anthropic)
+  - Headroom contribution: tokens conserved by compression, rtk, cache
+  - Window discrepancy detection (surge pricing, cache-miss anomalies)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _to_utc_iso(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _parse_timestamp(value: Any) -> datetime | None:
+    if not isinstance(value, str) or not value:
+        return None
+    normalized = value.replace("Z", "+00:00")
+    try:
+        dt = datetime.fromisoformat(normalized)
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def _safe_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _safe_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Rate-limit window (five_hour / seven_day / seven_day_opus / seven_day_sonnet)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RateLimitWindow:
+    """A single rolling rate-limit window returned by the Anthropic usage API.
+
+    ``used`` and ``limit`` are in Anthropic's internal token-equivalent units
+    (not raw tokens; Anthropic weights tokens differently per model family).
+    ``utilization_pct`` is the authoritative 0–100 % figure from the API.
+    """
+
+    used: int = 0
+    limit: int = 0
+    utilization_pct: float = 0.0
+    resets_at: datetime | None = None
+
+    @classmethod
+    def from_api_dict(cls, data: dict[str, Any]) -> RateLimitWindow:
+        return cls(
+            used=int(data.get("used") or 0),
+            limit=int(data.get("limit") or 0),
+            utilization_pct=float(data.get("utilization") or 0.0),
+            resets_at=_parse_timestamp(data.get("resets_at")),
+        )
+
+    def seconds_to_reset(self, *, now: datetime | None = None) -> float | None:
+        if self.resets_at is None:
+            return None
+        return max((self.resets_at - (now or _utc_now())).total_seconds(), 0.0)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "used": self.used,
+            "limit": self.limit,
+            "utilization_pct": round(self.utilization_pct, 2),
+            "resets_at": _to_utc_iso(self.resets_at) if self.resets_at else None,
+            "seconds_to_reset": self.seconds_to_reset(),
+        }
+
+
+# ---------------------------------------------------------------------------
+# Extra-usage / overage block
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ExtraUsage:
+    """Overage / extra-usage block from the Anthropic usage API.
+
+    ``monthly_limit_cents`` and ``used_credits_cents`` are in US cents as
+    returned by the API (divide by 100 for USD).
+    """
+
+    is_enabled: bool = False
+    monthly_limit_cents: int | None = None
+    used_credits_cents: int | None = None
+    utilization_pct: float | None = None
+
+    @classmethod
+    def from_api_dict(cls, data: dict[str, Any]) -> ExtraUsage:
+        return cls(
+            is_enabled=bool(data.get("is_enabled", False)),
+            monthly_limit_cents=_safe_int(data.get("monthly_limit")),
+            used_credits_cents=_safe_int(data.get("used_credits")),
+            utilization_pct=_safe_float(data.get("utilization")),
+        )
+
+    @property
+    def monthly_limit_usd(self) -> float | None:
+        if self.monthly_limit_cents is None:
+            return None
+        return self.monthly_limit_cents / 100.0
+
+    @property
+    def used_credits_usd(self) -> float | None:
+        if self.used_credits_cents is None:
+            return None
+        return self.used_credits_cents / 100.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "is_enabled": self.is_enabled,
+            "monthly_limit_usd": round(self.monthly_limit_usd, 2)
+            if self.monthly_limit_usd is not None
+            else None,
+            "used_credits_usd": round(self.used_credits_usd, 4)
+            if self.used_credits_usd is not None
+            else None,
+            "utilization_pct": round(self.utilization_pct, 2)
+            if self.utilization_pct is not None
+            else None,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Full snapshot from one API poll
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SubscriptionSnapshot:
+    """One complete poll of GET /api/oauth/usage."""
+
+    five_hour: RateLimitWindow = field(default_factory=RateLimitWindow)
+    seven_day: RateLimitWindow = field(default_factory=RateLimitWindow)
+    seven_day_opus: RateLimitWindow | None = None
+    seven_day_sonnet: RateLimitWindow | None = None
+    extra_usage: ExtraUsage = field(default_factory=ExtraUsage)
+    polled_at: datetime = field(default_factory=_utc_now)
+    token_prefix: str = ""
+    """First 8 chars of the OAuth token (for multi-account detection)."""
+
+    @classmethod
+    def from_api_response(cls, data: dict[str, Any], *, token: str = "") -> SubscriptionSnapshot:
+        snap = cls(token_prefix=token[:8] if token else "")
+        if "five_hour" in data and data["five_hour"]:
+            snap.five_hour = RateLimitWindow.from_api_dict(data["five_hour"])
+        if "seven_day" in data and data["seven_day"]:
+            snap.seven_day = RateLimitWindow.from_api_dict(data["seven_day"])
+        if "seven_day_opus" in data and data["seven_day_opus"]:
+            snap.seven_day_opus = RateLimitWindow.from_api_dict(data["seven_day_opus"])
+        if "seven_day_sonnet" in data and data["seven_day_sonnet"]:
+            snap.seven_day_sonnet = RateLimitWindow.from_api_dict(data["seven_day_sonnet"])
+        if "extra_usage" in data and data["extra_usage"]:
+            snap.extra_usage = ExtraUsage.from_api_dict(data["extra_usage"])
+        return snap
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "five_hour": self.five_hour.to_dict(),
+            "seven_day": self.seven_day.to_dict(),
+            "extra_usage": self.extra_usage.to_dict(),
+            "polled_at": _to_utc_iso(self.polled_at),
+            "token_prefix": self.token_prefix,
+        }
+        if self.seven_day_opus:
+            d["seven_day_opus"] = self.seven_day_opus.to_dict()
+        if self.seven_day_sonnet:
+            d["seven_day_sonnet"] = self.seven_day_sonnet.to_dict()
+        return d
+
+
+# ---------------------------------------------------------------------------
+# Transcript-based window token breakdown
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class WindowTokens:
+    """Token breakdown from Claude transcript JSONL files for one time window."""
+
+    input: int = 0
+    output: int = 0
+    cache_reads: int = 0
+    cache_writes_5m: int = 0
+    cache_writes_1h: int = 0
+    cache_writes_total: int = 0
+    by_model: dict[str, dict[str, int]] = field(default_factory=dict)
+    weighted_token_equivalent: float = 0.0
+    """Sonnet-normalised weighted total (opus×2, sonnet×1, haiku×0.5)."""
+
+    def total_raw(self) -> int:
+        return self.input + self.output + self.cache_reads + self.cache_writes_total
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "input": self.input,
+            "output": self.output,
+            "cache_reads": self.cache_reads,
+            "cache_writes_5m": self.cache_writes_5m,
+            "cache_writes_1h": self.cache_writes_1h,
+            "cache_writes_total": self.cache_writes_total,
+            "total_raw": self.total_raw(),
+            "weighted_token_equivalent": round(self.weighted_token_equivalent, 1),
+            "by_model": self.by_model,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Headroom contribution estimate
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class HeadroomContribution:
+    """Tokens conserved within the current 5h window by Headroom's layers.
+
+    These are cumulative counters reset when the 5h window rolls over.
+    """
+
+    tokens_submitted: int = 0
+    """Raw input tokens actually forwarded to Anthropic by the proxy."""
+
+    tokens_saved_compression: int = 0
+    """Input tokens removed by proxy compression."""
+
+    tokens_saved_rtk: int = 0
+    """Tokens avoided by CLI filtering (rtk) before reaching context."""
+
+    tokens_saved_cache_reads: int = 0
+    """Input tokens served from Anthropic prefix-cache (discounted reads)."""
+
+    compression_savings_usd: float = 0.0
+    cache_savings_usd: float = 0.0
+
+    def total_saved(self) -> int:
+        return self.tokens_saved_compression + self.tokens_saved_rtk + self.tokens_saved_cache_reads
+
+    def total_savings_usd(self) -> float:
+        return self.compression_savings_usd + self.cache_savings_usd
+
+    def raw_without_headroom(self) -> int:
+        return self.tokens_submitted + self.tokens_saved_compression + self.tokens_saved_rtk
+
+    def efficiency_pct(self) -> float:
+        raw = self.raw_without_headroom()
+        if raw == 0:
+            return 0.0
+        return round(self.total_saved() / raw * 100, 1)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "tokens_submitted": self.tokens_submitted,
+            "tokens_saved": {
+                "compression": self.tokens_saved_compression,
+                "rtk": self.tokens_saved_rtk,
+                "cache_reads": self.tokens_saved_cache_reads,
+                "total": self.total_saved(),
+            },
+            "raw_without_headroom": self.raw_without_headroom(),
+            "efficiency_pct": self.efficiency_pct(),
+            "savings_usd": {
+                "compression": round(self.compression_savings_usd, 4),
+                "cache": round(self.cache_savings_usd, 4),
+                "total": round(self.total_savings_usd(), 4),
+            },
+        }
+
+
+# ---------------------------------------------------------------------------
+# Anomaly / discrepancy record
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class WindowDiscrepancy:
+    """Detected anomaly between expected and API-reported utilization."""
+
+    kind: str
+    """'surge_pricing' | 'cache_miss' | 'none'"""
+
+    description: str = ""
+    severity: str = "info"
+    """'info' | 'warning' | 'alert'"""
+
+    expected_utilization_pct: float | None = None
+    actual_utilization_pct: float | None = None
+    delta_pct: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "description": self.description,
+            "severity": self.severity,
+            "expected_utilization_pct": self.expected_utilization_pct,
+            "actual_utilization_pct": self.actual_utilization_pct,
+            "delta_pct": self.delta_pct,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Full tracker state
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SubscriptionState:
+    """Persistent state for the subscription tracker."""
+
+    latest: SubscriptionSnapshot | None = None
+    window_tokens: WindowTokens | None = None
+    """Transcript-derived token breakdown for the current 5h window."""
+
+    contribution: HeadroomContribution = field(default_factory=HeadroomContribution)
+    discrepancies: list[WindowDiscrepancy] = field(default_factory=list)
+    history: list[SubscriptionSnapshot] = field(default_factory=list)
+
+    poll_count: int = 0
+    poll_errors: int = 0
+    last_error: str | None = None
+    last_active_at: datetime | None = None
+
+    _MAX_HISTORY: int = field(default=100, init=False, repr=False)
+    _MAX_DISCREPANCIES: int = field(default=20, init=False, repr=False)
+
+    def add_snapshot(self, snapshot: SubscriptionSnapshot) -> None:
+        self.latest = snapshot
+        self.history.append(snapshot)
+        if len(self.history) > self._MAX_HISTORY:
+            self.history = self.history[-self._MAX_HISTORY :]
+        self.poll_count += 1
+
+    def mark_error(self, msg: str) -> None:
+        self.poll_errors += 1
+        self.last_error = msg
+
+    def add_discrepancy(self, d: WindowDiscrepancy) -> None:
+        self.discrepancies.append(d)
+        if len(self.discrepancies) > self._MAX_DISCREPANCIES:
+            self.discrepancies = self.discrepancies[-self._MAX_DISCREPANCIES :]
+
+    def is_active(self, *, active_window_s: float = 60.0) -> bool:
+        if self.last_active_at is None:
+            return False
+        return (_utc_now() - self.last_active_at).total_seconds() <= active_window_s
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "latest": self.latest.to_dict() if self.latest else None,
+            "window_tokens": self.window_tokens.to_dict() if self.window_tokens else None,
+            "contribution": self.contribution.to_dict(),
+            "discrepancies": [d.to_dict() for d in self.discrepancies[-5:]],
+            "poll_count": self.poll_count,
+            "poll_errors": self.poll_errors,
+            "last_error": self.last_error,
+            "last_active_at": _to_utc_iso(self.last_active_at) if self.last_active_at else None,
+        }
+
+    def to_persist_dict(self) -> dict[str, Any]:
+        d = self.to_dict()
+        d["history"] = [s.to_dict() for s in self.history[-20:]]
+        return d
diff --git a/headroom/subscription/session_tracking.py b/headroom/subscription/session_tracking.py
index 9367d79dd3ed6973ed9c384a0ae8be2b08b488b0..754fa77465ce17556bdb2c76fc5905be6669774f 100644
--- a/headroom/subscription/session_tracking.py
+++ b/headroom/subscription/session_tracking.py
@@ -1,189 +1,189 @@
-"""Parse Claude Code transcript JSONL files for per-window token breakdowns.
-
-Mirrors the approach in the ClaudeCacheTTLStatusLine TypeScript reference
-implementation (session-tracking.ts). Reads ~/.claude/projects/**/*.jsonl
-and aggregates token usage for entries whose timestamp falls within a window.
-
-Model weights (Sonnet-normalised, empirical estimates):
-  opus:   2.0×  (higher rate-limit cost)
-  sonnet: 1.0×  (baseline)
-  haiku:  0.5×  (cheaper, lower rate-limit cost)
-
-The weighted_token_equivalent lets callers detect surge pricing by comparing
-it against the API-reported utilisation × window_limit.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-from pathlib import Path
-from typing import Any
-
-from headroom.subscription.models import WindowTokens
-
-logger = logging.getLogger(__name__)
-
-# Maximum bytes to read per transcript file (10 MB cap — generous, typical files <1 MB)
-_MAX_FILE_BYTES = 10 * 1024 * 1024
-
-# Sonnet-normalised model family weights
-MODEL_FAMILY_WEIGHTS: dict[str, float] = {
-    "opus": 2.0,
-    "sonnet": 1.0,
-    "haiku": 0.5,
-}
-DEFAULT_MODEL_WEIGHT: float = 1.0
-
-
-def _claude_config_dir() -> Path:
-    base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")
-    return Path(base)
-
-
-def get_model_weight(model_id: str) -> float:
-    """Return the Sonnet-normalised weight for a model ID.
-
-    Matches against known family names using a word-boundary check.
-    Falls back to DEFAULT_MODEL_WEIGHT for unrecognised models.
-    """
-    lower = model_id.lower()
-    import re
-
-    for family, weight in MODEL_FAMILY_WEIGHTS.items():
-        if re.search(rf"(?<![a-z]){family}(?![a-z])", lower):
-            return weight
-    return DEFAULT_MODEL_WEIGHT
-
-
-def find_transcript_files() -> list[Path]:
-    """Return all .jsonl files under ~/.claude/projects."""
-    projects = _claude_config_dir() / "projects"
-    results: list[Path] = []
-    _walk_jsonl(projects, results)
-    return results
-
-
-def _walk_jsonl(directory: Path, results: list[Path]) -> None:
-    try:
-        entries = list(directory.iterdir())
-    except (OSError, PermissionError):
-        return
-    for entry in entries:
-        try:
-            if entry.is_dir():
-                _walk_jsonl(entry, results)
-            elif entry.suffix == ".jsonl":
-                results.append(entry)
-        except OSError:
-            continue
-
-
-def _read_transcript_lines(path: Path) -> list[str]:
-    try:
-        size = path.stat().st_size
-        read_size = min(size, _MAX_FILE_BYTES)
-        with path.open("rb") as fh:
-            raw = fh.read(read_size)
-        return [line for line in raw.decode("utf-8", errors="replace").splitlines() if line.strip()]
-    except Exception:
-        return []
-
-
-def _add_usage_to_tokens(dest: WindowTokens, usage: dict[str, Any]) -> None:
-    dest.input += int(usage.get("input_tokens") or 0)
-    dest.output += int(usage.get("output_tokens") or 0)
-    dest.cache_reads += int(usage.get("cache_read_input_tokens") or 0)
-
-    cache_creation = usage.get("cache_creation") or {}
-    w5m = int(cache_creation.get("ephemeral_5m_input_tokens") or 0)
-    w1h = int(cache_creation.get("ephemeral_1h_input_tokens") or 0)
-    total_writes = int(usage.get("cache_creation_input_tokens") or (w5m + w1h))
-
-    dest.cache_writes_5m += w5m
-    dest.cache_writes_1h += w1h
-    dest.cache_writes_total += total_writes
-
-
-def compute_window_tokens(start_ts: float, end_ts: float) -> WindowTokens:
-    """Sum transcript token usage for entries in [start_ts, end_ts).
-
-    Args:
-        start_ts: Window start as a Unix timestamp (seconds).
-        end_ts: Window end as a Unix timestamp (seconds).
-
-    Returns:
-        :class:`WindowTokens` with aggregate + per-model breakdown and
-        ``weighted_token_equivalent`` (Sonnet-normalised).
-    """
-    totals = WindowTokens()
-    by_model: dict[str, WindowTokens] = {}
-    unattributed = WindowTokens()
-
-    for path in find_transcript_files():
-        for line in _read_transcript_lines(path):
-            try:
-                entry: dict[str, Any] = json.loads(line)
-            except (json.JSONDecodeError, ValueError):
-                continue
-
-            ts_str = entry.get("timestamp")
-            if not ts_str:
-                continue
-            try:
-                from datetime import datetime
-
-                dt = datetime.fromisoformat(str(ts_str).replace("Z", "+00:00"))
-                ts = dt.timestamp()
-            except (ValueError, TypeError):
-                continue
-
-            if ts < start_ts or ts >= end_ts:
-                continue
-
-            msg = entry.get("message") or {}
-            usage = msg.get("usage")
-            if not usage:
-                continue
-
-            _add_usage_to_tokens(totals, usage)
-
-            model_id: str | None = msg.get("model")
-            if model_id:
-                if model_id not in by_model:
-                    by_model[model_id] = WindowTokens()
-                _add_usage_to_tokens(by_model[model_id], usage)
-            else:
-                _add_usage_to_tokens(unattributed, usage)
-
-    # Compute Sonnet-normalised weighted equivalent
-    model_weights: dict[str, float] = {}
-    weighted = 0.0
-
-    for model_id, model_tokens in by_model.items():
-        w = get_model_weight(model_id)
-        model_weights[model_id] = w
-        weighted += _total_token_count(model_tokens) * w
-
-    weighted += _total_token_count(unattributed) * DEFAULT_MODEL_WEIGHT
-
-    totals.weighted_token_equivalent = weighted
-    totals.by_model = {mid: _window_tokens_to_dict(mt) for mid, mt in by_model.items()}
-
-    return totals
-
-
-def _total_token_count(t: WindowTokens) -> int:
-    return t.input + t.output + t.cache_reads + t.cache_writes_total
-
-
-def _window_tokens_to_dict(t: WindowTokens) -> dict[str, int]:
-    return {
-        "input": t.input,
-        "output": t.output,
-        "cache_reads": t.cache_reads,
-        "cache_writes_5m": t.cache_writes_5m,
-        "cache_writes_1h": t.cache_writes_1h,
-        "cache_writes_total": t.cache_writes_total,
-    }
+"""Parse Claude Code transcript JSONL files for per-window token breakdowns.
+
+Mirrors the approach in the ClaudeCacheTTLStatusLine TypeScript reference
+implementation (session-tracking.ts). Reads ~/.claude/projects/**/*.jsonl
+and aggregates token usage for entries whose timestamp falls within a window.
+
+Model weights (Sonnet-normalised, empirical estimates):
+  opus:   2.0×  (higher rate-limit cost)
+  sonnet: 1.0×  (baseline)
+  haiku:  0.5×  (cheaper, lower rate-limit cost)
+
+The weighted_token_equivalent lets callers detect surge pricing by comparing
+it against the API-reported utilisation × window_limit.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from headroom.subscription.models import WindowTokens
+
+logger = logging.getLogger(__name__)
+
+# Maximum bytes to read per transcript file (10 MB cap — generous, typical files <1 MB)
+_MAX_FILE_BYTES = 10 * 1024 * 1024
+
+# Sonnet-normalised model family weights
+MODEL_FAMILY_WEIGHTS: dict[str, float] = {
+    "opus": 2.0,
+    "sonnet": 1.0,
+    "haiku": 0.5,
+}
+DEFAULT_MODEL_WEIGHT: float = 1.0
+
+
+def _claude_config_dir() -> Path:
+    base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")
+    return Path(base)
+
+
+def get_model_weight(model_id: str) -> float:
+    """Return the Sonnet-normalised weight for a model ID.
+
+    Matches against known family names using a word-boundary check.
+    Falls back to DEFAULT_MODEL_WEIGHT for unrecognised models.
+    """
+    lower = model_id.lower()
+    import re
+
+    for family, weight in MODEL_FAMILY_WEIGHTS.items():
+        if re.search(rf"(?<![a-z]){family}(?![a-z])", lower):
+            return weight
+    return DEFAULT_MODEL_WEIGHT
+
+
+def find_transcript_files() -> list[Path]:
+    """Return all .jsonl files under ~/.claude/projects."""
+    projects = _claude_config_dir() / "projects"
+    results: list[Path] = []
+    _walk_jsonl(projects, results)
+    return results
+
+
+def _walk_jsonl(directory: Path, results: list[Path]) -> None:
+    try:
+        entries = list(directory.iterdir())
+    except (OSError, PermissionError):
+        return
+    for entry in entries:
+        try:
+            if entry.is_dir():
+                _walk_jsonl(entry, results)
+            elif entry.suffix == ".jsonl":
+                results.append(entry)
+        except OSError:
+            continue
+
+
+def _read_transcript_lines(path: Path) -> list[str]:
+    try:
+        size = path.stat().st_size
+        read_size = min(size, _MAX_FILE_BYTES)
+        with path.open("rb") as fh:
+            raw = fh.read(read_size)
+        return [line for line in raw.decode("utf-8", errors="replace").splitlines() if line.strip()]
+    except Exception:
+        return []
+
+
+def _add_usage_to_tokens(dest: WindowTokens, usage: dict[str, Any]) -> None:
+    dest.input += int(usage.get("input_tokens") or 0)
+    dest.output += int(usage.get("output_tokens") or 0)
+    dest.cache_reads += int(usage.get("cache_read_input_tokens") or 0)
+
+    cache_creation = usage.get("cache_creation") or {}
+    w5m = int(cache_creation.get("ephemeral_5m_input_tokens") or 0)
+    w1h = int(cache_creation.get("ephemeral_1h_input_tokens") or 0)
+    total_writes = int(usage.get("cache_creation_input_tokens") or (w5m + w1h))
+
+    dest.cache_writes_5m += w5m
+    dest.cache_writes_1h += w1h
+    dest.cache_writes_total += total_writes
+
+
+def compute_window_tokens(start_ts: float, end_ts: float) -> WindowTokens:
+    """Sum transcript token usage for entries in [start_ts, end_ts).
+
+    Args:
+        start_ts: Window start as a Unix timestamp (seconds).
+        end_ts: Window end as a Unix timestamp (seconds).
+
+    Returns:
+        :class:`WindowTokens` with aggregate + per-model breakdown and
+        ``weighted_token_equivalent`` (Sonnet-normalised).
+    """
+    totals = WindowTokens()
+    by_model: dict[str, WindowTokens] = {}
+    unattributed = WindowTokens()
+
+    for path in find_transcript_files():
+        for line in _read_transcript_lines(path):
+            try:
+                entry: dict[str, Any] = json.loads(line)
+            except (json.JSONDecodeError, ValueError):
+                continue
+
+            ts_str = entry.get("timestamp")
+            if not ts_str:
+                continue
+            try:
+                from datetime import datetime
+
+                dt = datetime.fromisoformat(str(ts_str).replace("Z", "+00:00"))
+                ts = dt.timestamp()
+            except (ValueError, TypeError):
+                continue
+
+            if ts < start_ts or ts >= end_ts:
+                continue
+
+            msg = entry.get("message") or {}
+            usage = msg.get("usage")
+            if not usage:
+                continue
+
+            _add_usage_to_tokens(totals, usage)
+
+            model_id: str | None = msg.get("model")
+            if model_id:
+                if model_id not in by_model:
+                    by_model[model_id] = WindowTokens()
+                _add_usage_to_tokens(by_model[model_id], usage)
+            else:
+                _add_usage_to_tokens(unattributed, usage)
+
+    # Compute Sonnet-normalised weighted equivalent
+    model_weights: dict[str, float] = {}
+    weighted = 0.0
+
+    for model_id, model_tokens in by_model.items():
+        w = get_model_weight(model_id)
+        model_weights[model_id] = w
+        weighted += _total_token_count(model_tokens) * w
+
+    weighted += _total_token_count(unattributed) * DEFAULT_MODEL_WEIGHT
+
+    totals.weighted_token_equivalent = weighted
+    totals.by_model = {mid: _window_tokens_to_dict(mt) for mid, mt in by_model.items()}
+
+    return totals
+
+
+def _total_token_count(t: WindowTokens) -> int:
+    return t.input + t.output + t.cache_reads + t.cache_writes_total
+
+
+def _window_tokens_to_dict(t: WindowTokens) -> dict[str, int]:
+    return {
+        "input": t.input,
+        "output": t.output,
+        "cache_reads": t.cache_reads,
+        "cache_writes_5m": t.cache_writes_5m,
+        "cache_writes_1h": t.cache_writes_1h,
+        "cache_writes_total": t.cache_writes_total,
+    }
diff --git a/headroom/subscription/tracker.py b/headroom/subscription/tracker.py
index 70e5e9467eca4e688e4e3dc83f179b9b8fca4d56..3eae0bb53dcf1f1fb02863d19213276bbcff3368 100644
--- a/headroom/subscription/tracker.py
+++ b/headroom/subscription/tracker.py
@@ -1,464 +1,464 @@
-"""Background subscription window tracker for Anthropic OAuth accounts.
-
-Polls GET https://api.anthropic.com/api/oauth/usage on a configurable interval
-while there has been at least one active OAuth session within the last minute.
-Falls back to a stored token from ~/.claude/.credentials.json when no live
-request has come through the proxy recently.
-
-Architecture:
-- Single asyncio.Task polling loop (started in start(), stopped via asyncio.Event)
-- Thread-safe state updates via threading.Lock (consistent with headroom patterns)
-- Atomic JSON persistence via tempfile + os.replace()
-- Module-level singleton via get_subscription_tracker() / configure_subscription_tracker()
-
-Also reads Claude transcript JSONL files (via session_tracking module) to provide
-token breakdowns per window that enable:
-  - Headroom efficiency metrics (tokens saved = raw - what proxy sent)
-  - Surge pricing detection (API utilization vs expected from weighted tokens)
-  - Cache miss detection (low cache_reads despite high input tokens)
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import logging
-import os
-import tempfile
-import threading
-from pathlib import Path
-from typing import Any
-
-from headroom import paths as _paths
-from headroom.subscription.base import QuotaTracker
-from headroom.subscription.client import SubscriptionClient
-from headroom.subscription.models import (
-    HeadroomContribution,
-    SubscriptionSnapshot,
-    SubscriptionState,
-    WindowDiscrepancy,
-    WindowTokens,
-    _utc_now,
-)
-
-logger = logging.getLogger(__name__)
-
-_DEFAULT_POLL_INTERVAL_S = 300
-_DEFAULT_ACTIVE_WINDOW_S = 60
-_PERSIST_FILE_ENV = _paths.HEADROOM_SUBSCRIPTION_STATE_PATH_ENV
-_DEFAULT_PERSIST_DIR = ".headroom"
-_DEFAULT_PERSIST_FILE = "subscription_state.json"
-
-# Surge pricing threshold: if actual utilization is >N% higher than expected,
-# flag it as a potential surge pricing event.
-_SURGE_THRESHOLD_PCT = 15.0
-
-# Cache miss threshold: if cache_reads < N% of total input when we expect
-# heavy caching (>50k input tokens in window), flag it.
-_CACHE_MISS_RATIO_THRESHOLD = 0.10
-
-
-def _get_persist_path() -> Path:
-    return _paths.subscription_state_path()
-
-
-class SubscriptionTracker(QuotaTracker):
-    """Background tracker for Anthropic Claude Code subscription windows.
-
-    Implements :class:`~headroom.subscription.base.QuotaTracker` so it can
-    be registered with :func:`~headroom.subscription.base.get_quota_registry`
-    alongside the Codex and Copilot trackers.
-
-    Args:
-        poll_interval_s: Seconds between polls while active (1–3600, default 300).
-        active_window_s: Seconds since last notify_active call that keeps
-            polling alive (default 60 = 1 minute).
-        enabled: Set to ``False`` to disable tracking (mirrors
-            ``ProxyConfig.subscription_tracking_enabled``).
-        persist_path: Where to persist state across restarts.
-        client: Injected client (for testing); defaults to SubscriptionClient().
-    """
-
-    # QuotaTracker identity
-    key = "subscription_window"
-    label = "Anthropic Claude Code"
-
-    def __init__(
-        self,
-        poll_interval_s: int = _DEFAULT_POLL_INTERVAL_S,
-        active_window_s: float = _DEFAULT_ACTIVE_WINDOW_S,
-        enabled: bool = True,
-        persist_path: Path | None = None,
-        client: SubscriptionClient | None = None,
-    ) -> None:
-        self._enabled = enabled
-        self._poll_interval_s = max(1, min(poll_interval_s, 3600))
-        self._active_window_s = max(5.0, active_window_s)
-        self._persist_path = persist_path or _get_persist_path()
-        self._client = client or SubscriptionClient()
-
-        self._lock = threading.Lock()
-        self._state = SubscriptionState()
-        self._current_token: str | None = None
-        self._full_tokens: dict[str, int] = {}  # token_prefix -> count of requests
-
-        self._stop_event: asyncio.Event | None = None
-        self._poll_task: asyncio.Task[None] | None = None
-
-        self._load_persisted_state()
-
-    # ------------------------------------------------------------------
-    # QuotaTracker interface
-    # ------------------------------------------------------------------
-
-    def is_available(self) -> bool:
-        """Returns ``True`` when subscription tracking is enabled in config."""
-        return self._enabled
-
-    def get_stats(self) -> dict[str, Any] | None:
-        """Return current tracker state dict for ``/stats``."""
-        return self.state
-
-    # ------------------------------------------------------------------
-    # Lifecycle
-    # ------------------------------------------------------------------
-
-    async def start(self) -> None:
-        """Start the background polling loop."""
-        if self._poll_task and not self._poll_task.done():
-            return
-        self._stop_event = asyncio.Event()
-        self._poll_task = asyncio.create_task(self._poll_loop(), name="subscription-tracker")
-        logger.info("Subscription tracker started (poll_interval=%ds)", self._poll_interval_s)
-
-    async def stop(self) -> None:
-        """Stop the background polling loop and persist current state."""
-        if self._stop_event:
-            self._stop_event.set()
-        if self._poll_task:
-            try:
-                await asyncio.wait_for(self._poll_task, timeout=5.0)
-            except (asyncio.TimeoutError, asyncio.CancelledError):
-                self._poll_task.cancel()
-        self._persist_state()
-        logger.info("Subscription tracker stopped")
-
-    # ------------------------------------------------------------------
-    # Proxy integration hooks
-    # ------------------------------------------------------------------
-
-    def notify_active(self, token: str) -> None:
-        """Called by the proxy handler when an OAuth request comes through.
-
-        Stores the token for polling and marks the tracker as recently active.
-        Only processes Bearer tokens that look like OAuth (not API keys).
-        """
-        if not token or not token.startswith("Bearer "):
-            return
-        raw = token[len("Bearer ") :]
-        # Skip raw API keys (not OAuth tokens)
-        if raw.startswith("sk-ant-api"):
-            return
-        with self._lock:
-            self._current_token = raw
-            self._state.last_active_at = _utc_now()
-            prefix = raw[:8]
-            self._full_tokens[prefix] = self._full_tokens.get(prefix, 0) + 1
-
-    def update_contribution(
-        self,
-        *,
-        tokens_submitted: int = 0,
-        tokens_saved_compression: int = 0,
-        tokens_saved_rtk: int = 0,
-        tokens_saved_cache_reads: int = 0,
-        compression_savings_usd: float = 0.0,
-        cache_savings_usd: float = 0.0,
-    ) -> None:
-        """Update headroom contribution counters for the current session window.
-
-        Called after each proxy request completes with the actual token deltas.
-        """
-        with self._lock:
-            c = self._state.contribution
-            c.tokens_submitted += max(tokens_submitted, 0)
-            c.tokens_saved_compression += max(tokens_saved_compression, 0)
-            c.tokens_saved_rtk += max(tokens_saved_rtk, 0)
-            c.tokens_saved_cache_reads += max(tokens_saved_cache_reads, 0)
-            c.compression_savings_usd += max(compression_savings_usd, 0.0)
-            c.cache_savings_usd += max(cache_savings_usd, 0.0)
-
-    # ------------------------------------------------------------------
-    # State access
-    # ------------------------------------------------------------------
-
-    @property
-    def state(self) -> dict[str, Any]:
-        """Return current tracker state as a serialisable dict."""
-        with self._lock:
-            return self._state.to_dict()
-
-    @property
-    def latest_snapshot(self) -> SubscriptionSnapshot | None:
-        with self._lock:
-            return self._state.latest
-
-    def is_active(self) -> bool:
-        with self._lock:
-            return self._state.is_active(active_window_s=self._active_window_s)
-
-    # ------------------------------------------------------------------
-    # Poll loop
-    # ------------------------------------------------------------------
-
-    async def _poll_loop(self) -> None:
-        assert self._stop_event is not None
-        while not self._stop_event.is_set():
-            try:
-                await self._maybe_poll()
-            except Exception as exc:
-                logger.warning("Subscription tracker poll error: %s", exc)
-            try:
-                # NOTE: do NOT wrap in asyncio.shield() — shield prevents the
-                # inner Event.wait() from being cancelled when wait_for times
-                # out, leaking one Task per poll interval. Over hours the
-                # accumulated idle waiters bog down the event loop scheduler
-                # (observed as the "aged proxy degradation" in 2026-04-17).
-                await asyncio.wait_for(
-                    self._stop_event.wait(),
-                    timeout=self._poll_interval_s,
-                )
-                break  # stop event was set
-            except asyncio.TimeoutError:
-                pass  # normal: poll interval elapsed
-
-    async def _maybe_poll(self) -> None:
-        with self._lock:
-            is_active = self._state.is_active(active_window_s=self._active_window_s)
-            token = self._current_token
-
-        if not is_active:
-            # Try background poll using credentials file token
-            from headroom.subscription.client import read_cached_oauth_token
-
-            bg_token = read_cached_oauth_token()
-            if not bg_token:
-                return
-            token = token or bg_token
-
-        snapshot = await self._client.fetch(token)
-        if snapshot is None:
-            with self._lock:
-                self._state.mark_error("fetch returned None")
-            return
-
-        # Read transcript-based window tokens
-        window_tokens = _compute_window_tokens_for_snapshot(snapshot)
-
-        # Detect anomalies
-        discrepancies = _detect_discrepancies(snapshot, window_tokens)
-
-        with self._lock:
-            self._state.add_snapshot(snapshot)
-            self._state.window_tokens = window_tokens
-            for d in discrepancies:
-                self._state.add_discrepancy(d)
-            self._state.last_error = None
-            # Reset contribution when 5h window rolls over
-            self._maybe_reset_contribution(snapshot)
-
-        self._persist_state()
-        logger.debug(
-            "Subscription poll: 5h=%.1f%% 7d=%.1f%%",
-            snapshot.five_hour.utilization_pct,
-            snapshot.seven_day.utilization_pct,
-        )
-
-        # Update OTEL metrics if configured
-        try:
-            from headroom.observability.metrics import get_otel_metrics
-
-            get_otel_metrics().record_subscription_window(self._state.to_dict())
-        except Exception:
-            pass
-
-    def _maybe_reset_contribution(self, snapshot: SubscriptionSnapshot) -> None:
-        """Reset contribution counters when the 5h window rolls over."""
-        prev = self._state.history[-2] if len(self._state.history) >= 2 else None
-        if prev is None:
-            return
-        prev_resets_at = prev.five_hour.resets_at
-        curr_resets_at = snapshot.five_hour.resets_at
-        if (
-            prev_resets_at is not None
-            and curr_resets_at is not None
-            and curr_resets_at != prev_resets_at
-        ):
-            logger.info("5h window rolled over; resetting headroom contribution counters")
-            self._state.contribution = HeadroomContribution()
-
-    # ------------------------------------------------------------------
-    # Persistence
-    # ------------------------------------------------------------------
-
-    def _persist_state(self) -> None:
-        try:
-            self._persist_path.parent.mkdir(parents=True, exist_ok=True)
-            with self._lock:
-                data = self._state.to_persist_dict()
-            with tempfile.NamedTemporaryFile(
-                mode="w",
-                dir=self._persist_path.parent,
-                delete=False,
-                suffix=".tmp",
-                encoding="utf-8",
-            ) as fh:
-                json.dump(data, fh, indent=2)
-                tmp_path = fh.name
-            os.replace(tmp_path, self._persist_path)
-        except Exception as exc:
-            logger.debug("Failed to persist subscription state: %s", exc)
-
-    def _load_persisted_state(self) -> None:
-        try:
-            with open(self._persist_path, encoding="utf-8") as fh:
-                raw = json.load(fh)
-            # Restore only the contribution counters and poll counts for now;
-            # snapshot data is re-fetched on first active poll.
-            contrib = raw.get("contribution", {})
-            c = self._state.contribution
-            c.tokens_submitted = int(contrib.get("tokens_submitted", 0))
-            saved = contrib.get("tokens_saved", {})
-            c.tokens_saved_compression = int(saved.get("compression", 0))
-            c.tokens_saved_rtk = int(saved.get("rtk", 0))
-            c.tokens_saved_cache_reads = int(saved.get("cache_reads", 0))
-            savings_usd = contrib.get("savings_usd", {})
-            c.compression_savings_usd = float(savings_usd.get("compression", 0.0))
-            c.cache_savings_usd = float(savings_usd.get("cache", 0.0))
-            self._state.poll_count = int(raw.get("poll_count", 0))
-            logger.debug("Loaded persisted subscription state from %s", self._persist_path)
-        except FileNotFoundError:
-            pass
-        except Exception as exc:
-            logger.debug("Could not load persisted subscription state: %s", exc)
-
-
-# ---------------------------------------------------------------------------
-# Transcript-based window token computation
-# ---------------------------------------------------------------------------
-
-
-def _compute_window_tokens_for_snapshot(snapshot: SubscriptionSnapshot) -> WindowTokens:
-    """Read Claude transcript files and sum tokens for the current 5h window."""
-    try:
-        from headroom.subscription import session_tracking
-
-        resets_at = snapshot.five_hour.resets_at
-        if resets_at is None:
-            return WindowTokens()
-        window_duration_s = 5 * 3600  # 5-hour window
-        start_ts = resets_at.timestamp() - window_duration_s
-        end_ts = resets_at.timestamp()
-        return session_tracking.compute_window_tokens(start_ts, end_ts)
-    except Exception as exc:
-        logger.debug("Could not compute window tokens from transcripts: %s", exc)
-        return WindowTokens()
-
-
-# ---------------------------------------------------------------------------
-# Anomaly detection
-# ---------------------------------------------------------------------------
-
-
-def _detect_discrepancies(
-    snapshot: SubscriptionSnapshot,
-    window_tokens: WindowTokens,
-) -> list[WindowDiscrepancy]:
-    """Detect surge pricing or cache miss anomalies in the snapshot."""
-    discrepancies: list[WindowDiscrepancy] = []
-
-    if snapshot.five_hour.limit > 0 and window_tokens.weighted_token_equivalent > 0:
-        expected_pct = window_tokens.weighted_token_equivalent / snapshot.five_hour.limit * 100.0
-        actual_pct = snapshot.five_hour.utilization_pct
-        delta = actual_pct - expected_pct
-
-        if delta > _SURGE_THRESHOLD_PCT:
-            discrepancies.append(
-                WindowDiscrepancy(
-                    kind="surge_pricing",
-                    description=(
-                        f"API 5h utilization ({actual_pct:.1f}%) is "
-                        f"{delta:.1f}% higher than transcript-implied "
-                        f"({expected_pct:.1f}%); possible surge weighting."
-                    ),
-                    severity="warning" if delta < 30 else "alert",
-                    expected_utilization_pct=round(expected_pct, 2),
-                    actual_utilization_pct=round(actual_pct, 2),
-                    delta_pct=round(delta, 2),
-                )
-            )
-
-    total_input = window_tokens.input
-    total_cache_reads = window_tokens.cache_reads
-    if total_input > 50_000 and total_cache_reads < total_input * _CACHE_MISS_RATIO_THRESHOLD:
-        cache_ratio = total_cache_reads / total_input if total_input else 0
-        discrepancies.append(
-            WindowDiscrepancy(
-                kind="cache_miss",
-                description=(
-                    f"Cache-read ratio is {cache_ratio:.1%} (threshold "
-                    f"{_CACHE_MISS_RATIO_THRESHOLD:.0%}); system may not be "
-                    "using prefix cache effectively."
-                ),
-                severity="warning",
-                expected_utilization_pct=None,
-                actual_utilization_pct=None,
-                delta_pct=None,
-            )
-        )
-
-    return discrepancies
-
-
-# ---------------------------------------------------------------------------
-# Module-level singleton
-# ---------------------------------------------------------------------------
-
-_tracker_lock = threading.Lock()
-_tracker_instance: SubscriptionTracker | None = None
-
-
-def get_subscription_tracker() -> SubscriptionTracker | None:
-    """Return the global singleton tracker, or None if not configured."""
-    return _tracker_instance
-
-
-def configure_subscription_tracker(
-    poll_interval_s: int = _DEFAULT_POLL_INTERVAL_S,
-    active_window_s: float = _DEFAULT_ACTIVE_WINDOW_S,
-    enabled: bool = True,
-    persist_path: Path | None = None,
-    client: SubscriptionClient | None = None,
-) -> SubscriptionTracker:
-    """Create (or return existing) global tracker singleton."""
-    global _tracker_instance
-    with _tracker_lock:
-        if _tracker_instance is None:
-            _tracker_instance = SubscriptionTracker(
-                poll_interval_s=poll_interval_s,
-                active_window_s=active_window_s,
-                enabled=enabled,
-                persist_path=persist_path,
-                client=client,
-            )
-    return _tracker_instance
-
-
-async def shutdown_subscription_tracker() -> None:
-    """Stop and clean up the global tracker."""
-    global _tracker_instance
-    with _tracker_lock:
-        tracker = _tracker_instance
-        _tracker_instance = None
-    if tracker:
-        await tracker.stop()
+"""Background subscription window tracker for Anthropic OAuth accounts.
+
+Polls GET https://api.anthropic.com/api/oauth/usage on a configurable interval
+while there has been at least one active OAuth session within the last minute.
+Falls back to a stored token from ~/.claude/.credentials.json when no live
+request has come through the proxy recently.
+
+Architecture:
+- Single asyncio.Task polling loop (started in start(), stopped via asyncio.Event)
+- Thread-safe state updates via threading.Lock (consistent with headroom patterns)
+- Atomic JSON persistence via tempfile + os.replace()
+- Module-level singleton via get_subscription_tracker() / configure_subscription_tracker()
+
+Also reads Claude transcript JSONL files (via session_tracking module) to provide
+token breakdowns per window that enable:
+  - Headroom efficiency metrics (tokens saved = raw - what proxy sent)
+  - Surge pricing detection (API utilization vs expected from weighted tokens)
+  - Cache miss detection (low cache_reads despite high input tokens)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import tempfile
+import threading
+from pathlib import Path
+from typing import Any
+
+from headroom import paths as _paths
+from headroom.subscription.base import QuotaTracker
+from headroom.subscription.client import SubscriptionClient
+from headroom.subscription.models import (
+    HeadroomContribution,
+    SubscriptionSnapshot,
+    SubscriptionState,
+    WindowDiscrepancy,
+    WindowTokens,
+    _utc_now,
+)
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_POLL_INTERVAL_S = 300
+_DEFAULT_ACTIVE_WINDOW_S = 60
+_PERSIST_FILE_ENV = _paths.HEADROOM_SUBSCRIPTION_STATE_PATH_ENV
+_DEFAULT_PERSIST_DIR = ".headroom"
+_DEFAULT_PERSIST_FILE = "subscription_state.json"
+
+# Surge pricing threshold: if actual utilization is >N% higher than expected,
+# flag it as a potential surge pricing event.
+_SURGE_THRESHOLD_PCT = 15.0
+
+# Cache miss threshold: if cache_reads < N% of total input when we expect
+# heavy caching (>50k input tokens in window), flag it.
+_CACHE_MISS_RATIO_THRESHOLD = 0.10
+
+
+def _get_persist_path() -> Path:
+    return _paths.subscription_state_path()
+
+
+class SubscriptionTracker(QuotaTracker):
+    """Background tracker for Anthropic Claude Code subscription windows.
+
+    Implements :class:`~headroom.subscription.base.QuotaTracker` so it can
+    be registered with :func:`~headroom.subscription.base.get_quota_registry`
+    alongside the Codex and Copilot trackers.
+
+    Args:
+        poll_interval_s: Seconds between polls while active (1–3600, default 300).
+        active_window_s: Seconds since last notify_active call that keeps
+            polling alive (default 60 = 1 minute).
+        enabled: Set to ``False`` to disable tracking (mirrors
+            ``ProxyConfig.subscription_tracking_enabled``).
+        persist_path: Where to persist state across restarts.
+        client: Injected client (for testing); defaults to SubscriptionClient().
+    """
+
+    # QuotaTracker identity
+    key = "subscription_window"
+    label = "Anthropic Claude Code"
+
+    def __init__(
+        self,
+        poll_interval_s: int = _DEFAULT_POLL_INTERVAL_S,
+        active_window_s: float = _DEFAULT_ACTIVE_WINDOW_S,
+        enabled: bool = True,
+        persist_path: Path | None = None,
+        client: SubscriptionClient | None = None,
+    ) -> None:
+        self._enabled = enabled
+        self._poll_interval_s = max(1, min(poll_interval_s, 3600))
+        self._active_window_s = max(5.0, active_window_s)
+        self._persist_path = persist_path or _get_persist_path()
+        self._client = client or SubscriptionClient()
+
+        self._lock = threading.Lock()
+        self._state = SubscriptionState()
+        self._current_token: str | None = None
+        self._full_tokens: dict[str, int] = {}  # token_prefix -> count of requests
+
+        self._stop_event: asyncio.Event | None = None
+        self._poll_task: asyncio.Task[None] | None = None
+
+        self._load_persisted_state()
+
+    # ------------------------------------------------------------------
+    # QuotaTracker interface
+    # ------------------------------------------------------------------
+
+    def is_available(self) -> bool:
+        """Returns ``True`` when subscription tracking is enabled in config."""
+        return self._enabled
+
+    def get_stats(self) -> dict[str, Any] | None:
+        """Return current tracker state dict for ``/stats``."""
+        return self.state
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self) -> None:
+        """Start the background polling loop."""
+        if self._poll_task and not self._poll_task.done():
+            return
+        self._stop_event = asyncio.Event()
+        self._poll_task = asyncio.create_task(self._poll_loop(), name="subscription-tracker")
+        logger.info("Subscription tracker started (poll_interval=%ds)", self._poll_interval_s)
+
+    async def stop(self) -> None:
+        """Stop the background polling loop and persist current state."""
+        if self._stop_event:
+            self._stop_event.set()
+        if self._poll_task:
+            try:
+                await asyncio.wait_for(self._poll_task, timeout=5.0)
+            except (asyncio.TimeoutError, asyncio.CancelledError):
+                self._poll_task.cancel()
+        self._persist_state()
+        logger.info("Subscription tracker stopped")
+
+    # ------------------------------------------------------------------
+    # Proxy integration hooks
+    # ------------------------------------------------------------------
+
+    def notify_active(self, token: str) -> None:
+        """Called by the proxy handler when an OAuth request comes through.
+
+        Stores the token for polling and marks the tracker as recently active.
+        Only processes Bearer tokens that look like OAuth (not API keys).
+        """
+        if not token or not token.startswith("Bearer "):
+            return
+        raw = token[len("Bearer ") :]
+        # Skip raw API keys (not OAuth tokens)
+        if raw.startswith("sk-ant-api"):
+            return
+        with self._lock:
+            self._current_token = raw
+            self._state.last_active_at = _utc_now()
+            prefix = raw[:8]
+            self._full_tokens[prefix] = self._full_tokens.get(prefix, 0) + 1
+
+    def update_contribution(
+        self,
+        *,
+        tokens_submitted: int = 0,
+        tokens_saved_compression: int = 0,
+        tokens_saved_rtk: int = 0,
+        tokens_saved_cache_reads: int = 0,
+        compression_savings_usd: float = 0.0,
+        cache_savings_usd: float = 0.0,
+    ) -> None:
+        """Update headroom contribution counters for the current session window.
+
+        Called after each proxy request completes with the actual token deltas.
+        """
+        with self._lock:
+            c = self._state.contribution
+            c.tokens_submitted += max(tokens_submitted, 0)
+            c.tokens_saved_compression += max(tokens_saved_compression, 0)
+            c.tokens_saved_rtk += max(tokens_saved_rtk, 0)
+            c.tokens_saved_cache_reads += max(tokens_saved_cache_reads, 0)
+            c.compression_savings_usd += max(compression_savings_usd, 0.0)
+            c.cache_savings_usd += max(cache_savings_usd, 0.0)
+
+    # ------------------------------------------------------------------
+    # State access
+    # ------------------------------------------------------------------
+
+    @property
+    def state(self) -> dict[str, Any]:
+        """Return current tracker state as a serialisable dict."""
+        with self._lock:
+            return self._state.to_dict()
+
+    @property
+    def latest_snapshot(self) -> SubscriptionSnapshot | None:
+        with self._lock:
+            return self._state.latest
+
+    def is_active(self) -> bool:
+        with self._lock:
+            return self._state.is_active(active_window_s=self._active_window_s)
+
+    # ------------------------------------------------------------------
+    # Poll loop
+    # ------------------------------------------------------------------
+
+    async def _poll_loop(self) -> None:
+        assert self._stop_event is not None
+        while not self._stop_event.is_set():
+            try:
+                await self._maybe_poll()
+            except Exception as exc:
+                logger.warning("Subscription tracker poll error: %s", exc)
+            try:
+                # NOTE: do NOT wrap in asyncio.shield() — shield prevents the
+                # inner Event.wait() from being cancelled when wait_for times
+                # out, leaking one Task per poll interval. Over hours the
+                # accumulated idle waiters bog down the event loop scheduler
+                # (observed as the "aged proxy degradation" in 2026-04-17).
+                await asyncio.wait_for(
+                    self._stop_event.wait(),
+                    timeout=self._poll_interval_s,
+                )
+                break  # stop event was set
+            except asyncio.TimeoutError:
+                pass  # normal: poll interval elapsed
+
+    async def _maybe_poll(self) -> None:
+        with self._lock:
+            is_active = self._state.is_active(active_window_s=self._active_window_s)
+            token = self._current_token
+
+        if not is_active:
+            # Try background poll using credentials file token
+            from headroom.subscription.client import read_cached_oauth_token
+
+            bg_token = read_cached_oauth_token()
+            if not bg_token:
+                return
+            token = token or bg_token
+
+        snapshot = await self._client.fetch(token)
+        if snapshot is None:
+            with self._lock:
+                self._state.mark_error("fetch returned None")
+            return
+
+        # Read transcript-based window tokens
+        window_tokens = _compute_window_tokens_for_snapshot(snapshot)
+
+        # Detect anomalies
+        discrepancies = _detect_discrepancies(snapshot, window_tokens)
+
+        with self._lock:
+            self._state.add_snapshot(snapshot)
+            self._state.window_tokens = window_tokens
+            for d in discrepancies:
+                self._state.add_discrepancy(d)
+            self._state.last_error = None
+            # Reset contribution when 5h window rolls over
+            self._maybe_reset_contribution(snapshot)
+
+        self._persist_state()
+        logger.debug(
+            "Subscription poll: 5h=%.1f%% 7d=%.1f%%",
+            snapshot.five_hour.utilization_pct,
+            snapshot.seven_day.utilization_pct,
+        )
+
+        # Update OTEL metrics if configured
+        try:
+            from headroom.observability.metrics import get_otel_metrics
+
+            get_otel_metrics().record_subscription_window(self._state.to_dict())
+        except Exception:
+            pass
+
+    def _maybe_reset_contribution(self, snapshot: SubscriptionSnapshot) -> None:
+        """Reset contribution counters when the 5h window rolls over."""
+        prev = self._state.history[-2] if len(self._state.history) >= 2 else None
+        if prev is None:
+            return
+        prev_resets_at = prev.five_hour.resets_at
+        curr_resets_at = snapshot.five_hour.resets_at
+        if (
+            prev_resets_at is not None
+            and curr_resets_at is not None
+            and curr_resets_at != prev_resets_at
+        ):
+            logger.info("5h window rolled over; resetting headroom contribution counters")
+            self._state.contribution = HeadroomContribution()
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def _persist_state(self) -> None:
+        try:
+            self._persist_path.parent.mkdir(parents=True, exist_ok=True)
+            with self._lock:
+                data = self._state.to_persist_dict()
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                dir=self._persist_path.parent,
+                delete=False,
+                suffix=".tmp",
+                encoding="utf-8",
+            ) as fh:
+                json.dump(data, fh, indent=2)
+                tmp_path = fh.name
+            os.replace(tmp_path, self._persist_path)
+        except Exception as exc:
+            logger.debug("Failed to persist subscription state: %s", exc)
+
+    def _load_persisted_state(self) -> None:
+        try:
+            with open(self._persist_path, encoding="utf-8") as fh:
+                raw = json.load(fh)
+            # Restore only the contribution counters and poll counts for now;
+            # snapshot data is re-fetched on first active poll.
+            contrib = raw.get("contribution", {})
+            c = self._state.contribution
+            c.tokens_submitted = int(contrib.get("tokens_submitted", 0))
+            saved = contrib.get("tokens_saved", {})
+            c.tokens_saved_compression = int(saved.get("compression", 0))
+            c.tokens_saved_rtk = int(saved.get("rtk", 0))
+            c.tokens_saved_cache_reads = int(saved.get("cache_reads", 0))
+            savings_usd = contrib.get("savings_usd", {})
+            c.compression_savings_usd = float(savings_usd.get("compression", 0.0))
+            c.cache_savings_usd = float(savings_usd.get("cache", 0.0))
+            self._state.poll_count = int(raw.get("poll_count", 0))
+            logger.debug("Loaded persisted subscription state from %s", self._persist_path)
+        except FileNotFoundError:
+            pass
+        except Exception as exc:
+            logger.debug("Could not load persisted subscription state: %s", exc)
+
+
+# ---------------------------------------------------------------------------
+# Transcript-based window token computation
+# ---------------------------------------------------------------------------
+
+
+def _compute_window_tokens_for_snapshot(snapshot: SubscriptionSnapshot) -> WindowTokens:
+    """Read Claude transcript files and sum tokens for the current 5h window."""
+    try:
+        from headroom.subscription import session_tracking
+
+        resets_at = snapshot.five_hour.resets_at
+        if resets_at is None:
+            return WindowTokens()
+        window_duration_s = 5 * 3600  # 5-hour window
+        start_ts = resets_at.timestamp() - window_duration_s
+        end_ts = resets_at.timestamp()
+        return session_tracking.compute_window_tokens(start_ts, end_ts)
+    except Exception as exc:
+        logger.debug("Could not compute window tokens from transcripts: %s", exc)
+        return WindowTokens()
+
+
+# ---------------------------------------------------------------------------
+# Anomaly detection
+# ---------------------------------------------------------------------------
+
+
+def _detect_discrepancies(
+    snapshot: SubscriptionSnapshot,
+    window_tokens: WindowTokens,
+) -> list[WindowDiscrepancy]:
+    """Detect surge pricing or cache miss anomalies in the snapshot."""
+    discrepancies: list[WindowDiscrepancy] = []
+
+    if snapshot.five_hour.limit > 0 and window_tokens.weighted_token_equivalent > 0:
+        expected_pct = window_tokens.weighted_token_equivalent / snapshot.five_hour.limit * 100.0
+        actual_pct = snapshot.five_hour.utilization_pct
+        delta = actual_pct - expected_pct
+
+        if delta > _SURGE_THRESHOLD_PCT:
+            discrepancies.append(
+                WindowDiscrepancy(
+                    kind="surge_pricing",
+                    description=(
+                        f"API 5h utilization ({actual_pct:.1f}%) is "
+                        f"{delta:.1f}% higher than transcript-implied "
+                        f"({expected_pct:.1f}%); possible surge weighting."
+                    ),
+                    severity="warning" if delta < 30 else "alert",
+                    expected_utilization_pct=round(expected_pct, 2),
+                    actual_utilization_pct=round(actual_pct, 2),
+                    delta_pct=round(delta, 2),
+                )
+            )
+
+    total_input = window_tokens.input
+    total_cache_reads = window_tokens.cache_reads
+    if total_input > 50_000 and total_cache_reads < total_input * _CACHE_MISS_RATIO_THRESHOLD:
+        cache_ratio = total_cache_reads / total_input if total_input else 0
+        discrepancies.append(
+            WindowDiscrepancy(
+                kind="cache_miss",
+                description=(
+                    f"Cache-read ratio is {cache_ratio:.1%} (threshold "
+                    f"{_CACHE_MISS_RATIO_THRESHOLD:.0%}); system may not be "
+                    "using prefix cache effectively."
+                ),
+                severity="warning",
+                expected_utilization_pct=None,
+                actual_utilization_pct=None,
+                delta_pct=None,
+            )
+        )
+
+    return discrepancies
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+_tracker_lock = threading.Lock()
+_tracker_instance: SubscriptionTracker | None = None
+
+
+def get_subscription_tracker() -> SubscriptionTracker | None:
+    """Return the global singleton tracker, or None if not configured."""
+    return _tracker_instance
+
+
+def configure_subscription_tracker(
+    poll_interval_s: int = _DEFAULT_POLL_INTERVAL_S,
+    active_window_s: float = _DEFAULT_ACTIVE_WINDOW_S,
+    enabled: bool = True,
+    persist_path: Path | None = None,
+    client: SubscriptionClient | None = None,
+) -> SubscriptionTracker:
+    """Create (or return existing) global tracker singleton."""
+    global _tracker_instance
+    with _tracker_lock:
+        if _tracker_instance is None:
+            _tracker_instance = SubscriptionTracker(
+                poll_interval_s=poll_interval_s,
+                active_window_s=active_window_s,
+                enabled=enabled,
+                persist_path=persist_path,
+                client=client,
+            )
+    return _tracker_instance
+
+
+async def shutdown_subscription_tracker() -> None:
+    """Stop and clean up the global tracker."""
+    global _tracker_instance
+    with _tracker_lock:
+        tracker = _tracker_instance
+        _tracker_instance = None
+    if tracker:
+        await tracker.stop()
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 1c98f6cd5c7f76f3fa651a1f687b347e8ce53e8a..8c264fc7c0dee06a8e1c52dff2176d1095971a66 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -1,2130 +1,2130 @@
-"""Content router for intelligent compression strategy selection.
-
-This module provides the ContentRouter, which analyzes content and routes it
-to the optimal compressor. It handles mixed content by splitting, routing
-each section to the appropriate compressor, and reassembling.
-
-Supported Compressors:
-- CodeAwareCompressor: Source code (AST-preserving)
-- SmartCrusher: JSON arrays
-- SearchCompressor: grep/ripgrep results
-- LogCompressor: Build/test output
-- KompressCompressor: Plain text (ML-based)
-- Kompress: Plain text (ML-based, requires [ml] extra)
-
-Routing Strategy:
-1. Use source hint if available (highest confidence)
-2. Check for mixed content (split and route sections)
-3. Detect content type (JSON, code, search, logs, text)
-4. Route to appropriate compressor
-5. Reassemble and return with routing metadata
-
-Usage:
-    >>> from headroom.transforms import ContentRouter
-    >>> router = ContentRouter()
-    >>> result = router.compress(content)  # Auto-routes to best compressor
-    >>> print(result.strategy_used)
-    >>> print(result.routing_log)
-
-Pipeline Usage:
-    >>> pipeline = TransformPipeline([
-    ...     ContentRouter(),   # Handles all content types
-    ...     RollingWindow(),   # Final size constraint
-    ... ])
-"""
-
-from __future__ import annotations
-
-import hashlib
-import logging
-import os
-import re
-import time
-from concurrent.futures import ThreadPoolExecutor
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import Any
-
-from ..config import DEFAULT_EXCLUDE_TOOLS, ReadLifecycleConfig, TransformResult
-from ..tokenizer import Tokenizer
-from .base import Transform
-from .content_detector import ContentType, DetectionResult, detect_content_type
-
-logger = logging.getLogger(__name__)
-
-_magika_detector: Any | None = None
-_magika_status: bool | None = None
-
-
-def _get_magika_detector() -> Any | None:
-    """Load the Magika detector only when router detection actually runs."""
-    global _magika_detector, _magika_status
-
-    if _magika_status is False:
-        return None
-    if _magika_detector is not None:
-        return _magika_detector
-
-    try:
-        from ..compression.detector import get_detector
-
-        _magika_detector = get_detector(prefer_magika=True)
-        _magika_status = True
-        logger.info("ContentRouter: Using Magika ML-based content detection")
-    except ImportError:
-        _magika_status = False
-        logger.debug("Magika not available, using regex-based detection")
-
-    return _magika_detector
-
-
-def _detect_content(content: str) -> DetectionResult:
-    """Detect content type using Magika if available, else regex fallback."""
-    magika_detector = _get_magika_detector()
-    if magika_detector is not None:
-        result = magika_detector.detect(content)
-        # Map Magika ContentType to router's expected format
-        type_map = {
-            "json": ContentType.JSON_ARRAY,
-            "code": ContentType.SOURCE_CODE,
-            "log": ContentType.BUILD_OUTPUT,
-            "diff": ContentType.GIT_DIFF,
-            "markdown": ContentType.PLAIN_TEXT,
-            "text": ContentType.PLAIN_TEXT,
-            "unknown": ContentType.PLAIN_TEXT,
-        }
-        mapped_type = type_map.get(result.content_type.value, ContentType.PLAIN_TEXT)
-        return DetectionResult(
-            content_type=mapped_type,
-            confidence=result.confidence,
-            metadata={"language": result.language, "raw_label": result.raw_label},
-        )
-    else:
-        return detect_content_type(content)
-
-
-def _create_content_signature(
-    content_type: str,
-    content: str,
-    language: str | None = None,
-) -> Any:
-    """Create a ToolSignature for non-JSON content types.
-
-    This allows TOIN to track compression patterns for code, search results,
-    logs, and text - not just JSON arrays.
-
-    Args:
-        content_type: The type of content (e.g., "code_aware", "search", "log", "text").
-        content: The content being compressed (for structural hints).
-        language: Optional language hint for code.
-
-    Returns:
-        A ToolSignature for TOIN tracking.
-    """
-    try:
-        from ..telemetry.models import ToolSignature
-
-        # Create a deterministic structure hash based on content type
-        # This groups similar content types together for pattern learning
-        if language:
-            hash_input = f"content:{content_type}:{language}"
-        else:
-            hash_input = f"content:{content_type}"
-
-        # Add a structural hint from the content (first 100 chars, hashed)
-        # This helps differentiate tool outputs of the same type
-        content_sample = content[:100] if content else ""
-        structure_hint = hashlib.sha256(content_sample.encode()).hexdigest()[:8]
-        hash_input = f"{hash_input}:{structure_hint}"
-
-        # Keep SHA256: structure_hash feeds into TOIN which persists to disk.
-        # Changing hash function would invalidate all learned patterns.
-        structure_hash = hashlib.sha256(hash_input.encode()).hexdigest()[:24]
-
-        return ToolSignature(
-            structure_hash=structure_hash,
-            field_count=0,  # Not applicable for non-JSON
-            has_nested_objects=False,
-            has_arrays=False,
-            max_depth=0,
-        )
-    except ImportError:
-        return None
-
-
-class CompressionCache:
-    """Two-tier compression cache with TTL.
-
-    Tier 1 (skip set): content hashes that won't compress — instant skip,
-    near-zero memory (just ints in a set).
-
-    Tier 2 (result cache): compressed results for content that DID compress —
-    reuse the compressed text on subsequent requests.
-
-    Entries expire after TTL (default 30min). No max-entries cap — TTL is the
-    natural bound. Memory grows proportional to compressible content × TTL,
-    which is bounded by session duration.
-
-    Uses in-process dict for ultra-fast lookups (~100ns). Could be backed
-    by memcached/Redis for multi-process deployments.
-    """
-
-    def __init__(self, ttl_seconds: int = 1800):
-        # Tier 2: compressed results {hash: (text, ratio, strategy, timestamp)}
-        self._results: dict[int, tuple[str, float, str, float]] = {}
-        # Tier 1: hashes of content that won't compress {hash: timestamp}
-        self._skip: dict[int, float] = {}
-        self._ttl_seconds = ttl_seconds
-        # Metrics
-        self._hits = 0
-        self._misses = 0
-        self._skip_hits = 0
-        self._evictions = 0
-        self._total_lookup_ns = 0
-        self._lookup_count = 0
-
-    def get(self, key: int) -> tuple[str, float, str] | None:
-        """Get cached compression result.
-
-        Returns (compressed_text, ratio, strategy) or None if not found/expired.
-        Use is_skipped() first to check if content is known non-compressible.
-        """
-        t0 = time.perf_counter_ns()
-        entry = self._results.get(key)
-        if entry is not None:
-            compressed, ratio, strategy, created_at = entry
-            if (time.time() - created_at) < self._ttl_seconds:
-                self._hits += 1
-                self._total_lookup_ns += time.perf_counter_ns() - t0
-                self._lookup_count += 1
-                return (compressed, ratio, strategy)
-            else:
-                del self._results[key]
-                self._evictions += 1
-        self._misses += 1
-        self._total_lookup_ns += time.perf_counter_ns() - t0
-        self._lookup_count += 1
-        return None
-
-    def is_skipped(self, key: int) -> bool:
-        """Check if content is known non-compressible (Tier 1)."""
-        ts = self._skip.get(key)
-        if ts is not None:
-            if (time.time() - ts) < self._ttl_seconds:
-                self._skip_hits += 1
-                return True
-            else:
-                del self._skip[key]
-                self._evictions += 1
-        return False
-
-    def put(self, key: int, compressed: str, ratio: float, strategy: str) -> None:
-        """Store a compressed result (Tier 2)."""
-        self._results[key] = (compressed, ratio, strategy, time.time())
-
-    def mark_skip(self, key: int) -> None:
-        """Mark content as non-compressible (Tier 1)."""
-        self._skip[key] = time.time()
-
-    def move_to_skip(self, key: int) -> None:
-        """Move a result to skip set (threshold tightened, no longer qualifies)."""
-        self._results.pop(key, None)
-        self._skip[key] = time.time()
-
-    @property
-    def size(self) -> int:
-        return len(self._results)
-
-    @property
-    def skip_size(self) -> int:
-        return len(self._skip)
-
-    @property
-    def stats(self) -> dict[str, int | float]:
-        avg_ns = self._total_lookup_ns / self._lookup_count if self._lookup_count else 0
-        return {
-            "cache_hits": self._hits,
-            "cache_skip_hits": self._skip_hits,
-            "cache_misses": self._misses,
-            "cache_evictions": self._evictions,
-            "cache_size": len(self._results),
-            "cache_skip_size": len(self._skip),
-            "cache_avg_lookup_ns": avg_ns,
-        }
-
-    def clear(self) -> None:
-        """Clear all entries (e.g., on session end)."""
-        self._results.clear()
-        self._skip.clear()
-
-
-class CompressionStrategy(Enum):
-    """Available compression strategies."""
-
-    CODE_AWARE = "code_aware"
-    SMART_CRUSHER = "smart_crusher"
-    SEARCH = "search"
-    LOG = "log"
-    KOMPRESS = "kompress"
-    TEXT = "text"
-    DIFF = "diff"
-    HTML = "html"
-    MIXED = "mixed"
-    PASSTHROUGH = "passthrough"
-
-
-@dataclass
-class RoutingDecision:
-    """Record of a single routing decision."""
-
-    content_type: ContentType
-    strategy: CompressionStrategy
-    original_tokens: int
-    compressed_tokens: int
-    confidence: float = 1.0
-    section_index: int = 0
-
-    @property
-    def compression_ratio(self) -> float:
-        if self.original_tokens == 0:
-            return 1.0
-        return self.compressed_tokens / self.original_tokens
-
-
-@dataclass
-class ContentSection:
-    """A typed section of content."""
-
-    content: str
-    content_type: ContentType
-    language: str | None = None
-    start_line: int = 0
-    end_line: int = 0
-    is_code_fence: bool = False
-
-
-@dataclass
-class RouterCompressionResult:
-    """Result from ContentRouter with routing metadata.
-
-    Attributes:
-        compressed: The compressed content.
-        original: Original content before compression.
-        strategy_used: Primary strategy used for compression.
-        routing_log: List of routing decisions made.
-        sections_processed: Number of content sections processed.
-    """
-
-    compressed: str
-    original: str
-    strategy_used: CompressionStrategy
-    routing_log: list[RoutingDecision] = field(default_factory=list)
-    sections_processed: int = 1
-
-    @property
-    def total_original_tokens(self) -> int:
-        """Total tokens before compression."""
-        return sum(r.original_tokens for r in self.routing_log)
-
-    @property
-    def total_compressed_tokens(self) -> int:
-        """Total tokens after compression."""
-        return sum(r.compressed_tokens for r in self.routing_log)
-
-    @property
-    def compression_ratio(self) -> float:
-        """Overall compression ratio."""
-        if self.total_original_tokens == 0:
-            return 1.0
-        return self.total_compressed_tokens / self.total_original_tokens
-
-    @property
-    def tokens_saved(self) -> int:
-        """Number of tokens saved."""
-        return max(0, self.total_original_tokens - self.total_compressed_tokens)
-
-    @property
-    def savings_percentage(self) -> float:
-        """Percentage of tokens saved."""
-        if self.total_original_tokens == 0:
-            return 0.0
-        return (self.tokens_saved / self.total_original_tokens) * 100
-
-    def summary(self) -> str:
-        """Human-readable routing summary."""
-        if self.strategy_used == CompressionStrategy.MIXED:
-            strategies = {r.strategy.value for r in self.routing_log}
-            return (
-                f"Mixed content: {self.sections_processed} sections, "
-                f"routed to {strategies}. "
-                f"{self.total_original_tokens:,}→{self.total_compressed_tokens:,} tokens "
-                f"({self.savings_percentage:.0f}% saved)"
-            )
-        else:
-            return (
-                f"Pure {self.strategy_used.value}: "
-                f"{self.total_original_tokens:,}→{self.total_compressed_tokens:,} tokens "
-                f"({self.savings_percentage:.0f}% saved)"
-            )
-
-
-@dataclass
-class ContentRouterConfig:
-    """Configuration for intelligent content routing.
-
-    Attributes:
-        enable_code_aware: Enable AST-based code compression.
-        enable_smart_crusher: Enable JSON array compression.
-        enable_search_compressor: Enable search result compression.
-        enable_log_compressor: Enable build/test log compression.
-        enable_image_optimizer: Enable image token optimization.
-        prefer_code_aware_for_code: Use CodeAware over Kompress for code.
-        mixed_content_threshold: Min distinct types to consider "mixed".
-        min_section_tokens: Minimum tokens for a section to compress.
-        fallback_strategy: Strategy when no compressor matches.
-        skip_user_messages: Never compress user messages (they're the subject).
-        skip_recent_messages: Don't compress last N messages (likely the subject).
-        protect_analysis_context: Detect "analyze/review" intent, skip compression.
-    """
-
-    # Enable/disable specific compressors
-    enable_code_aware: bool = False  # Disabled: use code graph MCP tools instead
-    enable_kompress: bool = True  # Kompress: ModernBERT token compressor
-    enable_smart_crusher: bool = True
-    enable_search_compressor: bool = True
-    enable_log_compressor: bool = True
-    enable_html_extractor: bool = True  # HTML content extraction
-    enable_image_optimizer: bool = True  # Image token optimization
-
-    # Routing preferences
-    prefer_code_aware_for_code: bool = False  # Disabled: let code pass through unmangled
-    mixed_content_threshold: int = 2  # Min types to consider mixed
-    min_section_tokens: int = 20  # Min tokens to compress a section
-
-    # Fallback: Kompress handles unknown/mixed content instead of passing through
-    fallback_strategy: CompressionStrategy = CompressionStrategy.KOMPRESS
-
-    # Protection: Don't compress content that's likely the subject of analysis
-    skip_user_messages: bool = True  # User messages contain what they want analyzed
-    protect_recent_code: int = 4  # Don't compress CODE in last N messages (0 = disabled)
-    protect_analysis_context: bool = True  # Detect "analyze/review" intent, protect code
-
-    # Adaptive Read protection: fraction of total messages to protect from
-    # compression.  At 10 msgs, protects ~5 Reads.  At 100 msgs, protects ~10.
-    # Old Reads beyond this window become compressible even though they are
-    # in DEFAULT_EXCLUDE_TOOLS.  0.0 = always exclude all (old behavior).
-    protect_recent_reads_fraction: float = (
-        0.0  # 0.0 = protect ALL excluded-tool outputs (safest for coding agents)
-    )
-
-    # Adaptive compression ratio: scales with context pressure.
-    # At low pressure (<30% full), use the relaxed threshold (reject marginal).
-    # At high pressure (>80% full), use the aggressive threshold (accept anything helpful).
-    # Linearly interpolates between the two.
-    min_ratio_relaxed: float = 0.85  # when context is mostly empty
-    min_ratio_aggressive: float = 0.65  # when context is nearly full
-
-    # CCR (Compress-Cache-Retrieve) settings for SmartCrusher
-    ccr_enabled: bool = True  # Enable CCR marker injection for reversible compression
-    ccr_inject_marker: bool = True  # Add retrieval markers to compressed content
-
-    # Tag protection: preserve custom/workflow XML tags from text compression.
-    # When False (default), entire <custom-tag>content</custom-tag> blocks are
-    # protected verbatim.  When True, only the tag markers are protected and
-    # the content between them can be compressed.
-    compress_tagged_content: bool = False
-
-    # Tools to exclude from compression (output passed through unmodified)
-    # Set to None to use DEFAULT_EXCLUDE_TOOLS, or provide custom set
-    exclude_tools: set[str] | None = None
-
-    # Read lifecycle management (stale/superseded detection)
-    read_lifecycle: ReadLifecycleConfig = field(default_factory=ReadLifecycleConfig)
-
-    # Per-tool compression profiles (tool_name → CompressionProfile)
-    # Set to None to use DEFAULT_TOOL_PROFILES from config
-    tool_profiles: dict[str, Any] | None = None
-
-
-# Patterns for detecting mixed content
-_CODE_FENCE_PATTERN = re.compile(r"^```(\w*)\s*$", re.MULTILINE)
-_JSON_BLOCK_START = re.compile(r"^\s*[\[{]", re.MULTILINE)
-_SEARCH_RESULT_PATTERN = re.compile(r"^\S+:\d+:", re.MULTILINE)
-_PROSE_PATTERN = re.compile(r"[A-Z][a-z]+\s+\w+\s+\w+")
-
-
-def is_mixed_content(content: str) -> bool:
-    """Detect if content contains multiple distinct types.
-
-    Args:
-        content: Content to analyze.
-
-    Returns:
-        True if content appears to be mixed (multiple types).
-    """
-    indicators = {
-        "has_code_fences": bool(_CODE_FENCE_PATTERN.search(content)),
-        "has_json_blocks": bool(_JSON_BLOCK_START.search(content)),
-        "has_prose": len(_PROSE_PATTERN.findall(content)) > 5,
-        "has_search_results": bool(_SEARCH_RESULT_PATTERN.search(content)),
-    }
-
-    # Mixed if 2+ indicators are true
-    return sum(indicators.values()) >= 2
-
-
-def split_into_sections(content: str) -> list[ContentSection]:
-    """Parse mixed content into typed sections.
-
-    Args:
-        content: Mixed content to split.
-
-    Returns:
-        List of ContentSection objects.
-    """
-    sections: list[ContentSection] = []
-    lines = content.split("\n")
-
-    i = 0
-    while i < len(lines):
-        line = lines[i]
-
-        # Code fence: ```language
-        if match := _CODE_FENCE_PATTERN.match(line):
-            language = match.group(1) or "unknown"
-            code_lines = []
-            start_line = i
-            i += 1
-
-            while i < len(lines) and not lines[i].startswith("```"):
-                code_lines.append(lines[i])
-                i += 1
-
-            sections.append(
-                ContentSection(
-                    content="\n".join(code_lines),
-                    content_type=ContentType.SOURCE_CODE,
-                    language=language,
-                    start_line=start_line,
-                    end_line=i,
-                    is_code_fence=True,
-                )
-            )
-            i += 1  # Skip closing ```
-            continue
-
-        # JSON block
-        if line.strip().startswith(("[", "{")):
-            json_content, end_i = _extract_json_block(lines, i)
-            if json_content:
-                sections.append(
-                    ContentSection(
-                        content=json_content,
-                        content_type=ContentType.JSON_ARRAY,
-                        start_line=i,
-                        end_line=end_i,
-                    )
-                )
-                i = end_i + 1
-                continue
-
-        # Search result lines
-        if _SEARCH_RESULT_PATTERN.match(line):
-            search_lines = []
-            start_line = i
-            while i < len(lines) and _SEARCH_RESULT_PATTERN.match(lines[i]):
-                search_lines.append(lines[i])
-                i += 1
-            sections.append(
-                ContentSection(
-                    content="\n".join(search_lines),
-                    content_type=ContentType.SEARCH_RESULTS,
-                    start_line=start_line,
-                    end_line=i - 1,
-                )
-            )
-            continue
-
-        # Collect text until next special section
-        text_lines = [line]
-        start_line = i
-        i += 1
-
-        while i < len(lines):
-            next_line = lines[i]
-            # Stop if we hit a special section
-            if (
-                _CODE_FENCE_PATTERN.match(next_line)
-                or next_line.strip().startswith(("[", "{"))
-                or _SEARCH_RESULT_PATTERN.match(next_line)
-            ):
-                break
-            text_lines.append(next_line)
-            i += 1
-
-        # Only add non-empty text sections
-        text_content = "\n".join(text_lines)
-        if text_content.strip():
-            sections.append(
-                ContentSection(
-                    content=text_content,
-                    content_type=ContentType.PLAIN_TEXT,
-                    start_line=start_line,
-                    end_line=i - 1,
-                )
-            )
-
-    return sections
-
-
-def _extract_json_block(lines: list[str], start: int) -> tuple[str | None, int]:
-    """Extract a complete JSON block from lines.
-
-    Args:
-        lines: All lines of content.
-        start: Starting line index.
-
-    Returns:
-        Tuple of (json_content, end_line_index) or (None, start) if invalid.
-    """
-    bracket_count = 0
-    brace_count = 0
-    json_lines = []
-
-    for i in range(start, len(lines)):
-        line = lines[i]
-        json_lines.append(line)
-
-        bracket_count += line.count("[") - line.count("]")
-        brace_count += line.count("{") - line.count("}")
-
-        if bracket_count <= 0 and brace_count <= 0 and json_lines:
-            return "\n".join(json_lines), i
-
-    # Didn't find complete JSON
-    return None, start
-
-
-class ContentRouter(Transform):
-    """Intelligent router that selects optimal compression strategy.
-
-    ContentRouter is the recommended entry point for Headroom's compression.
-    It analyzes content and routes it to the most appropriate compressor,
-    handling mixed content by splitting and reassembling.
-
-    Key Features:
-    - Automatic content type detection
-    - Source hint support for high-confidence routing
-    - Mixed content handling (split → route → reassemble)
-    - Graceful fallback when compressors unavailable
-    - Rich routing metadata for debugging
-
-    Example:
-        >>> router = ContentRouter()
-        >>>
-        >>> # Automatically uses CodeAwareCompressor
-        >>> result = router.compress(python_code)
-        >>> print(result.strategy_used)  # CompressionStrategy.CODE_AWARE
-        >>>
-        >>> # Automatically uses SmartCrusher
-        >>> result = router.compress(json_array)
-        >>> print(result.strategy_used)  # CompressionStrategy.SMART_CRUSHER
-        >>>
-        >>> # Splits and routes each section
-        >>> result = router.compress(readme_with_code)
-        >>> print(result.strategy_used)  # CompressionStrategy.MIXED
-
-    Pipeline Integration:
-        >>> pipeline = TransformPipeline([
-        ...     ContentRouter(),   # Handles ALL content types
-        ...     RollingWindow(),   # Final size constraint
-        ... ])
-    """
-
-    name: str = "content_router"
-
-    def __init__(self, config: ContentRouterConfig | None = None):
-        """Initialize content router.
-
-        Args:
-            config: Router configuration. Uses defaults if None.
-        """
-        self.config = config or ContentRouterConfig()
-
-        # Lazy-loaded compressors
-        self._code_compressor: Any = None
-        self._smart_crusher: Any = None
-        self._search_compressor: Any = None
-        self._log_compressor: Any = None
-        self._diff_compressor: Any = None
-        self._html_extractor: Any = None
-        self._kompress: Any = None
-        self._image_optimizer: Any = None
-
-        # TOIN integration for cross-strategy learning
-        self._toin: Any = None
-
-        self._cache = CompressionCache()
-
-    def _record_to_toin(
-        self,
-        strategy: CompressionStrategy,
-        content: str,
-        compressed: str,
-        original_tokens: int,
-        compressed_tokens: int,
-        language: str | None = None,
-        context: str = "",
-    ) -> None:
-        """Record compression to TOIN for cross-user learning.
-
-        This allows TOIN to track compression patterns for ALL content types,
-        not just JSON arrays. When the LLM retrieves original content via CCR,
-        TOIN learns which compressions users need to expand.
-
-        Args:
-            strategy: The compression strategy used.
-            content: Original content (for signature generation).
-            compressed: Compressed content.
-            original_tokens: Token count before compression.
-            compressed_tokens: Token count after compression.
-            language: Optional language hint for code.
-            context: Query context for pattern learning.
-        """
-        # Skip SmartCrusher - it handles its own TOIN recording
-        if strategy == CompressionStrategy.SMART_CRUSHER:
-            return
-
-        # Skip if no actual compression happened
-        if original_tokens <= compressed_tokens:
-            return
-
-        try:
-            # Lazy load TOIN
-            if self._toin is None:
-                from ..telemetry.toin import get_toin
-
-                self._toin = get_toin()
-
-            # Create a content-type signature
-            signature = _create_content_signature(
-                content_type=strategy.value,
-                content=content,
-                language=language,
-            )
-
-            if signature is None:
-                return
-
-            # Record the compression
-            self._toin.record_compression(
-                tool_signature=signature,
-                original_count=1,  # Single content block
-                compressed_count=1,
-                original_tokens=original_tokens,
-                compressed_tokens=compressed_tokens,
-                strategy=strategy.value,
-                query_context=context if context else None,
-            )
-
-            logger.debug(
-                "TOIN: Recorded %s compression: %d → %d tokens",
-                strategy.value,
-                original_tokens,
-                compressed_tokens,
-            )
-
-        except Exception as e:
-            # TOIN recording should never break compression
-            logger.debug("TOIN recording failed (non-fatal): %s", e)
-
-    def _timed_compress(
-        self, content: str, context: str, bias: float
-    ) -> tuple[RouterCompressionResult, float]:
-        """Compress with wall-clock timing.  Used by parallel executor."""
-        t0 = time.perf_counter()
-        result = self.compress(content, context=context, bias=bias)
-        return result, (time.perf_counter() - t0) * 1000
-
-    def compress(
-        self,
-        content: str,
-        context: str = "",
-        question: str | None = None,
-        bias: float = 1.0,
-    ) -> RouterCompressionResult:
-        """Compress content using optimal strategy based on content detection.
-
-        Args:
-            content: Content to compress.
-            context: Optional context for relevance-aware compression.
-            question: Optional question for QA-aware compression. When provided,
-                tokens relevant to answering this question are preserved.
-            bias: Compression bias multiplier (>1 = keep more, <1 = keep fewer).
-
-        Returns:
-            RouterCompressionResult with compressed content and routing metadata.
-        """
-        if not content or not content.strip():
-            return RouterCompressionResult(
-                compressed=content,
-                original=content,
-                strategy_used=CompressionStrategy.PASSTHROUGH,
-                routing_log=[],
-            )
-
-        # Determine strategy from content analysis
-        strategy = self._determine_strategy(content)
-
-        if strategy == CompressionStrategy.MIXED:
-            return self._compress_mixed(content, context, question, bias=bias)
-        else:
-            return self._compress_pure(content, strategy, context, question, bias=bias)
-
-    def _determine_strategy(self, content: str) -> CompressionStrategy:
-        """Determine the compression strategy from content analysis.
-
-        Args:
-            content: Content to analyze.
-
-        Returns:
-            Selected compression strategy.
-        """
-        # 1. Check for mixed content
-        if is_mixed_content(content):
-            return CompressionStrategy.MIXED
-
-        # 2. Detect content type from content itself
-        detection = _detect_content(content)
-        return self._strategy_from_detection(detection)
-
-    def _strategy_from_detection(self, detection: Any) -> CompressionStrategy:
-        """Get strategy from content detection result.
-
-        Args:
-            detection: Result from detect_content_type.
-
-        Returns:
-            Selected strategy.
-        """
-        mapping = {
-            ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,
-            ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,
-            ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,
-            ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,
-            ContentType.GIT_DIFF: CompressionStrategy.DIFF,
-            ContentType.HTML: CompressionStrategy.HTML,
-            ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,
-        }
-
-        strategy = mapping.get(detection.content_type, self.config.fallback_strategy)
-
-        # Override: prefer CodeAware for code if configured
-        if (
-            strategy == CompressionStrategy.CODE_AWARE
-            and not self.config.prefer_code_aware_for_code
-        ):
-            strategy = CompressionStrategy.KOMPRESS
-
-        return strategy
-
-    def _compress_mixed(
-        self,
-        content: str,
-        context: str,
-        question: str | None = None,
-        bias: float = 1.0,
-    ) -> RouterCompressionResult:
-        """Compress mixed content by splitting and routing sections.
-
-        Args:
-            content: Mixed content to compress.
-            context: User context for relevance.
-            question: Optional question for QA-aware compression.
-            bias: Compression bias multiplier.
-
-        Returns:
-            RouterCompressionResult with reassembled content.
-        """
-        sections = split_into_sections(content)
-
-        if not sections:
-            return RouterCompressionResult(
-                compressed=content,
-                original=content,
-                strategy_used=CompressionStrategy.PASSTHROUGH,
-            )
-
-        compressed_sections: list[str] = []
-        routing_log: list[RoutingDecision] = []
-
-        for i, section in enumerate(sections):
-            # Get strategy for this section
-            strategy = self._strategy_from_detection_type(section.content_type)
-
-            # Compress section
-            original_tokens = len(section.content.split())
-            compressed_content, compressed_tokens = self._apply_strategy_to_content(
-                section.content,
-                strategy,
-                context,
-                section.language,
-                question,
-                bias=bias,
-            )
-
-            # Preserve code fence markers
-            if section.is_code_fence and section.language:
-                compressed_content = f"```{section.language}\n{compressed_content}\n```"
-
-            compressed_sections.append(compressed_content)
-            routing_log.append(
-                RoutingDecision(
-                    content_type=section.content_type,
-                    strategy=strategy,
-                    original_tokens=original_tokens,
-                    compressed_tokens=compressed_tokens,
-                    section_index=i,
-                )
-            )
-
-        return RouterCompressionResult(
-            compressed="\n\n".join(compressed_sections),
-            original=content,
-            strategy_used=CompressionStrategy.MIXED,
-            routing_log=routing_log,
-            sections_processed=len(sections),
-        )
-
-    def _compress_pure(
-        self,
-        content: str,
-        strategy: CompressionStrategy,
-        context: str,
-        question: str | None = None,
-        bias: float = 1.0,
-    ) -> RouterCompressionResult:
-        """Compress pure (non-mixed) content.
-
-        Args:
-            content: Content to compress.
-            strategy: Selected strategy.
-            context: User context.
-            question: Optional question for QA-aware compression.
-            bias: Compression bias multiplier.
-
-        Returns:
-            RouterCompressionResult.
-        """
-        original_tokens = len(content.split())
-
-        compressed, compressed_tokens = self._apply_strategy_to_content(
-            content, strategy, context, question=question, bias=bias
-        )
-
-        return RouterCompressionResult(
-            compressed=compressed,
-            original=content,
-            strategy_used=strategy,
-            routing_log=[
-                RoutingDecision(
-                    content_type=self._content_type_from_strategy(strategy),
-                    strategy=strategy,
-                    original_tokens=original_tokens,
-                    compressed_tokens=compressed_tokens,
-                )
-            ],
-        )
-
-    def _apply_strategy_to_content(
-        self,
-        content: str,
-        strategy: CompressionStrategy,
-        context: str,
-        language: str | None = None,
-        question: str | None = None,
-        bias: float = 1.0,
-    ) -> tuple[str, int]:
-        """Apply a compression strategy to content.
-
-        Args:
-            content: Content to compress.
-            strategy: Strategy to use.
-            context: User context.
-            language: Language hint for code.
-            question: Optional question for QA-aware compression.
-            bias: Compression bias multiplier (>1 = keep more, <1 = keep fewer).
-
-        Returns:
-            Tuple of (compressed_content, compressed_token_count).
-        """
-        # Track original tokens for TOIN recording
-        original_tokens = len(content.split())
-        compressed: str | None = None
-        compressed_tokens: int | None = None
-
-        try:
-            if strategy == CompressionStrategy.CODE_AWARE:
-                if self.config.enable_code_aware:
-                    compressor = self._get_code_compressor()
-                    if compressor:
-                        result = compressor.compress(content, language=language, context=context)
-                        compressed, compressed_tokens = result.compressed, result.compressed_tokens
-                if compressed is None:
-                    # Fallback to Kompress
-                    compressed, compressed_tokens = self._try_ml_compressor(
-                        content, context, question
-                    )
-                    strategy = CompressionStrategy.KOMPRESS  # Update for TOIN
-
-            elif strategy == CompressionStrategy.SMART_CRUSHER:
-                # SmartCrusher handles its own TOIN recording
-                if self.config.enable_smart_crusher:
-                    crusher = self._get_smart_crusher()
-                    if crusher:
-                        result = crusher.crush(content, query=context, bias=bias)
-                        return result.compressed, len(result.compressed.split())
-
-            elif strategy == CompressionStrategy.SEARCH:
-                if self.config.enable_search_compressor:
-                    compressor = self._get_search_compressor()
-                    if compressor:
-                        result = compressor.compress(content, context=context, bias=bias)
-                        compressed, compressed_tokens = (
-                            result.compressed,
-                            len(result.compressed.split()),
-                        )
-
-            elif strategy == CompressionStrategy.LOG:
-                if self.config.enable_log_compressor:
-                    compressor = self._get_log_compressor()
-                    if compressor:
-                        result = compressor.compress(content, bias=bias)
-                        compressed, compressed_tokens = (
-                            result.compressed,
-                            result.compressed_line_count,
-                        )
-
-            elif strategy == CompressionStrategy.DIFF:
-                compressor = self._get_diff_compressor()
-                if compressor:
-                    result = compressor.compress(content, context=context)
-                    compressed, compressed_tokens = (
-                        result.compressed,
-                        result.compressed_line_count,
-                    )
-
-            elif strategy == CompressionStrategy.HTML:
-                if self.config.enable_html_extractor:
-                    extractor = self._get_html_extractor()
-                    if extractor:
-                        result = extractor.extract(content)
-                        compressed = result.extracted
-                        # Estimate tokens from extracted text (simple word count)
-                        compressed_tokens = len(compressed.split()) if compressed else 0
-
-            elif strategy == CompressionStrategy.KOMPRESS:
-                compressed, compressed_tokens = self._try_ml_compressor(content, context, question)
-
-            elif strategy == CompressionStrategy.TEXT:
-                # Prefer Kompress ML compressor for text
-                # Passes through unchanged if Kompress not available
-                compressed, compressed_tokens = self._try_ml_compressor(content, context, question)
-
-        except Exception as e:
-            logger.warning("Compression with %s failed: %s", strategy.value, e)
-
-        # If compression succeeded, record to TOIN
-        if compressed is not None and compressed_tokens is not None:
-            self._record_to_toin(
-                strategy=strategy,
-                content=content,
-                compressed=compressed,
-                original_tokens=original_tokens,
-                compressed_tokens=compressed_tokens,
-                language=language,
-                context=context,
-            )
-            return compressed, compressed_tokens
-
-        # Fallback: return unchanged
-        return content, original_tokens
-
-    def _try_ml_compressor(
-        self, content: str, context: str, question: str | None = None
-    ) -> tuple[str, int]:
-        """ML-based compression using Kompress.
-
-        Kompress (ModernBERT, trained on 330K structured tool outputs)
-        auto-downloads from HuggingFace on first use. No heuristic fallback.
-
-        Custom/workflow XML tags (<system-reminder>, <tool_call>, <thinking>)
-        are protected before compression and restored after.  Standard HTML
-        tags are left alone (HTMLExtractor handles those separately).
-
-        Args:
-            content: Content to compress.
-            context: User context.
-            question: Optional question for QA-aware compression.
-
-        Returns:
-            Tuple of (compressed, token_count).
-        """
-        from .tag_protector import protect_tags, restore_tags
-
-        # Protect custom tags before any ML compression
-        cleaned, protected = protect_tags(
-            content,
-            compress_tagged_content=self.config.compress_tagged_content,
-        )
-
-        # If the entire content is custom tags with nothing to compress
-        if protected and not cleaned.strip():
-            return content, len(content.split())
-
-        # Use the cleaned (tag-free) text for compression
-        text_to_compress = cleaned if protected else content
-        compressed: str | None = None
-        compressed_tokens: int | None = None
-
-        # Primary: Kompress — downloads from chopratejas/kompress-base on first use
-        if self.config.enable_kompress:
-            compressor = self._get_kompress()
-            if compressor:
-                try:
-                    result = compressor.compress(
-                        text_to_compress,
-                        context=context,
-                        question=question,
-                        target_ratio=getattr(self, "_runtime_target_ratio", None),
-                    )
-                    compressed = result.compressed
-                    compressed_tokens = result.compressed_tokens
-                except Exception as e:
-                    logger.warning("Kompress failed: %s", e)
-
-        if compressed is None:
-            return content, len(content.split())
-
-        # Restore protected tag blocks into the compressed text
-        if protected:
-            compressed = restore_tags(compressed, protected)
-            compressed_tokens = len(compressed.split())
-
-        return compressed, compressed_tokens or len(compressed.split())
-
-    def _strategy_from_detection_type(self, content_type: ContentType) -> CompressionStrategy:
-        """Get strategy from ContentType enum."""
-        mapping = {
-            ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,
-            ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,
-            ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,
-            ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,
-            ContentType.GIT_DIFF: CompressionStrategy.DIFF,
-            ContentType.HTML: CompressionStrategy.HTML,
-            ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,
-        }
-        return mapping.get(content_type, self.config.fallback_strategy)
-
-    def _content_type_from_strategy(self, strategy: CompressionStrategy) -> ContentType:
-        """Get ContentType from strategy."""
-        mapping = {
-            CompressionStrategy.CODE_AWARE: ContentType.SOURCE_CODE,
-            CompressionStrategy.SMART_CRUSHER: ContentType.JSON_ARRAY,
-            CompressionStrategy.SEARCH: ContentType.SEARCH_RESULTS,
-            CompressionStrategy.LOG: ContentType.BUILD_OUTPUT,
-            CompressionStrategy.DIFF: ContentType.GIT_DIFF,
-            CompressionStrategy.HTML: ContentType.HTML,
-            CompressionStrategy.TEXT: ContentType.PLAIN_TEXT,
-            CompressionStrategy.KOMPRESS: ContentType.PLAIN_TEXT,
-            CompressionStrategy.PASSTHROUGH: ContentType.PLAIN_TEXT,
-        }
-        return mapping.get(strategy, ContentType.PLAIN_TEXT)
-
-    # Lazy compressor getters
-
-    def _get_code_compressor(self) -> Any:
-        """Get CodeAwareCompressor (lazy load)."""
-        if self._code_compressor is None:
-            try:
-                from .code_compressor import CodeAwareCompressor, _check_tree_sitter_available
-
-                if _check_tree_sitter_available():
-                    self._code_compressor = CodeAwareCompressor()
-                else:
-                    logger.debug("tree-sitter not available")
-            except ImportError:
-                logger.debug("CodeAwareCompressor not available")
-        return self._code_compressor
-
-    def _get_smart_crusher(self) -> Any:
-        """Get SmartCrusher (lazy load) with CCR config."""
-        if self._smart_crusher is None:
-            try:
-                from ..config import CCRConfig
-                from .smart_crusher import SmartCrusher
-
-                # Pass CCR config for marker injection
-                ccr_config = CCRConfig(
-                    enabled=self.config.ccr_enabled,
-                    inject_retrieval_marker=self.config.ccr_inject_marker,
-                )
-                self._smart_crusher = SmartCrusher(ccr_config=ccr_config)
-            except ImportError:
-                logger.debug("SmartCrusher not available")
-        return self._smart_crusher
-
-    def _get_search_compressor(self) -> Any:
-        """Get SearchCompressor (lazy load)."""
-        if self._search_compressor is None:
-            try:
-                from .search_compressor import SearchCompressor
-
-                self._search_compressor = SearchCompressor()
-            except ImportError:
-                logger.debug("SearchCompressor not available")
-        return self._search_compressor
-
-    def _get_log_compressor(self) -> Any:
-        """Get LogCompressor (lazy load)."""
-        if self._log_compressor is None:
-            try:
-                from .log_compressor import LogCompressor
-
-                self._log_compressor = LogCompressor()
-            except ImportError:
-                logger.debug("LogCompressor not available")
-        return self._log_compressor
-
-    def _get_diff_compressor(self) -> Any:
-        """Get DiffCompressor (lazy load)."""
-        if self._diff_compressor is None:
-            try:
-                from .diff_compressor import DiffCompressor
-
-                self._diff_compressor = DiffCompressor()
-            except ImportError:
-                logger.debug("DiffCompressor not available")
-        return self._diff_compressor
-
-    def _get_html_extractor(self) -> Any:
-        """Get HTMLExtractor (lazy load)."""
-        if self._html_extractor is None:
-            try:
-                from .html_extractor import HTMLExtractor
-
-                self._html_extractor = HTMLExtractor()
-            except ImportError:
-                logger.debug("HTMLExtractor not available (install trafilatura)")
-        return self._html_extractor
-
-    def eager_load_compressors(self) -> dict[str, str]:
-        """Pre-load compressors at startup to avoid first-request latency.
-
-        Call this during proxy startup to load models and parsers
-        before any requests arrive. Eliminates cold-start latency spikes.
-
-        Returns:
-            Dict of component name -> status string for logging.
-        """
-        status: dict[str, str] = {}
-
-        # 1. ML text compressor: Kompress
-        if self.config.enable_kompress:
-            compressor = self._get_kompress()
-            if compressor:
-                logger.info("Kompress model pre-loaded at startup")
-                status["kompress"] = "enabled"
-            else:
-                status["kompress"] = "unavailable"
-
-        # 2. Magika content detector (avoids 100-200ms on first content detection)
-        try:
-            from ..compression.detector import _get_magika, _magika_available
-
-            if _magika_available():
-                _get_magika()  # Initializes the singleton
-                logger.info("Magika content detector pre-loaded at startup")
-                status["magika"] = "enabled"
-            else:
-                status["magika"] = "not installed"
-        except Exception as e:
-            logger.debug("Magika pre-load skipped: %s", e)
-            status["magika"] = "skipped"
-
-        # 3. CodeAware compressor + common tree-sitter parsers
-        if self.config.enable_code_aware:
-            code_compressor = self._get_code_compressor()
-            if code_compressor:
-                status["code_aware"] = "enabled"
-                # Pre-load tree-sitter parsers for common languages
-                # Each parser is ~50ms to load; doing it here avoids 500ms+ on first code hit
-                try:
-                    from .code_compressor import _check_tree_sitter_available, _get_parser
-
-                    if _check_tree_sitter_available():
-                        common_languages = [
-                            "python",
-                            "javascript",
-                            "typescript",
-                            "go",
-                            "rust",
-                            "java",
-                            "c",
-                            "cpp",
-                        ]
-                        loaded = []
-                        for lang in common_languages:
-                            try:
-                                _get_parser(lang)
-                                loaded.append(lang)
-                            except (ValueError, ImportError):
-                                pass  # Language not available, skip
-                        if loaded:
-                            logger.info("Tree-sitter parsers pre-loaded: %s", ", ".join(loaded))
-                            status["tree_sitter"] = f"loaded ({len(loaded)} languages)"
-                except Exception as e:
-                    logger.debug("Tree-sitter pre-load skipped: %s", e)
-                    status["tree_sitter"] = "skipped"
-            else:
-                status["code_aware"] = "not installed"
-
-        # 4. SmartCrusher (lightweight init, but ensures import + TOIN ready)
-        smart_crusher = self._get_smart_crusher()
-        if smart_crusher:
-            status["smart_crusher"] = "ready"
-
-        return status
-
-    def _get_kompress(self) -> Any:
-        """Get KompressCompressor (lazy load). Downloads from HuggingFace on first use.
-
-        Respects runtime kompress_model kwarg:
-        - None: use default (chopratejas/kompress-base) — cached on self
-        - "disabled": return None (skip ML compression entirely)
-        - any model ID string: create compressor with that model
-          (model weights are cached at module level in kompress_compressor.py,
-          so repeated calls with the same model_id are cheap)
-        """
-        model_id = getattr(self, "_runtime_kompress_model", None)
-
-        # Explicitly disabled — no ML compression
-        if model_id == "disabled":
-            return None
-
-        # Custom model — don't touch self._kompress (that's the default cache)
-        if model_id:
-            try:
-                from .kompress_compressor import (
-                    KompressCompressor,
-                    KompressConfig,
-                    is_kompress_available,
-                )
-
-                if is_kompress_available():
-                    return KompressCompressor(config=KompressConfig(model_id=model_id))
-            except ImportError:
-                pass
-            return None
-
-        # Default path — exactly as before, cached on self
-        if self._kompress is None:
-            try:
-                from .kompress_compressor import KompressCompressor, is_kompress_available
-
-                if is_kompress_available():
-                    self._kompress = KompressCompressor()
-            except ImportError:
-                logger.debug("Kompress dependencies not available")
-        return self._kompress
-
-    def _get_image_optimizer(self) -> Any:
-        """Get ImageCompressor (lazy load).
-
-        The ImageCompressor handles image token compression using:
-        - Trained MiniLM classifier from HuggingFace (chopratejas/technique-router)
-        - SigLIP for image analysis
-        - Provider-specific compression (OpenAI detail, Anthropic/Google resize)
-        """
-        if self._image_optimizer is None:
-            try:
-                from ..image import ImageCompressor
-
-                self._image_optimizer = ImageCompressor()
-            except ImportError:
-                logger.debug("ImageCompressor not available")
-        return self._image_optimizer
-
-    def optimize_images_in_messages(
-        self,
-        messages: list[dict[str, Any]],
-        tokenizer: Tokenizer,
-        provider: str = "openai",
-        user_query: str | None = None,
-    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
-        """Optimize images in messages.
-
-        This is a convenience method for image optimization that can be called
-        directly or as part of the transform pipeline.
-
-        Uses ImageCompressor with trained MiniLM router from HuggingFace
-        (chopratejas/technique-router) + SigLIP for image analysis.
-
-        Args:
-            messages: Messages potentially containing images.
-            tokenizer: Tokenizer for token counting (unused, kept for API compat).
-            provider: LLM provider (openai, anthropic, google).
-            user_query: User query for task intent detection (unused, auto-extracted).
-
-        Returns:
-            Tuple of (optimized_messages, metrics).
-        """
-        if not self.config.enable_image_optimizer:
-            return messages, {"images_optimized": 0, "tokens_saved": 0}
-
-        compressor = self._get_image_optimizer()
-        if compressor is None:
-            return messages, {"images_optimized": 0, "tokens_saved": 0}
-
-        # Check if there are images to compress
-        if not compressor.has_images(messages):
-            return messages, {"images_optimized": 0, "tokens_saved": 0}
-
-        # Compress images (query is auto-extracted from messages)
-        optimized = compressor.compress(messages, provider=provider)
-
-        # Get metrics from last compression
-        result = compressor.last_result
-        if result:
-            metrics = {
-                "images_optimized": result.compressed_tokens < result.original_tokens,
-                "tokens_before": result.original_tokens,
-                "tokens_after": result.compressed_tokens,
-                "tokens_saved": result.original_tokens - result.compressed_tokens,
-                "technique": result.technique.value,
-                "confidence": result.confidence,
-            }
-        else:
-            metrics = {"images_optimized": 0, "tokens_saved": 0}
-
-        return optimized, metrics
-
-    # Transform interface
-
-    def _build_tool_name_map(self, messages: list[dict[str, Any]]) -> dict[str, str]:
-        """Build mapping from tool_call_id to tool_name.
-
-        Scans assistant messages to find tool calls and extract their names.
-        Supports both OpenAI and Anthropic message formats.
-        """
-        mapping: dict[str, str] = {}
-
-        for msg in messages:
-            if msg.get("role") != "assistant":
-                continue
-
-            # OpenAI format: tool_calls array
-            for tc in msg.get("tool_calls", []):
-                if isinstance(tc, dict):
-                    tc_id = tc.get("id", "")
-                    name = tc.get("function", {}).get("name", "")
-                    if tc_id and name:
-                        mapping[tc_id] = name
-
-            # Anthropic format: content blocks with type=tool_use
-            content = msg.get("content", [])
-            if isinstance(content, list):
-                for block in content:
-                    if isinstance(block, dict) and block.get("type") == "tool_use":
-                        tc_id = block.get("id", "")
-                        name = block.get("name", "")
-                        if tc_id and name:
-                            mapping[tc_id] = name
-
-        return mapping
-
-    def apply(
-        self,
-        messages: list[dict[str, Any]],
-        tokenizer: Tokenizer,
-        **kwargs: Any,
-    ) -> TransformResult:
-        """Apply intelligent routing to messages.
-
-        Args:
-            messages: Messages to transform.
-            tokenizer: Tokenizer for counting.
-            **kwargs: Additional arguments (context).
-
-        Returns:
-            TransformResult with routed and compressed messages.
-        """
-        # Pre-process: Read lifecycle management (stale/superseded detection)
-        if self.config.read_lifecycle.enabled:
-            from .read_lifecycle import ReadLifecycleManager
-
-            lifecycle_mgr = ReadLifecycleManager(
-                self.config.read_lifecycle,
-                compression_store=kwargs.get("compression_store"),
-            )
-            lifecycle_result = lifecycle_mgr.apply(
-                messages,
-                frozen_message_count=kwargs.get("frozen_message_count", 0),
-            )
-            messages = lifecycle_result.messages
-            # lifecycle transforms tracked separately, merged at the end
-            lifecycle_transforms = lifecycle_result.transforms_applied
-            lifecycle_ccr_hashes = lifecycle_result.ccr_hashes
-        else:
-            lifecycle_transforms = []
-            lifecycle_ccr_hashes = []
-
-        # Runtime overrides from CompressConfig (via kwargs from compress())
-        # These override self.config defaults for this call only.
-        skip_user = (
-            kwargs.get("compress_user_messages") is not True and self.config.skip_user_messages
-        )
-        skip_system = kwargs.get("compress_system_messages") is False
-        protect_recent = kwargs.get("protect_recent", self.config.protect_recent_code)
-        protect_analysis = kwargs.get(
-            "protect_analysis_context", self.config.protect_analysis_context
-        )
-        min_tokens = kwargs.get("min_tokens_to_compress", 50)
-        # Store runtime options on self for access by _route_and_compress_block
-        self._runtime_target_ratio: float | None = kwargs.get("target_ratio")
-        self._runtime_kompress_model: str | None = kwargs.get("kompress_model")
-
-        tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)
-        context = kwargs.get("context", "")
-        hook_biases: dict[int, float] = kwargs.get("biases") or {}
-
-        # Build tool name map for exclusion checking
-        tool_name_map = self._build_tool_name_map(messages)
-
-        # Compute excluded tool IDs based on config
-        exclude_tools = (
-            self.config.exclude_tools
-            if self.config.exclude_tools is not None
-            else DEFAULT_EXCLUDE_TOOLS
-        )
-        excluded_tool_ids = {
-            tool_id for tool_id, name in tool_name_map.items() if name in exclude_tools
-        }
-
-        # --- Adaptive parameters based on context pressure ---
-        num_messages = len(messages)
-        model_limit = kwargs.get("model_limit", 0)
-
-        # Adaptive Read protection: protect a fraction of recent messages
-        if self.config.protect_recent_reads_fraction > 0:
-            # Scale: at 10 msgs protect 5, at 50 msgs protect 25, at 200 msgs protect 100
-            # But cap at a reasonable floor so very short convos still protect everything
-            read_protection_window = max(
-                4,  # always protect at least last 4 messages
-                int(num_messages * self.config.protect_recent_reads_fraction),
-            )
-        else:
-            read_protection_window = num_messages  # 0.0 = protect all (old behavior)
-
-        # Adaptive compression ratio: scale with context pressure
-        if model_limit > 0:
-            context_pressure = min(1.0, tokens_before / model_limit)
-        else:
-            context_pressure = 0.5  # default: moderate
-
-        # Linear interpolation between relaxed and aggressive thresholds
-        # pressure 0.0 → relaxed, pressure 1.0 → aggressive
-        min_ratio = (
-            self.config.min_ratio_relaxed
-            + (self.config.min_ratio_aggressive - self.config.min_ratio_relaxed) * context_pressure
-        )
-        # Clamp to [aggressive, relaxed] range
-        min_ratio = max(
-            self.config.min_ratio_aggressive,
-            min(self.config.min_ratio_relaxed, min_ratio),
-        )
-
-        if context_pressure > 0.3:
-            logger.debug(
-                "content_router adaptive: pressure=%.2f, min_ratio=%.2f, "
-                "read_protect_window=%d/%d msgs",
-                context_pressure,
-                min_ratio,
-                read_protection_window,
-                num_messages,
-            )
-
-        transformed_messages: list[dict[str, Any]] = []
-        transforms_applied: list[str] = []
-        warnings: list[str] = []
-        compressor_timing: dict[str, float] = {}  # strategy → cumulative ms
-
-        # Routing reason counters for summary logging
-        route_counts: dict[str, int] = {
-            "excluded_tool": 0,
-            "user_msg": 0,
-            "small": 0,
-            "recent_code": 0,
-            "analysis_ctx": 0,
-            "ratio_too_high": 0,
-            "non_string": 0,
-            "content_blocks": 0,
-        }
-        compressed_details: list[str] = []  # e.g. ["code_aware:0.72", "kompress:0.65"]
-
-        # Check for analysis intent in the most recent user message
-        analysis_intent = False
-        if self.config.protect_analysis_context:
-            analysis_intent = self._detect_analysis_intent(messages)
-
-        frozen_message_count = kwargs.get("frozen_message_count", 0)
-
-        # ------------------------------------------------------------------
-        # Two-pass parallel compression.
-        #
-        # Pass 1 (sequential): categorise every message — frozen, protected,
-        #   cached, small, etc. are resolved immediately.  Cache-miss messages
-        #   that need full compression are collected into *pending_tasks*.
-        #
-        # Pass 2 (parallel): all cache-miss compressions run concurrently in
-        #   a thread pool.  Each self.compress() call is independent.
-        #
-        # Pass 3 (sequential): results are stitched back into message order,
-        #   caches updated, and counters incremented.
-        # ------------------------------------------------------------------
-
-        # Pre-allocate result slots — None means "pending compression".
-        result_slots: list[dict[str, Any] | None] = [None] * num_messages
-
-        # Tasks: list of (slot_index, content, context, bias, content_key)
-        _PendingTask = tuple[int, str, str, float, int]
-        pending_tasks: list[_PendingTask] = []
-
-        for i, message in enumerate(messages):
-            # Skip frozen messages (in provider's prefix cache).
-            # Modifying these would invalidate the cache, replacing a 90%
-            # read discount with a 25% write penalty (Anthropic).
-            if i < frozen_message_count:
-                result_slots[i] = message
-                continue
-
-            role = message.get("role", "")
-            content = message.get("content", "")
-            bias = 1.0  # Default bias, may be overridden for tool messages
-
-            messages_from_end = num_messages - i
-
-            # Handle list content (Anthropic format with content blocks)
-            if isinstance(content, list):
-                transformed_message = self._process_content_blocks(
-                    message,
-                    content,
-                    context,
-                    transforms_applied,
-                    excluded_tool_ids,
-                    tool_name_map=tool_name_map,
-                    route_counts=route_counts,
-                    compressed_details=compressed_details,
-                    min_ratio=min_ratio,
-                    read_protection_window=read_protection_window,
-                    messages_from_end=messages_from_end,
-                    compressor_timing=compressor_timing,
-                )
-                result_slots[i] = transformed_message
-                route_counts["content_blocks"] += 1
-                continue
-
-            # Skip non-string content (other types)
-            if not isinstance(content, str):
-                result_slots[i] = message
-                route_counts["non_string"] += 1
-                continue
-
-            # Skip OpenAI-style tool messages for excluded tools
-            # BUT: allow compression of old excluded-tool outputs beyond the
-            # adaptive protection window (age-based decay).
-            if role == "tool":
-                tool_call_id = message.get("tool_call_id", "")
-                if tool_call_id in excluded_tool_ids:
-                    if messages_from_end <= read_protection_window:
-                        # Recent — protect as before
-                        result_slots[i] = message
-                        transforms_applied.append("router:excluded:tool")
-                        route_counts["excluded_tool"] += 1
-                        continue
-                    # Old excluded-tool output — fall through to compression
-                    # (the LLM is unlikely to need exact content from this far back,
-                    # and CCR provides retrieval if it does)
-                # Look up tool-specific compression bias for OpenAI tool messages
-                tool_name = tool_name_map.get(tool_call_id, "")
-                bias = self._get_tool_bias(tool_name) if tool_name else 1.0
-
-            # Protection 1: Never compress user messages (unless overridden)
-            if skip_user and role == "user":
-                result_slots[i] = message
-                transforms_applied.append("router:protected:user_message")
-                route_counts["user_msg"] += 1
-                continue
-
-            # Protection 1b: Never compress system messages (when disabled)
-            if skip_system and role == "system":
-                result_slots[i] = message
-                transforms_applied.append("router:protected:system_message")
-                route_counts.setdefault("system_msg", 0)
-                route_counts["system_msg"] += 1
-                continue
-
-            if not content or tokenizer.count_text(content) < min_tokens:
-                # Skip small content
-                result_slots[i] = message
-                route_counts["small"] += 1
-                continue
-
-            # Detect content type for protection decisions
-            detection = _detect_content(content)
-            is_code = detection.content_type == ContentType.SOURCE_CODE
-
-            # Protection 2: Don't compress recent CODE
-            messages_from_end = num_messages - i
-            if protect_recent > 0 and messages_from_end <= protect_recent and is_code:
-                result_slots[i] = message
-                transforms_applied.append("router:protected:recent_code")
-                route_counts["recent_code"] += 1
-                continue
-
-            # Protection 3: Don't compress CODE when analysis intent detected
-            if protect_analysis and analysis_intent and is_code:
-                result_slots[i] = message
-                transforms_applied.append("router:protected:analysis_context")
-                route_counts["analysis_ctx"] += 1
-                continue
-
-            # Compression pinning: if this message was already compressed
-            # (contains a CCR retrieval marker), skip recompression.
-            # Recompressing would change byte content and break provider
-            # prefix caching with no meaningful further reduction.
-            if "Retrieve more: hash=" in content or "Retrieve original: hash=" in content:
-                result_slots[i] = message
-                route_counts.setdefault("already_compressed", 0)
-                route_counts["already_compressed"] += 1
-                continue
-
-            # Route and compress based on content detection
-            # Merge tool-specific bias with hook-provided bias (multiplicative)
-            msg_bias = bias if role == "tool" else 1.0
-            if i in hook_biases:
-                msg_bias *= hook_biases[i]
-
-            # 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)
-
-            # Tier 1: skip set — instant rejection
-            if self._cache.is_skipped(content_key):
-                result_slots[i] = message
-                route_counts["ratio_too_high"] += 1
-                route_counts.setdefault("cache_hit", 0)
-                route_counts["cache_hit"] += 1
-                continue
-
-            # Tier 2: result cache — reuse compressed output
-            cached = self._cache.get(content_key)
-            if cached is not None:
-                cached_compressed, cached_ratio, cached_strategy = cached
-                # Re-check ratio against current min_ratio (shifts with context pressure)
-                if cached_ratio < min_ratio:
-                    result_slots[i] = {**message, "content": cached_compressed}
-                    transforms_applied.append(f"router:{cached_strategy}:{cached_ratio:.2f}")
-                    compressed_details.append(f"{cached_strategy}:{cached_ratio:.2f}")
-                else:
-                    # Threshold tightened — no longer qualifies. Move to skip.
-                    self._cache.move_to_skip(content_key)
-                    result_slots[i] = message
-                    route_counts["ratio_too_high"] += 1
-                route_counts.setdefault("cache_hit", 0)
-                route_counts["cache_hit"] += 1
-                continue
-
-            # Cache miss — defer to parallel compression pass
-            route_counts.setdefault("cache_miss", 0)
-            route_counts["cache_miss"] += 1
-            pending_tasks.append((i, content, context, msg_bias, content_key))
-
-        # --- Pass 2: Parallel compression of all cache-miss messages ---
-        if pending_tasks:
-            max_workers = min(
-                len(pending_tasks), int(os.environ.get("HEADROOM_COMPRESS_WORKERS", "4"))
-            )
-            t_parallel_start = time.perf_counter()
-
-            if max_workers <= 1 or len(pending_tasks) == 1:
-                # Single task or parallelism disabled — compress inline
-                task_results = []
-                for _, task_content, task_ctx, task_bias, _ in pending_tasks:
-                    t0 = time.perf_counter()
-                    r = self.compress(task_content, context=task_ctx, bias=task_bias)
-                    task_results.append((r, (time.perf_counter() - t0) * 1000))
-            else:
-                # Parallel compression via thread pool
-                with ThreadPoolExecutor(max_workers=max_workers) as executor:
-                    futures = []
-                    for _, task_content, task_ctx, task_bias, _ in pending_tasks:
-                        futures.append(
-                            executor.submit(self._timed_compress, task_content, task_ctx, task_bias)
-                        )
-                    task_results = [f.result() for f in futures]
-
-            parallel_ms = (time.perf_counter() - t_parallel_start) * 1000
-            compressor_timing["parallel_compress_total"] = parallel_ms
-
-            # --- Pass 3: Merge results back (sequential, updates caches) ---
-            for (slot_idx, _, _, _, content_key), (result, compress_ms) in zip(
-                pending_tasks, task_results
-            ):
-                message = messages[slot_idx]
-                strategy_key = f"compressor:{result.strategy_used.value}"
-                compressor_timing[strategy_key] = (
-                    compressor_timing.get(strategy_key, 0.0) + compress_ms
-                )
-
-                if result.compression_ratio < min_ratio:
-                    # Compressed — store in result cache
-                    self._cache.put(
-                        content_key,
-                        result.compressed,
-                        result.compression_ratio,
-                        result.strategy_used.value,
-                    )
-                    result_slots[slot_idx] = {**message, "content": result.compressed}
-                    transforms_applied.append(
-                        f"router:{result.strategy_used.value}:{result.compression_ratio:.2f}"
-                    )
-                    compressed_details.append(
-                        f"{result.strategy_used.value}:{result.compression_ratio:.2f}"
-                    )
-                else:
-                    # Didn't compress — add to skip set
-                    self._cache.mark_skip(content_key)
-                    result_slots[slot_idx] = message
-                    route_counts["ratio_too_high"] += 1
-
-        # Build final message list from slots
-        transformed_messages = [m for m in result_slots if m is not None]
-
-        tokens_after = sum(
-            tokenizer.count_text(str(m.get("content", ""))) for m in transformed_messages
-        )
-
-        # Log routing summary
-        parts = []
-        if compressed_details:
-            parts.append(f"{len(compressed_details)} compressed ({', '.join(compressed_details)})")
-        if route_counts["excluded_tool"]:
-            parts.append(f"{route_counts['excluded_tool']} excluded (Read/Glob)")
-        if route_counts["user_msg"]:
-            parts.append(f"{route_counts['user_msg']} skipped (user)")
-        if route_counts["small"]:
-            parts.append(f"{route_counts['small']} skipped (<50 words)")
-        if route_counts["recent_code"]:
-            parts.append(f"{route_counts['recent_code']} protected (recent code)")
-        if route_counts["analysis_ctx"]:
-            parts.append(f"{route_counts['analysis_ctx']} protected (analysis ctx)")
-        if route_counts.get("already_compressed"):
-            parts.append(f"{route_counts['already_compressed']} pinned (already compressed)")
-        if route_counts["ratio_too_high"]:
-            parts.append(f"{route_counts['ratio_too_high']} unchanged (ratio>={min_ratio:.2f})")
-        if route_counts["content_blocks"]:
-            parts.append(f"{route_counts['content_blocks']} content-block msgs")
-        if route_counts["non_string"]:
-            parts.append(f"{route_counts['non_string']} non-string")
-        if route_counts.get("cache_hit"):
-            parts.append(f"{route_counts['cache_hit']} cache hits")
-        if route_counts.get("cache_miss"):
-            parts.append(f"{route_counts['cache_miss']} cache misses")
-        cs = self._cache.stats
-        if cs["cache_size"] > 0 or cs["cache_skip_size"] > 0:
-            parts.append(
-                f"cache[{cs['cache_size']} results, {cs['cache_skip_size']} skips, "
-                f"{cs['cache_avg_lookup_ns']:.0f}ns avg]"
-            )
-        if parts:
-            logger.info(
-                "content_router: %d msgs — %s",
-                num_messages,
-                ", ".join(parts),
-            )
-
-        all_transforms = lifecycle_transforms + transforms_applied
-        return TransformResult(
-            messages=transformed_messages,
-            tokens_before=tokens_before,
-            tokens_after=tokens_after,
-            transforms_applied=all_transforms if all_transforms else ["router:noop"],
-            markers_inserted=lifecycle_ccr_hashes,
-            warnings=warnings,
-            timing=compressor_timing,
-        )
-
-    def _get_tool_bias(self, tool_name: str) -> float:
-        """Look up compression bias for a tool name.
-
-        Checks user-configured profiles first, then DEFAULT_TOOL_PROFILES.
-        Returns 1.0 (moderate) if no profile is configured.
-        """
-        from ..config import DEFAULT_TOOL_PROFILES
-
-        # Check user-configured profiles
-        if self.config.tool_profiles:
-            profile = self.config.tool_profiles.get(tool_name)
-            if profile:
-                return float(profile.bias)
-
-        # Check default profiles
-        profile = DEFAULT_TOOL_PROFILES.get(tool_name)
-        if profile:
-            return profile.bias
-
-        return 1.0  # Default: moderate
-
-    def _process_content_blocks(
-        self,
-        message: dict[str, Any],
-        content_blocks: list[Any],
-        context: str,
-        transforms_applied: list[str],
-        excluded_tool_ids: set[str],
-        tool_name_map: dict[str, str] | None = None,
-        route_counts: dict[str, int] | None = None,
-        compressed_details: list[str] | None = None,
-        min_ratio: float = 0.85,
-        read_protection_window: int = 8,
-        messages_from_end: int = 0,
-        compressor_timing: dict[str, float] | None = None,
-    ) -> dict[str, Any]:
-        """Process content blocks (Anthropic format) for tool_result compression.
-
-        Handles tool_result blocks by compressing their string content using
-        the appropriate strategy (typically SmartCrusher for JSON arrays).
-
-        Args:
-            message: The original message.
-            content_blocks: List of content blocks.
-            context: Context for compression.
-            transforms_applied: List to append transform names to.
-            excluded_tool_ids: Tool IDs to skip compression for.
-            tool_name_map: Mapping from tool_call_id to tool_name for profile lookup.
-            route_counts: Optional routing reason counters to update.
-            compressed_details: Optional list to append compression details to.
-            min_ratio: Adaptive compression ratio threshold.
-            read_protection_window: Messages from end within which excluded tools are protected.
-            messages_from_end: How far this message is from the end of the conversation.
-
-        Returns:
-            Transformed message with compressed content blocks.
-        """
-        new_blocks = []
-        any_compressed = False
-
-        for block in content_blocks:
-            if not isinstance(block, dict):
-                new_blocks.append(block)
-                continue
-
-            block_type = block.get("type")
-
-            # Handle tool_result blocks
-            if block_type == "tool_result":
-                # Check if tool is excluded from compression
-                tool_use_id = block.get("tool_use_id", "")
-                if tool_use_id in excluded_tool_ids:
-                    if messages_from_end <= read_protection_window:
-                        # Recent — protect as before
-                        new_blocks.append(block)
-                        transforms_applied.append("router:excluded:tool")
-                        if route_counts is not None:
-                            route_counts["excluded_tool"] += 1
-                        continue
-                    # Old excluded-tool output — fall through to compression
-
-                # Look up tool-specific compression bias
-                tool_name = (tool_name_map or {}).get(tool_use_id, "")
-                bias = self._get_tool_bias(tool_name) if tool_name else 1.0
-
-                tool_content = block.get("content", "")
-
-                # Only process string content
-                if isinstance(tool_content, str) and len(tool_content) > 500:
-                    # Compression pinning: skip already-compressed content
-                    if (
-                        "Retrieve more: hash=" in tool_content
-                        or "Retrieve original: hash=" in tool_content
-                    ):
-                        new_blocks.append(block)
-                        if route_counts is not None:
-                            route_counts.setdefault("already_compressed", 0)
-                            route_counts["already_compressed"] += 1
-                        continue
-
-                    # Two-tier compression cache
-                    content_key = hash(tool_content)
-
-                    # Tier 1: skip set — instant rejection
-                    if self._cache.is_skipped(content_key):
-                        new_blocks.append(block)
-                        if route_counts is not None:
-                            route_counts["ratio_too_high"] += 1
-                            route_counts.setdefault("cache_hit", 0)
-                            route_counts["cache_hit"] += 1
-                        continue
-
-                    # Tier 2: result cache — reuse compressed output
-                    cached = self._cache.get(content_key)
-                    if cached is not None:
-                        cached_compressed, cached_ratio, cached_strategy = cached
-                        if cached_ratio < min_ratio:
-                            new_blocks.append({**block, "content": cached_compressed})
-                            transforms_applied.append(f"router:tool_result:{cached_strategy}")
-                            if compressed_details is not None:
-                                compressed_details.append(
-                                    f"tool:{cached_strategy}:{cached_ratio:.2f}"
-                                )
-                            any_compressed = True
-                        else:
-                            # Threshold tightened — move to skip
-                            self._cache.move_to_skip(content_key)
-                            new_blocks.append(block)
-                            if route_counts is not None:
-                                route_counts["ratio_too_high"] += 1
-                        if route_counts is not None:
-                            route_counts.setdefault("cache_hit", 0)
-                            route_counts["cache_hit"] += 1
-                        continue
-
-                    # Cache miss — run full compression
-                    if route_counts is not None:
-                        route_counts.setdefault("cache_miss", 0)
-                        route_counts["cache_miss"] += 1
-                    t0 = time.perf_counter()
-                    result = self.compress(tool_content, context=context, bias=bias)
-                    compress_ms = (time.perf_counter() - t0) * 1000
-                    if compressor_timing is not None:
-                        key = f"compressor:{result.strategy_used.value}"
-                        compressor_timing[key] = compressor_timing.get(key, 0.0) + compress_ms
-                    if result.compression_ratio < min_ratio:
-                        # Compressed — store in result cache
-                        self._cache.put(
-                            content_key,
-                            result.compressed,
-                            result.compression_ratio,
-                            result.strategy_used.value,
-                        )
-                        new_blocks.append({**block, "content": result.compressed})
-                        transforms_applied.append(
-                            f"router:tool_result:{result.strategy_used.value}"
-                        )
-                        if compressed_details is not None:
-                            compressed_details.append(
-                                f"tool:{result.strategy_used.value}:{result.compression_ratio:.2f}"
-                            )
-                        any_compressed = True
-                        continue
-                    else:
-                        # Didn't compress — add to skip set
-                        self._cache.mark_skip(content_key)
-                        if route_counts is not None:
-                            route_counts["ratio_too_high"] += 1
-                else:
-                    if route_counts is not None:
-                        route_counts["small"] += 1
-
-            # Keep block unchanged
-            new_blocks.append(block)
-
-        if any_compressed:
-            return {**message, "content": new_blocks}
-        return message
-
-    def _detect_analysis_intent(self, messages: list[dict[str, Any]]) -> bool:
-        """Detect if user wants to analyze/review code.
-
-        Looks at the most recent user message for analysis keywords.
-
-        Args:
-            messages: Conversation messages.
-
-        Returns:
-            True if analysis intent detected.
-        """
-        # Analysis keywords that suggest user wants full code details
-        analysis_keywords = {
-            "analyze",
-            "analyse",
-            "review",
-            "audit",
-            "inspect",
-            "security",
-            "vulnerability",
-            "bug",
-            "issue",
-            "problem",
-            "explain",
-            "understand",
-            "how does",
-            "what does",
-            "debug",
-            "fix",
-            "error",
-            "wrong",
-            "broken",
-            "refactor",
-            "improve",
-            "optimize",
-            "clean up",
-        }
-
-        # Find most recent user message
-        for message in reversed(messages):
-            if message.get("role") == "user":
-                content = message.get("content", "")
-                if isinstance(content, str):
-                    content_lower = content.lower()
-                    for keyword in analysis_keywords:
-                        if keyword in content_lower:
-                            return True
-                break
-
-        return False
-
-    def should_apply(
-        self,
-        messages: list[dict[str, Any]],
-        tokenizer: Tokenizer,
-        **kwargs: Any,
-    ) -> bool:
-        """Check if routing should be applied.
-
-        Always returns True - the router handles all content types.
-        """
-        return True
-
-
-def route_and_compress(
-    content: str,
-    context: str = "",
-) -> str:
-    """Convenience function for one-off routing and compression.
-
-    Args:
-        content: Content to compress.
-        context: Optional context for relevance-aware compression.
-
-    Returns:
-        Compressed content.
-
-    Example:
-        >>> compressed = route_and_compress(mixed_content)
-    """
-    router = ContentRouter()
-    result = router.compress(content, context=context)
-    return result.compressed
+"""Content router for intelligent compression strategy selection.
+
+This module provides the ContentRouter, which analyzes content and routes it
+to the optimal compressor. It handles mixed content by splitting, routing
+each section to the appropriate compressor, and reassembling.
+
+Supported Compressors:
+- CodeAwareCompressor: Source code (AST-preserving)
+- SmartCrusher: JSON arrays
+- SearchCompressor: grep/ripgrep results
+- LogCompressor: Build/test output
+- KompressCompressor: Plain text (ML-based)
+- Kompress: Plain text (ML-based, requires [ml] extra)
+
+Routing Strategy:
+1. Use source hint if available (highest confidence)
+2. Check for mixed content (split and route sections)
+3. Detect content type (JSON, code, search, logs, text)
+4. Route to appropriate compressor
+5. Reassemble and return with routing metadata
+
+Usage:
+    >>> from headroom.transforms import ContentRouter
+    >>> router = ContentRouter()
+    >>> result = router.compress(content)  # Auto-routes to best compressor
+    >>> print(result.strategy_used)
+    >>> print(result.routing_log)
+
+Pipeline Usage:
+    >>> pipeline = TransformPipeline([
+    ...     ContentRouter(),   # Handles all content types
+    ...     RollingWindow(),   # Final size constraint
+    ... ])
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from ..config import DEFAULT_EXCLUDE_TOOLS, ReadLifecycleConfig, TransformResult
+from ..tokenizer import Tokenizer
+from .base import Transform
+from .content_detector import ContentType, DetectionResult, detect_content_type
+
+logger = logging.getLogger(__name__)
+
+_magika_detector: Any | None = None
+_magika_status: bool | None = None
+
+
+def _get_magika_detector() -> Any | None:
+    """Load the Magika detector only when router detection actually runs."""
+    global _magika_detector, _magika_status
+
+    if _magika_status is False:
+        return None
+    if _magika_detector is not None:
+        return _magika_detector
+
+    try:
+        from ..compression.detector import get_detector
+
+        _magika_detector = get_detector(prefer_magika=True)
+        _magika_status = True
+        logger.info("ContentRouter: Using Magika ML-based content detection")
+    except ImportError:
+        _magika_status = False
+        logger.debug("Magika not available, using regex-based detection")
+
+    return _magika_detector
+
+
+def _detect_content(content: str) -> DetectionResult:
+    """Detect content type using Magika if available, else regex fallback."""
+    magika_detector = _get_magika_detector()
+    if magika_detector is not None:
+        result = magika_detector.detect(content)
+        # Map Magika ContentType to router's expected format
+        type_map = {
+            "json": ContentType.JSON_ARRAY,
+            "code": ContentType.SOURCE_CODE,
+            "log": ContentType.BUILD_OUTPUT,
+            "diff": ContentType.GIT_DIFF,
+            "markdown": ContentType.PLAIN_TEXT,
+            "text": ContentType.PLAIN_TEXT,
+            "unknown": ContentType.PLAIN_TEXT,
+        }
+        mapped_type = type_map.get(result.content_type.value, ContentType.PLAIN_TEXT)
+        return DetectionResult(
+            content_type=mapped_type,
+            confidence=result.confidence,
+            metadata={"language": result.language, "raw_label": result.raw_label},
+        )
+    else:
+        return detect_content_type(content)
+
+
+def _create_content_signature(
+    content_type: str,
+    content: str,
+    language: str | None = None,
+) -> Any:
+    """Create a ToolSignature for non-JSON content types.
+
+    This allows TOIN to track compression patterns for code, search results,
+    logs, and text - not just JSON arrays.
+
+    Args:
+        content_type: The type of content (e.g., "code_aware", "search", "log", "text").
+        content: The content being compressed (for structural hints).
+        language: Optional language hint for code.
+
+    Returns:
+        A ToolSignature for TOIN tracking.
+    """
+    try:
+        from ..telemetry.models import ToolSignature
+
+        # Create a deterministic structure hash based on content type
+        # This groups similar content types together for pattern learning
+        if language:
+            hash_input = f"content:{content_type}:{language}"
+        else:
+            hash_input = f"content:{content_type}"
+
+        # Add a structural hint from the content (first 100 chars, hashed)
+        # This helps differentiate tool outputs of the same type
+        content_sample = content[:100] if content else ""
+        structure_hint = hashlib.sha256(content_sample.encode()).hexdigest()[:8]
+        hash_input = f"{hash_input}:{structure_hint}"
+
+        # Keep SHA256: structure_hash feeds into TOIN which persists to disk.
+        # Changing hash function would invalidate all learned patterns.
+        structure_hash = hashlib.sha256(hash_input.encode()).hexdigest()[:24]
+
+        return ToolSignature(
+            structure_hash=structure_hash,
+            field_count=0,  # Not applicable for non-JSON
+            has_nested_objects=False,
+            has_arrays=False,
+            max_depth=0,
+        )
+    except ImportError:
+        return None
+
+
+class CompressionCache:
+    """Two-tier compression cache with TTL.
+
+    Tier 1 (skip set): content hashes that won't compress — instant skip,
+    near-zero memory (just ints in a set).
+
+    Tier 2 (result cache): compressed results for content that DID compress —
+    reuse the compressed text on subsequent requests.
+
+    Entries expire after TTL (default 30min). No max-entries cap — TTL is the
+    natural bound. Memory grows proportional to compressible content × TTL,
+    which is bounded by session duration.
+
+    Uses in-process dict for ultra-fast lookups (~100ns). Could be backed
+    by memcached/Redis for multi-process deployments.
+    """
+
+    def __init__(self, ttl_seconds: int = 1800):
+        # Tier 2: compressed results {hash: (text, ratio, strategy, timestamp)}
+        self._results: dict[int, tuple[str, float, str, float]] = {}
+        # Tier 1: hashes of content that won't compress {hash: timestamp}
+        self._skip: dict[int, float] = {}
+        self._ttl_seconds = ttl_seconds
+        # Metrics
+        self._hits = 0
+        self._misses = 0
+        self._skip_hits = 0
+        self._evictions = 0
+        self._total_lookup_ns = 0
+        self._lookup_count = 0
+
+    def get(self, key: int) -> tuple[str, float, str] | None:
+        """Get cached compression result.
+
+        Returns (compressed_text, ratio, strategy) or None if not found/expired.
+        Use is_skipped() first to check if content is known non-compressible.
+        """
+        t0 = time.perf_counter_ns()
+        entry = self._results.get(key)
+        if entry is not None:
+            compressed, ratio, strategy, created_at = entry
+            if (time.time() - created_at) < self._ttl_seconds:
+                self._hits += 1
+                self._total_lookup_ns += time.perf_counter_ns() - t0
+                self._lookup_count += 1
+                return (compressed, ratio, strategy)
+            else:
+                del self._results[key]
+                self._evictions += 1
+        self._misses += 1
+        self._total_lookup_ns += time.perf_counter_ns() - t0
+        self._lookup_count += 1
+        return None
+
+    def is_skipped(self, key: int) -> bool:
+        """Check if content is known non-compressible (Tier 1)."""
+        ts = self._skip.get(key)
+        if ts is not None:
+            if (time.time() - ts) < self._ttl_seconds:
+                self._skip_hits += 1
+                return True
+            else:
+                del self._skip[key]
+                self._evictions += 1
+        return False
+
+    def put(self, key: int, compressed: str, ratio: float, strategy: str) -> None:
+        """Store a compressed result (Tier 2)."""
+        self._results[key] = (compressed, ratio, strategy, time.time())
+
+    def mark_skip(self, key: int) -> None:
+        """Mark content as non-compressible (Tier 1)."""
+        self._skip[key] = time.time()
+
+    def move_to_skip(self, key: int) -> None:
+        """Move a result to skip set (threshold tightened, no longer qualifies)."""
+        self._results.pop(key, None)
+        self._skip[key] = time.time()
+
+    @property
+    def size(self) -> int:
+        return len(self._results)
+
+    @property
+    def skip_size(self) -> int:
+        return len(self._skip)
+
+    @property
+    def stats(self) -> dict[str, int | float]:
+        avg_ns = self._total_lookup_ns / self._lookup_count if self._lookup_count else 0
+        return {
+            "cache_hits": self._hits,
+            "cache_skip_hits": self._skip_hits,
+            "cache_misses": self._misses,
+            "cache_evictions": self._evictions,
+            "cache_size": len(self._results),
+            "cache_skip_size": len(self._skip),
+            "cache_avg_lookup_ns": avg_ns,
+        }
+
+    def clear(self) -> None:
+        """Clear all entries (e.g., on session end)."""
+        self._results.clear()
+        self._skip.clear()
+
+
+class CompressionStrategy(Enum):
+    """Available compression strategies."""
+
+    CODE_AWARE = "code_aware"
+    SMART_CRUSHER = "smart_crusher"
+    SEARCH = "search"
+    LOG = "log"
+    KOMPRESS = "kompress"
+    TEXT = "text"
+    DIFF = "diff"
+    HTML = "html"
+    MIXED = "mixed"
+    PASSTHROUGH = "passthrough"
+
+
+@dataclass
+class RoutingDecision:
+    """Record of a single routing decision."""
+
+    content_type: ContentType
+    strategy: CompressionStrategy
+    original_tokens: int
+    compressed_tokens: int
+    confidence: float = 1.0
+    section_index: int = 0
+
+    @property
+    def compression_ratio(self) -> float:
+        if self.original_tokens == 0:
+            return 1.0
+        return self.compressed_tokens / self.original_tokens
+
+
+@dataclass
+class ContentSection:
+    """A typed section of content."""
+
+    content: str
+    content_type: ContentType
+    language: str | None = None
+    start_line: int = 0
+    end_line: int = 0
+    is_code_fence: bool = False
+
+
+@dataclass
+class RouterCompressionResult:
+    """Result from ContentRouter with routing metadata.
+
+    Attributes:
+        compressed: The compressed content.
+        original: Original content before compression.
+        strategy_used: Primary strategy used for compression.
+        routing_log: List of routing decisions made.
+        sections_processed: Number of content sections processed.
+    """
+
+    compressed: str
+    original: str
+    strategy_used: CompressionStrategy
+    routing_log: list[RoutingDecision] = field(default_factory=list)
+    sections_processed: int = 1
+
+    @property
+    def total_original_tokens(self) -> int:
+        """Total tokens before compression."""
+        return sum(r.original_tokens for r in self.routing_log)
+
+    @property
+    def total_compressed_tokens(self) -> int:
+        """Total tokens after compression."""
+        return sum(r.compressed_tokens for r in self.routing_log)
+
+    @property
+    def compression_ratio(self) -> float:
+        """Overall compression ratio."""
+        if self.total_original_tokens == 0:
+            return 1.0
+        return self.total_compressed_tokens / self.total_original_tokens
+
+    @property
+    def tokens_saved(self) -> int:
+        """Number of tokens saved."""
+        return max(0, self.total_original_tokens - self.total_compressed_tokens)
+
+    @property
+    def savings_percentage(self) -> float:
+        """Percentage of tokens saved."""
+        if self.total_original_tokens == 0:
+            return 0.0
+        return (self.tokens_saved / self.total_original_tokens) * 100
+
+    def summary(self) -> str:
+        """Human-readable routing summary."""
+        if self.strategy_used == CompressionStrategy.MIXED:
+            strategies = {r.strategy.value for r in self.routing_log}
+            return (
+                f"Mixed content: {self.sections_processed} sections, "
+                f"routed to {strategies}. "
+                f"{self.total_original_tokens:,}→{self.total_compressed_tokens:,} tokens "
+                f"({self.savings_percentage:.0f}% saved)"
+            )
+        else:
+            return (
+                f"Pure {self.strategy_used.value}: "
+                f"{self.total_original_tokens:,}→{self.total_compressed_tokens:,} tokens "
+                f"({self.savings_percentage:.0f}% saved)"
+            )
+
+
+@dataclass
+class ContentRouterConfig:
+    """Configuration for intelligent content routing.
+
+    Attributes:
+        enable_code_aware: Enable AST-based code compression.
+        enable_smart_crusher: Enable JSON array compression.
+        enable_search_compressor: Enable search result compression.
+        enable_log_compressor: Enable build/test log compression.
+        enable_image_optimizer: Enable image token optimization.
+        prefer_code_aware_for_code: Use CodeAware over Kompress for code.
+        mixed_content_threshold: Min distinct types to consider "mixed".
+        min_section_tokens: Minimum tokens for a section to compress.
+        fallback_strategy: Strategy when no compressor matches.
+        skip_user_messages: Never compress user messages (they're the subject).
+        skip_recent_messages: Don't compress last N messages (likely the subject).
+        protect_analysis_context: Detect "analyze/review" intent, skip compression.
+    """
+
+    # Enable/disable specific compressors
+    enable_code_aware: bool = False  # Disabled: use code graph MCP tools instead
+    enable_kompress: bool = True  # Kompress: ModernBERT token compressor
+    enable_smart_crusher: bool = True
+    enable_search_compressor: bool = True
+    enable_log_compressor: bool = True
+    enable_html_extractor: bool = True  # HTML content extraction
+    enable_image_optimizer: bool = True  # Image token optimization
+
+    # Routing preferences
+    prefer_code_aware_for_code: bool = False  # Disabled: let code pass through unmangled
+    mixed_content_threshold: int = 2  # Min types to consider mixed
+    min_section_tokens: int = 20  # Min tokens to compress a section
+
+    # Fallback: Kompress handles unknown/mixed content instead of passing through
+    fallback_strategy: CompressionStrategy = CompressionStrategy.KOMPRESS
+
+    # Protection: Don't compress content that's likely the subject of analysis
+    skip_user_messages: bool = True  # User messages contain what they want analyzed
+    protect_recent_code: int = 4  # Don't compress CODE in last N messages (0 = disabled)
+    protect_analysis_context: bool = True  # Detect "analyze/review" intent, protect code
+
+    # Adaptive Read protection: fraction of total messages to protect from
+    # compression.  At 10 msgs, protects ~5 Reads.  At 100 msgs, protects ~10.
+    # Old Reads beyond this window become compressible even though they are
+    # in DEFAULT_EXCLUDE_TOOLS.  0.0 = always exclude all (old behavior).
+    protect_recent_reads_fraction: float = (
+        0.0  # 0.0 = protect ALL excluded-tool outputs (safest for coding agents)
+    )
+
+    # Adaptive compression ratio: scales with context pressure.
+    # At low pressure (<30% full), use the relaxed threshold (reject marginal).
+    # At high pressure (>80% full), use the aggressive threshold (accept anything helpful).
+    # Linearly interpolates between the two.
+    min_ratio_relaxed: float = 0.85  # when context is mostly empty
+    min_ratio_aggressive: float = 0.65  # when context is nearly full
+
+    # CCR (Compress-Cache-Retrieve) settings for SmartCrusher
+    ccr_enabled: bool = True  # Enable CCR marker injection for reversible compression
+    ccr_inject_marker: bool = True  # Add retrieval markers to compressed content
+
+    # Tag protection: preserve custom/workflow XML tags from text compression.
+    # When False (default), entire <custom-tag>content</custom-tag> blocks are
+    # protected verbatim.  When True, only the tag markers are protected and
+    # the content between them can be compressed.
+    compress_tagged_content: bool = False
+
+    # Tools to exclude from compression (output passed through unmodified)
+    # Set to None to use DEFAULT_EXCLUDE_TOOLS, or provide custom set
+    exclude_tools: set[str] | None = None
+
+    # Read lifecycle management (stale/superseded detection)
+    read_lifecycle: ReadLifecycleConfig = field(default_factory=ReadLifecycleConfig)
+
+    # Per-tool compression profiles (tool_name → CompressionProfile)
+    # Set to None to use DEFAULT_TOOL_PROFILES from config
+    tool_profiles: dict[str, Any] | None = None
+
+
+# Patterns for detecting mixed content
+_CODE_FENCE_PATTERN = re.compile(r"^```(\w*)\s*$", re.MULTILINE)
+_JSON_BLOCK_START = re.compile(r"^\s*[\[{]", re.MULTILINE)
+_SEARCH_RESULT_PATTERN = re.compile(r"^\S+:\d+:", re.MULTILINE)
+_PROSE_PATTERN = re.compile(r"[A-Z][a-z]+\s+\w+\s+\w+")
+
+
+def is_mixed_content(content: str) -> bool:
+    """Detect if content contains multiple distinct types.
+
+    Args:
+        content: Content to analyze.
+
+    Returns:
+        True if content appears to be mixed (multiple types).
+    """
+    indicators = {
+        "has_code_fences": bool(_CODE_FENCE_PATTERN.search(content)),
+        "has_json_blocks": bool(_JSON_BLOCK_START.search(content)),
+        "has_prose": len(_PROSE_PATTERN.findall(content)) > 5,
+        "has_search_results": bool(_SEARCH_RESULT_PATTERN.search(content)),
+    }
+
+    # Mixed if 2+ indicators are true
+    return sum(indicators.values()) >= 2
+
+
+def split_into_sections(content: str) -> list[ContentSection]:
+    """Parse mixed content into typed sections.
+
+    Args:
+        content: Mixed content to split.
+
+    Returns:
+        List of ContentSection objects.
+    """
+    sections: list[ContentSection] = []
+    lines = content.split("\n")
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+
+        # Code fence: ```language
+        if match := _CODE_FENCE_PATTERN.match(line):
+            language = match.group(1) or "unknown"
+            code_lines = []
+            start_line = i
+            i += 1
+
+            while i < len(lines) and not lines[i].startswith("```"):
+                code_lines.append(lines[i])
+                i += 1
+
+            sections.append(
+                ContentSection(
+                    content="\n".join(code_lines),
+                    content_type=ContentType.SOURCE_CODE,
+                    language=language,
+                    start_line=start_line,
+                    end_line=i,
+                    is_code_fence=True,
+                )
+            )
+            i += 1  # Skip closing ```
+            continue
+
+        # JSON block
+        if line.strip().startswith(("[", "{")):
+            json_content, end_i = _extract_json_block(lines, i)
+            if json_content:
+                sections.append(
+                    ContentSection(
+                        content=json_content,
+                        content_type=ContentType.JSON_ARRAY,
+                        start_line=i,
+                        end_line=end_i,
+                    )
+                )
+                i = end_i + 1
+                continue
+
+        # Search result lines
+        if _SEARCH_RESULT_PATTERN.match(line):
+            search_lines = []
+            start_line = i
+            while i < len(lines) and _SEARCH_RESULT_PATTERN.match(lines[i]):
+                search_lines.append(lines[i])
+                i += 1
+            sections.append(
+                ContentSection(
+                    content="\n".join(search_lines),
+                    content_type=ContentType.SEARCH_RESULTS,
+                    start_line=start_line,
+                    end_line=i - 1,
+                )
+            )
+            continue
+
+        # Collect text until next special section
+        text_lines = [line]
+        start_line = i
+        i += 1
+
+        while i < len(lines):
+            next_line = lines[i]
+            # Stop if we hit a special section
+            if (
+                _CODE_FENCE_PATTERN.match(next_line)
+                or next_line.strip().startswith(("[", "{"))
+                or _SEARCH_RESULT_PATTERN.match(next_line)
+            ):
+                break
+            text_lines.append(next_line)
+            i += 1
+
+        # Only add non-empty text sections
+        text_content = "\n".join(text_lines)
+        if text_content.strip():
+            sections.append(
+                ContentSection(
+                    content=text_content,
+                    content_type=ContentType.PLAIN_TEXT,
+                    start_line=start_line,
+                    end_line=i - 1,
+                )
+            )
+
+    return sections
+
+
+def _extract_json_block(lines: list[str], start: int) -> tuple[str | None, int]:
+    """Extract a complete JSON block from lines.
+
+    Args:
+        lines: All lines of content.
+        start: Starting line index.
+
+    Returns:
+        Tuple of (json_content, end_line_index) or (None, start) if invalid.
+    """
+    bracket_count = 0
+    brace_count = 0
+    json_lines = []
+
+    for i in range(start, len(lines)):
+        line = lines[i]
+        json_lines.append(line)
+
+        bracket_count += line.count("[") - line.count("]")
+        brace_count += line.count("{") - line.count("}")
+
+        if bracket_count <= 0 and brace_count <= 0 and json_lines:
+            return "\n".join(json_lines), i
+
+    # Didn't find complete JSON
+    return None, start
+
+
+class ContentRouter(Transform):
+    """Intelligent router that selects optimal compression strategy.
+
+    ContentRouter is the recommended entry point for Headroom's compression.
+    It analyzes content and routes it to the most appropriate compressor,
+    handling mixed content by splitting and reassembling.
+
+    Key Features:
+    - Automatic content type detection
+    - Source hint support for high-confidence routing
+    - Mixed content handling (split → route → reassemble)
+    - Graceful fallback when compressors unavailable
+    - Rich routing metadata for debugging
+
+    Example:
+        >>> router = ContentRouter()
+        >>>
+        >>> # Automatically uses CodeAwareCompressor
+        >>> result = router.compress(python_code)
+        >>> print(result.strategy_used)  # CompressionStrategy.CODE_AWARE
+        >>>
+        >>> # Automatically uses SmartCrusher
+        >>> result = router.compress(json_array)
+        >>> print(result.strategy_used)  # CompressionStrategy.SMART_CRUSHER
+        >>>
+        >>> # Splits and routes each section
+        >>> result = router.compress(readme_with_code)
+        >>> print(result.strategy_used)  # CompressionStrategy.MIXED
+
+    Pipeline Integration:
+        >>> pipeline = TransformPipeline([
+        ...     ContentRouter(),   # Handles ALL content types
+        ...     RollingWindow(),   # Final size constraint
+        ... ])
+    """
+
+    name: str = "content_router"
+
+    def __init__(self, config: ContentRouterConfig | None = None):
+        """Initialize content router.
+
+        Args:
+            config: Router configuration. Uses defaults if None.
+        """
+        self.config = config or ContentRouterConfig()
+
+        # Lazy-loaded compressors
+        self._code_compressor: Any = None
+        self._smart_crusher: Any = None
+        self._search_compressor: Any = None
+        self._log_compressor: Any = None
+        self._diff_compressor: Any = None
+        self._html_extractor: Any = None
+        self._kompress: Any = None
+        self._image_optimizer: Any = None
+
+        # TOIN integration for cross-strategy learning
+        self._toin: Any = None
+
+        self._cache = CompressionCache()
+
+    def _record_to_toin(
+        self,
+        strategy: CompressionStrategy,
+        content: str,
+        compressed: str,
+        original_tokens: int,
+        compressed_tokens: int,
+        language: str | None = None,
+        context: str = "",
+    ) -> None:
+        """Record compression to TOIN for cross-user learning.
+
+        This allows TOIN to track compression patterns for ALL content types,
+        not just JSON arrays. When the LLM retrieves original content via CCR,
+        TOIN learns which compressions users need to expand.
+
+        Args:
+            strategy: The compression strategy used.
+            content: Original content (for signature generation).
+            compressed: Compressed content.
+            original_tokens: Token count before compression.
+            compressed_tokens: Token count after compression.
+            language: Optional language hint for code.
+            context: Query context for pattern learning.
+        """
+        # Skip SmartCrusher - it handles its own TOIN recording
+        if strategy == CompressionStrategy.SMART_CRUSHER:
+            return
+
+        # Skip if no actual compression happened
+        if original_tokens <= compressed_tokens:
+            return
+
+        try:
+            # Lazy load TOIN
+            if self._toin is None:
+                from ..telemetry.toin import get_toin
+
+                self._toin = get_toin()
+
+            # Create a content-type signature
+            signature = _create_content_signature(
+                content_type=strategy.value,
+                content=content,
+                language=language,
+            )
+
+            if signature is None:
+                return
+
+            # Record the compression
+            self._toin.record_compression(
+                tool_signature=signature,
+                original_count=1,  # Single content block
+                compressed_count=1,
+                original_tokens=original_tokens,
+                compressed_tokens=compressed_tokens,
+                strategy=strategy.value,
+                query_context=context if context else None,
+            )
+
+            logger.debug(
+                "TOIN: Recorded %s compression: %d → %d tokens",
+                strategy.value,
+                original_tokens,
+                compressed_tokens,
+            )
+
+        except Exception as e:
+            # TOIN recording should never break compression
+            logger.debug("TOIN recording failed (non-fatal): %s", e)
+
+    def _timed_compress(
+        self, content: str, context: str, bias: float
+    ) -> tuple[RouterCompressionResult, float]:
+        """Compress with wall-clock timing.  Used by parallel executor."""
+        t0 = time.perf_counter()
+        result = self.compress(content, context=context, bias=bias)
+        return result, (time.perf_counter() - t0) * 1000
+
+    def compress(
+        self,
+        content: str,
+        context: str = "",
+        question: str | None = None,
+        bias: float = 1.0,
+    ) -> RouterCompressionResult:
+        """Compress content using optimal strategy based on content detection.
+
+        Args:
+            content: Content to compress.
+            context: Optional context for relevance-aware compression.
+            question: Optional question for QA-aware compression. When provided,
+                tokens relevant to answering this question are preserved.
+            bias: Compression bias multiplier (>1 = keep more, <1 = keep fewer).
+
+        Returns:
+            RouterCompressionResult with compressed content and routing metadata.
+        """
+        if not content or not content.strip():
+            return RouterCompressionResult(
+                compressed=content,
+                original=content,
+                strategy_used=CompressionStrategy.PASSTHROUGH,
+                routing_log=[],
+            )
+
+        # Determine strategy from content analysis
+        strategy = self._determine_strategy(content)
+
+        if strategy == CompressionStrategy.MIXED:
+            return self._compress_mixed(content, context, question, bias=bias)
+        else:
+            return self._compress_pure(content, strategy, context, question, bias=bias)
+
+    def _determine_strategy(self, content: str) -> CompressionStrategy:
+        """Determine the compression strategy from content analysis.
+
+        Args:
+            content: Content to analyze.
+
+        Returns:
+            Selected compression strategy.
+        """
+        # 1. Check for mixed content
+        if is_mixed_content(content):
+            return CompressionStrategy.MIXED
+
+        # 2. Detect content type from content itself
+        detection = _detect_content(content)
+        return self._strategy_from_detection(detection)
+
+    def _strategy_from_detection(self, detection: Any) -> CompressionStrategy:
+        """Get strategy from content detection result.
+
+        Args:
+            detection: Result from detect_content_type.
+
+        Returns:
+            Selected strategy.
+        """
+        mapping = {
+            ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,
+            ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,
+            ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,
+            ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,
+            ContentType.GIT_DIFF: CompressionStrategy.DIFF,
+            ContentType.HTML: CompressionStrategy.HTML,
+            ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,
+        }
+
+        strategy = mapping.get(detection.content_type, self.config.fallback_strategy)
+
+        # Override: prefer CodeAware for code if configured
+        if (
+            strategy == CompressionStrategy.CODE_AWARE
+            and not self.config.prefer_code_aware_for_code
+        ):
+            strategy = CompressionStrategy.KOMPRESS
+
+        return strategy
+
+    def _compress_mixed(
+        self,
+        content: str,
+        context: str,
+        question: str | None = None,
+        bias: float = 1.0,
+    ) -> RouterCompressionResult:
+        """Compress mixed content by splitting and routing sections.
+
+        Args:
+            content: Mixed content to compress.
+            context: User context for relevance.
+            question: Optional question for QA-aware compression.
+            bias: Compression bias multiplier.
+
+        Returns:
+            RouterCompressionResult with reassembled content.
+        """
+        sections = split_into_sections(content)
+
+        if not sections:
+            return RouterCompressionResult(
+                compressed=content,
+                original=content,
+                strategy_used=CompressionStrategy.PASSTHROUGH,
+            )
+
+        compressed_sections: list[str] = []
+        routing_log: list[RoutingDecision] = []
+
+        for i, section in enumerate(sections):
+            # Get strategy for this section
+            strategy = self._strategy_from_detection_type(section.content_type)
+
+            # Compress section
+            original_tokens = len(section.content.split())
+            compressed_content, compressed_tokens = self._apply_strategy_to_content(
+                section.content,
+                strategy,
+                context,
+                section.language,
+                question,
+                bias=bias,
+            )
+
+            # Preserve code fence markers
+            if section.is_code_fence and section.language:
+                compressed_content = f"```{section.language}\n{compressed_content}\n```"
+
+            compressed_sections.append(compressed_content)
+            routing_log.append(
+                RoutingDecision(
+                    content_type=section.content_type,
+                    strategy=strategy,
+                    original_tokens=original_tokens,
+                    compressed_tokens=compressed_tokens,
+                    section_index=i,
+                )
+            )
+
+        return RouterCompressionResult(
+            compressed="\n\n".join(compressed_sections),
+            original=content,
+            strategy_used=CompressionStrategy.MIXED,
+            routing_log=routing_log,
+            sections_processed=len(sections),
+        )
+
+    def _compress_pure(
+        self,
+        content: str,
+        strategy: CompressionStrategy,
+        context: str,
+        question: str | None = None,
+        bias: float = 1.0,
+    ) -> RouterCompressionResult:
+        """Compress pure (non-mixed) content.
+
+        Args:
+            content: Content to compress.
+            strategy: Selected strategy.
+            context: User context.
+            question: Optional question for QA-aware compression.
+            bias: Compression bias multiplier.
+
+        Returns:
+            RouterCompressionResult.
+        """
+        original_tokens = len(content.split())
+
+        compressed, compressed_tokens = self._apply_strategy_to_content(
+            content, strategy, context, question=question, bias=bias
+        )
+
+        return RouterCompressionResult(
+            compressed=compressed,
+            original=content,
+            strategy_used=strategy,
+            routing_log=[
+                RoutingDecision(
+                    content_type=self._content_type_from_strategy(strategy),
+                    strategy=strategy,
+                    original_tokens=original_tokens,
+                    compressed_tokens=compressed_tokens,
+                )
+            ],
+        )
+
+    def _apply_strategy_to_content(
+        self,
+        content: str,
+        strategy: CompressionStrategy,
+        context: str,
+        language: str | None = None,
+        question: str | None = None,
+        bias: float = 1.0,
+    ) -> tuple[str, int]:
+        """Apply a compression strategy to content.
+
+        Args:
+            content: Content to compress.
+            strategy: Strategy to use.
+            context: User context.
+            language: Language hint for code.
+            question: Optional question for QA-aware compression.
+            bias: Compression bias multiplier (>1 = keep more, <1 = keep fewer).
+
+        Returns:
+            Tuple of (compressed_content, compressed_token_count).
+        """
+        # Track original tokens for TOIN recording
+        original_tokens = len(content.split())
+        compressed: str | None = None
+        compressed_tokens: int | None = None
+
+        try:
+            if strategy == CompressionStrategy.CODE_AWARE:
+                if self.config.enable_code_aware:
+                    compressor = self._get_code_compressor()
+                    if compressor:
+                        result = compressor.compress(content, language=language, context=context)
+                        compressed, compressed_tokens = result.compressed, result.compressed_tokens
+                if compressed is None:
+                    # Fallback to Kompress
+                    compressed, compressed_tokens = self._try_ml_compressor(
+                        content, context, question
+                    )
+                    strategy = CompressionStrategy.KOMPRESS  # Update for TOIN
+
+            elif strategy == CompressionStrategy.SMART_CRUSHER:
+                # SmartCrusher handles its own TOIN recording
+                if self.config.enable_smart_crusher:
+                    crusher = self._get_smart_crusher()
+                    if crusher:
+                        result = crusher.crush(content, query=context, bias=bias)
+                        return result.compressed, len(result.compressed.split())
+
+            elif strategy == CompressionStrategy.SEARCH:
+                if self.config.enable_search_compressor:
+                    compressor = self._get_search_compressor()
+                    if compressor:
+                        result = compressor.compress(content, context=context, bias=bias)
+                        compressed, compressed_tokens = (
+                            result.compressed,
+                            len(result.compressed.split()),
+                        )
+
+            elif strategy == CompressionStrategy.LOG:
+                if self.config.enable_log_compressor:
+                    compressor = self._get_log_compressor()
+                    if compressor:
+                        result = compressor.compress(content, bias=bias)
+                        compressed, compressed_tokens = (
+                            result.compressed,
+                            result.compressed_line_count,
+                        )
+
+            elif strategy == CompressionStrategy.DIFF:
+                compressor = self._get_diff_compressor()
+                if compressor:
+                    result = compressor.compress(content, context=context)
+                    compressed, compressed_tokens = (
+                        result.compressed,
+                        result.compressed_line_count,
+                    )
+
+            elif strategy == CompressionStrategy.HTML:
+                if self.config.enable_html_extractor:
+                    extractor = self._get_html_extractor()
+                    if extractor:
+                        result = extractor.extract(content)
+                        compressed = result.extracted
+                        # Estimate tokens from extracted text (simple word count)
+                        compressed_tokens = len(compressed.split()) if compressed else 0
+
+            elif strategy == CompressionStrategy.KOMPRESS:
+                compressed, compressed_tokens = self._try_ml_compressor(content, context, question)
+
+            elif strategy == CompressionStrategy.TEXT:
+                # Prefer Kompress ML compressor for text
+                # Passes through unchanged if Kompress not available
+                compressed, compressed_tokens = self._try_ml_compressor(content, context, question)
+
+        except Exception as e:
+            logger.warning("Compression with %s failed: %s", strategy.value, e)
+
+        # If compression succeeded, record to TOIN
+        if compressed is not None and compressed_tokens is not None:
+            self._record_to_toin(
+                strategy=strategy,
+                content=content,
+                compressed=compressed,
+                original_tokens=original_tokens,
+                compressed_tokens=compressed_tokens,
+                language=language,
+                context=context,
+            )
+            return compressed, compressed_tokens
+
+        # Fallback: return unchanged
+        return content, original_tokens
+
+    def _try_ml_compressor(
+        self, content: str, context: str, question: str | None = None
+    ) -> tuple[str, int]:
+        """ML-based compression using Kompress.
+
+        Kompress (ModernBERT, trained on 330K structured tool outputs)
+        auto-downloads from HuggingFace on first use. No heuristic fallback.
+
+        Custom/workflow XML tags (<system-reminder>, <tool_call>, <thinking>)
+        are protected before compression and restored after.  Standard HTML
+        tags are left alone (HTMLExtractor handles those separately).
+
+        Args:
+            content: Content to compress.
+            context: User context.
+            question: Optional question for QA-aware compression.
+
+        Returns:
+            Tuple of (compressed, token_count).
+        """
+        from .tag_protector import protect_tags, restore_tags
+
+        # Protect custom tags before any ML compression
+        cleaned, protected = protect_tags(
+            content,
+            compress_tagged_content=self.config.compress_tagged_content,
+        )
+
+        # If the entire content is custom tags with nothing to compress
+        if protected and not cleaned.strip():
+            return content, len(content.split())
+
+        # Use the cleaned (tag-free) text for compression
+        text_to_compress = cleaned if protected else content
+        compressed: str | None = None
+        compressed_tokens: int | None = None
+
+        # Primary: Kompress — downloads from chopratejas/kompress-base on first use
+        if self.config.enable_kompress:
+            compressor = self._get_kompress()
+            if compressor:
+                try:
+                    result = compressor.compress(
+                        text_to_compress,
+                        context=context,
+                        question=question,
+                        target_ratio=getattr(self, "_runtime_target_ratio", None),
+                    )
+                    compressed = result.compressed
+                    compressed_tokens = result.compressed_tokens
+                except Exception as e:
+                    logger.warning("Kompress failed: %s", e)
+
+        if compressed is None:
+            return content, len(content.split())
+
+        # Restore protected tag blocks into the compressed text
+        if protected:
+            compressed = restore_tags(compressed, protected)
+            compressed_tokens = len(compressed.split())
+
+        return compressed, compressed_tokens or len(compressed.split())
+
+    def _strategy_from_detection_type(self, content_type: ContentType) -> CompressionStrategy:
+        """Get strategy from ContentType enum."""
+        mapping = {
+            ContentType.SOURCE_CODE: CompressionStrategy.CODE_AWARE,
+            ContentType.JSON_ARRAY: CompressionStrategy.SMART_CRUSHER,
+            ContentType.SEARCH_RESULTS: CompressionStrategy.SEARCH,
+            ContentType.BUILD_OUTPUT: CompressionStrategy.LOG,
+            ContentType.GIT_DIFF: CompressionStrategy.DIFF,
+            ContentType.HTML: CompressionStrategy.HTML,
+            ContentType.PLAIN_TEXT: CompressionStrategy.TEXT,
+        }
+        return mapping.get(content_type, self.config.fallback_strategy)
+
+    def _content_type_from_strategy(self, strategy: CompressionStrategy) -> ContentType:
+        """Get ContentType from strategy."""
+        mapping = {
+            CompressionStrategy.CODE_AWARE: ContentType.SOURCE_CODE,
+            CompressionStrategy.SMART_CRUSHER: ContentType.JSON_ARRAY,
+            CompressionStrategy.SEARCH: ContentType.SEARCH_RESULTS,
+            CompressionStrategy.LOG: ContentType.BUILD_OUTPUT,
+            CompressionStrategy.DIFF: ContentType.GIT_DIFF,
+            CompressionStrategy.HTML: ContentType.HTML,
+            CompressionStrategy.TEXT: ContentType.PLAIN_TEXT,
+            CompressionStrategy.KOMPRESS: ContentType.PLAIN_TEXT,
+            CompressionStrategy.PASSTHROUGH: ContentType.PLAIN_TEXT,
+        }
+        return mapping.get(strategy, ContentType.PLAIN_TEXT)
+
+    # Lazy compressor getters
+
+    def _get_code_compressor(self) -> Any:
+        """Get CodeAwareCompressor (lazy load)."""
+        if self._code_compressor is None:
+            try:
+                from .code_compressor import CodeAwareCompressor, _check_tree_sitter_available
+
+                if _check_tree_sitter_available():
+                    self._code_compressor = CodeAwareCompressor()
+                else:
+                    logger.debug("tree-sitter not available")
+            except ImportError:
+                logger.debug("CodeAwareCompressor not available")
+        return self._code_compressor
+
+    def _get_smart_crusher(self) -> Any:
+        """Get SmartCrusher (lazy load) with CCR config."""
+        if self._smart_crusher is None:
+            try:
+                from ..config import CCRConfig
+                from .smart_crusher import SmartCrusher
+
+                # Pass CCR config for marker injection
+                ccr_config = CCRConfig(
+                    enabled=self.config.ccr_enabled,
+                    inject_retrieval_marker=self.config.ccr_inject_marker,
+                )
+                self._smart_crusher = SmartCrusher(ccr_config=ccr_config)
+            except ImportError:
+                logger.debug("SmartCrusher not available")
+        return self._smart_crusher
+
+    def _get_search_compressor(self) -> Any:
+        """Get SearchCompressor (lazy load)."""
+        if self._search_compressor is None:
+            try:
+                from .search_compressor import SearchCompressor
+
+                self._search_compressor = SearchCompressor()
+            except ImportError:
+                logger.debug("SearchCompressor not available")
+        return self._search_compressor
+
+    def _get_log_compressor(self) -> Any:
+        """Get LogCompressor (lazy load)."""
+        if self._log_compressor is None:
+            try:
+                from .log_compressor import LogCompressor
+
+                self._log_compressor = LogCompressor()
+            except ImportError:
+                logger.debug("LogCompressor not available")
+        return self._log_compressor
+
+    def _get_diff_compressor(self) -> Any:
+        """Get DiffCompressor (lazy load)."""
+        if self._diff_compressor is None:
+            try:
+                from .diff_compressor import DiffCompressor
+
+                self._diff_compressor = DiffCompressor()
+            except ImportError:
+                logger.debug("DiffCompressor not available")
+        return self._diff_compressor
+
+    def _get_html_extractor(self) -> Any:
+        """Get HTMLExtractor (lazy load)."""
+        if self._html_extractor is None:
+            try:
+                from .html_extractor import HTMLExtractor
+
+                self._html_extractor = HTMLExtractor()
+            except ImportError:
+                logger.debug("HTMLExtractor not available (install trafilatura)")
+        return self._html_extractor
+
+    def eager_load_compressors(self) -> dict[str, str]:
+        """Pre-load compressors at startup to avoid first-request latency.
+
+        Call this during proxy startup to load models and parsers
+        before any requests arrive. Eliminates cold-start latency spikes.
+
+        Returns:
+            Dict of component name -> status string for logging.
+        """
+        status: dict[str, str] = {}
+
+        # 1. ML text compressor: Kompress
+        if self.config.enable_kompress:
+            compressor = self._get_kompress()
+            if compressor:
+                logger.info("Kompress model pre-loaded at startup")
+                status["kompress"] = "enabled"
+            else:
+                status["kompress"] = "unavailable"
+
+        # 2. Magika content detector (avoids 100-200ms on first content detection)
+        try:
+            from ..compression.detector import _get_magika, _magika_available
+
+            if _magika_available():
+                _get_magika()  # Initializes the singleton
+                logger.info("Magika content detector pre-loaded at startup")
+                status["magika"] = "enabled"
+            else:
+                status["magika"] = "not installed"
+        except Exception as e:
+            logger.debug("Magika pre-load skipped: %s", e)
+            status["magika"] = "skipped"
+
+        # 3. CodeAware compressor + common tree-sitter parsers
+        if self.config.enable_code_aware:
+            code_compressor = self._get_code_compressor()
+            if code_compressor:
+                status["code_aware"] = "enabled"
+                # Pre-load tree-sitter parsers for common languages
+                # Each parser is ~50ms to load; doing it here avoids 500ms+ on first code hit
+                try:
+                    from .code_compressor import _check_tree_sitter_available, _get_parser
+
+                    if _check_tree_sitter_available():
+                        common_languages = [
+                            "python",
+                            "javascript",
+                            "typescript",
+                            "go",
+                            "rust",
+                            "java",
+                            "c",
+                            "cpp",
+                        ]
+                        loaded = []
+                        for lang in common_languages:
+                            try:
+                                _get_parser(lang)
+                                loaded.append(lang)
+                            except (ValueError, ImportError):
+                                pass  # Language not available, skip
+                        if loaded:
+                            logger.info("Tree-sitter parsers pre-loaded: %s", ", ".join(loaded))
+                            status["tree_sitter"] = f"loaded ({len(loaded)} languages)"
+                except Exception as e:
+                    logger.debug("Tree-sitter pre-load skipped: %s", e)
+                    status["tree_sitter"] = "skipped"
+            else:
+                status["code_aware"] = "not installed"
+
+        # 4. SmartCrusher (lightweight init, but ensures import + TOIN ready)
+        smart_crusher = self._get_smart_crusher()
+        if smart_crusher:
+            status["smart_crusher"] = "ready"
+
+        return status
+
+    def _get_kompress(self) -> Any:
+        """Get KompressCompressor (lazy load). Downloads from HuggingFace on first use.
+
+        Respects runtime kompress_model kwarg:
+        - None: use default (chopratejas/kompress-base) — cached on self
+        - "disabled": return None (skip ML compression entirely)
+        - any model ID string: create compressor with that model
+          (model weights are cached at module level in kompress_compressor.py,
+          so repeated calls with the same model_id are cheap)
+        """
+        model_id = getattr(self, "_runtime_kompress_model", None)
+
+        # Explicitly disabled — no ML compression
+        if model_id == "disabled":
+            return None
+
+        # Custom model — don't touch self._kompress (that's the default cache)
+        if model_id:
+            try:
+                from .kompress_compressor import (
+                    KompressCompressor,
+                    KompressConfig,
+                    is_kompress_available,
+                )
+
+                if is_kompress_available():
+                    return KompressCompressor(config=KompressConfig(model_id=model_id))
+            except ImportError:
+                pass
+            return None
+
+        # Default path — exactly as before, cached on self
+        if self._kompress is None:
+            try:
+                from .kompress_compressor import KompressCompressor, is_kompress_available
+
+                if is_kompress_available():
+                    self._kompress = KompressCompressor()
+            except ImportError:
+                logger.debug("Kompress dependencies not available")
+        return self._kompress
+
+    def _get_image_optimizer(self) -> Any:
+        """Get ImageCompressor (lazy load).
+
+        The ImageCompressor handles image token compression using:
+        - Trained MiniLM classifier from HuggingFace (chopratejas/technique-router)
+        - SigLIP for image analysis
+        - Provider-specific compression (OpenAI detail, Anthropic/Google resize)
+        """
+        if self._image_optimizer is None:
+            try:
+                from ..image import ImageCompressor
+
+                self._image_optimizer = ImageCompressor()
+            except ImportError:
+                logger.debug("ImageCompressor not available")
+        return self._image_optimizer
+
+    def optimize_images_in_messages(
+        self,
+        messages: list[dict[str, Any]],
+        tokenizer: Tokenizer,
+        provider: str = "openai",
+        user_query: str | None = None,
+    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+        """Optimize images in messages.
+
+        This is a convenience method for image optimization that can be called
+        directly or as part of the transform pipeline.
+
+        Uses ImageCompressor with trained MiniLM router from HuggingFace
+        (chopratejas/technique-router) + SigLIP for image analysis.
+
+        Args:
+            messages: Messages potentially containing images.
+            tokenizer: Tokenizer for token counting (unused, kept for API compat).
+            provider: LLM provider (openai, anthropic, google).
+            user_query: User query for task intent detection (unused, auto-extracted).
+
+        Returns:
+            Tuple of (optimized_messages, metrics).
+        """
+        if not self.config.enable_image_optimizer:
+            return messages, {"images_optimized": 0, "tokens_saved": 0}
+
+        compressor = self._get_image_optimizer()
+        if compressor is None:
+            return messages, {"images_optimized": 0, "tokens_saved": 0}
+
+        # Check if there are images to compress
+        if not compressor.has_images(messages):
+            return messages, {"images_optimized": 0, "tokens_saved": 0}
+
+        # Compress images (query is auto-extracted from messages)
+        optimized = compressor.compress(messages, provider=provider)
+
+        # Get metrics from last compression
+        result = compressor.last_result
+        if result:
+            metrics = {
+                "images_optimized": result.compressed_tokens < result.original_tokens,
+                "tokens_before": result.original_tokens,
+                "tokens_after": result.compressed_tokens,
+                "tokens_saved": result.original_tokens - result.compressed_tokens,
+                "technique": result.technique.value,
+                "confidence": result.confidence,
+            }
+        else:
+            metrics = {"images_optimized": 0, "tokens_saved": 0}
+
+        return optimized, metrics
+
+    # Transform interface
+
+    def _build_tool_name_map(self, messages: list[dict[str, Any]]) -> dict[str, str]:
+        """Build mapping from tool_call_id to tool_name.
+
+        Scans assistant messages to find tool calls and extract their names.
+        Supports both OpenAI and Anthropic message formats.
+        """
+        mapping: dict[str, str] = {}
+
+        for msg in messages:
+            if msg.get("role") != "assistant":
+                continue
+
+            # OpenAI format: tool_calls array
+            for tc in msg.get("tool_calls", []):
+                if isinstance(tc, dict):
+                    tc_id = tc.get("id", "")
+                    name = tc.get("function", {}).get("name", "")
+                    if tc_id and name:
+                        mapping[tc_id] = name
+
+            # Anthropic format: content blocks with type=tool_use
+            content = msg.get("content", [])
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "tool_use":
+                        tc_id = block.get("id", "")
+                        name = block.get("name", "")
+                        if tc_id and name:
+                            mapping[tc_id] = name
+
+        return mapping
+
+    def apply(
+        self,
+        messages: list[dict[str, Any]],
+        tokenizer: Tokenizer,
+        **kwargs: Any,
+    ) -> TransformResult:
+        """Apply intelligent routing to messages.
+
+        Args:
+            messages: Messages to transform.
+            tokenizer: Tokenizer for counting.
+            **kwargs: Additional arguments (context).
+
+        Returns:
+            TransformResult with routed and compressed messages.
+        """
+        # Pre-process: Read lifecycle management (stale/superseded detection)
+        if self.config.read_lifecycle.enabled:
+            from .read_lifecycle import ReadLifecycleManager
+
+            lifecycle_mgr = ReadLifecycleManager(
+                self.config.read_lifecycle,
+                compression_store=kwargs.get("compression_store"),
+            )
+            lifecycle_result = lifecycle_mgr.apply(
+                messages,
+                frozen_message_count=kwargs.get("frozen_message_count", 0),
+            )
+            messages = lifecycle_result.messages
+            # lifecycle transforms tracked separately, merged at the end
+            lifecycle_transforms = lifecycle_result.transforms_applied
+            lifecycle_ccr_hashes = lifecycle_result.ccr_hashes
+        else:
+            lifecycle_transforms = []
+            lifecycle_ccr_hashes = []
+
+        # Runtime overrides from CompressConfig (via kwargs from compress())
+        # These override self.config defaults for this call only.
+        skip_user = (
+            kwargs.get("compress_user_messages") is not True and self.config.skip_user_messages
+        )
+        skip_system = kwargs.get("compress_system_messages") is False
+        protect_recent = kwargs.get("protect_recent", self.config.protect_recent_code)
+        protect_analysis = kwargs.get(
+            "protect_analysis_context", self.config.protect_analysis_context
+        )
+        min_tokens = kwargs.get("min_tokens_to_compress", 50)
+        # Store runtime options on self for access by _route_and_compress_block
+        self._runtime_target_ratio: float | None = kwargs.get("target_ratio")
+        self._runtime_kompress_model: str | None = kwargs.get("kompress_model")
+
+        tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)
+        context = kwargs.get("context", "")
+        hook_biases: dict[int, float] = kwargs.get("biases") or {}
+
+        # Build tool name map for exclusion checking
+        tool_name_map = self._build_tool_name_map(messages)
+
+        # Compute excluded tool IDs based on config
+        exclude_tools = (
+            self.config.exclude_tools
+            if self.config.exclude_tools is not None
+            else DEFAULT_EXCLUDE_TOOLS
+        )
+        excluded_tool_ids = {
+            tool_id for tool_id, name in tool_name_map.items() if name in exclude_tools
+        }
+
+        # --- Adaptive parameters based on context pressure ---
+        num_messages = len(messages)
+        model_limit = kwargs.get("model_limit", 0)
+
+        # Adaptive Read protection: protect a fraction of recent messages
+        if self.config.protect_recent_reads_fraction > 0:
+            # Scale: at 10 msgs protect 5, at 50 msgs protect 25, at 200 msgs protect 100
+            # But cap at a reasonable floor so very short convos still protect everything
+            read_protection_window = max(
+                4,  # always protect at least last 4 messages
+                int(num_messages * self.config.protect_recent_reads_fraction),
+            )
+        else:
+            read_protection_window = num_messages  # 0.0 = protect all (old behavior)
+
+        # Adaptive compression ratio: scale with context pressure
+        if model_limit > 0:
+            context_pressure = min(1.0, tokens_before / model_limit)
+        else:
+            context_pressure = 0.5  # default: moderate
+
+        # Linear interpolation between relaxed and aggressive thresholds
+        # pressure 0.0 → relaxed, pressure 1.0 → aggressive
+        min_ratio = (
+            self.config.min_ratio_relaxed
+            + (self.config.min_ratio_aggressive - self.config.min_ratio_relaxed) * context_pressure
+        )
+        # Clamp to [aggressive, relaxed] range
+        min_ratio = max(
+            self.config.min_ratio_aggressive,
+            min(self.config.min_ratio_relaxed, min_ratio),
+        )
+
+        if context_pressure > 0.3:
+            logger.debug(
+                "content_router adaptive: pressure=%.2f, min_ratio=%.2f, "
+                "read_protect_window=%d/%d msgs",
+                context_pressure,
+                min_ratio,
+                read_protection_window,
+                num_messages,
+            )
+
+        transformed_messages: list[dict[str, Any]] = []
+        transforms_applied: list[str] = []
+        warnings: list[str] = []
+        compressor_timing: dict[str, float] = {}  # strategy → cumulative ms
+
+        # Routing reason counters for summary logging
+        route_counts: dict[str, int] = {
+            "excluded_tool": 0,
+            "user_msg": 0,
+            "small": 0,
+            "recent_code": 0,
+            "analysis_ctx": 0,
+            "ratio_too_high": 0,
+            "non_string": 0,
+            "content_blocks": 0,
+        }
+        compressed_details: list[str] = []  # e.g. ["code_aware:0.72", "kompress:0.65"]
+
+        # Check for analysis intent in the most recent user message
+        analysis_intent = False
+        if self.config.protect_analysis_context:
+            analysis_intent = self._detect_analysis_intent(messages)
+
+        frozen_message_count = kwargs.get("frozen_message_count", 0)
+
+        # ------------------------------------------------------------------
+        # Two-pass parallel compression.
+        #
+        # Pass 1 (sequential): categorise every message — frozen, protected,
+        #   cached, small, etc. are resolved immediately.  Cache-miss messages
+        #   that need full compression are collected into *pending_tasks*.
+        #
+        # Pass 2 (parallel): all cache-miss compressions run concurrently in
+        #   a thread pool.  Each self.compress() call is independent.
+        #
+        # Pass 3 (sequential): results are stitched back into message order,
+        #   caches updated, and counters incremented.
+        # ------------------------------------------------------------------
+
+        # Pre-allocate result slots — None means "pending compression".
+        result_slots: list[dict[str, Any] | None] = [None] * num_messages
+
+        # Tasks: list of (slot_index, content, context, bias, content_key)
+        _PendingTask = tuple[int, str, str, float, int]
+        pending_tasks: list[_PendingTask] = []
+
+        for i, message in enumerate(messages):
+            # Skip frozen messages (in provider's prefix cache).
+            # Modifying these would invalidate the cache, replacing a 90%
+            # read discount with a 25% write penalty (Anthropic).
+            if i < frozen_message_count:
+                result_slots[i] = message
+                continue
+
+            role = message.get("role", "")
+            content = message.get("content", "")
+            bias = 1.0  # Default bias, may be overridden for tool messages
+
+            messages_from_end = num_messages - i
+
+            # Handle list content (Anthropic format with content blocks)
+            if isinstance(content, list):
+                transformed_message = self._process_content_blocks(
+                    message,
+                    content,
+                    context,
+                    transforms_applied,
+                    excluded_tool_ids,
+                    tool_name_map=tool_name_map,
+                    route_counts=route_counts,
+                    compressed_details=compressed_details,
+                    min_ratio=min_ratio,
+                    read_protection_window=read_protection_window,
+                    messages_from_end=messages_from_end,
+                    compressor_timing=compressor_timing,
+                )
+                result_slots[i] = transformed_message
+                route_counts["content_blocks"] += 1
+                continue
+
+            # Skip non-string content (other types)
+            if not isinstance(content, str):
+                result_slots[i] = message
+                route_counts["non_string"] += 1
+                continue
+
+            # Skip OpenAI-style tool messages for excluded tools
+            # BUT: allow compression of old excluded-tool outputs beyond the
+            # adaptive protection window (age-based decay).
+            if role == "tool":
+                tool_call_id = message.get("tool_call_id", "")
+                if tool_call_id in excluded_tool_ids:
+                    if messages_from_end <= read_protection_window:
+                        # Recent — protect as before
+                        result_slots[i] = message
+                        transforms_applied.append("router:excluded:tool")
+                        route_counts["excluded_tool"] += 1
+                        continue
+                    # Old excluded-tool output — fall through to compression
+                    # (the LLM is unlikely to need exact content from this far back,
+                    # and CCR provides retrieval if it does)
+                # Look up tool-specific compression bias for OpenAI tool messages
+                tool_name = tool_name_map.get(tool_call_id, "")
+                bias = self._get_tool_bias(tool_name) if tool_name else 1.0
+
+            # Protection 1: Never compress user messages (unless overridden)
+            if skip_user and role == "user":
+                result_slots[i] = message
+                transforms_applied.append("router:protected:user_message")
+                route_counts["user_msg"] += 1
+                continue
+
+            # Protection 1b: Never compress system messages (when disabled)
+            if skip_system and role == "system":
+                result_slots[i] = message
+                transforms_applied.append("router:protected:system_message")
+                route_counts.setdefault("system_msg", 0)
+                route_counts["system_msg"] += 1
+                continue
+
+            if not content or tokenizer.count_text(content) < min_tokens:
+                # Skip small content
+                result_slots[i] = message
+                route_counts["small"] += 1
+                continue
+
+            # Detect content type for protection decisions
+            detection = _detect_content(content)
+            is_code = detection.content_type == ContentType.SOURCE_CODE
+
+            # Protection 2: Don't compress recent CODE
+            messages_from_end = num_messages - i
+            if protect_recent > 0 and messages_from_end <= protect_recent and is_code:
+                result_slots[i] = message
+                transforms_applied.append("router:protected:recent_code")
+                route_counts["recent_code"] += 1
+                continue
+
+            # Protection 3: Don't compress CODE when analysis intent detected
+            if protect_analysis and analysis_intent and is_code:
+                result_slots[i] = message
+                transforms_applied.append("router:protected:analysis_context")
+                route_counts["analysis_ctx"] += 1
+                continue
+
+            # Compression pinning: if this message was already compressed
+            # (contains a CCR retrieval marker), skip recompression.
+            # Recompressing would change byte content and break provider
+            # prefix caching with no meaningful further reduction.
+            if "Retrieve more: hash=" in content or "Retrieve original: hash=" in content:
+                result_slots[i] = message
+                route_counts.setdefault("already_compressed", 0)
+                route_counts["already_compressed"] += 1
+                continue
+
+            # Route and compress based on content detection
+            # Merge tool-specific bias with hook-provided bias (multiplicative)
+            msg_bias = bias if role == "tool" else 1.0
+            if i in hook_biases:
+                msg_bias *= hook_biases[i]
+
+            # 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)
+
+            # Tier 1: skip set — instant rejection
+            if self._cache.is_skipped(content_key):
+                result_slots[i] = message
+                route_counts["ratio_too_high"] += 1
+                route_counts.setdefault("cache_hit", 0)
+                route_counts["cache_hit"] += 1
+                continue
+
+            # Tier 2: result cache — reuse compressed output
+            cached = self._cache.get(content_key)
+            if cached is not None:
+                cached_compressed, cached_ratio, cached_strategy = cached
+                # Re-check ratio against current min_ratio (shifts with context pressure)
+                if cached_ratio < min_ratio:
+                    result_slots[i] = {**message, "content": cached_compressed}
+                    transforms_applied.append(f"router:{cached_strategy}:{cached_ratio:.2f}")
+                    compressed_details.append(f"{cached_strategy}:{cached_ratio:.2f}")
+                else:
+                    # Threshold tightened — no longer qualifies. Move to skip.
+                    self._cache.move_to_skip(content_key)
+                    result_slots[i] = message
+                    route_counts["ratio_too_high"] += 1
+                route_counts.setdefault("cache_hit", 0)
+                route_counts["cache_hit"] += 1
+                continue
+
+            # Cache miss — defer to parallel compression pass
+            route_counts.setdefault("cache_miss", 0)
+            route_counts["cache_miss"] += 1
+            pending_tasks.append((i, content, context, msg_bias, content_key))
+
+        # --- Pass 2: Parallel compression of all cache-miss messages ---
+        if pending_tasks:
+            max_workers = min(
+                len(pending_tasks), int(os.environ.get("HEADROOM_COMPRESS_WORKERS", "4"))
+            )
+            t_parallel_start = time.perf_counter()
+
+            if max_workers <= 1 or len(pending_tasks) == 1:
+                # Single task or parallelism disabled — compress inline
+                task_results = []
+                for _, task_content, task_ctx, task_bias, _ in pending_tasks:
+                    t0 = time.perf_counter()
+                    r = self.compress(task_content, context=task_ctx, bias=task_bias)
+                    task_results.append((r, (time.perf_counter() - t0) * 1000))
+            else:
+                # Parallel compression via thread pool
+                with ThreadPoolExecutor(max_workers=max_workers) as executor:
+                    futures = []
+                    for _, task_content, task_ctx, task_bias, _ in pending_tasks:
+                        futures.append(
+                            executor.submit(self._timed_compress, task_content, task_ctx, task_bias)
+                        )
+                    task_results = [f.result() for f in futures]
+
+            parallel_ms = (time.perf_counter() - t_parallel_start) * 1000
+            compressor_timing["parallel_compress_total"] = parallel_ms
+
+            # --- Pass 3: Merge results back (sequential, updates caches) ---
+            for (slot_idx, _, _, _, content_key), (result, compress_ms) in zip(
+                pending_tasks, task_results
+            ):
+                message = messages[slot_idx]
+                strategy_key = f"compressor:{result.strategy_used.value}"
+                compressor_timing[strategy_key] = (
+                    compressor_timing.get(strategy_key, 0.0) + compress_ms
+                )
+
+                if result.compression_ratio < min_ratio:
+                    # Compressed — store in result cache
+                    self._cache.put(
+                        content_key,
+                        result.compressed,
+                        result.compression_ratio,
+                        result.strategy_used.value,
+                    )
+                    result_slots[slot_idx] = {**message, "content": result.compressed}
+                    transforms_applied.append(
+                        f"router:{result.strategy_used.value}:{result.compression_ratio:.2f}"
+                    )
+                    compressed_details.append(
+                        f"{result.strategy_used.value}:{result.compression_ratio:.2f}"
+                    )
+                else:
+                    # Didn't compress — add to skip set
+                    self._cache.mark_skip(content_key)
+                    result_slots[slot_idx] = message
+                    route_counts["ratio_too_high"] += 1
+
+        # Build final message list from slots
+        transformed_messages = [m for m in result_slots if m is not None]
+
+        tokens_after = sum(
+            tokenizer.count_text(str(m.get("content", ""))) for m in transformed_messages
+        )
+
+        # Log routing summary
+        parts = []
+        if compressed_details:
+            parts.append(f"{len(compressed_details)} compressed ({', '.join(compressed_details)})")
+        if route_counts["excluded_tool"]:
+            parts.append(f"{route_counts['excluded_tool']} excluded (Read/Glob)")
+        if route_counts["user_msg"]:
+            parts.append(f"{route_counts['user_msg']} skipped (user)")
+        if route_counts["small"]:
+            parts.append(f"{route_counts['small']} skipped (<50 words)")
+        if route_counts["recent_code"]:
+            parts.append(f"{route_counts['recent_code']} protected (recent code)")
+        if route_counts["analysis_ctx"]:
+            parts.append(f"{route_counts['analysis_ctx']} protected (analysis ctx)")
+        if route_counts.get("already_compressed"):
+            parts.append(f"{route_counts['already_compressed']} pinned (already compressed)")
+        if route_counts["ratio_too_high"]:
+            parts.append(f"{route_counts['ratio_too_high']} unchanged (ratio>={min_ratio:.2f})")
+        if route_counts["content_blocks"]:
+            parts.append(f"{route_counts['content_blocks']} content-block msgs")
+        if route_counts["non_string"]:
+            parts.append(f"{route_counts['non_string']} non-string")
+        if route_counts.get("cache_hit"):
+            parts.append(f"{route_counts['cache_hit']} cache hits")
+        if route_counts.get("cache_miss"):
+            parts.append(f"{route_counts['cache_miss']} cache misses")
+        cs = self._cache.stats
+        if cs["cache_size"] > 0 or cs["cache_skip_size"] > 0:
+            parts.append(
+                f"cache[{cs['cache_size']} results, {cs['cache_skip_size']} skips, "
+                f"{cs['cache_avg_lookup_ns']:.0f}ns avg]"
+            )
+        if parts:
+            logger.info(
+                "content_router: %d msgs — %s",
+                num_messages,
+                ", ".join(parts),
+            )
+
+        all_transforms = lifecycle_transforms + transforms_applied
+        return TransformResult(
+            messages=transformed_messages,
+            tokens_before=tokens_before,
+            tokens_after=tokens_after,
+            transforms_applied=all_transforms if all_transforms else ["router:noop"],
+            markers_inserted=lifecycle_ccr_hashes,
+            warnings=warnings,
+            timing=compressor_timing,
+        )
+
+    def _get_tool_bias(self, tool_name: str) -> float:
+        """Look up compression bias for a tool name.
+
+        Checks user-configured profiles first, then DEFAULT_TOOL_PROFILES.
+        Returns 1.0 (moderate) if no profile is configured.
+        """
+        from ..config import DEFAULT_TOOL_PROFILES
+
+        # Check user-configured profiles
+        if self.config.tool_profiles:
+            profile = self.config.tool_profiles.get(tool_name)
+            if profile:
+                return float(profile.bias)
+
+        # Check default profiles
+        profile = DEFAULT_TOOL_PROFILES.get(tool_name)
+        if profile:
+            return profile.bias
+
+        return 1.0  # Default: moderate
+
+    def _process_content_blocks(
+        self,
+        message: dict[str, Any],
+        content_blocks: list[Any],
+        context: str,
+        transforms_applied: list[str],
+        excluded_tool_ids: set[str],
+        tool_name_map: dict[str, str] | None = None,
+        route_counts: dict[str, int] | None = None,
+        compressed_details: list[str] | None = None,
+        min_ratio: float = 0.85,
+        read_protection_window: int = 8,
+        messages_from_end: int = 0,
+        compressor_timing: dict[str, float] | None = None,
+    ) -> dict[str, Any]:
+        """Process content blocks (Anthropic format) for tool_result compression.
+
+        Handles tool_result blocks by compressing their string content using
+        the appropriate strategy (typically SmartCrusher for JSON arrays).
+
+        Args:
+            message: The original message.
+            content_blocks: List of content blocks.
+            context: Context for compression.
+            transforms_applied: List to append transform names to.
+            excluded_tool_ids: Tool IDs to skip compression for.
+            tool_name_map: Mapping from tool_call_id to tool_name for profile lookup.
+            route_counts: Optional routing reason counters to update.
+            compressed_details: Optional list to append compression details to.
+            min_ratio: Adaptive compression ratio threshold.
+            read_protection_window: Messages from end within which excluded tools are protected.
+            messages_from_end: How far this message is from the end of the conversation.
+
+        Returns:
+            Transformed message with compressed content blocks.
+        """
+        new_blocks = []
+        any_compressed = False
+
+        for block in content_blocks:
+            if not isinstance(block, dict):
+                new_blocks.append(block)
+                continue
+
+            block_type = block.get("type")
+
+            # Handle tool_result blocks
+            if block_type == "tool_result":
+                # Check if tool is excluded from compression
+                tool_use_id = block.get("tool_use_id", "")
+                if tool_use_id in excluded_tool_ids:
+                    if messages_from_end <= read_protection_window:
+                        # Recent — protect as before
+                        new_blocks.append(block)
+                        transforms_applied.append("router:excluded:tool")
+                        if route_counts is not None:
+                            route_counts["excluded_tool"] += 1
+                        continue
+                    # Old excluded-tool output — fall through to compression
+
+                # Look up tool-specific compression bias
+                tool_name = (tool_name_map or {}).get(tool_use_id, "")
+                bias = self._get_tool_bias(tool_name) if tool_name else 1.0
+
+                tool_content = block.get("content", "")
+
+                # Only process string content
+                if isinstance(tool_content, str) and len(tool_content) > 500:
+                    # Compression pinning: skip already-compressed content
+                    if (
+                        "Retrieve more: hash=" in tool_content
+                        or "Retrieve original: hash=" in tool_content
+                    ):
+                        new_blocks.append(block)
+                        if route_counts is not None:
+                            route_counts.setdefault("already_compressed", 0)
+                            route_counts["already_compressed"] += 1
+                        continue
+
+                    # Two-tier compression cache
+                    content_key = hash(tool_content)
+
+                    # Tier 1: skip set — instant rejection
+                    if self._cache.is_skipped(content_key):
+                        new_blocks.append(block)
+                        if route_counts is not None:
+                            route_counts["ratio_too_high"] += 1
+                            route_counts.setdefault("cache_hit", 0)
+                            route_counts["cache_hit"] += 1
+                        continue
+
+                    # Tier 2: result cache — reuse compressed output
+                    cached = self._cache.get(content_key)
+                    if cached is not None:
+                        cached_compressed, cached_ratio, cached_strategy = cached
+                        if cached_ratio < min_ratio:
+                            new_blocks.append({**block, "content": cached_compressed})
+                            transforms_applied.append(f"router:tool_result:{cached_strategy}")
+                            if compressed_details is not None:
+                                compressed_details.append(
+                                    f"tool:{cached_strategy}:{cached_ratio:.2f}"
+                                )
+                            any_compressed = True
+                        else:
+                            # Threshold tightened — move to skip
+                            self._cache.move_to_skip(content_key)
+                            new_blocks.append(block)
+                            if route_counts is not None:
+                                route_counts["ratio_too_high"] += 1
+                        if route_counts is not None:
+                            route_counts.setdefault("cache_hit", 0)
+                            route_counts["cache_hit"] += 1
+                        continue
+
+                    # Cache miss — run full compression
+                    if route_counts is not None:
+                        route_counts.setdefault("cache_miss", 0)
+                        route_counts["cache_miss"] += 1
+                    t0 = time.perf_counter()
+                    result = self.compress(tool_content, context=context, bias=bias)
+                    compress_ms = (time.perf_counter() - t0) * 1000
+                    if compressor_timing is not None:
+                        key = f"compressor:{result.strategy_used.value}"
+                        compressor_timing[key] = compressor_timing.get(key, 0.0) + compress_ms
+                    if result.compression_ratio < min_ratio:
+                        # Compressed — store in result cache
+                        self._cache.put(
+                            content_key,
+                            result.compressed,
+                            result.compression_ratio,
+                            result.strategy_used.value,
+                        )
+                        new_blocks.append({**block, "content": result.compressed})
+                        transforms_applied.append(
+                            f"router:tool_result:{result.strategy_used.value}"
+                        )
+                        if compressed_details is not None:
+                            compressed_details.append(
+                                f"tool:{result.strategy_used.value}:{result.compression_ratio:.2f}"
+                            )
+                        any_compressed = True
+                        continue
+                    else:
+                        # Didn't compress — add to skip set
+                        self._cache.mark_skip(content_key)
+                        if route_counts is not None:
+                            route_counts["ratio_too_high"] += 1
+                else:
+                    if route_counts is not None:
+                        route_counts["small"] += 1
+
+            # Keep block unchanged
+            new_blocks.append(block)
+
+        if any_compressed:
+            return {**message, "content": new_blocks}
+        return message
+
+    def _detect_analysis_intent(self, messages: list[dict[str, Any]]) -> bool:
+        """Detect if user wants to analyze/review code.
+
+        Looks at the most recent user message for analysis keywords.
+
+        Args:
+            messages: Conversation messages.
+
+        Returns:
+            True if analysis intent detected.
+        """
+        # Analysis keywords that suggest user wants full code details
+        analysis_keywords = {
+            "analyze",
+            "analyse",
+            "review",
+            "audit",
+            "inspect",
+            "security",
+            "vulnerability",
+            "bug",
+            "issue",
+            "problem",
+            "explain",
+            "understand",
+            "how does",
+            "what does",
+            "debug",
+            "fix",
+            "error",
+            "wrong",
+            "broken",
+            "refactor",
+            "improve",
+            "optimize",
+            "clean up",
+        }
+
+        # Find most recent user message
+        for message in reversed(messages):
+            if message.get("role") == "user":
+                content = message.get("content", "")
+                if isinstance(content, str):
+                    content_lower = content.lower()
+                    for keyword in analysis_keywords:
+                        if keyword in content_lower:
+                            return True
+                break
+
+        return False
+
+    def should_apply(
+        self,
+        messages: list[dict[str, Any]],
+        tokenizer: Tokenizer,
+        **kwargs: Any,
+    ) -> bool:
+        """Check if routing should be applied.
+
+        Always returns True - the router handles all content types.
+        """
+        return True
+
+
+def route_and_compress(
+    content: str,
+    context: str = "",
+) -> str:
+    """Convenience function for one-off routing and compression.
+
+    Args:
+        content: Content to compress.
+        context: Optional context for relevance-aware compression.
+
+    Returns:
+        Compressed content.
+
+    Example:
+        >>> compressed = route_and_compress(mixed_content)
+    """
+    router = ContentRouter()
+    result = router.compress(content, context=context)
+    return result.compressed
diff --git a/scripts/changelog-gen.py b/scripts/changelog-gen.py
index 761591643f78d278bcc0974de8980f8071e4eb67..3364e1794d62cf5c5a59678b2e5d81b32a0749a3 100644
--- a/scripts/changelog-gen.py
+++ b/scripts/changelog-gen.py
@@ -1,203 +1,203 @@
-#!/usr/bin/env python3
-"""Generate changelog from conventional commits."""
-
-from __future__ import annotations
-
-import argparse
-import re
-import subprocess
-from datetime import date
-from pathlib import Path
-from typing import NamedTuple
-
-ROOT = Path(__file__).parent.parent
-
-COMMIT_PATTERN = re.compile(
-    r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"
-)
-BREAKING_CHANGE_PATTERN = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)
-COMMIT_ENTRY_PATTERN = re.compile(r"^(.+?)(?:\n(.+))?\|(\w+)$", re.MULTILINE)
-FIELD_SEP = "\x1f"
-RECORD_SEP = "\x1e"
-GIT_LOG_FORMAT = "%s%x1f%b%x1f%h%x1e"
-
-TYPE_LABELS: dict[str, str] = {
-    "feat": "Features",
-    "fix": "Bug Fixes",
-    "ci": "CI/CD",
-    "chore": "Chores",
-    "perf": "Performance",
-    "refactor": "Refactors",
-    "docs": "Documentation",
-    "style": "Styles",
-    "test": "Tests",
-    "other": "Other Changes",
-}
-
-
-class ParsedCommit(NamedTuple):
-    type: str
-    scope: str | None
-    breaking: bool
-    message: str
-    hash: str
-
-
-def iter_commit_entries(log_output: str) -> list[tuple[str, str, str]]:
-    """Split raw git log output into (subject, body, hash) tuples."""
-
-    if not log_output.strip():
-        return []
-
-    if RECORD_SEP in log_output and FIELD_SEP in log_output:
-        entries: list[tuple[str, str, str]] = []
-        for raw_entry in log_output.split(RECORD_SEP):
-            if not raw_entry:
-                continue
-            if FIELD_SEP not in raw_entry:
-                continue
-            subject, body_and_hash = raw_entry.split(FIELD_SEP, 1)
-            if FIELD_SEP not in body_and_hash:
-                continue
-            body, commit_hash = body_and_hash.rsplit(FIELD_SEP, 1)
-            entries.append((subject.strip(), body.strip(), commit_hash.strip()))
-        return entries
-
-    return [
-        (
-            match.group(1).strip(),
-            (match.group(2) or "").strip(),
-            match.group(3).strip(),
-        )
-        for match in COMMIT_ENTRY_PATTERN.finditer(log_output)
-    ]
-
-
-def get_merge_summary(subject: str, body: str) -> str:
-    """Return the first meaningful summary line for a merge commit."""
-
-    if not subject.startswith("Merge "):
-        return ""
-
-    for line in body.splitlines():
-        stripped = line.strip()
-        if stripped:
-            return stripped
-    return ""
-
-
-def parse_commits(log_output: str) -> list[ParsedCommit]:
-    """Parse git log output into structured commits."""
-
-    commits: list[ParsedCommit] = []
-
-    for subject, body, commit_hash in iter_commit_entries(log_output):
-        is_breaking = bool(BREAKING_CHANGE_PATTERN.search(body))
-        merge_summary = get_merge_summary(subject, body)
-        candidates = [subject]
-        if merge_summary:
-            candidates.insert(0, merge_summary)
-
-        for candidate in candidates:
-            commit_match = COMMIT_PATTERN.match(candidate)
-            if not commit_match:
-                continue
-
-            scope = commit_match.group(2)
-            if scope:
-                scope = scope[1:-1]
-            commits.append(
-                ParsedCommit(
-                    type=commit_match.group(1),
-                    scope=scope,
-                    breaking=is_breaking or bool(commit_match.group(3)),
-                    message=commit_match.group(4),
-                    hash=commit_hash,
-                )
-            )
-            break
-        else:
-            fallback_message = merge_summary or subject
-            if not fallback_message or fallback_message.startswith("Merge "):
-                continue
-            commits.append(
-                ParsedCommit(
-                    type="other",
-                    scope=None,
-                    breaking=is_breaking,
-                    message=fallback_message,
-                    hash=commit_hash,
-                )
-            )
-
-    return commits
-
-
-def generate_changelog(version: str, commits: list[ParsedCommit]) -> str:
-    """Generate markdown changelog from parsed commits."""
-    today = date.today().isoformat()
-    lines = [f"## [{version}] - {today}", ""]
-
-    # Collect breaking changes
-    breaking_commits = [c for c in commits if c.breaking]
-    if breaking_commits:
-        lines.append("### Breaking Changes")
-        for commit in breaking_commits:
-            if commit.scope:
-                lines.append(f"- **{commit.scope}**: {commit.message} ({commit.hash})")
-            else:
-                lines.append(f"- {commit.message} ({commit.hash})")
-        lines.append("")
-
-    # Group by type
-    by_type: dict[str, list[ParsedCommit]] = {}
-    for commit in commits:
-        by_type.setdefault(commit.type, []).append(commit)
-
-    for commit_type, label in TYPE_LABELS.items():
-        type_commits = by_type.get(commit_type, [])
-        if not type_commits:
-            continue
-        lines.append(f"### {label}")
-        for commit in type_commits:
-            if commit.scope:
-                lines.append(f"- **{commit.scope}**: {commit.message} ({commit.hash})")
-            else:
-                lines.append(f"- {commit.message} ({commit.hash})")
-        lines.append("")
-
-    return "\n".join(lines) + "\n"
-
-
-def run_git_log(since: str | None, cwd: Path) -> str:
-    """Run git log command and return output."""
-    cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]
-    if since:
-        cmd.append(f"{since}..HEAD")
-    else:
-        cmd.append("HEAD")
-    result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
-    return result.stdout
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Generate changelog from conventional commits")
-    parser.add_argument("--version", required=True, help="Version number (e.g., 0.6.0)")
-    parser.add_argument("--since", help="Starting tag (exclusive)")
-    parser.add_argument("--dry-run", action="store_true", help="Print to stdout instead of writing")
-    args = parser.parse_args()
-
-    log_output = run_git_log(args.since, ROOT)
-    commits = parse_commits(log_output)
-    changelog = generate_changelog(args.version, commits)
-
-    if args.dry_run:
-        print(changelog)
-    else:
-        output_path = ROOT / ".changelog.md"
-        output_path.write_text(changelog, encoding="utf-8")
-        print(f"Changelog written to {output_path}")
-
-
-if __name__ == "__main__":
-    main()
+#!/usr/bin/env python3
+"""Generate changelog from conventional commits."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+from datetime import date
+from pathlib import Path
+from typing import NamedTuple
+
+ROOT = Path(__file__).parent.parent
+
+COMMIT_PATTERN = re.compile(
+    r"^(feat|fix|ci|chore|perf|refactor|docs|style|test)(\(.+\))?(!)?:\s*(.+)$"
+)
+BREAKING_CHANGE_PATTERN = re.compile(r"^BREAKING CHANGE:\s*(.+)$", re.MULTILINE)
+COMMIT_ENTRY_PATTERN = re.compile(r"^(.+?)(?:\n(.+))?\|(\w+)$", re.MULTILINE)
+FIELD_SEP = "\x1f"
+RECORD_SEP = "\x1e"
+GIT_LOG_FORMAT = "%s%x1f%b%x1f%h%x1e"
+
+TYPE_LABELS: dict[str, str] = {
+    "feat": "Features",
+    "fix": "Bug Fixes",
+    "ci": "CI/CD",
+    "chore": "Chores",
+    "perf": "Performance",
+    "refactor": "Refactors",
+    "docs": "Documentation",
+    "style": "Styles",
+    "test": "Tests",
+    "other": "Other Changes",
+}
+
+
+class ParsedCommit(NamedTuple):
+    type: str
+    scope: str | None
+    breaking: bool
+    message: str
+    hash: str
+
+
+def iter_commit_entries(log_output: str) -> list[tuple[str, str, str]]:
+    """Split raw git log output into (subject, body, hash) tuples."""
+
+    if not log_output.strip():
+        return []
+
+    if RECORD_SEP in log_output and FIELD_SEP in log_output:
+        entries: list[tuple[str, str, str]] = []
+        for raw_entry in log_output.split(RECORD_SEP):
+            if not raw_entry:
+                continue
+            if FIELD_SEP not in raw_entry:
+                continue
+            subject, body_and_hash = raw_entry.split(FIELD_SEP, 1)
+            if FIELD_SEP not in body_and_hash:
+                continue
+            body, commit_hash = body_and_hash.rsplit(FIELD_SEP, 1)
+            entries.append((subject.strip(), body.strip(), commit_hash.strip()))
+        return entries
+
+    return [
+        (
+            match.group(1).strip(),
+            (match.group(2) or "").strip(),
+            match.group(3).strip(),
+        )
+        for match in COMMIT_ENTRY_PATTERN.finditer(log_output)
+    ]
+
+
+def get_merge_summary(subject: str, body: str) -> str:
+    """Return the first meaningful summary line for a merge commit."""
+
+    if not subject.startswith("Merge "):
+        return ""
+
+    for line in body.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return ""
+
+
+def parse_commits(log_output: str) -> list[ParsedCommit]:
+    """Parse git log output into structured commits."""
+
+    commits: list[ParsedCommit] = []
+
+    for subject, body, commit_hash in iter_commit_entries(log_output):
+        is_breaking = bool(BREAKING_CHANGE_PATTERN.search(body))
+        merge_summary = get_merge_summary(subject, body)
+        candidates = [subject]
+        if merge_summary:
+            candidates.insert(0, merge_summary)
+
+        for candidate in candidates:
+            commit_match = COMMIT_PATTERN.match(candidate)
+            if not commit_match:
+                continue
+
+            scope = commit_match.group(2)
+            if scope:
+                scope = scope[1:-1]
+            commits.append(
+                ParsedCommit(
+                    type=commit_match.group(1),
+                    scope=scope,
+                    breaking=is_breaking or bool(commit_match.group(3)),
+                    message=commit_match.group(4),
+                    hash=commit_hash,
+                )
+            )
+            break
+        else:
+            fallback_message = merge_summary or subject
+            if not fallback_message or fallback_message.startswith("Merge "):
+                continue
+            commits.append(
+                ParsedCommit(
+                    type="other",
+                    scope=None,
+                    breaking=is_breaking,
+                    message=fallback_message,
+                    hash=commit_hash,
+                )
+            )
+
+    return commits
+
+
+def generate_changelog(version: str, commits: list[ParsedCommit]) -> str:
+    """Generate markdown changelog from parsed commits."""
+    today = date.today().isoformat()
+    lines = [f"## [{version}] - {today}", ""]
+
+    # Collect breaking changes
+    breaking_commits = [c for c in commits if c.breaking]
+    if breaking_commits:
+        lines.append("### Breaking Changes")
+        for commit in breaking_commits:
+            if commit.scope:
+                lines.append(f"- **{commit.scope}**: {commit.message} ({commit.hash})")
+            else:
+                lines.append(f"- {commit.message} ({commit.hash})")
+        lines.append("")
+
+    # Group by type
+    by_type: dict[str, list[ParsedCommit]] = {}
+    for commit in commits:
+        by_type.setdefault(commit.type, []).append(commit)
+
+    for commit_type, label in TYPE_LABELS.items():
+        type_commits = by_type.get(commit_type, [])
+        if not type_commits:
+            continue
+        lines.append(f"### {label}")
+        for commit in type_commits:
+            if commit.scope:
+                lines.append(f"- **{commit.scope}**: {commit.message} ({commit.hash})")
+            else:
+                lines.append(f"- {commit.message} ({commit.hash})")
+        lines.append("")
+
+    return "\n".join(lines) + "\n"
+
+
+def run_git_log(since: str | None, cwd: Path) -> str:
+    """Run git log command and return output."""
+    cmd = ["git", "log", "--first-parent", f"--pretty=format:{GIT_LOG_FORMAT}"]
+    if since:
+        cmd.append(f"{since}..HEAD")
+    else:
+        cmd.append("HEAD")
+    result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
+    return result.stdout
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate changelog from conventional commits")
+    parser.add_argument("--version", required=True, help="Version number (e.g., 0.6.0)")
+    parser.add_argument("--since", help="Starting tag (exclusive)")
+    parser.add_argument("--dry-run", action="store_true", help="Print to stdout instead of writing")
+    args = parser.parse_args()
+
+    log_output = run_git_log(args.since, ROOT)
+    commits = parse_commits(log_output)
+    changelog = generate_changelog(args.version, commits)
+
+    if args.dry_run:
+        print(changelog)
+    else:
+        output_path = ROOT / ".changelog.md"
+        output_path.write_text(changelog, encoding="utf-8")
+        print(f"Changelog written to {output_path}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/sync-plugin-versions.py b/scripts/sync-plugin-versions.py
index e262172263e016519769dd77fe43bab15f7241a5..b8d88d4f1a16a5b5902c378797ea2feca95b76e0 100644
--- a/scripts/sync-plugin-versions.py
+++ b/scripts/sync-plugin-versions.py
@@ -1,55 +1,55 @@
-"""Sync plugin manifest versions to the repo's computed release semver."""
-
-from __future__ import annotations
-
-import subprocess
-import sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-if str(ROOT) not in sys.path:
-    sys.path.insert(0, str(ROOT))
-
-from headroom.release_version import (  # noqa: E402
-    compute_release_version,
-    determine_bump_level,
-    find_latest_release_tag,
-    get_canonical_version,
-    list_release_commits,
-    list_release_tags,
-)
-
-
-def compute_repo_semver(root: Path) -> str:
-    """Return the npm-style semver for the repo's next release."""
-    tags = list_release_tags(root)
-    previous_tag = find_latest_release_tag(tags) or ""
-    level = determine_bump_level(list_release_commits(root, previous_tag))
-    info = compute_release_version(
-        canonical_version=get_canonical_version(root),
-        level=level,
-        tags=tags,
-    )
-    return info.npm_version
-
-
-def main() -> None:
-    root = ROOT
-    version = compute_repo_semver(root)
-    subprocess.run(
-        [
-            sys.executable,
-            str(root / "scripts" / "version-sync.py"),
-            "--root",
-            str(root),
-            "--version",
-            version,
-            "--plugin-manifests-only",
-        ],
-        cwd=root,
-        check=True,
-    )
-
-
-if __name__ == "__main__":
-    main()
+"""Sync plugin manifest versions to the repo's computed release semver."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from headroom.release_version import (  # noqa: E402
+    compute_release_version,
+    determine_bump_level,
+    find_latest_release_tag,
+    get_canonical_version,
+    list_release_commits,
+    list_release_tags,
+)
+
+
+def compute_repo_semver(root: Path) -> str:
+    """Return the npm-style semver for the repo's next release."""
+    tags = list_release_tags(root)
+    previous_tag = find_latest_release_tag(tags) or ""
+    level = determine_bump_level(list_release_commits(root, previous_tag))
+    info = compute_release_version(
+        canonical_version=get_canonical_version(root),
+        level=level,
+        tags=tags,
+    )
+    return info.npm_version
+
+
+def main() -> None:
+    root = ROOT
+    version = compute_repo_semver(root)
+    subprocess.run(
+        [
+            sys.executable,
+            str(root / "scripts" / "version-sync.py"),
+            "--root",
+            str(root),
+            "--version",
+            version,
+            "--plugin-manifests-only",
+        ],
+        cwd=root,
+        check=True,
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/tests/test_changelog_gen.py b/scripts/tests/test_changelog_gen.py
index 00ba618a8ab48f98f4639f32b973509fee4f4355..cca0022e8f0a7edf68aaf5d5fea9c921f366e363 100644
--- a/scripts/tests/test_changelog_gen.py
+++ b/scripts/tests/test_changelog_gen.py
@@ -1,302 +1,302 @@
-"""Tests for changelog-gen.py."""
-
-from __future__ import annotations
-
-import importlib.util
-from pathlib import Path
-
-import pytest
-
-ROOT = Path(__file__).resolve().parent.parent.parent
-
-# Load changelog_gen module from scripts directory (filename has hyphen)
-_spec = importlib.util.spec_from_file_location(
-    "changelog_gen", ROOT / "scripts" / "changelog-gen.py"
-)
-if _spec is None:
-    raise ImportError("Could not load changelog_gen module")
-_changelog_gen = importlib.util.module_from_spec(_spec)
-if _spec.loader is None:
-    raise ImportError("Could not load changelog_gen module")
-_spec.loader.exec_module(_changelog_gen)
-
-COMMIT_PATTERN = _changelog_gen.COMMIT_PATTERN
-BREAKING_CHANGE_PATTERN = _changelog_gen.BREAKING_CHANGE_PATTERN
-FIELD_SEP = _changelog_gen.FIELD_SEP
-RECORD_SEP = _changelog_gen.RECORD_SEP
-ParsedCommit = _changelog_gen.ParsedCommit
-generate_changelog = _changelog_gen.generate_changelog
-iter_commit_entries = _changelog_gen.iter_commit_entries
-parse_commits = _changelog_gen.parse_commits
-
-
-def make_log_entry(subject: str, commit_hash: str, body: str = "") -> str:
-    return f"{subject}{FIELD_SEP}{body}{FIELD_SEP}{commit_hash}{RECORD_SEP}"
-
-
-class TestParseCommits:
-    """Tests for parse_commits function."""
-
-    def test_parses_feat_commit(self) -> None:
-        log_output = make_log_entry("feat(core): add feature", "abc1234")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "feat"
-        assert commits[0].scope == "core"
-        assert commits[0].message == "add feature"
-        assert commits[0].hash == "abc1234"
-        assert commits[0].breaking is False
-
-    def test_parses_fix_commit(self) -> None:
-        log_output = make_log_entry("fix(ui): fix bug", "def5678")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "fix"
-        assert commits[0].scope == "ui"
-        assert commits[0].message == "fix bug"
-        assert commits[0].hash == "def5678"
-
-    def test_parses_ci_commit(self) -> None:
-        log_output = make_log_entry("ci: update github actions", "xyz789")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "ci"
-        assert commits[0].scope is None
-        assert commits[0].message == "update github actions"
-        assert commits[0].hash == "xyz789"
-
-    def test_parses_chore_commit(self) -> None:
-        log_output = make_log_entry("chore: cleanup", "xyz999")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "chore"
-        assert commits[0].scope is None
-
-    def test_parses_perf_commit(self) -> None:
-        log_output = make_log_entry("perf(dashboard): improve performance", "abc111")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "perf"
-        assert commits[0].scope == "dashboard"
-
-    def test_parses_refactor_commit(self) -> None:
-        log_output = make_log_entry("refactor(api): refactor endpoint", "abc222")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "refactor"
-        assert commits[0].scope == "api"
-
-    def test_parses_docs_commit(self) -> None:
-        log_output = make_log_entry("docs: update readme", "abc333")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "docs"
-
-    def test_parses_style_commit(self) -> None:
-        log_output = make_log_entry("style: format code", "abc444")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "style"
-
-    def test_parses_test_commit(self) -> None:
-        log_output = make_log_entry("test: add tests for feature", "abc555")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "test"
-
-    def test_detects_breaking_change_in_body(self) -> None:
-        log_output = make_log_entry(
-            "feat(core): add feature",
-            "abc666",
-            "BREAKING CHANGE: api changed",
-        )
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].breaking is True
-
-    def test_detects_breaking_change_exclamation(self) -> None:
-        log_output = make_log_entry("feat(core)!: api changed", "abc777")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].breaking is True
-
-    def test_no_scope_no_problem(self) -> None:
-        log_output = make_log_entry("feat: simple feature", "abc888")
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].scope is None
-        assert commits[0].message == "simple feature"
-
-    def test_uses_pr_title_from_merge_commit_body(self) -> None:
-        log_output = make_log_entry(
-            "Merge pull request #173 from JerrettDavis/fix/pipeline-permissions-and-docs",
-            "73f6673",
-            "fix: repair release and docs pipelines",
-        )
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "fix"
-        assert commits[0].message == "repair release and docs pipelines"
-
-    def test_falls_back_to_other_changes_for_non_conventional_merge(self) -> None:
-        log_output = make_log_entry(
-            "Merge pull request #186 from skorokithakis/patch-1",
-            "1e80ee3",
-            "Add support for custom Anthropic API URL",
-        )
-        commits = parse_commits(log_output)
-        assert len(commits) == 1
-        assert commits[0].type == "other"
-        assert commits[0].message == "Add support for custom Anthropic API URL"
-
-    def test_iter_commit_entries_parses_real_git_log_delimiters(self) -> None:
-        log_output = make_log_entry(
-            "fix: patch release flow", "abc1234", "BREAKING CHANGE: no"
-        ) + make_log_entry("docs: update readme", "def5678")
-        assert iter_commit_entries(log_output) == [
-            ("fix: patch release flow", "BREAKING CHANGE: no", "abc1234"),
-            ("docs: update readme", "", "def5678"),
-        ]
-
-    def test_iter_commit_entries_keeps_field_separator_inside_body(self) -> None:
-        body = f"line one{FIELD_SEP}line two"
-        log_output = make_log_entry("fix: patch release flow", "abc1234", body)
-        assert iter_commit_entries(log_output) == [
-            ("fix: patch release flow", body, "abc1234"),
-        ]
-
-
-class TestGenerateChangelog:
-    """Tests for generate_changelog function."""
-
-    def test_generates_version_header(self) -> None:
-        commits = [
-            ParsedCommit(type="feat", scope=None, breaking=False, message="test", hash="abc123")
-        ]
-        result = generate_changelog("0.6.0", commits)
-        assert "## [0.6.0]" in result
-
-    def test_includes_date(self) -> None:
-        commits = []
-        result = generate_changelog("0.6.0", commits)
-        import re
-
-        date_match = re.search(r"\d{4}-\d{2}-\d{2}", result)
-        assert date_match is not None
-
-    def test_groups_by_type(self) -> None:
-        commits = [
-            ParsedCommit(
-                type="feat", scope=None, breaking=False, message="add feature", hash="abc123"
-            ),
-            ParsedCommit(type="fix", scope=None, breaking=False, message="fix bug", hash="def456"),
-        ]
-        result = generate_changelog("0.6.0", commits)
-        assert "### Features" in result
-        assert "### Bug Fixes" in result
-        assert "- add feature (abc123)" in result
-        assert "- fix bug (def456)" in result
-
-    def test_includes_scope_in_bullet(self) -> None:
-        commits = [
-            ParsedCommit(
-                type="feat", scope="core", breaking=False, message="add feature", hash="abc123"
-            )
-        ]
-        result = generate_changelog("0.6.0", commits)
-        assert "- **core**: add feature (abc123)" in result
-
-    def test_breaking_change_section_when_present(self) -> None:
-        commits = [
-            ParsedCommit(
-                type="feat", scope="core", breaking=True, message="api changed", hash="abc123"
-            )
-        ]
-        result = generate_changelog("0.6.0", commits)
-        assert "### Breaking Changes" in result
-        assert "**core**" in result
-
-    def test_no_breaking_change_section_when_none(self) -> None:
-        commits = [
-            ParsedCommit(
-                type="feat", scope=None, breaking=False, message="add feature", hash="abc123"
-            )
-        ]
-        result = generate_changelog("0.6.0", commits)
-        assert "Breaking Changes" not in result
-
-    def test_includes_other_changes_section(self) -> None:
-        commits = [
-            ParsedCommit(
-                type="other",
-                scope=None,
-                breaking=False,
-                message="Add support for custom Anthropic API URL",
-                hash="abc123",
-            )
-        ]
-        result = generate_changelog("0.6.0", commits)
-        assert "### Other Changes" in result
-        assert "- Add support for custom Anthropic API URL (abc123)" in result
-
-
-class TestIntegrationWithMock:
-    """Integration tests with mocked subprocess.run."""
-
-    def test_full_flow_with_mocked_git(self) -> None:
-        log_output = (
-            make_log_entry("feat(core): add new feature", "abc1234")
-            + make_log_entry("fix(ui): fix bug", "def5678")
-            + make_log_entry("ci: update github actions", "xyz789")
-            + make_log_entry(
-                "feat(outer): breaking change", "bbb111", "BREAKING CHANGE: this is breaking"
-            )
-            + make_log_entry("chore: cleanup", "yyy999")
-        )
-        commits = parse_commits(log_output)
-
-        assert len(commits) == 5
-        assert any(c.type == "feat" and c.scope == "core" for c in commits)
-        assert any(c.type == "fix" and c.scope == "ui" for c in commits)
-        assert any(c.type == "ci" for c in commits)
-        assert any(c.type == "feat" and c.breaking for c in commits)
-        assert any(c.type == "chore" for c in commits)
-
-        changelog = generate_changelog("0.7.0", commits)
-        assert "## [0.7.0]" in changelog
-        assert "### Features" in changelog
-        assert "### Bug Fixes" in changelog
-        assert "### CI/CD" in changelog
-        assert "### Breaking Changes" in changelog
-
-
-class TestCommitPattern:
-    """Tests for the commit regex pattern."""
-
-    def test_feat_with_scope(self) -> None:
-        match = COMMIT_PATTERN.match("feat(core): add feature")
-        assert match is not None
-        assert match.group(1) == "feat"
-        assert match.group(2) == "(core)"
-        assert match.group(4) == "add feature"
-
-    def test_fix_without_scope(self) -> None:
-        match = COMMIT_PATTERN.match("fix: fix bug")
-        assert match is not None
-        assert match.group(1) == "fix"
-        assert match.group(2) is None
-        assert match.group(4) == "fix bug"
-
-    def test_with_exclamation(self) -> None:
-        match = COMMIT_PATTERN.match("feat(core)!: api changed")
-        assert match is not None
-        assert match.group(3) == "!"
-
-    def test_without_exclamation(self) -> None:
-        match = COMMIT_PATTERN.match("feat(core): add feature")
-        assert match is not None
-        assert match.group(3) is None
-
-
-if __name__ == "__main__":
-    pytest.main([__file__, "-v"])
+"""Tests for changelog-gen.py."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+
+# Load changelog_gen module from scripts directory (filename has hyphen)
+_spec = importlib.util.spec_from_file_location(
+    "changelog_gen", ROOT / "scripts" / "changelog-gen.py"
+)
+if _spec is None:
+    raise ImportError("Could not load changelog_gen module")
+_changelog_gen = importlib.util.module_from_spec(_spec)
+if _spec.loader is None:
+    raise ImportError("Could not load changelog_gen module")
+_spec.loader.exec_module(_changelog_gen)
+
+COMMIT_PATTERN = _changelog_gen.COMMIT_PATTERN
+BREAKING_CHANGE_PATTERN = _changelog_gen.BREAKING_CHANGE_PATTERN
+FIELD_SEP = _changelog_gen.FIELD_SEP
+RECORD_SEP = _changelog_gen.RECORD_SEP
+ParsedCommit = _changelog_gen.ParsedCommit
+generate_changelog = _changelog_gen.generate_changelog
+iter_commit_entries = _changelog_gen.iter_commit_entries
+parse_commits = _changelog_gen.parse_commits
+
+
+def make_log_entry(subject: str, commit_hash: str, body: str = "") -> str:
+    return f"{subject}{FIELD_SEP}{body}{FIELD_SEP}{commit_hash}{RECORD_SEP}"
+
+
+class TestParseCommits:
+    """Tests for parse_commits function."""
+
+    def test_parses_feat_commit(self) -> None:
+        log_output = make_log_entry("feat(core): add feature", "abc1234")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "feat"
+        assert commits[0].scope == "core"
+        assert commits[0].message == "add feature"
+        assert commits[0].hash == "abc1234"
+        assert commits[0].breaking is False
+
+    def test_parses_fix_commit(self) -> None:
+        log_output = make_log_entry("fix(ui): fix bug", "def5678")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "fix"
+        assert commits[0].scope == "ui"
+        assert commits[0].message == "fix bug"
+        assert commits[0].hash == "def5678"
+
+    def test_parses_ci_commit(self) -> None:
+        log_output = make_log_entry("ci: update github actions", "xyz789")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "ci"
+        assert commits[0].scope is None
+        assert commits[0].message == "update github actions"
+        assert commits[0].hash == "xyz789"
+
+    def test_parses_chore_commit(self) -> None:
+        log_output = make_log_entry("chore: cleanup", "xyz999")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "chore"
+        assert commits[0].scope is None
+
+    def test_parses_perf_commit(self) -> None:
+        log_output = make_log_entry("perf(dashboard): improve performance", "abc111")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "perf"
+        assert commits[0].scope == "dashboard"
+
+    def test_parses_refactor_commit(self) -> None:
+        log_output = make_log_entry("refactor(api): refactor endpoint", "abc222")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "refactor"
+        assert commits[0].scope == "api"
+
+    def test_parses_docs_commit(self) -> None:
+        log_output = make_log_entry("docs: update readme", "abc333")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "docs"
+
+    def test_parses_style_commit(self) -> None:
+        log_output = make_log_entry("style: format code", "abc444")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "style"
+
+    def test_parses_test_commit(self) -> None:
+        log_output = make_log_entry("test: add tests for feature", "abc555")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "test"
+
+    def test_detects_breaking_change_in_body(self) -> None:
+        log_output = make_log_entry(
+            "feat(core): add feature",
+            "abc666",
+            "BREAKING CHANGE: api changed",
+        )
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].breaking is True
+
+    def test_detects_breaking_change_exclamation(self) -> None:
+        log_output = make_log_entry("feat(core)!: api changed", "abc777")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].breaking is True
+
+    def test_no_scope_no_problem(self) -> None:
+        log_output = make_log_entry("feat: simple feature", "abc888")
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].scope is None
+        assert commits[0].message == "simple feature"
+
+    def test_uses_pr_title_from_merge_commit_body(self) -> None:
+        log_output = make_log_entry(
+            "Merge pull request #173 from JerrettDavis/fix/pipeline-permissions-and-docs",
+            "73f6673",
+            "fix: repair release and docs pipelines",
+        )
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "fix"
+        assert commits[0].message == "repair release and docs pipelines"
+
+    def test_falls_back_to_other_changes_for_non_conventional_merge(self) -> None:
+        log_output = make_log_entry(
+            "Merge pull request #186 from skorokithakis/patch-1",
+            "1e80ee3",
+            "Add support for custom Anthropic API URL",
+        )
+        commits = parse_commits(log_output)
+        assert len(commits) == 1
+        assert commits[0].type == "other"
+        assert commits[0].message == "Add support for custom Anthropic API URL"
+
+    def test_iter_commit_entries_parses_real_git_log_delimiters(self) -> None:
+        log_output = make_log_entry(
+            "fix: patch release flow", "abc1234", "BREAKING CHANGE: no"
+        ) + make_log_entry("docs: update readme", "def5678")
+        assert iter_commit_entries(log_output) == [
+            ("fix: patch release flow", "BREAKING CHANGE: no", "abc1234"),
+            ("docs: update readme", "", "def5678"),
+        ]
+
+    def test_iter_commit_entries_keeps_field_separator_inside_body(self) -> None:
+        body = f"line one{FIELD_SEP}line two"
+        log_output = make_log_entry("fix: patch release flow", "abc1234", body)
+        assert iter_commit_entries(log_output) == [
+            ("fix: patch release flow", body, "abc1234"),
+        ]
+
+
+class TestGenerateChangelog:
+    """Tests for generate_changelog function."""
+
+    def test_generates_version_header(self) -> None:
+        commits = [
+            ParsedCommit(type="feat", scope=None, breaking=False, message="test", hash="abc123")
+        ]
+        result = generate_changelog("0.6.0", commits)
+        assert "## [0.6.0]" in result
+
+    def test_includes_date(self) -> None:
+        commits = []
+        result = generate_changelog("0.6.0", commits)
+        import re
+
+        date_match = re.search(r"\d{4}-\d{2}-\d{2}", result)
+        assert date_match is not None
+
+    def test_groups_by_type(self) -> None:
+        commits = [
+            ParsedCommit(
+                type="feat", scope=None, breaking=False, message="add feature", hash="abc123"
+            ),
+            ParsedCommit(type="fix", scope=None, breaking=False, message="fix bug", hash="def456"),
+        ]
+        result = generate_changelog("0.6.0", commits)
+        assert "### Features" in result
+        assert "### Bug Fixes" in result
+        assert "- add feature (abc123)" in result
+        assert "- fix bug (def456)" in result
+
+    def test_includes_scope_in_bullet(self) -> None:
+        commits = [
+            ParsedCommit(
+                type="feat", scope="core", breaking=False, message="add feature", hash="abc123"
+            )
+        ]
+        result = generate_changelog("0.6.0", commits)
+        assert "- **core**: add feature (abc123)" in result
+
+    def test_breaking_change_section_when_present(self) -> None:
+        commits = [
+            ParsedCommit(
+                type="feat", scope="core", breaking=True, message="api changed", hash="abc123"
+            )
+        ]
+        result = generate_changelog("0.6.0", commits)
+        assert "### Breaking Changes" in result
+        assert "**core**" in result
+
+    def test_no_breaking_change_section_when_none(self) -> None:
+        commits = [
+            ParsedCommit(
+                type="feat", scope=None, breaking=False, message="add feature", hash="abc123"
+            )
+        ]
+        result = generate_changelog("0.6.0", commits)
+        assert "Breaking Changes" not in result
+
+    def test_includes_other_changes_section(self) -> None:
+        commits = [
+            ParsedCommit(
+                type="other",
+                scope=None,
+                breaking=False,
+                message="Add support for custom Anthropic API URL",
+                hash="abc123",
+            )
+        ]
+        result = generate_changelog("0.6.0", commits)
+        assert "### Other Changes" in result
+        assert "- Add support for custom Anthropic API URL (abc123)" in result
+
+
+class TestIntegrationWithMock:
+    """Integration tests with mocked subprocess.run."""
+
+    def test_full_flow_with_mocked_git(self) -> None:
+        log_output = (
+            make_log_entry("feat(core): add new feature", "abc1234")
+            + make_log_entry("fix(ui): fix bug", "def5678")
+            + make_log_entry("ci: update github actions", "xyz789")
+            + make_log_entry(
+                "feat(outer): breaking change", "bbb111", "BREAKING CHANGE: this is breaking"
+            )
+            + make_log_entry("chore: cleanup", "yyy999")
+        )
+        commits = parse_commits(log_output)
+
+        assert len(commits) == 5
+        assert any(c.type == "feat" and c.scope == "core" for c in commits)
+        assert any(c.type == "fix" and c.scope == "ui" for c in commits)
+        assert any(c.type == "ci" for c in commits)
+        assert any(c.type == "feat" and c.breaking for c in commits)
+        assert any(c.type == "chore" for c in commits)
+
+        changelog = generate_changelog("0.7.0", commits)
+        assert "## [0.7.0]" in changelog
+        assert "### Features" in changelog
+        assert "### Bug Fixes" in changelog
+        assert "### CI/CD" in changelog
+        assert "### Breaking Changes" in changelog
+
+
+class TestCommitPattern:
+    """Tests for the commit regex pattern."""
+
+    def test_feat_with_scope(self) -> None:
+        match = COMMIT_PATTERN.match("feat(core): add feature")
+        assert match is not None
+        assert match.group(1) == "feat"
+        assert match.group(2) == "(core)"
+        assert match.group(4) == "add feature"
+
+    def test_fix_without_scope(self) -> None:
+        match = COMMIT_PATTERN.match("fix: fix bug")
+        assert match is not None
+        assert match.group(1) == "fix"
+        assert match.group(2) is None
+        assert match.group(4) == "fix bug"
+
+    def test_with_exclamation(self) -> None:
+        match = COMMIT_PATTERN.match("feat(core)!: api changed")
+        assert match is not None
+        assert match.group(3) == "!"
+
+    def test_without_exclamation(self) -> None:
+        match = COMMIT_PATTERN.match("feat(core): add feature")
+        assert match is not None
+        assert match.group(3) is None
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])
diff --git a/scripts/tests/test_sync_plugin_versions.py b/scripts/tests/test_sync_plugin_versions.py
index 66c2361e536355018e5d88a0d13089af11ff6db4..5d1e6bff1753e66ef015c2fa8ef21a2442b90312 100644
--- a/scripts/tests/test_sync_plugin_versions.py
+++ b/scripts/tests/test_sync_plugin_versions.py
@@ -1,68 +1,68 @@
-"""Tests for sync-plugin-versions.py."""
-
-from __future__ import annotations
-
-import importlib.util
-from pathlib import Path
-
-
-def _load_module():
-    script = Path(__file__).parent.parent / "sync-plugin-versions.py"
-    spec = importlib.util.spec_from_file_location("sync_plugin_versions", script)
-    assert spec is not None
-    assert spec.loader is not None
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-def test_compute_repo_semver_uses_release_helpers(monkeypatch) -> None:
-    module = _load_module()
-    calls: dict[str, object] = {}
-
-    monkeypatch.setattr(module, "list_release_tags", lambda root: ["v0.9.0"])
-    monkeypatch.setattr(module, "find_latest_release_tag", lambda tags: "v0.9.0")
-    monkeypatch.setattr(module, "list_release_commits", lambda root, tag: ["feat: add init"])
-    monkeypatch.setattr(module, "determine_bump_level", lambda commits: "minor")
-    monkeypatch.setattr(module, "get_canonical_version", lambda root: "0.5.25")
-
-    def fake_compute_release_version(*, canonical_version: str, level: str, tags: list[str]):
-        calls["canonical_version"] = canonical_version
-        calls["level"] = level
-        calls["tags"] = tags
-        return type("Info", (), {"npm_version": "0.10.0"})()
-
-    monkeypatch.setattr(module, "compute_release_version", fake_compute_release_version)
-
-    assert module.compute_repo_semver(Path("repo")) == "0.10.0"
-    assert calls == {
-        "canonical_version": "0.5.25",
-        "level": "minor",
-        "tags": ["v0.9.0"],
-    }
-
-
-def test_main_runs_plugin_only_version_sync(monkeypatch) -> None:
-    module = _load_module()
-    commands: list[list[str]] = []
-
-    monkeypatch.setattr(module, "compute_repo_semver", lambda root: "0.10.0")
-    monkeypatch.setattr(
-        module.subprocess,
-        "run",
-        lambda command, cwd, check: commands.append(command),
-    )
-
-    module.main()
-
-    assert commands == [
-        [
-            module.sys.executable,
-            str(module.ROOT / "scripts" / "version-sync.py"),
-            "--root",
-            str(module.ROOT),
-            "--version",
-            "0.10.0",
-            "--plugin-manifests-only",
-        ]
-    ]
+"""Tests for sync-plugin-versions.py."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+
+def _load_module():
+    script = Path(__file__).parent.parent / "sync-plugin-versions.py"
+    spec = importlib.util.spec_from_file_location("sync_plugin_versions", script)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_compute_repo_semver_uses_release_helpers(monkeypatch) -> None:
+    module = _load_module()
+    calls: dict[str, object] = {}
+
+    monkeypatch.setattr(module, "list_release_tags", lambda root: ["v0.9.0"])
+    monkeypatch.setattr(module, "find_latest_release_tag", lambda tags: "v0.9.0")
+    monkeypatch.setattr(module, "list_release_commits", lambda root, tag: ["feat: add init"])
+    monkeypatch.setattr(module, "determine_bump_level", lambda commits: "minor")
+    monkeypatch.setattr(module, "get_canonical_version", lambda root: "0.5.25")
+
+    def fake_compute_release_version(*, canonical_version: str, level: str, tags: list[str]):
+        calls["canonical_version"] = canonical_version
+        calls["level"] = level
+        calls["tags"] = tags
+        return type("Info", (), {"npm_version": "0.10.0"})()
+
+    monkeypatch.setattr(module, "compute_release_version", fake_compute_release_version)
+
+    assert module.compute_repo_semver(Path("repo")) == "0.10.0"
+    assert calls == {
+        "canonical_version": "0.5.25",
+        "level": "minor",
+        "tags": ["v0.9.0"],
+    }
+
+
+def test_main_runs_plugin_only_version_sync(monkeypatch) -> None:
+    module = _load_module()
+    commands: list[list[str]] = []
+
+    monkeypatch.setattr(module, "compute_repo_semver", lambda root: "0.10.0")
+    monkeypatch.setattr(
+        module.subprocess,
+        "run",
+        lambda command, cwd, check: commands.append(command),
+    )
+
+    module.main()
+
+    assert commands == [
+        [
+            module.sys.executable,
+            str(module.ROOT / "scripts" / "version-sync.py"),
+            "--root",
+            str(module.ROOT),
+            "--version",
+            "0.10.0",
+            "--plugin-manifests-only",
+        ]
+    ]
diff --git a/tests/test_backend_anyllm.py b/tests/test_backend_anyllm.py
index b75aa66b50369cfd5aa3ef7ddc81350eeb569c7a..584702d4156672f5e91bdd0bbdfda464a05161bb 100644
--- a/tests/test_backend_anyllm.py
+++ b/tests/test_backend_anyllm.py
@@ -1,384 +1,384 @@
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-import pytest
-
-from headroom.backends import anyllm
-from headroom.backends.base import BackendResponse, StreamEvent
-
-
-class FakeAsyncStream:
-    def __init__(self, items) -> None:  # noqa: ANN001
-        self._items = list(items)
-
-    def __aiter__(self):
-        self._iter = iter(self._items)
-        return self
-
-    async def __anext__(self):
-        try:
-            return next(self._iter)
-        except StopIteration as exc:
-            raise StopAsyncIteration from exc
-
-
-class FakeAnyLLMInstance:
-    def __init__(self) -> None:
-        self.calls: list[dict[str, object]] = []
-        self.response = None
-        self.raise_error: Exception | None = None
-
-    async def acompletion(self, **kwargs):  # noqa: ANN003
-        self.calls.append(kwargs)
-        if self.raise_error is not None:
-            raise self.raise_error
-        return self.response
-
-
-def make_backend(
-    monkeypatch: pytest.MonkeyPatch, provider: str = "groq"
-) -> tuple[anyllm.AnyLLMBackend, FakeAnyLLMInstance]:
-    fake_instance = FakeAnyLLMInstance()
-
-    class FakeAnyLLM:
-        @staticmethod
-        def create(requested_provider: str):
-            assert requested_provider == provider
-            return fake_instance
-
-    monkeypatch.setattr(anyllm, "ANYLLM_AVAILABLE", True)
-    monkeypatch.setattr(anyllm, "AnyLLM", FakeAnyLLM)
-    return anyllm.AnyLLMBackend(provider=provider.upper()), fake_instance
-
-
-def make_choice(
-    content: str = "hello", finish_reason: str = "stop", tool_calls=None, index: int = 0
-):
-    return SimpleNamespace(
-        index=index,
-        finish_reason=finish_reason,
-        message=SimpleNamespace(role="assistant", content=content, tool_calls=tool_calls),
-    )
-
-
-def make_response(*choices, usage=None):
-    return SimpleNamespace(
-        id="resp_123",
-        created=123456,
-        choices=list(choices),
-        usage=usage,
-    )
-
-
-def make_tool_call(tool_id: str, name: str, arguments):
-    return SimpleNamespace(id=tool_id, function=SimpleNamespace(name=name, arguments=arguments))
-
-
-def test_init_raises_without_anyllm() -> None:
-    original_available = anyllm.ANYLLM_AVAILABLE
-    try:
-        anyllm.ANYLLM_AVAILABLE = False
-        with pytest.raises(ImportError):
-            anyllm.AnyLLMBackend()
-    finally:
-        anyllm.ANYLLM_AVAILABLE = original_available
-
-
-def test_init_name_and_basic_methods(monkeypatch: pytest.MonkeyPatch) -> None:
-    backend, instance = make_backend(monkeypatch, provider="groq")
-
-    assert backend.provider == "groq"
-    assert backend.name == "anyllm-groq"
-    assert backend.map_model_id("claude-3-5") == "claude-3-5"
-    assert backend.supports_model("anything") is True
-    assert backend.llm is instance
-
-
-def test_convert_content_blocks_and_messages(monkeypatch: pytest.MonkeyPatch) -> None:
-    backend, _instance = make_backend(monkeypatch)
-
-    assert backend._convert_content_blocks([{"type": "text", "text": "hello"}]) == "hello"
-    assert backend._convert_content_blocks(
-        [
-            {"type": "text", "text": "caption"},
-            {
-                "type": "image",
-                "source": {"type": "base64", "media_type": "image/jpeg", "data": "abc"},
-            },
-            {"type": "image", "source": {"type": "url", "url": "https://example.com/img.png"}},
-        ]
-    ) == [
-        {"type": "text", "text": "caption"},
-        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,abc"}},
-        {"type": "image_url", "image_url": {"url": "https://example.com/img.png"}},
-    ]
-    assert backend._convert_content_blocks([{"type": "tool_use", "id": "ignored"}]) == ""
-
-    converted = backend._convert_messages(
-        [
-            {"role": "user", "content": "plain text"},
-            {
-                "role": "assistant",
-                "content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}],
-            },
-            {
-                "role": "user",
-                "content": [
-                    {"type": "text", "text": "look"},
-                    {"type": "image", "source": {"type": "url", "url": "https://example.com"}},
-                ],
-            },
-            {"role": "user", "content": 123},
-        ]
-    )
-
-    assert converted == [
-        {"role": "user", "content": "plain text"},
-        {"role": "assistant", "content": "a\nb"},
-        {
-            "role": "user",
-            "content": [
-                {"type": "text", "text": "look"},
-                {"type": "image_url", "image_url": {"url": "https://example.com"}},
-            ],
-        },
-    ]
-
-
-def test_to_anthropic_response_maps_tool_calls_and_usage(monkeypatch: pytest.MonkeyPatch) -> None:
-    backend, _instance = make_backend(monkeypatch)
-    response = make_response(
-        make_choice(
-            content="hello",
-            finish_reason="tool_calls",
-            tool_calls=[
-                make_tool_call("tc1", "memory_save", '{"content":"python"}'),
-                make_tool_call("tc2", "memory_search", {"query": "python"}),
-            ],
-        ),
-        usage=SimpleNamespace(prompt_tokens=12, completion_tokens=7),
-    )
-
-    converted = backend._to_anthropic_response(response, "claude-sonnet")
-
-    assert converted["type"] == "message"
-    assert converted["role"] == "assistant"
-    assert converted["model"] == "claude-sonnet"
-    assert converted["stop_reason"] == "tool_use"
-    assert converted["usage"] == {"input_tokens": 12, "output_tokens": 7}
-    assert converted["content"][0] == {"type": "text", "text": "hello"}
-    assert converted["content"][1]["input"] == {"content": "python"}
-    assert converted["content"][2]["input"] == {"query": "python"}
-
-
-@pytest.mark.asyncio
-async def test_send_message_builds_anthropic_response(monkeypatch: pytest.MonkeyPatch) -> None:
-    backend, instance = make_backend(monkeypatch)
-    instance.response = make_response(
-        make_choice("done", "stop"),
-        usage=SimpleNamespace(prompt_tokens=4, completion_tokens=6),
-    )
-
-    result = await backend.send_message(
-        {
-            "model": "claude-3-7-sonnet",
-            "messages": [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],
-            "system": [{"text": "system rule"}, "extra"],
-            "max_tokens": 200,
-            "temperature": 0.3,
-            "top_p": 0.8,
-            "stop_sequences": ["END"],
-            "tools": [{"name": "t"}],
-            "tool_choice": {"type": "auto"},
-        },
-        {},
-    )
-
-    assert isinstance(result, BackendResponse)
-    assert result.status_code == 200
-    assert result.headers == {"content-type": "application/json"}
-    assert result.body["content"][0]["text"] == "done"
-    assert instance.calls[0]["messages"][0] == {"role": "system", "content": "system rule extra"}
-    assert instance.calls[0]["stop"] == ["END"]
-
-
-@pytest.mark.asyncio
-async def test_send_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None:
-    backend, instance = make_backend(monkeypatch)
-    instance.raise_error = RuntimeError("authentication api_key missing")
-
-    result = await backend.send_message({"messages": []}, {})
-
-    assert result.status_code == 401
-    assert result.body["error"]["type"] == "authentication_error"
-    assert result.error == "authentication api_key missing"
-
-
-@pytest.mark.asyncio
-async def test_stream_message_yields_events_and_error(monkeypatch: pytest.MonkeyPatch) -> None:
-    backend, instance = make_backend(monkeypatch)
-    instance.response = FakeAsyncStream(
-        [
-            SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="hel"))]),
-            SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="lo"))]),
-            SimpleNamespace(choices=[]),
-        ]
-    )
-
-    events = [
-        event
-        async for event in backend.stream_message(
-            {"model": "claude", "messages": [], "system": "sys"}, {}
-        )
-    ]
-
-    assert [event.event_type for event in events] == [
-        "message_start",
-        "content_block_start",
-        "content_block_delta",
-        "content_block_delta",
-        "content_block_stop",
-        "message_delta",
-        "message_stop",
-    ]
-    assert events[0].data["message"]["model"] == "claude"
-    assert events[5].data["usage"] == {"output_tokens": 2}
-    assert instance.calls[0]["stream"] is True
-    assert instance.calls[0]["messages"][0] == {"role": "system", "content": "sys"}
-
-    backend_error, instance_error = make_backend(monkeypatch, provider="openai")
-    instance_error.raise_error = RuntimeError("stream broke")
-    error_events = [event async for event in backend_error.stream_message({"messages": []}, {})]
-    assert error_events[-1].event_type == "error"
-    assert error_events[-1].data["error"]["message"] == "stream broke"
-
-
-@pytest.mark.asyncio
-async def test_send_openai_message_maps_choices_and_tool_calls(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    backend, instance = make_backend(monkeypatch)
-    instance.response = make_response(
-        make_choice(
-            content="answer",
-            finish_reason="stop",
-            tool_calls=[
-                make_tool_call("tc1", "memory_search", '{"query":"python"}'),
-                SimpleNamespace(id="tc2", function=None),
-            ],
-            index=0,
-        ),
-        usage=SimpleNamespace(prompt_tokens=2, completion_tokens=3, total_tokens=5),
-    )
-
-    result = await backend.send_openai_message(
-        {
-            "model": "gpt-4o",
-            "messages": [{"role": "user", "content": "hi"}],
-            "max_tokens": 50,
-            "temperature": 0.2,
-            "top_p": 0.9,
-            "stop": ["END"],
-            "tools": [{"name": "memory"}],
-            "tool_choice": "auto",
-            "response_format": {"type": "json_object"},
-            "seed": 1,
-            "n": 2,
-        },
-        {},
-    )
-
-    assert result.status_code == 200
-    assert result.body["object"] == "chat.completion"
-    assert (
-        result.body["choices"][0]["message"]["tool_calls"][0]["function"]["name"] == "memory_search"
-    )
-    assert result.body["choices"][0]["message"]["tool_calls"][1] == {
-        "id": "tc2",
-        "type": "function",
-    }
-    assert result.body["usage"] == {"prompt_tokens": 2, "completion_tokens": 3, "total_tokens": 5}
-
-
-@pytest.mark.asyncio
-async def test_send_openai_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None:
-    backend, instance = make_backend(monkeypatch)
-    instance.raise_error = RuntimeError("model not found")
-
-    result = await backend.send_openai_message({"messages": []}, {})
-
-    assert result.status_code == 404
-    assert result.body["error"]["type"] == "model_not_found"
-
-
-@pytest.mark.asyncio
-async def test_stream_openai_message_yields_sse_chunks_and_done(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    backend, instance = make_backend(monkeypatch)
-    instance.response = FakeAsyncStream(
-        [
-            SimpleNamespace(
-                model_dump=lambda **kwargs: {
-                    "id": "chunk1",
-                    "choices": [{"delta": {"content": "a"}}],
-                }
-            ),
-            SimpleNamespace(
-                model_dump=lambda **kwargs: {
-                    "id": "chunk2",
-                    "choices": [{"delta": {"content": "b"}}],
-                }
-            ),
-        ]
-    )
-
-    chunks = [
-        chunk
-        async for chunk in backend.stream_openai_message(
-            {
-                "messages": [{"role": "user", "content": "hi"}],
-                "stream_options": {"include_usage": True},
-            },
-            {},
-        )
-    ]
-
-    assert chunks[0].startswith("data: {")
-    assert chunks[-1] == "data: [DONE]\n\n"
-    assert instance.calls[0]["stream"] is True
-    assert instance.calls[0]["stream_options"] == {"include_usage": True}
-
-    backend_error, instance_error = make_backend(monkeypatch, provider="anthropic")
-    instance_error.raise_error = RuntimeError("rate limit hit")
-    error_chunks = [
-        chunk async for chunk in backend_error.stream_openai_message({"messages": []}, {})
-    ]
-    assert '"backend_error"' in error_chunks[0]
-    assert error_chunks[-1] == "data: [DONE]\n\n"
-
-
-def test_error_response_classifies_common_failures(monkeypatch: pytest.MonkeyPatch) -> None:
-    backend, _instance = make_backend(monkeypatch)
-
-    auth = backend._error_response(RuntimeError("authentication api key missing"))
-    rate = backend._error_response(RuntimeError("rate limit exceeded"), openai_format=True)
-    model = backend._error_response(RuntimeError("model not found"), openai_format=True)
-    generic = backend._error_response(RuntimeError("other error"))
-
-    assert auth.status_code == 401
-    assert auth.body["error"]["type"] == "authentication_error"
-    assert rate.status_code == 429
-    assert rate.body["error"]["type"] == "rate_limit_exceeded"
-    assert model.status_code == 404
-    assert model.body["error"]["type"] == "model_not_found"
-    assert generic.status_code == 500
-    assert generic.body["error"]["type"] == "api_error"
-
-
-@pytest.mark.asyncio
-async def test_close_is_noop(monkeypatch: pytest.MonkeyPatch) -> None:
-    backend, _instance = make_backend(monkeypatch)
-    assert await backend.close() is None
-    assert isinstance(StreamEvent(event_type="message_start", data={}), StreamEvent)
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from headroom.backends import anyllm
+from headroom.backends.base import BackendResponse, StreamEvent
+
+
+class FakeAsyncStream:
+    def __init__(self, items) -> None:  # noqa: ANN001
+        self._items = list(items)
+
+    def __aiter__(self):
+        self._iter = iter(self._items)
+        return self
+
+    async def __anext__(self):
+        try:
+            return next(self._iter)
+        except StopIteration as exc:
+            raise StopAsyncIteration from exc
+
+
+class FakeAnyLLMInstance:
+    def __init__(self) -> None:
+        self.calls: list[dict[str, object]] = []
+        self.response = None
+        self.raise_error: Exception | None = None
+
+    async def acompletion(self, **kwargs):  # noqa: ANN003
+        self.calls.append(kwargs)
+        if self.raise_error is not None:
+            raise self.raise_error
+        return self.response
+
+
+def make_backend(
+    monkeypatch: pytest.MonkeyPatch, provider: str = "groq"
+) -> tuple[anyllm.AnyLLMBackend, FakeAnyLLMInstance]:
+    fake_instance = FakeAnyLLMInstance()
+
+    class FakeAnyLLM:
+        @staticmethod
+        def create(requested_provider: str):
+            assert requested_provider == provider
+            return fake_instance
+
+    monkeypatch.setattr(anyllm, "ANYLLM_AVAILABLE", True)
+    monkeypatch.setattr(anyllm, "AnyLLM", FakeAnyLLM)
+    return anyllm.AnyLLMBackend(provider=provider.upper()), fake_instance
+
+
+def make_choice(
+    content: str = "hello", finish_reason: str = "stop", tool_calls=None, index: int = 0
+):
+    return SimpleNamespace(
+        index=index,
+        finish_reason=finish_reason,
+        message=SimpleNamespace(role="assistant", content=content, tool_calls=tool_calls),
+    )
+
+
+def make_response(*choices, usage=None):
+    return SimpleNamespace(
+        id="resp_123",
+        created=123456,
+        choices=list(choices),
+        usage=usage,
+    )
+
+
+def make_tool_call(tool_id: str, name: str, arguments):
+    return SimpleNamespace(id=tool_id, function=SimpleNamespace(name=name, arguments=arguments))
+
+
+def test_init_raises_without_anyllm() -> None:
+    original_available = anyllm.ANYLLM_AVAILABLE
+    try:
+        anyllm.ANYLLM_AVAILABLE = False
+        with pytest.raises(ImportError):
+            anyllm.AnyLLMBackend()
+    finally:
+        anyllm.ANYLLM_AVAILABLE = original_available
+
+
+def test_init_name_and_basic_methods(monkeypatch: pytest.MonkeyPatch) -> None:
+    backend, instance = make_backend(monkeypatch, provider="groq")
+
+    assert backend.provider == "groq"
+    assert backend.name == "anyllm-groq"
+    assert backend.map_model_id("claude-3-5") == "claude-3-5"
+    assert backend.supports_model("anything") is True
+    assert backend.llm is instance
+
+
+def test_convert_content_blocks_and_messages(monkeypatch: pytest.MonkeyPatch) -> None:
+    backend, _instance = make_backend(monkeypatch)
+
+    assert backend._convert_content_blocks([{"type": "text", "text": "hello"}]) == "hello"
+    assert backend._convert_content_blocks(
+        [
+            {"type": "text", "text": "caption"},
+            {
+                "type": "image",
+                "source": {"type": "base64", "media_type": "image/jpeg", "data": "abc"},
+            },
+            {"type": "image", "source": {"type": "url", "url": "https://example.com/img.png"}},
+        ]
+    ) == [
+        {"type": "text", "text": "caption"},
+        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,abc"}},
+        {"type": "image_url", "image_url": {"url": "https://example.com/img.png"}},
+    ]
+    assert backend._convert_content_blocks([{"type": "tool_use", "id": "ignored"}]) == ""
+
+    converted = backend._convert_messages(
+        [
+            {"role": "user", "content": "plain text"},
+            {
+                "role": "assistant",
+                "content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}],
+            },
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "look"},
+                    {"type": "image", "source": {"type": "url", "url": "https://example.com"}},
+                ],
+            },
+            {"role": "user", "content": 123},
+        ]
+    )
+
+    assert converted == [
+        {"role": "user", "content": "plain text"},
+        {"role": "assistant", "content": "a\nb"},
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "look"},
+                {"type": "image_url", "image_url": {"url": "https://example.com"}},
+            ],
+        },
+    ]
+
+
+def test_to_anthropic_response_maps_tool_calls_and_usage(monkeypatch: pytest.MonkeyPatch) -> None:
+    backend, _instance = make_backend(monkeypatch)
+    response = make_response(
+        make_choice(
+            content="hello",
+            finish_reason="tool_calls",
+            tool_calls=[
+                make_tool_call("tc1", "memory_save", '{"content":"python"}'),
+                make_tool_call("tc2", "memory_search", {"query": "python"}),
+            ],
+        ),
+        usage=SimpleNamespace(prompt_tokens=12, completion_tokens=7),
+    )
+
+    converted = backend._to_anthropic_response(response, "claude-sonnet")
+
+    assert converted["type"] == "message"
+    assert converted["role"] == "assistant"
+    assert converted["model"] == "claude-sonnet"
+    assert converted["stop_reason"] == "tool_use"
+    assert converted["usage"] == {"input_tokens": 12, "output_tokens": 7}
+    assert converted["content"][0] == {"type": "text", "text": "hello"}
+    assert converted["content"][1]["input"] == {"content": "python"}
+    assert converted["content"][2]["input"] == {"query": "python"}
+
+
+@pytest.mark.asyncio
+async def test_send_message_builds_anthropic_response(monkeypatch: pytest.MonkeyPatch) -> None:
+    backend, instance = make_backend(monkeypatch)
+    instance.response = make_response(
+        make_choice("done", "stop"),
+        usage=SimpleNamespace(prompt_tokens=4, completion_tokens=6),
+    )
+
+    result = await backend.send_message(
+        {
+            "model": "claude-3-7-sonnet",
+            "messages": [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],
+            "system": [{"text": "system rule"}, "extra"],
+            "max_tokens": 200,
+            "temperature": 0.3,
+            "top_p": 0.8,
+            "stop_sequences": ["END"],
+            "tools": [{"name": "t"}],
+            "tool_choice": {"type": "auto"},
+        },
+        {},
+    )
+
+    assert isinstance(result, BackendResponse)
+    assert result.status_code == 200
+    assert result.headers == {"content-type": "application/json"}
+    assert result.body["content"][0]["text"] == "done"
+    assert instance.calls[0]["messages"][0] == {"role": "system", "content": "system rule extra"}
+    assert instance.calls[0]["stop"] == ["END"]
+
+
+@pytest.mark.asyncio
+async def test_send_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None:
+    backend, instance = make_backend(monkeypatch)
+    instance.raise_error = RuntimeError("authentication api_key missing")
+
+    result = await backend.send_message({"messages": []}, {})
+
+    assert result.status_code == 401
+    assert result.body["error"]["type"] == "authentication_error"
+    assert result.error == "authentication api_key missing"
+
+
+@pytest.mark.asyncio
+async def test_stream_message_yields_events_and_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    backend, instance = make_backend(monkeypatch)
+    instance.response = FakeAsyncStream(
+        [
+            SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="hel"))]),
+            SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="lo"))]),
+            SimpleNamespace(choices=[]),
+        ]
+    )
+
+    events = [
+        event
+        async for event in backend.stream_message(
+            {"model": "claude", "messages": [], "system": "sys"}, {}
+        )
+    ]
+
+    assert [event.event_type for event in events] == [
+        "message_start",
+        "content_block_start",
+        "content_block_delta",
+        "content_block_delta",
+        "content_block_stop",
+        "message_delta",
+        "message_stop",
+    ]
+    assert events[0].data["message"]["model"] == "claude"
+    assert events[5].data["usage"] == {"output_tokens": 2}
+    assert instance.calls[0]["stream"] is True
+    assert instance.calls[0]["messages"][0] == {"role": "system", "content": "sys"}
+
+    backend_error, instance_error = make_backend(monkeypatch, provider="openai")
+    instance_error.raise_error = RuntimeError("stream broke")
+    error_events = [event async for event in backend_error.stream_message({"messages": []}, {})]
+    assert error_events[-1].event_type == "error"
+    assert error_events[-1].data["error"]["message"] == "stream broke"
+
+
+@pytest.mark.asyncio
+async def test_send_openai_message_maps_choices_and_tool_calls(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    backend, instance = make_backend(monkeypatch)
+    instance.response = make_response(
+        make_choice(
+            content="answer",
+            finish_reason="stop",
+            tool_calls=[
+                make_tool_call("tc1", "memory_search", '{"query":"python"}'),
+                SimpleNamespace(id="tc2", function=None),
+            ],
+            index=0,
+        ),
+        usage=SimpleNamespace(prompt_tokens=2, completion_tokens=3, total_tokens=5),
+    )
+
+    result = await backend.send_openai_message(
+        {
+            "model": "gpt-4o",
+            "messages": [{"role": "user", "content": "hi"}],
+            "max_tokens": 50,
+            "temperature": 0.2,
+            "top_p": 0.9,
+            "stop": ["END"],
+            "tools": [{"name": "memory"}],
+            "tool_choice": "auto",
+            "response_format": {"type": "json_object"},
+            "seed": 1,
+            "n": 2,
+        },
+        {},
+    )
+
+    assert result.status_code == 200
+    assert result.body["object"] == "chat.completion"
+    assert (
+        result.body["choices"][0]["message"]["tool_calls"][0]["function"]["name"] == "memory_search"
+    )
+    assert result.body["choices"][0]["message"]["tool_calls"][1] == {
+        "id": "tc2",
+        "type": "function",
+    }
+    assert result.body["usage"] == {"prompt_tokens": 2, "completion_tokens": 3, "total_tokens": 5}
+
+
+@pytest.mark.asyncio
+async def test_send_openai_message_returns_error_response(monkeypatch: pytest.MonkeyPatch) -> None:
+    backend, instance = make_backend(monkeypatch)
+    instance.raise_error = RuntimeError("model not found")
+
+    result = await backend.send_openai_message({"messages": []}, {})
+
+    assert result.status_code == 404
+    assert result.body["error"]["type"] == "model_not_found"
+
+
+@pytest.mark.asyncio
+async def test_stream_openai_message_yields_sse_chunks_and_done(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    backend, instance = make_backend(monkeypatch)
+    instance.response = FakeAsyncStream(
+        [
+            SimpleNamespace(
+                model_dump=lambda **kwargs: {
+                    "id": "chunk1",
+                    "choices": [{"delta": {"content": "a"}}],
+                }
+            ),
+            SimpleNamespace(
+                model_dump=lambda **kwargs: {
+                    "id": "chunk2",
+                    "choices": [{"delta": {"content": "b"}}],
+                }
+            ),
+        ]
+    )
+
+    chunks = [
+        chunk
+        async for chunk in backend.stream_openai_message(
+            {
+                "messages": [{"role": "user", "content": "hi"}],
+                "stream_options": {"include_usage": True},
+            },
+            {},
+        )
+    ]
+
+    assert chunks[0].startswith("data: {")
+    assert chunks[-1] == "data: [DONE]\n\n"
+    assert instance.calls[0]["stream"] is True
+    assert instance.calls[0]["stream_options"] == {"include_usage": True}
+
+    backend_error, instance_error = make_backend(monkeypatch, provider="anthropic")
+    instance_error.raise_error = RuntimeError("rate limit hit")
+    error_chunks = [
+        chunk async for chunk in backend_error.stream_openai_message({"messages": []}, {})
+    ]
+    assert '"backend_error"' in error_chunks[0]
+    assert error_chunks[-1] == "data: [DONE]\n\n"
+
+
+def test_error_response_classifies_common_failures(monkeypatch: pytest.MonkeyPatch) -> None:
+    backend, _instance = make_backend(monkeypatch)
+
+    auth = backend._error_response(RuntimeError("authentication api key missing"))
+    rate = backend._error_response(RuntimeError("rate limit exceeded"), openai_format=True)
+    model = backend._error_response(RuntimeError("model not found"), openai_format=True)
+    generic = backend._error_response(RuntimeError("other error"))
+
+    assert auth.status_code == 401
+    assert auth.body["error"]["type"] == "authentication_error"
+    assert rate.status_code == 429
+    assert rate.body["error"]["type"] == "rate_limit_exceeded"
+    assert model.status_code == 404
+    assert model.body["error"]["type"] == "model_not_found"
+    assert generic.status_code == 500
+    assert generic.body["error"]["type"] == "api_error"
+
+
+@pytest.mark.asyncio
+async def test_close_is_noop(monkeypatch: pytest.MonkeyPatch) -> None:
+    backend, _instance = make_backend(monkeypatch)
+    assert await backend.close() is None
+    assert isinstance(StreamEvent(event_type="message_start", data={}), StreamEvent)
diff --git a/tests/test_ccr_batch_store.py b/tests/test_ccr_batch_store.py
index 04a31bbf09ba929dba3d240117e77b5b830b6255..a4ab6bbec77cfc17c885bd851823f83b12ac65f3 100644
--- a/tests/test_ccr_batch_store.py
+++ b/tests/test_ccr_batch_store.py
@@ -1,126 +1,126 @@
-from __future__ import annotations
-
-import sys
-from dataclasses import dataclass
-
-from headroom.ccr.batch_store import (
-    BatchContext,
-    BatchContextStore,
-    BatchRequestContext,
-    get_batch_context_store,
-    reset_batch_context_store,
-)
-
-
-def test_batch_context_defaults_and_expiry(monkeypatch) -> None:
-    monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: 100.0)
-    context = BatchContext(batch_id="batch-1", provider="anthropic", created_at=100.0)
-    assert context.expires_at == 100.0 + 86400
-    assert context.is_expired is False
-
-    request = BatchRequestContext(
-        custom_id="req-1",
-        messages=[{"role": "user", "content": "hello"}],
-        tools=[{"name": "tool"}],
-        model="gpt-4o",
-        system_instruction="system",
-        extras={"x": 1},
-    )
-    context.add_request(request)
-    assert context.get_request("req-1") is request
-    assert context.get_request("missing") is None
-
-    monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: context.expires_at + 1)
-    assert context.is_expired is True
-
-
-async def test_batch_context_store_core_operations(monkeypatch) -> None:
-    now = {"value": 100.0}
-    monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: now["value"])
-
-    store = BatchContextStore(ttl=10, max_contexts=2)
-    first = BatchContext(batch_id="b1", provider="anthropic")
-    second = BatchContext(batch_id="b2", provider="google")
-    third = BatchContext(batch_id="b3", provider="openai")
-
-    await store.store(first)
-    now["value"] = 101.0
-    await store.store(second)
-    assert (await store.get("b1")) is first
-
-    now["value"] = 102.0
-    await store.store(third)
-    assert await store.get("b1") is None
-    assert await store.get("b2") is second
-    assert await store.get("b3") is third
-
-    assert await store.remove("b2") is True
-    assert await store.remove("b2") is False
-
-
-async def test_batch_context_store_cleanup_stats_and_memory_stats(monkeypatch) -> None:
-    now = {"value": 200.0}
-    monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: now["value"])
-    store = BatchContextStore(ttl=5, max_contexts=10)
-
-    first = BatchContext(batch_id="b1", provider="anthropic")
-    first.add_request(
-        BatchRequestContext(custom_id="r1", messages=[{"content": "alpha"}], tools=[])
-    )
-    second = BatchContext(batch_id="b2", provider="google")
-    second.add_request(
-        BatchRequestContext(custom_id="r2", messages=[{"content": ["nested"]}], tools=[{}])
-    )
-
-    await store.store(first)
-    await store.store(second)
-    assert await store.stats() == {
-        "total_contexts": 2,
-        "max_contexts": 10,
-        "ttl_seconds": 5,
-        "providers": {"anthropic": 1, "google": 1},
-    }
-
-    now["value"] = 210.0
-    assert await store.cleanup_expired() == 2
-    assert (await store.stats())["total_contexts"] == 0
-
-    @dataclass
-    class FakeComponentStats:
-        name: str
-        entry_count: int
-        size_bytes: int
-        budget_bytes: int | None
-        hits: int
-        misses: int
-        evictions: int
-
-    monkeypatch.setitem(
-        sys.modules,
-        "headroom.memory.tracker",
-        type("TrackerModule", (), {"ComponentStats": FakeComponentStats}),
-    )
-
-    now["value"] = 220.0
-    third = BatchContext(batch_id="b3", provider="openai")
-    third.add_request(
-        BatchRequestContext(
-            custom_id="r3", messages=[{"content": "payload"}], tools=[{"name": "t"}]
-        )
-    )
-    await store.store(third)
-    stats = store.get_memory_stats()
-    assert stats.name == "batch_context_store"
-    assert stats.entry_count == 1
-    assert stats.size_bytes > 0
-
-
-def test_global_batch_context_store_reset() -> None:
-    reset_batch_context_store()
-    store_one = get_batch_context_store()
-    store_two = get_batch_context_store()
-    assert store_one is store_two
-
-    reset_batch_context_store()
-    store_three = get_batch_context_store()
-    assert store_three is not store_one
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+
+from headroom.ccr.batch_store import (
+    BatchContext,
+    BatchContextStore,
+    BatchRequestContext,
+    get_batch_context_store,
+    reset_batch_context_store,
+)
+
+
+def test_batch_context_defaults_and_expiry(monkeypatch) -> None:
+    monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: 100.0)
+    context = BatchContext(batch_id="batch-1", provider="anthropic", created_at=100.0)
+    assert context.expires_at == 100.0 + 86400
+    assert context.is_expired is False
+
+    request = BatchRequestContext(
+        custom_id="req-1",
+        messages=[{"role": "user", "content": "hello"}],
+        tools=[{"name": "tool"}],
+        model="gpt-4o",
+        system_instruction="system",
+        extras={"x": 1},
+    )
+    context.add_request(request)
+    assert context.get_request("req-1") is request
+    assert context.get_request("missing") is None
+
+    monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: context.expires_at + 1)
+    assert context.is_expired is True
+
+
+async def test_batch_context_store_core_operations(monkeypatch) -> None:
+    now = {"value": 100.0}
+    monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: now["value"])
+
+    store = BatchContextStore(ttl=10, max_contexts=2)
+    first = BatchContext(batch_id="b1", provider="anthropic")
+    second = BatchContext(batch_id="b2", provider="google")
+    third = BatchContext(batch_id="b3", provider="openai")
+
+    await store.store(first)
+    now["value"] = 101.0
+    await store.store(second)
+    assert (await store.get("b1")) is first
+
+    now["value"] = 102.0
+    await store.store(third)
+    assert await store.get("b1") is None
+    assert await store.get("b2") is second
+    assert await store.get("b3") is third
+
+    assert await store.remove("b2") is True
+    assert await store.remove("b2") is False
+
+
+async def test_batch_context_store_cleanup_stats_and_memory_stats(monkeypatch) -> None:
+    now = {"value": 200.0}
+    monkeypatch.setattr("headroom.ccr.batch_store.time.time", lambda: now["value"])
+    store = BatchContextStore(ttl=5, max_contexts=10)
+
+    first = BatchContext(batch_id="b1", provider="anthropic")
+    first.add_request(
+        BatchRequestContext(custom_id="r1", messages=[{"content": "alpha"}], tools=[])
+    )
+    second = BatchContext(batch_id="b2", provider="google")
+    second.add_request(
+        BatchRequestContext(custom_id="r2", messages=[{"content": ["nested"]}], tools=[{}])
+    )
+
+    await store.store(first)
+    await store.store(second)
+    assert await store.stats() == {
+        "total_contexts": 2,
+        "max_contexts": 10,
+        "ttl_seconds": 5,
+        "providers": {"anthropic": 1, "google": 1},
+    }
+
+    now["value"] = 210.0
+    assert await store.cleanup_expired() == 2
+    assert (await store.stats())["total_contexts"] == 0
+
+    @dataclass
+    class FakeComponentStats:
+        name: str
+        entry_count: int
+        size_bytes: int
+        budget_bytes: int | None
+        hits: int
+        misses: int
+        evictions: int
+
+    monkeypatch.setitem(
+        sys.modules,
+        "headroom.memory.tracker",
+        type("TrackerModule", (), {"ComponentStats": FakeComponentStats}),
+    )
+
+    now["value"] = 220.0
+    third = BatchContext(batch_id="b3", provider="openai")
+    third.add_request(
+        BatchRequestContext(
+            custom_id="r3", messages=[{"content": "payload"}], tools=[{"name": "t"}]
+        )
+    )
+    await store.store(third)
+    stats = store.get_memory_stats()
+    assert stats.name == "batch_context_store"
+    assert stats.entry_count == 1
+    assert stats.size_bytes > 0
+
+
+def test_global_batch_context_store_reset() -> None:
+    reset_batch_context_store()
+    store_one = get_batch_context_store()
+    store_two = get_batch_context_store()
+    assert store_one is store_two
+
+    reset_batch_context_store()
+    store_three = get_batch_context_store()
+    assert store_three is not store_one
diff --git a/tests/test_ccr_response_handler_extra.py b/tests/test_ccr_response_handler_extra.py
index 9a8e9a0a330b78bbc594b5e7a38357bfa91bb550..93d79bb97e0c8d6d33de49044b822d0c4d406828 100644
--- a/tests/test_ccr_response_handler_extra.py
+++ b/tests/test_ccr_response_handler_extra.py
@@ -1,372 +1,372 @@
-from __future__ import annotations
-
-import json
-from typing import Any
-
-import pytest
-
-from headroom.ccr.response_handler import (
-    CCRResponseHandler,
-    CCRToolCall,
-    CCRToolResult,
-    StreamingCCRBuffer,
-    StreamingCCRHandler,
-)
-from headroom.ccr.tool_injection import CCR_TOOL_NAME
-
-
-class FakeStore:
-    def __init__(
-        self, *, search_error: Exception | None = None, retrieve_error: Exception | None = None
-    ) -> None:
-        self.search_error = search_error
-        self.retrieve_error = retrieve_error
-
-    def search(self, hash_key: str, query: str) -> list[dict[str, str]]:
-        if self.search_error:
-            raise self.search_error
-        return [{"id": "1", "text": query}]
-
-    def retrieve(self, hash_key: str):
-        if self.retrieve_error:
-            raise self.retrieve_error
-        return {"unexpected": True}
-
-
-async def _async_iter(items: list[bytes]):
-    for item in items:
-        yield item
-
-
-def test_extract_tool_calls_google_and_invalid_shapes() -> None:
-    handler = CCRResponseHandler()
-    google_response = {
-        "candidates": [
-            {
-                "content": {
-                    "parts": [
-                        {"text": "hello"},
-                        {"functionCall": {"name": CCR_TOOL_NAME, "args": {"hash": "abc"}}},
-                    ]
-                }
-            }
-        ]
-    }
-    assert handler._extract_tool_calls(google_response, "google") == [
-        {"functionCall": {"name": CCR_TOOL_NAME, "args": {"hash": "abc"}}}
-    ]
-    assert handler._extract_tool_calls({"content": "bad"}, "anthropic") == []
-    with pytest.raises(IndexError):
-        handler._extract_tool_calls({"choices": []}, "openai")
-    assert handler._extract_tool_calls({"candidates": []}, "google") == []
-
-
-def test_parse_ccr_tool_calls_google_and_other_calls() -> None:
-    handler = CCRResponseHandler()
-    response = {
-        "candidates": [
-            {
-                "content": {
-                    "parts": [
-                        {
-                            "functionCall": {
-                                "name": CCR_TOOL_NAME,
-                                "args": {
-                                    "hash": "aaaaaaaaaaaaaaaaaaaaaaaa",
-                                    "query": "pizza",
-                                },
-                            }
-                        },
-                        {"functionCall": {"name": "other_tool", "args": {}}},
-                    ]
-                }
-            }
-        ]
-    }
-    ccr_calls, other_calls = handler._parse_ccr_tool_calls(response, "google")
-    assert ccr_calls == [
-        CCRToolCall(
-            tool_call_id=CCR_TOOL_NAME,
-            hash_key="aaaaaaaaaaaaaaaaaaaaaaaa",
-            query="pizza",
-        )
-    ]
-    assert other_calls == [{"functionCall": {"name": "other_tool", "args": {}}}]
-
-
-def test_execute_retrieval_error_paths(monkeypatch: pytest.MonkeyPatch) -> None:
-    handler = CCRResponseHandler()
-    monkeypatch.setattr(
-        "headroom.ccr.response_handler.get_compression_store",
-        lambda: FakeStore(search_error=RuntimeError("search boom")),
-    )
-    search_result = handler._execute_retrieval(
-        CCRToolCall(tool_call_id="t1", hash_key="abc", query="find")
-    )
-    assert search_result.success is False
-    assert "Retrieval failed: search boom" in search_result.content
-
-    monkeypatch.setattr(
-        "headroom.ccr.response_handler.get_compression_store",
-        lambda: FakeStore(retrieve_error=RuntimeError("retrieve boom")),
-    )
-    retrieve_result = handler._execute_retrieval(CCRToolCall(tool_call_id="t2", hash_key="abc"))
-    assert retrieve_result.success is False
-    assert "Retrieval failed: retrieve boom" in retrieve_result.content
-
-
-def test_create_tool_result_message_google_and_generic_formats() -> None:
-    handler = CCRResponseHandler()
-    results = [
-        CCRToolResult(tool_call_id="headroom_retrieve", content='{"count": 1}', success=True)
-    ]
-    google_message = handler._create_tool_result_message(results, "google")
-    assert google_message == {
-        "role": "user",
-        "parts": [{"functionResponse": {"name": "headroom_retrieve", "response": {"count": 1}}}],
-    }
-
-    generic_message = handler._create_tool_result_message(
-        [CCRToolResult(tool_call_id="tool-1", content="not-json", success=False)],
-        "other",
-    )
-    assert generic_message["role"] == "tool"
-    assert json.loads(generic_message["content"]) == [
-        {"tool_call_id": "tool-1", "result": "not-json"}
-    ]
-
-    invalid_google = handler._create_tool_result_message(
-        [CCRToolResult(tool_call_id="headroom_retrieve", content="not-json", success=True)],
-        "google",
-    )
-    assert invalid_google["parts"][0]["functionResponse"]["response"] == {"content": "not-json"}
-
-
-def test_extract_assistant_message_google_and_generic() -> None:
-    handler = CCRResponseHandler()
-    google_message = handler._extract_assistant_message(
-        {"candidates": [{"content": {"parts": [{"text": "hello"}]}}]},
-        "google",
-    )
-    assert google_message == {"role": "model", "parts": [{"text": "hello"}]}
-
-    assert handler._extract_assistant_message({}, "google") == {"role": "model", "parts": []}
-    assert handler._extract_assistant_message({"content": "plain"}, "other") == {
-        "role": "assistant",
-        "content": "plain",
-    }
-
-
-@pytest.mark.asyncio
-async def test_handle_response_openai_success_and_failure(monkeypatch: pytest.MonkeyPatch) -> None:
-    handler = CCRResponseHandler()
-    initial_response = {
-        "choices": [
-            {
-                "message": {
-                    "role": "assistant",
-                    "content": None,
-                    "tool_calls": [
-                        {
-                            "id": "call_1",
-                            "type": "function",
-                            "function": {
-                                "name": CCR_TOOL_NAME,
-                                "arguments": '{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}',
-                            },
-                        }
-                    ],
-                }
-            }
-        ]
-    }
-    monkeypatch.setattr(
-        handler,
-        "_execute_retrieval",
-        lambda call: CCRToolResult(
-            tool_call_id=call.tool_call_id,
-            content='{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}',
-            success=True,
-        ),
-    )
-
-    captured_messages: list[list[dict[str, Any]]] = []
-
-    async def success_api_call(messages, tools):
-        captured_messages.append(messages)
-        return {"choices": [{"message": {"role": "assistant", "content": "done"}}]}
-
-    result = await handler.handle_response(
-        initial_response, [{"role": "user", "content": "hi"}], [], success_api_call, "openai"
-    )
-    assert result == {"choices": [{"message": {"role": "assistant", "content": "done"}}]}
-    assert captured_messages[0][1]["role"] == "assistant"
-    assert captured_messages[0][2]["role"] == "tool"
-    assert handler.get_stats()["total_retrievals"] == 1
-
-    async def failing_api_call(messages, tools):
-        raise RuntimeError("continuation failed")
-
-    failed = await handler.handle_response(initial_response, [], [], failing_api_call, "openai")
-    assert failed == initial_response
-
-
-def test_streaming_buffer_and_parse_sse_helpers() -> None:
-    buffer = StreamingCCRBuffer()
-    assert buffer.add_chunk(b"plain") is False
-    assert buffer.get_accumulated() == b"plain"
-
-    handler = StreamingCCRHandler(CCRResponseHandler(), provider="anthropic")
-    anthropic_data = b"\n".join(
-        [
-            b'data: {"type":"content_block_start","content_block":{"type":"text","text":"Hel"}}',
-            b'data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"lo"}}',
-            b'data: {"type":"content_block_stop"}',
-            b'data: {"type":"content_block_start","content_block":{"type":"tool_use","id":"tool_1","name":"headroom_retrieve"}}',
-            b'data: {"type":"content_block_delta","delta":{"type":"input_json_delta","partial_json":"{\\"hash\\":\\"abc\\"}"}}',
-            b'data: {"type":"content_block_stop"}',
-            b'data: {"type":"message_delta","delta":{"stop_reason":"tool_use"}}',
-            b"data: [DONE]",
-        ]
-    )
-    parsed = handler._parse_sse_stream(anthropic_data)
-    assert parsed["content"][0] == {"type": "text", "text": "Hello"}
-    assert parsed["content"][1]["name"] == "headroom_retrieve"
-    assert parsed["content"][1]["input"] == {"hash": "abc"}
-    assert parsed["stop_reason"] == "tool_use"
-
-    openai_handler = StreamingCCRHandler(CCRResponseHandler(), provider="openai")
-    parsed_openai = openai_handler._reconstruct_openai_response(
-        [
-            {"choices": [{"delta": {"content": "Hi"}}]},
-            {
-                "choices": [
-                    {
-                        "delta": {
-                            "tool_calls": [
-                                {
-                                    "index": 0,
-                                    "id": "call_1",
-                                    "function": {
-                                        "name": "headroom_retrieve",
-                                        "arguments": '{"hash":"aaaaaaaaaaaa',
-                                    },
-                                }
-                            ]
-                        }
-                    }
-                ]
-            },
-            {
-                "choices": [
-                    {
-                        "delta": {
-                            "tool_calls": [
-                                {
-                                    "index": 0,
-                                    "function": {"arguments": 'aaaaaaaaaaaa"}'},
-                                }
-                            ]
-                        }
-                    }
-                ]
-            },
-        ]
-    )
-    message = parsed_openai["choices"][0]["message"]
-    assert message["content"] == "Hi"
-    assert message["tool_calls"][0]["id"] == "call_1"
-    assert message["tool_calls"][0]["function"]["arguments"] == (
-        '{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}'
-    )
-
-
-@pytest.mark.asyncio
-async def test_streaming_handler_process_stream_pass_through_and_ccr(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    response_handler = CCRResponseHandler()
-    handler = StreamingCCRHandler(response_handler, provider="anthropic")
-
-    passthrough_chunks = [
-        b'data: {"type":"content_block_delta","delta":{"text":"hello"}}',
-        b'data: {"stop_reason":"end_turn"}',
-    ]
-    yielded = [
-        chunk
-        async for chunk in handler.process_stream(
-            _async_iter(passthrough_chunks), [], None, lambda m, t: None
-        )
-    ]
-    assert yielded == passthrough_chunks
-
-    ccr_handler = StreamingCCRHandler(response_handler, provider="anthropic")
-    monkeypatch.setattr(
-        ccr_handler,
-        "_parse_sse_stream",
-        lambda data: {
-            "content": [
-                {
-                    "type": "tool_use",
-                    "id": "tool_1",
-                    "name": CCR_TOOL_NAME,
-                    "input": {"hash": "abc"},
-                }
-            ]
-        },
-    )
-
-    async def fake_handle_response(response, messages, tools, api_call_fn, provider):  # noqa: ANN001
-        return {"content": [{"type": "text", "text": "done"}]}
-
-    async def fake_response_to_sse(response):  # noqa: ANN001
-        yield b"event: message_start\n"
-        yield b"event: message_stop\n"
-
-    monkeypatch.setattr(response_handler, "handle_response", fake_handle_response)
-    monkeypatch.setattr(ccr_handler, "_response_to_sse", fake_response_to_sse)
-
-    ccr_chunks = [
-        b'{"type":"tool_use","name":"headroom_retrieve"',
-        b',"stop_reason":"tool_use"}',
-        b"tail",
-    ]
-    streamed = [
-        chunk
-        async for chunk in ccr_handler.process_stream(
-            _async_iter(ccr_chunks), [], None, lambda m, t: None
-        )
-    ]
-    assert streamed == [b"event: message_start\n", b"event: message_stop\n"]
-
-
-@pytest.mark.asyncio
-async def test_streaming_handler_falls_back_to_buffer_on_processing_error(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    response_handler = CCRResponseHandler()
-    handler = StreamingCCRHandler(response_handler, provider="openai")
-    monkeypatch.setattr(
-        handler,
-        "_parse_sse_stream",
-        lambda data: (_ for _ in ()).throw(RuntimeError("parse failed")),
-    )
-
-    chunks = [b'{"type":"tool_use","name":"headroom_retrieve"', b',"stop_reason":"tool_use"}']
-    streamed = [
-        chunk
-        async for chunk in handler.process_stream(_async_iter(chunks), [], None, lambda m, t: None)
-    ]
-    assert streamed == [b"".join(chunks)]
-
-
-@pytest.mark.asyncio
-async def test_response_to_sse_formats() -> None:
-    anthropic = StreamingCCRHandler(CCRResponseHandler(), provider="anthropic")
-    anthropic_chunks = [chunk async for chunk in anthropic._response_to_sse({"content": []})]
-    assert anthropic_chunks[0] == b"event: message_start\n"
-    assert anthropic_chunks[-1] == b'data: {"type": "message_stop"}\n\n'
-
-    openai = StreamingCCRHandler(CCRResponseHandler(), provider="openai")
-    openai_chunks = [chunk async for chunk in openai._response_to_sse({"choices": []})]
-    assert openai_chunks == [b'data: {"choices": []}\n\n', b"data: [DONE]\n\n"]
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import pytest
+
+from headroom.ccr.response_handler import (
+    CCRResponseHandler,
+    CCRToolCall,
+    CCRToolResult,
+    StreamingCCRBuffer,
+    StreamingCCRHandler,
+)
+from headroom.ccr.tool_injection import CCR_TOOL_NAME
+
+
+class FakeStore:
+    def __init__(
+        self, *, search_error: Exception | None = None, retrieve_error: Exception | None = None
+    ) -> None:
+        self.search_error = search_error
+        self.retrieve_error = retrieve_error
+
+    def search(self, hash_key: str, query: str) -> list[dict[str, str]]:
+        if self.search_error:
+            raise self.search_error
+        return [{"id": "1", "text": query}]
+
+    def retrieve(self, hash_key: str):
+        if self.retrieve_error:
+            raise self.retrieve_error
+        return {"unexpected": True}
+
+
+async def _async_iter(items: list[bytes]):
+    for item in items:
+        yield item
+
+
+def test_extract_tool_calls_google_and_invalid_shapes() -> None:
+    handler = CCRResponseHandler()
+    google_response = {
+        "candidates": [
+            {
+                "content": {
+                    "parts": [
+                        {"text": "hello"},
+                        {"functionCall": {"name": CCR_TOOL_NAME, "args": {"hash": "abc"}}},
+                    ]
+                }
+            }
+        ]
+    }
+    assert handler._extract_tool_calls(google_response, "google") == [
+        {"functionCall": {"name": CCR_TOOL_NAME, "args": {"hash": "abc"}}}
+    ]
+    assert handler._extract_tool_calls({"content": "bad"}, "anthropic") == []
+    with pytest.raises(IndexError):
+        handler._extract_tool_calls({"choices": []}, "openai")
+    assert handler._extract_tool_calls({"candidates": []}, "google") == []
+
+
+def test_parse_ccr_tool_calls_google_and_other_calls() -> None:
+    handler = CCRResponseHandler()
+    response = {
+        "candidates": [
+            {
+                "content": {
+                    "parts": [
+                        {
+                            "functionCall": {
+                                "name": CCR_TOOL_NAME,
+                                "args": {
+                                    "hash": "aaaaaaaaaaaaaaaaaaaaaaaa",
+                                    "query": "pizza",
+                                },
+                            }
+                        },
+                        {"functionCall": {"name": "other_tool", "args": {}}},
+                    ]
+                }
+            }
+        ]
+    }
+    ccr_calls, other_calls = handler._parse_ccr_tool_calls(response, "google")
+    assert ccr_calls == [
+        CCRToolCall(
+            tool_call_id=CCR_TOOL_NAME,
+            hash_key="aaaaaaaaaaaaaaaaaaaaaaaa",
+            query="pizza",
+        )
+    ]
+    assert other_calls == [{"functionCall": {"name": "other_tool", "args": {}}}]
+
+
+def test_execute_retrieval_error_paths(monkeypatch: pytest.MonkeyPatch) -> None:
+    handler = CCRResponseHandler()
+    monkeypatch.setattr(
+        "headroom.ccr.response_handler.get_compression_store",
+        lambda: FakeStore(search_error=RuntimeError("search boom")),
+    )
+    search_result = handler._execute_retrieval(
+        CCRToolCall(tool_call_id="t1", hash_key="abc", query="find")
+    )
+    assert search_result.success is False
+    assert "Retrieval failed: search boom" in search_result.content
+
+    monkeypatch.setattr(
+        "headroom.ccr.response_handler.get_compression_store",
+        lambda: FakeStore(retrieve_error=RuntimeError("retrieve boom")),
+    )
+    retrieve_result = handler._execute_retrieval(CCRToolCall(tool_call_id="t2", hash_key="abc"))
+    assert retrieve_result.success is False
+    assert "Retrieval failed: retrieve boom" in retrieve_result.content
+
+
+def test_create_tool_result_message_google_and_generic_formats() -> None:
+    handler = CCRResponseHandler()
+    results = [
+        CCRToolResult(tool_call_id="headroom_retrieve", content='{"count": 1}', success=True)
+    ]
+    google_message = handler._create_tool_result_message(results, "google")
+    assert google_message == {
+        "role": "user",
+        "parts": [{"functionResponse": {"name": "headroom_retrieve", "response": {"count": 1}}}],
+    }
+
+    generic_message = handler._create_tool_result_message(
+        [CCRToolResult(tool_call_id="tool-1", content="not-json", success=False)],
+        "other",
+    )
+    assert generic_message["role"] == "tool"
+    assert json.loads(generic_message["content"]) == [
+        {"tool_call_id": "tool-1", "result": "not-json"}
+    ]
+
+    invalid_google = handler._create_tool_result_message(
+        [CCRToolResult(tool_call_id="headroom_retrieve", content="not-json", success=True)],
+        "google",
+    )
+    assert invalid_google["parts"][0]["functionResponse"]["response"] == {"content": "not-json"}
+
+
+def test_extract_assistant_message_google_and_generic() -> None:
+    handler = CCRResponseHandler()
+    google_message = handler._extract_assistant_message(
+        {"candidates": [{"content": {"parts": [{"text": "hello"}]}}]},
+        "google",
+    )
+    assert google_message == {"role": "model", "parts": [{"text": "hello"}]}
+
+    assert handler._extract_assistant_message({}, "google") == {"role": "model", "parts": []}
+    assert handler._extract_assistant_message({"content": "plain"}, "other") == {
+        "role": "assistant",
+        "content": "plain",
+    }
+
+
+@pytest.mark.asyncio
+async def test_handle_response_openai_success_and_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+    handler = CCRResponseHandler()
+    initial_response = {
+        "choices": [
+            {
+                "message": {
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": "call_1",
+                            "type": "function",
+                            "function": {
+                                "name": CCR_TOOL_NAME,
+                                "arguments": '{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}',
+                            },
+                        }
+                    ],
+                }
+            }
+        ]
+    }
+    monkeypatch.setattr(
+        handler,
+        "_execute_retrieval",
+        lambda call: CCRToolResult(
+            tool_call_id=call.tool_call_id,
+            content='{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}',
+            success=True,
+        ),
+    )
+
+    captured_messages: list[list[dict[str, Any]]] = []
+
+    async def success_api_call(messages, tools):
+        captured_messages.append(messages)
+        return {"choices": [{"message": {"role": "assistant", "content": "done"}}]}
+
+    result = await handler.handle_response(
+        initial_response, [{"role": "user", "content": "hi"}], [], success_api_call, "openai"
+    )
+    assert result == {"choices": [{"message": {"role": "assistant", "content": "done"}}]}
+    assert captured_messages[0][1]["role"] == "assistant"
+    assert captured_messages[0][2]["role"] == "tool"
+    assert handler.get_stats()["total_retrievals"] == 1
+
+    async def failing_api_call(messages, tools):
+        raise RuntimeError("continuation failed")
+
+    failed = await handler.handle_response(initial_response, [], [], failing_api_call, "openai")
+    assert failed == initial_response
+
+
+def test_streaming_buffer_and_parse_sse_helpers() -> None:
+    buffer = StreamingCCRBuffer()
+    assert buffer.add_chunk(b"plain") is False
+    assert buffer.get_accumulated() == b"plain"
+
+    handler = StreamingCCRHandler(CCRResponseHandler(), provider="anthropic")
+    anthropic_data = b"\n".join(
+        [
+            b'data: {"type":"content_block_start","content_block":{"type":"text","text":"Hel"}}',
+            b'data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"lo"}}',
+            b'data: {"type":"content_block_stop"}',
+            b'data: {"type":"content_block_start","content_block":{"type":"tool_use","id":"tool_1","name":"headroom_retrieve"}}',
+            b'data: {"type":"content_block_delta","delta":{"type":"input_json_delta","partial_json":"{\\"hash\\":\\"abc\\"}"}}',
+            b'data: {"type":"content_block_stop"}',
+            b'data: {"type":"message_delta","delta":{"stop_reason":"tool_use"}}',
+            b"data: [DONE]",
+        ]
+    )
+    parsed = handler._parse_sse_stream(anthropic_data)
+    assert parsed["content"][0] == {"type": "text", "text": "Hello"}
+    assert parsed["content"][1]["name"] == "headroom_retrieve"
+    assert parsed["content"][1]["input"] == {"hash": "abc"}
+    assert parsed["stop_reason"] == "tool_use"
+
+    openai_handler = StreamingCCRHandler(CCRResponseHandler(), provider="openai")
+    parsed_openai = openai_handler._reconstruct_openai_response(
+        [
+            {"choices": [{"delta": {"content": "Hi"}}]},
+            {
+                "choices": [
+                    {
+                        "delta": {
+                            "tool_calls": [
+                                {
+                                    "index": 0,
+                                    "id": "call_1",
+                                    "function": {
+                                        "name": "headroom_retrieve",
+                                        "arguments": '{"hash":"aaaaaaaaaaaa',
+                                    },
+                                }
+                            ]
+                        }
+                    }
+                ]
+            },
+            {
+                "choices": [
+                    {
+                        "delta": {
+                            "tool_calls": [
+                                {
+                                    "index": 0,
+                                    "function": {"arguments": 'aaaaaaaaaaaa"}'},
+                                }
+                            ]
+                        }
+                    }
+                ]
+            },
+        ]
+    )
+    message = parsed_openai["choices"][0]["message"]
+    assert message["content"] == "Hi"
+    assert message["tool_calls"][0]["id"] == "call_1"
+    assert message["tool_calls"][0]["function"]["arguments"] == (
+        '{"hash":"aaaaaaaaaaaaaaaaaaaaaaaa"}'
+    )
+
+
+@pytest.mark.asyncio
+async def test_streaming_handler_process_stream_pass_through_and_ccr(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    response_handler = CCRResponseHandler()
+    handler = StreamingCCRHandler(response_handler, provider="anthropic")
+
+    passthrough_chunks = [
+        b'data: {"type":"content_block_delta","delta":{"text":"hello"}}',
+        b'data: {"stop_reason":"end_turn"}',
+    ]
+    yielded = [
+        chunk
+        async for chunk in handler.process_stream(
+            _async_iter(passthrough_chunks), [], None, lambda m, t: None
+        )
+    ]
+    assert yielded == passthrough_chunks
+
+    ccr_handler = StreamingCCRHandler(response_handler, provider="anthropic")
+    monkeypatch.setattr(
+        ccr_handler,
+        "_parse_sse_stream",
+        lambda data: {
+            "content": [
+                {
+                    "type": "tool_use",
+                    "id": "tool_1",
+                    "name": CCR_TOOL_NAME,
+                    "input": {"hash": "abc"},
+                }
+            ]
+        },
+    )
+
+    async def fake_handle_response(response, messages, tools, api_call_fn, provider):  # noqa: ANN001
+        return {"content": [{"type": "text", "text": "done"}]}
+
+    async def fake_response_to_sse(response):  # noqa: ANN001
+        yield b"event: message_start\n"
+        yield b"event: message_stop\n"
+
+    monkeypatch.setattr(response_handler, "handle_response", fake_handle_response)
+    monkeypatch.setattr(ccr_handler, "_response_to_sse", fake_response_to_sse)
+
+    ccr_chunks = [
+        b'{"type":"tool_use","name":"headroom_retrieve"',
+        b',"stop_reason":"tool_use"}',
+        b"tail",
+    ]
+    streamed = [
+        chunk
+        async for chunk in ccr_handler.process_stream(
+            _async_iter(ccr_chunks), [], None, lambda m, t: None
+        )
+    ]
+    assert streamed == [b"event: message_start\n", b"event: message_stop\n"]
+
+
+@pytest.mark.asyncio
+async def test_streaming_handler_falls_back_to_buffer_on_processing_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    response_handler = CCRResponseHandler()
+    handler = StreamingCCRHandler(response_handler, provider="openai")
+    monkeypatch.setattr(
+        handler,
+        "_parse_sse_stream",
+        lambda data: (_ for _ in ()).throw(RuntimeError("parse failed")),
+    )
+
+    chunks = [b'{"type":"tool_use","name":"headroom_retrieve"', b',"stop_reason":"tool_use"}']
+    streamed = [
+        chunk
+        async for chunk in handler.process_stream(_async_iter(chunks), [], None, lambda m, t: None)
+    ]
+    assert streamed == [b"".join(chunks)]
+
+
+@pytest.mark.asyncio
+async def test_response_to_sse_formats() -> None:
+    anthropic = StreamingCCRHandler(CCRResponseHandler(), provider="anthropic")
+    anthropic_chunks = [chunk async for chunk in anthropic._response_to_sse({"content": []})]
+    assert anthropic_chunks[0] == b"event: message_start\n"
+    assert anthropic_chunks[-1] == b'data: {"type": "message_stop"}\n\n'
+
+    openai = StreamingCCRHandler(CCRResponseHandler(), provider="openai")
+    openai_chunks = [chunk async for chunk in openai._response_to_sse({"choices": []})]
+    assert openai_chunks == [b'data: {"choices": []}\n\n', b"data: [DONE]\n\n"]
diff --git a/tests/test_cli/test_wrap_copilot.py b/tests/test_cli/test_wrap_copilot.py
index 79ddbe3420df68196d792aa7ea5ed2f8a3707a3e..84065b0f28492d4f341bbc9caa30ea109ccc118e 100644
--- a/tests/test_cli/test_wrap_copilot.py
+++ b/tests/test_cli/test_wrap_copilot.py
@@ -1,335 +1,335 @@
-"""Tests for `headroom wrap copilot` command."""
-
-from __future__ import annotations
-
-import importlib
-import sys
-import types
-from pathlib import Path
-from unittest.mock import patch
-
-import click
-import pytest
-from click.testing import CliRunner
-
-from headroom.copilot_auth import DEFAULT_API_URL
-
-
-@pytest.fixture
-def runner() -> CliRunner:
-    return CliRunner()
-
-
-@pytest.fixture
-def wrap_modules(monkeypatch: pytest.MonkeyPatch) -> tuple[types.ModuleType, click.Group]:
-    headroom_pkg = sys.modules.get("headroom")
-    saved_headroom_cli_attr = (
-        headroom_pkg.cli if headroom_pkg is not None and hasattr(headroom_pkg, "cli") else None
-    )
-    saved_modules = {
-        name: sys.modules.get(name)
-        for name in ("headroom.cli", "headroom.cli.main", "headroom.cli.wrap")
-    }
-
-    fake_main_module = types.ModuleType("headroom.cli.main")
-    fake_main_module.main = click.Group()
-    sys.modules["headroom.cli.main"] = fake_main_module
-    sys.modules.pop("headroom.cli", None)
-    sys.modules.pop("headroom.cli.wrap", None)
-
-    wrap_cli = importlib.import_module("headroom.cli.wrap")
-    monkeypatch.setattr(wrap_cli, "_check_proxy", lambda _port: False)
-
-    try:
-        yield wrap_cli, fake_main_module.main
-    finally:
-        for name in ("headroom.cli.wrap", "headroom.cli.main", "headroom.cli"):
-            sys.modules.pop(name, None)
-        for name, module in saved_modules.items():
-            if module is not None:
-                sys.modules[name] = module
-        if saved_modules["headroom.cli"] is not None:
-            cli_pkg = saved_modules["headroom.cli"]
-            if saved_modules["headroom.cli.main"] is not None:
-                cli_pkg.main = saved_modules["headroom.cli.main"]
-            if saved_modules["headroom.cli.wrap"] is not None:
-                cli_pkg.wrap = saved_modules["headroom.cli.wrap"]
-        if headroom_pkg is not None:
-            if saved_headroom_cli_attr is None:
-                if hasattr(headroom_pkg, "cli"):
-                    delattr(headroom_pkg, "cli")
-            else:
-                headroom_pkg.cli = saved_headroom_cli_attr
-
-
-def test_wrap_copilot_auto_anthropic_injects_instructions(
-    runner: CliRunner,
-    wrap_modules: tuple[types.ModuleType, click.Group],
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    wrap_cli, main = wrap_modules
-    monkeypatch.chdir(tmp_path)
-    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")
-    captured: dict[str, object] = {}
-
-    def fake_launch_tool(**kwargs):  # noqa: ANN003
-        captured.update(kwargs)
-
-    with (
-        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
-        patch("headroom.cli.wrap.has_oauth_auth", return_value=False),
-        patch("headroom.cli.wrap._ensure_rtk_binary", return_value=Path("/tmp/rtk")),
-        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
-    ):
-        result = runner.invoke(
-            main,
-            ["wrap", "copilot", "--", "--model", "claude-sonnet-4-20250514"],
-        )
-
-    assert result.exit_code == 0, result.output
-    instructions = tmp_path / ".github" / "copilot-instructions.md"
-    assert instructions.exists()
-    content = instructions.read_text()
-    assert wrap_cli._RTK_MARKER in content
-    assert "RTK (Rust Token Killer)" in content
-
-    env = captured["env"]
-    assert isinstance(env, dict)
-    assert env["COPILOT_PROVIDER_TYPE"] == "anthropic"
-    assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787"
-    assert "COPILOT_PROVIDER_WIRE_API" not in env
-    assert captured["agent_type"] == "copilot"
-    assert captured["tool_label"] == "COPILOT"
-    assert captured["args"] == ("--model", "claude-sonnet-4-20250514")
-
-
-def test_wrap_copilot_openai_backend_sets_completions_env(
-    runner: CliRunner,
-    wrap_modules: tuple[types.ModuleType, click.Group],
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    _wrap_cli, main = wrap_modules
-    monkeypatch.setenv("OPENAI_API_KEY", "sk-test-dummy")
-    captured: dict[str, object] = {}
-
-    def fake_launch_tool(**kwargs):  # noqa: ANN003
-        captured.update(kwargs)
-
-    with (
-        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
-        patch("headroom.cli.wrap.has_oauth_auth", return_value=False),
-        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
-    ):
-        result = runner.invoke(
-            main,
-            [
-                "wrap",
-                "copilot",
-                "--no-rtk",
-                "--backend",
-                "anyllm",
-                "--anyllm-provider",
-                "groq",
-                "--region",
-                "us-central1",
-                "--",
-                "--model",
-                "gpt-4o",
-            ],
-        )
-
-    assert result.exit_code == 0, result.output
-
-    env = captured["env"]
-    assert isinstance(env, dict)
-    assert env["COPILOT_PROVIDER_TYPE"] == "openai"
-    assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"
-    assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"
-    assert captured["backend"] == "anyllm"
-    assert captured["anyllm_provider"] == "groq"
-    assert captured["region"] == "us-central1"
-    assert captured["args"] == ("--model", "gpt-4o")
-
-
-def test_wrap_copilot_auto_detects_running_proxy_backend(
-    runner: CliRunner,
-    wrap_modules: tuple[types.ModuleType, click.Group],
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    _wrap_cli, main = wrap_modules
-    monkeypatch.setenv("OPENAI_API_KEY", "sk-test-dummy")
-    captured: dict[str, object] = {}
-
-    def fake_launch_tool(**kwargs):  # noqa: ANN003
-        captured.update(kwargs)
-
-    with (
-        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
-        patch("headroom.cli.wrap.has_oauth_auth", return_value=False),
-        patch("headroom.cli.wrap._check_proxy", return_value=True),
-        patch("headroom.cli.wrap._detect_running_proxy_backend", return_value="anyllm"),
-        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
-    ):
-        result = runner.invoke(
-            main,
-            ["wrap", "copilot", "--no-rtk", "--", "--model", "gpt-4o"],
-        )
-
-    assert result.exit_code == 0, result.output
-    env = captured["env"]
-    assert isinstance(env, dict)
-    assert env["COPILOT_PROVIDER_TYPE"] == "openai"
-    assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"
-    assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"
-
-
-def test_wrap_copilot_prefers_existing_oauth_session(
-    runner: CliRunner,
-    wrap_modules: tuple[types.ModuleType, click.Group],
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    _wrap_cli, main = wrap_modules
-    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")
-    captured: dict[str, object] = {}
-
-    def fake_launch_tool(**kwargs):  # noqa: ANN003
-        captured.update(kwargs)
-
-    with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):
-        with patch("headroom.cli.wrap.resolve_client_bearer_token", return_value="gho-existing"):
-            with patch("headroom.cli.wrap.has_oauth_auth", return_value=True):
-                with patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool):
-                    result = runner.invoke(
-                        main,
-                        ["wrap", "copilot", "--no-rtk", "--", "--model", "claude-sonnet-4.6"],
-                    )
-
-    assert result.exit_code == 0, result.output
-    env = captured["env"]
-    assert isinstance(env, dict)
-    assert env["COPILOT_PROVIDER_TYPE"] == "openai"
-    assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"
-    assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"
-    assert env["COPILOT_PROVIDER_BEARER_TOKEN"] == "gho-existing"
-    assert "COPILOT_PROVIDER_API_KEY" not in env
-    assert captured["openai_api_url"] == DEFAULT_API_URL
-
-
-def test_wrap_copilot_translated_backend_still_requires_byok(
-    runner: CliRunner,
-    wrap_modules: tuple[types.ModuleType, click.Group],
-) -> None:
-    _wrap_cli, main = wrap_modules
-    with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):
-        with patch("headroom.cli.wrap.has_oauth_auth", return_value=True):
-            result = runner.invoke(
-                main,
-                [
-                    "wrap",
-                    "copilot",
-                    "--no-rtk",
-                    "--backend",
-                    "anyllm",
-                    "--",
-                    "--model",
-                    "gpt-4o",
-                ],
-            )
-
-    assert result.exit_code == 1
-    assert "Copilot BYOK mode requires a provider API key" in result.output
-
-
-def test_wrap_copilot_rejects_wire_api_for_anthropic_provider(
-    runner: CliRunner,
-    wrap_modules: tuple[types.ModuleType, click.Group],
-) -> None:
-    _wrap_cli, main = wrap_modules
-    with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):
-        result = runner.invoke(
-            main,
-            [
-                "wrap",
-                "copilot",
-                "--wire-api",
-                "responses",
-                "--",
-                "--model",
-                "claude-sonnet-4-20250514",
-            ],
-        )
-
-    assert result.exit_code != 0
-    assert "--wire-api is only valid" in result.output
-
-
-def test_wrap_copilot_rejects_responses_for_translated_backends(
-    runner: CliRunner,
-    wrap_modules: tuple[types.ModuleType, click.Group],
-) -> None:
-    _wrap_cli, main = wrap_modules
-    with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):
-        result = runner.invoke(
-            main,
-            [
-                "wrap",
-                "copilot",
-                "--backend",
-                "anyllm",
-                "--wire-api",
-                "responses",
-                "--",
-                "--model",
-                "gpt-4o",
-            ],
-        )
-
-    assert result.exit_code != 0
-    assert "not supported with translated backends" in result.output
-
-
-def test_wrap_copilot_clears_stale_wire_api_in_anthropic_mode(
-    runner: CliRunner,
-    wrap_modules: tuple[types.ModuleType, click.Group],
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    _wrap_cli, main = wrap_modules
-    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")
-    captured: dict[str, object] = {}
-
-    def fake_launch_tool(**kwargs):  # noqa: ANN003
-        captured.update(kwargs)
-
-    with (
-        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
-        patch("headroom.cli.wrap.has_oauth_auth", return_value=False),
-        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
-    ):
-        result = runner.invoke(
-            main,
-            ["wrap", "copilot", "--no-rtk", "--", "--model", "claude-sonnet-4-20250514"],
-            env={
-                "COPILOT_PROVIDER_WIRE_API": "responses",
-                "ANTHROPIC_API_KEY": "sk-test-dummy",
-            },
-        )
-
-    assert result.exit_code == 0, result.output
-    env = captured["env"]
-    assert isinstance(env, dict)
-    assert env["COPILOT_PROVIDER_TYPE"] == "anthropic"
-    assert "COPILOT_PROVIDER_WIRE_API" not in env
-
-
-def test_wrap_copilot_fails_when_binary_missing(
-    runner: CliRunner,
-    wrap_modules: tuple[types.ModuleType, click.Group],
-) -> None:
-    _wrap_cli, main = wrap_modules
-    with patch("headroom.cli.wrap.shutil.which", return_value=None):
-        result = runner.invoke(main, ["wrap", "copilot", "--", "--model", "gpt-4o"])
-
-    assert result.exit_code == 1
-    assert "'copilot' not found in PATH" in result.output
-    assert "Install GitHub Copilot CLI" in result.output
+"""Tests for `headroom wrap copilot` command."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+import types
+from pathlib import Path
+from unittest.mock import patch
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from headroom.copilot_auth import DEFAULT_API_URL
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    return CliRunner()
+
+
+@pytest.fixture
+def wrap_modules(monkeypatch: pytest.MonkeyPatch) -> tuple[types.ModuleType, click.Group]:
+    headroom_pkg = sys.modules.get("headroom")
+    saved_headroom_cli_attr = (
+        headroom_pkg.cli if headroom_pkg is not None and hasattr(headroom_pkg, "cli") else None
+    )
+    saved_modules = {
+        name: sys.modules.get(name)
+        for name in ("headroom.cli", "headroom.cli.main", "headroom.cli.wrap")
+    }
+
+    fake_main_module = types.ModuleType("headroom.cli.main")
+    fake_main_module.main = click.Group()
+    sys.modules["headroom.cli.main"] = fake_main_module
+    sys.modules.pop("headroom.cli", None)
+    sys.modules.pop("headroom.cli.wrap", None)
+
+    wrap_cli = importlib.import_module("headroom.cli.wrap")
+    monkeypatch.setattr(wrap_cli, "_check_proxy", lambda _port: False)
+
+    try:
+        yield wrap_cli, fake_main_module.main
+    finally:
+        for name in ("headroom.cli.wrap", "headroom.cli.main", "headroom.cli"):
+            sys.modules.pop(name, None)
+        for name, module in saved_modules.items():
+            if module is not None:
+                sys.modules[name] = module
+        if saved_modules["headroom.cli"] is not None:
+            cli_pkg = saved_modules["headroom.cli"]
+            if saved_modules["headroom.cli.main"] is not None:
+                cli_pkg.main = saved_modules["headroom.cli.main"]
+            if saved_modules["headroom.cli.wrap"] is not None:
+                cli_pkg.wrap = saved_modules["headroom.cli.wrap"]
+        if headroom_pkg is not None:
+            if saved_headroom_cli_attr is None:
+                if hasattr(headroom_pkg, "cli"):
+                    delattr(headroom_pkg, "cli")
+            else:
+                headroom_pkg.cli = saved_headroom_cli_attr
+
+
+def test_wrap_copilot_auto_anthropic_injects_instructions(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    wrap_cli, main = wrap_modules
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")
+    captured: dict[str, object] = {}
+
+    def fake_launch_tool(**kwargs):  # noqa: ANN003
+        captured.update(kwargs)
+
+    with (
+        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
+        patch("headroom.cli.wrap.has_oauth_auth", return_value=False),
+        patch("headroom.cli.wrap._ensure_rtk_binary", return_value=Path("/tmp/rtk")),
+        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
+    ):
+        result = runner.invoke(
+            main,
+            ["wrap", "copilot", "--", "--model", "claude-sonnet-4-20250514"],
+        )
+
+    assert result.exit_code == 0, result.output
+    instructions = tmp_path / ".github" / "copilot-instructions.md"
+    assert instructions.exists()
+    content = instructions.read_text()
+    assert wrap_cli._RTK_MARKER in content
+    assert "RTK (Rust Token Killer)" in content
+
+    env = captured["env"]
+    assert isinstance(env, dict)
+    assert env["COPILOT_PROVIDER_TYPE"] == "anthropic"
+    assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787"
+    assert "COPILOT_PROVIDER_WIRE_API" not in env
+    assert captured["agent_type"] == "copilot"
+    assert captured["tool_label"] == "COPILOT"
+    assert captured["args"] == ("--model", "claude-sonnet-4-20250514")
+
+
+def test_wrap_copilot_openai_backend_sets_completions_env(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _wrap_cli, main = wrap_modules
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-test-dummy")
+    captured: dict[str, object] = {}
+
+    def fake_launch_tool(**kwargs):  # noqa: ANN003
+        captured.update(kwargs)
+
+    with (
+        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
+        patch("headroom.cli.wrap.has_oauth_auth", return_value=False),
+        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
+    ):
+        result = runner.invoke(
+            main,
+            [
+                "wrap",
+                "copilot",
+                "--no-rtk",
+                "--backend",
+                "anyllm",
+                "--anyllm-provider",
+                "groq",
+                "--region",
+                "us-central1",
+                "--",
+                "--model",
+                "gpt-4o",
+            ],
+        )
+
+    assert result.exit_code == 0, result.output
+
+    env = captured["env"]
+    assert isinstance(env, dict)
+    assert env["COPILOT_PROVIDER_TYPE"] == "openai"
+    assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"
+    assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"
+    assert captured["backend"] == "anyllm"
+    assert captured["anyllm_provider"] == "groq"
+    assert captured["region"] == "us-central1"
+    assert captured["args"] == ("--model", "gpt-4o")
+
+
+def test_wrap_copilot_auto_detects_running_proxy_backend(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _wrap_cli, main = wrap_modules
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-test-dummy")
+    captured: dict[str, object] = {}
+
+    def fake_launch_tool(**kwargs):  # noqa: ANN003
+        captured.update(kwargs)
+
+    with (
+        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
+        patch("headroom.cli.wrap.has_oauth_auth", return_value=False),
+        patch("headroom.cli.wrap._check_proxy", return_value=True),
+        patch("headroom.cli.wrap._detect_running_proxy_backend", return_value="anyllm"),
+        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
+    ):
+        result = runner.invoke(
+            main,
+            ["wrap", "copilot", "--no-rtk", "--", "--model", "gpt-4o"],
+        )
+
+    assert result.exit_code == 0, result.output
+    env = captured["env"]
+    assert isinstance(env, dict)
+    assert env["COPILOT_PROVIDER_TYPE"] == "openai"
+    assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"
+    assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"
+
+
+def test_wrap_copilot_prefers_existing_oauth_session(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _wrap_cli, main = wrap_modules
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")
+    captured: dict[str, object] = {}
+
+    def fake_launch_tool(**kwargs):  # noqa: ANN003
+        captured.update(kwargs)
+
+    with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):
+        with patch("headroom.cli.wrap.resolve_client_bearer_token", return_value="gho-existing"):
+            with patch("headroom.cli.wrap.has_oauth_auth", return_value=True):
+                with patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool):
+                    result = runner.invoke(
+                        main,
+                        ["wrap", "copilot", "--no-rtk", "--", "--model", "claude-sonnet-4.6"],
+                    )
+
+    assert result.exit_code == 0, result.output
+    env = captured["env"]
+    assert isinstance(env, dict)
+    assert env["COPILOT_PROVIDER_TYPE"] == "openai"
+    assert env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"
+    assert env["COPILOT_PROVIDER_WIRE_API"] == "completions"
+    assert env["COPILOT_PROVIDER_BEARER_TOKEN"] == "gho-existing"
+    assert "COPILOT_PROVIDER_API_KEY" not in env
+    assert captured["openai_api_url"] == DEFAULT_API_URL
+
+
+def test_wrap_copilot_translated_backend_still_requires_byok(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+) -> None:
+    _wrap_cli, main = wrap_modules
+    with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):
+        with patch("headroom.cli.wrap.has_oauth_auth", return_value=True):
+            result = runner.invoke(
+                main,
+                [
+                    "wrap",
+                    "copilot",
+                    "--no-rtk",
+                    "--backend",
+                    "anyllm",
+                    "--",
+                    "--model",
+                    "gpt-4o",
+                ],
+            )
+
+    assert result.exit_code == 1
+    assert "Copilot BYOK mode requires a provider API key" in result.output
+
+
+def test_wrap_copilot_rejects_wire_api_for_anthropic_provider(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+) -> None:
+    _wrap_cli, main = wrap_modules
+    with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):
+        result = runner.invoke(
+            main,
+            [
+                "wrap",
+                "copilot",
+                "--wire-api",
+                "responses",
+                "--",
+                "--model",
+                "claude-sonnet-4-20250514",
+            ],
+        )
+
+    assert result.exit_code != 0
+    assert "--wire-api is only valid" in result.output
+
+
+def test_wrap_copilot_rejects_responses_for_translated_backends(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+) -> None:
+    _wrap_cli, main = wrap_modules
+    with patch("headroom.cli.wrap.shutil.which", return_value="copilot"):
+        result = runner.invoke(
+            main,
+            [
+                "wrap",
+                "copilot",
+                "--backend",
+                "anyllm",
+                "--wire-api",
+                "responses",
+                "--",
+                "--model",
+                "gpt-4o",
+            ],
+        )
+
+    assert result.exit_code != 0
+    assert "not supported with translated backends" in result.output
+
+
+def test_wrap_copilot_clears_stale_wire_api_in_anthropic_mode(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _wrap_cli, main = wrap_modules
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")
+    captured: dict[str, object] = {}
+
+    def fake_launch_tool(**kwargs):  # noqa: ANN003
+        captured.update(kwargs)
+
+    with (
+        patch("headroom.cli.wrap.shutil.which", return_value="copilot"),
+        patch("headroom.cli.wrap.has_oauth_auth", return_value=False),
+        patch("headroom.cli.wrap._launch_tool", side_effect=fake_launch_tool),
+    ):
+        result = runner.invoke(
+            main,
+            ["wrap", "copilot", "--no-rtk", "--", "--model", "claude-sonnet-4-20250514"],
+            env={
+                "COPILOT_PROVIDER_WIRE_API": "responses",
+                "ANTHROPIC_API_KEY": "sk-test-dummy",
+            },
+        )
+
+    assert result.exit_code == 0, result.output
+    env = captured["env"]
+    assert isinstance(env, dict)
+    assert env["COPILOT_PROVIDER_TYPE"] == "anthropic"
+    assert "COPILOT_PROVIDER_WIRE_API" not in env
+
+
+def test_wrap_copilot_fails_when_binary_missing(
+    runner: CliRunner,
+    wrap_modules: tuple[types.ModuleType, click.Group],
+) -> None:
+    _wrap_cli, main = wrap_modules
+    with patch("headroom.cli.wrap.shutil.which", return_value=None):
+        result = runner.invoke(main, ["wrap", "copilot", "--", "--model", "gpt-4o"])
+
+    assert result.exit_code == 1
+    assert "'copilot' not found in PATH" in result.output
+    assert "Install GitHub Copilot CLI" in result.output
diff --git a/tests/test_cli_learn.py b/tests/test_cli_learn.py
index 875a4454054a89ea3ecb390f1d1574406b0182e7..33a64d82d2cb2eb11a99071f526bea6de7c75dc5 100644
--- a/tests/test_cli_learn.py
+++ b/tests/test_cli_learn.py
@@ -1,266 +1,266 @@
-from __future__ import annotations
-
-from pathlib import Path
-from types import SimpleNamespace
-
-import click
-import click.shell_completion as click_shell_completion
-import pytest
-from click.testing import CliRunner
-
-from headroom.cli.learn import _AgentChoice
-from headroom.cli.main import main
-
-
-@pytest.fixture
-def runner() -> CliRunner:
-    return CliRunner()
-
-
-class FakeWriter:
-    def __init__(self) -> None:
-        self.calls: list[tuple[list[object], object, bool]] = []
-
-    def write(self, recommendations, project, dry_run: bool):  # noqa: ANN001, ANN201
-        self.calls.append((recommendations, project, dry_run))
-        return SimpleNamespace(
-            dry_run=dry_run,
-            content_by_file={
-                Path(project.project_path) / "AGENTS.md": "<!-- headroom -->\nRule 1\nRule 2"
-            },
-        )
-
-
-class FakePlugin:
-    def __init__(self, name: str, display_name: str, projects: list[object]) -> None:
-        self.name = name
-        self.display_name = display_name
-        self._projects = projects
-        self.writer = FakeWriter()
-        self.scan_calls: list[tuple[object, int]] = []
-
-    def detect(self) -> bool:
-        return True
-
-    def create_writer(self) -> FakeWriter:
-        return self.writer
-
-    def discover_projects(self) -> list[object]:
-        return self._projects
-
-    def scan_project(self, project, max_workers: int = 1):  # noqa: ANN001, ANN201
-        self.scan_calls.append((project, max_workers))
-        return [SimpleNamespace(events=["event"], tool_calls=[], failure_count=0)]
-
-
-class FakeAnalyzer:
-    def __init__(self, model: str | None = None) -> None:
-        self.model = model
-        self.calls: list[tuple[object, list[object]]] = []
-
-    def analyze(self, project, sessions):  # noqa: ANN001, ANN201
-        self.calls.append((project, sessions))
-        return SimpleNamespace(
-            total_sessions=len(sessions),
-            total_calls=3,
-            total_failures=1,
-            failure_rate=1 / 3,
-            recommendations=[SimpleNamespace(section="Rules")],
-        )
-
-
-def test_agent_choice_convert_and_shell_complete(monkeypatch: pytest.MonkeyPatch) -> None:
-    choice = _AgentChoice()
-    monkeypatch.setattr(click, "shell_completion", click_shell_completion)
-    monkeypatch.setattr(
-        "headroom.learn.registry.get_registry",
-        lambda: {"codex": object(), "claude": object()},
-    )
-    monkeypatch.setattr(
-        "headroom.learn.registry.available_agent_names",
-        lambda: ["claude", "codex"],
-    )
-
-    assert choice.convert("auto", None, None) == "auto"
-    assert choice.convert("CODEX", None, None) == "codex"
-    with pytest.raises(Exception, match="Unknown agent: bad"):
-        choice.convert("bad", None, None)
-
-    completions = choice.shell_complete(None, None, "c")  # type: ignore[arg-type]
-    assert [item.value for item in completions] == ["claude", "codex"]
-    assert choice.get_metavar(None) == "[auto|<agent>]"  # type: ignore[arg-type]
-
-
-def test_learn_exits_cleanly_when_model_detection_fails(
-    monkeypatch: pytest.MonkeyPatch, runner: CliRunner
-) -> None:
-    monkeypatch.setattr(
-        "headroom.learn.analyzer._detect_default_model",
-        lambda: (_ for _ in ()).throw(RuntimeError("no model")),
-    )
-
-    result = runner.invoke(main, ["learn"], catch_exceptions=False)
-
-    assert result.exit_code == 1
-    assert "Error: no model" in result.output
-
-
-def test_learn_auto_agent_reports_no_detected_plugins(
-    monkeypatch: pytest.MonkeyPatch, runner: CliRunner
-) -> None:
-    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
-    monkeypatch.setattr("headroom.learn.registry.auto_detect_plugins", lambda: [])
-    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)
-
-    result = runner.invoke(main, ["learn"], catch_exceptions=False)
-
-    assert result.exit_code == 0
-    assert "No coding agent data found." in result.output
-
-
-def test_learn_single_agent_shows_available_projects_when_cwd_missing(
-    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
-) -> None:
-    project = SimpleNamespace(name="demo", project_path=tmp_path / "demo")
-    plugin = FakePlugin("codex", "Codex", [project])
-
-    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
-    monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)
-    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)
-
-    with runner.isolated_filesystem(temp_dir=tmp_path):
-        result = runner.invoke(main, ["learn", "--agent", "codex"], catch_exceptions=False)
-
-    assert result.exit_code == 0
-    assert "No codex project data found for" in result.output
-    assert "Available codex projects:" in result.output
-    assert "demo" in result.output
-
-
-def test_learn_project_lookup_and_apply_flow(
-    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
-) -> None:
-    project_path = tmp_path / "project-a"
-    project_path.mkdir()
-    matched = SimpleNamespace(name="project-a", project_path=project_path)
-    unmatched = SimpleNamespace(name="project-b", project_path=tmp_path / "project-b")
-    plugin = FakePlugin("codex", "Codex", [matched, unmatched])
-    analyzer = FakeAnalyzer()
-
-    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
-    monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)
-    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)
-
-    result = runner.invoke(
-        main,
-        ["learn", "--agent", "codex", "--project", str(project_path), "--apply", "--workers", "4"],
-        catch_exceptions=False,
-    )
-
-    assert result.exit_code == 0, result.output
-    assert "Path: " in result.output
-    assert "Analyzing with gpt-4o..." in result.output
-    assert "Recommendations: 1" in result.output
-    assert "[WROTE]" in result.output
-    assert "Rule 1" in result.output
-    assert plugin.scan_calls == [(matched, 4)]
-    assert analyzer.calls[0][0] is matched
-    assert plugin.writer.calls[0][2] is False
-
-
-def test_learn_reports_missing_requested_project_and_lists_discovered(
-    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
-) -> None:
-    requested = tmp_path / "missing"
-    requested.mkdir()
-    discovered = SimpleNamespace(name="project-a", project_path=tmp_path / "project-a")
-    plugin = FakePlugin("claude", "Claude Code", [discovered])
-
-    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
-    monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)
-    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)
-
-    result = runner.invoke(
-        main,
-        ["learn", "--agent", "claude", "--project", str(requested)],
-        catch_exceptions=False,
-    )
-
-    assert result.exit_code == 0
-    assert f"No project data found for {requested.resolve()}" in result.output
-    assert "Available discovered projects:" in result.output
-    assert "[claude]" in result.output
-
-
-def test_learn_analyze_all_uses_default_workers_and_prints_summary(
-    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
-) -> None:
-    projects_a = [SimpleNamespace(name="a", project_path=tmp_path / "a")]
-    projects_b = [SimpleNamespace(name="b", project_path=tmp_path / "b")]
-    plugin_a = FakePlugin("codex", "Codex", projects_a)
-    plugin_b = FakePlugin("claude", "Claude Code", projects_b)
-    analyzer = FakeAnalyzer()
-
-    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
-    monkeypatch.setattr(
-        "headroom.learn.registry.auto_detect_plugins",
-        lambda: [plugin_a, plugin_b],
-    )
-    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)
-    monkeypatch.setattr("os.cpu_count", lambda: 12)
-
-    result = runner.invoke(main, ["learn", "--all"], catch_exceptions=False)
-
-    assert result.exit_code == 0, result.output
-    assert "Detected agents: Codex, Claude Code" in result.output
-    assert "Total: 2 projects, 2 failures, 2 recommendations" in result.output
-    assert plugin_a.scan_calls == [(projects_a[0], 8)]
-    assert plugin_b.scan_calls == [(projects_b[0], 8)]
-
-
-def test_learn_handles_empty_sessions_and_no_pattern_outputs(
-    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
-) -> None:
-    no_sessions = SimpleNamespace(name="empty", project_path=tmp_path / "empty")
-    no_failures = SimpleNamespace(name="clean", project_path=tmp_path / "clean")
-    no_actions = SimpleNamespace(name="no-actions", project_path=tmp_path / "no-actions")
-
-    class BranchingPlugin(FakePlugin):
-        def scan_project(self, project, max_workers: int = 1):  # noqa: ANN001, ANN201
-            self.scan_calls.append((project, max_workers))
-            if project is no_sessions:
-                return []
-            return [SimpleNamespace(events=["event"], tool_calls=[], failure_count=0)]
-
-    class BranchingAnalyzer(FakeAnalyzer):
-        def analyze(self, project, sessions):  # noqa: ANN001, ANN201
-            self.calls.append((project, sessions))
-            if project is no_failures:
-                return SimpleNamespace(
-                    total_sessions=1,
-                    total_calls=2,
-                    total_failures=0,
-                    failure_rate=0.0,
-                    recommendations=[],
-                )
-            return SimpleNamespace(
-                total_sessions=1,
-                total_calls=2,
-                total_failures=1,
-                failure_rate=0.5,
-                recommendations=[],
-            )
-
-    plugin = BranchingPlugin("codex", "Codex", [no_sessions, no_failures, no_actions])
-    analyzer = BranchingAnalyzer()
-
-    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
-    monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)
-    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)
-
-    result = runner.invoke(main, ["learn", "--agent", "codex", "--all"], catch_exceptions=False)
-
-    assert result.exit_code == 0, result.output
-    assert "No conversation data found." in result.output
-    assert "No failures or patterns found." in result.output
-    assert "No actionable patterns found." in result.output
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import click
+import click.shell_completion as click_shell_completion
+import pytest
+from click.testing import CliRunner
+
+from headroom.cli.learn import _AgentChoice
+from headroom.cli.main import main
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    return CliRunner()
+
+
+class FakeWriter:
+    def __init__(self) -> None:
+        self.calls: list[tuple[list[object], object, bool]] = []
+
+    def write(self, recommendations, project, dry_run: bool):  # noqa: ANN001, ANN201
+        self.calls.append((recommendations, project, dry_run))
+        return SimpleNamespace(
+            dry_run=dry_run,
+            content_by_file={
+                Path(project.project_path) / "AGENTS.md": "<!-- headroom -->\nRule 1\nRule 2"
+            },
+        )
+
+
+class FakePlugin:
+    def __init__(self, name: str, display_name: str, projects: list[object]) -> None:
+        self.name = name
+        self.display_name = display_name
+        self._projects = projects
+        self.writer = FakeWriter()
+        self.scan_calls: list[tuple[object, int]] = []
+
+    def detect(self) -> bool:
+        return True
+
+    def create_writer(self) -> FakeWriter:
+        return self.writer
+
+    def discover_projects(self) -> list[object]:
+        return self._projects
+
+    def scan_project(self, project, max_workers: int = 1):  # noqa: ANN001, ANN201
+        self.scan_calls.append((project, max_workers))
+        return [SimpleNamespace(events=["event"], tool_calls=[], failure_count=0)]
+
+
+class FakeAnalyzer:
+    def __init__(self, model: str | None = None) -> None:
+        self.model = model
+        self.calls: list[tuple[object, list[object]]] = []
+
+    def analyze(self, project, sessions):  # noqa: ANN001, ANN201
+        self.calls.append((project, sessions))
+        return SimpleNamespace(
+            total_sessions=len(sessions),
+            total_calls=3,
+            total_failures=1,
+            failure_rate=1 / 3,
+            recommendations=[SimpleNamespace(section="Rules")],
+        )
+
+
+def test_agent_choice_convert_and_shell_complete(monkeypatch: pytest.MonkeyPatch) -> None:
+    choice = _AgentChoice()
+    monkeypatch.setattr(click, "shell_completion", click_shell_completion)
+    monkeypatch.setattr(
+        "headroom.learn.registry.get_registry",
+        lambda: {"codex": object(), "claude": object()},
+    )
+    monkeypatch.setattr(
+        "headroom.learn.registry.available_agent_names",
+        lambda: ["claude", "codex"],
+    )
+
+    assert choice.convert("auto", None, None) == "auto"
+    assert choice.convert("CODEX", None, None) == "codex"
+    with pytest.raises(Exception, match="Unknown agent: bad"):
+        choice.convert("bad", None, None)
+
+    completions = choice.shell_complete(None, None, "c")  # type: ignore[arg-type]
+    assert [item.value for item in completions] == ["claude", "codex"]
+    assert choice.get_metavar(None) == "[auto|<agent>]"  # type: ignore[arg-type]
+
+
+def test_learn_exits_cleanly_when_model_detection_fails(
+    monkeypatch: pytest.MonkeyPatch, runner: CliRunner
+) -> None:
+    monkeypatch.setattr(
+        "headroom.learn.analyzer._detect_default_model",
+        lambda: (_ for _ in ()).throw(RuntimeError("no model")),
+    )
+
+    result = runner.invoke(main, ["learn"], catch_exceptions=False)
+
+    assert result.exit_code == 1
+    assert "Error: no model" in result.output
+
+
+def test_learn_auto_agent_reports_no_detected_plugins(
+    monkeypatch: pytest.MonkeyPatch, runner: CliRunner
+) -> None:
+    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
+    monkeypatch.setattr("headroom.learn.registry.auto_detect_plugins", lambda: [])
+    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)
+
+    result = runner.invoke(main, ["learn"], catch_exceptions=False)
+
+    assert result.exit_code == 0
+    assert "No coding agent data found." in result.output
+
+
+def test_learn_single_agent_shows_available_projects_when_cwd_missing(
+    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
+) -> None:
+    project = SimpleNamespace(name="demo", project_path=tmp_path / "demo")
+    plugin = FakePlugin("codex", "Codex", [project])
+
+    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
+    monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)
+    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)
+
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        result = runner.invoke(main, ["learn", "--agent", "codex"], catch_exceptions=False)
+
+    assert result.exit_code == 0
+    assert "No codex project data found for" in result.output
+    assert "Available codex projects:" in result.output
+    assert "demo" in result.output
+
+
+def test_learn_project_lookup_and_apply_flow(
+    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
+) -> None:
+    project_path = tmp_path / "project-a"
+    project_path.mkdir()
+    matched = SimpleNamespace(name="project-a", project_path=project_path)
+    unmatched = SimpleNamespace(name="project-b", project_path=tmp_path / "project-b")
+    plugin = FakePlugin("codex", "Codex", [matched, unmatched])
+    analyzer = FakeAnalyzer()
+
+    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
+    monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)
+    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)
+
+    result = runner.invoke(
+        main,
+        ["learn", "--agent", "codex", "--project", str(project_path), "--apply", "--workers", "4"],
+        catch_exceptions=False,
+    )
+
+    assert result.exit_code == 0, result.output
+    assert "Path: " in result.output
+    assert "Analyzing with gpt-4o..." in result.output
+    assert "Recommendations: 1" in result.output
+    assert "[WROTE]" in result.output
+    assert "Rule 1" in result.output
+    assert plugin.scan_calls == [(matched, 4)]
+    assert analyzer.calls[0][0] is matched
+    assert plugin.writer.calls[0][2] is False
+
+
+def test_learn_reports_missing_requested_project_and_lists_discovered(
+    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
+) -> None:
+    requested = tmp_path / "missing"
+    requested.mkdir()
+    discovered = SimpleNamespace(name="project-a", project_path=tmp_path / "project-a")
+    plugin = FakePlugin("claude", "Claude Code", [discovered])
+
+    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
+    monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)
+    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", FakeAnalyzer)
+
+    result = runner.invoke(
+        main,
+        ["learn", "--agent", "claude", "--project", str(requested)],
+        catch_exceptions=False,
+    )
+
+    assert result.exit_code == 0
+    assert f"No project data found for {requested.resolve()}" in result.output
+    assert "Available discovered projects:" in result.output
+    assert "[claude]" in result.output
+
+
+def test_learn_analyze_all_uses_default_workers_and_prints_summary(
+    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
+) -> None:
+    projects_a = [SimpleNamespace(name="a", project_path=tmp_path / "a")]
+    projects_b = [SimpleNamespace(name="b", project_path=tmp_path / "b")]
+    plugin_a = FakePlugin("codex", "Codex", projects_a)
+    plugin_b = FakePlugin("claude", "Claude Code", projects_b)
+    analyzer = FakeAnalyzer()
+
+    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
+    monkeypatch.setattr(
+        "headroom.learn.registry.auto_detect_plugins",
+        lambda: [plugin_a, plugin_b],
+    )
+    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)
+    monkeypatch.setattr("os.cpu_count", lambda: 12)
+
+    result = runner.invoke(main, ["learn", "--all"], catch_exceptions=False)
+
+    assert result.exit_code == 0, result.output
+    assert "Detected agents: Codex, Claude Code" in result.output
+    assert "Total: 2 projects, 2 failures, 2 recommendations" in result.output
+    assert plugin_a.scan_calls == [(projects_a[0], 8)]
+    assert plugin_b.scan_calls == [(projects_b[0], 8)]
+
+
+def test_learn_handles_empty_sessions_and_no_pattern_outputs(
+    monkeypatch: pytest.MonkeyPatch, runner: CliRunner, tmp_path: Path
+) -> None:
+    no_sessions = SimpleNamespace(name="empty", project_path=tmp_path / "empty")
+    no_failures = SimpleNamespace(name="clean", project_path=tmp_path / "clean")
+    no_actions = SimpleNamespace(name="no-actions", project_path=tmp_path / "no-actions")
+
+    class BranchingPlugin(FakePlugin):
+        def scan_project(self, project, max_workers: int = 1):  # noqa: ANN001, ANN201
+            self.scan_calls.append((project, max_workers))
+            if project is no_sessions:
+                return []
+            return [SimpleNamespace(events=["event"], tool_calls=[], failure_count=0)]
+
+    class BranchingAnalyzer(FakeAnalyzer):
+        def analyze(self, project, sessions):  # noqa: ANN001, ANN201
+            self.calls.append((project, sessions))
+            if project is no_failures:
+                return SimpleNamespace(
+                    total_sessions=1,
+                    total_calls=2,
+                    total_failures=0,
+                    failure_rate=0.0,
+                    recommendations=[],
+                )
+            return SimpleNamespace(
+                total_sessions=1,
+                total_calls=2,
+                total_failures=1,
+                failure_rate=0.5,
+                recommendations=[],
+            )
+
+    plugin = BranchingPlugin("codex", "Codex", [no_sessions, no_failures, no_actions])
+    analyzer = BranchingAnalyzer()
+
+    monkeypatch.setattr("headroom.learn.analyzer._detect_default_model", lambda: "gpt-4o")
+    monkeypatch.setattr("headroom.learn.registry.get_plugin", lambda name: plugin)
+    monkeypatch.setattr("headroom.learn.analyzer.SessionAnalyzer", lambda model=None: analyzer)
+
+    result = runner.invoke(main, ["learn", "--agent", "codex", "--all"], catch_exceptions=False)
+
+    assert result.exit_code == 0, result.output
+    assert "No conversation data found." in result.output
+    assert "No failures or patterns found." in result.output
+    assert "No actionable patterns found." in result.output
diff --git a/tests/test_codex_rate_limits.py b/tests/test_codex_rate_limits.py
index 58586e533f4ab2f354596a3b46f3bbcfd8e05e88..3da06d12bb9753ea19fbbb717081d7fcc2ffca50 100644
--- a/tests/test_codex_rate_limits.py
+++ b/tests/test_codex_rate_limits.py
@@ -1,227 +1,227 @@
-"""Unit tests for headroom.subscription.codex_rate_limits."""
-
-from __future__ import annotations
-
-import time
-
-from headroom.subscription.codex_rate_limits import (
-    CodexRateLimitState,
-    CodexRateLimitWindow,
-    parse_codex_rate_limits,
-)
-
-# ---------------------------------------------------------------------------
-# CodexRateLimitWindow helpers
-# ---------------------------------------------------------------------------
-
-
-class TestCodexRateLimitWindow:
-    def test_window_label_minutes(self):
-        w = CodexRateLimitWindow(used_percent=10.0, window_minutes=45)
-        assert w.window_label == "45m"
-
-    def test_window_label_hours(self):
-        w = CodexRateLimitWindow(used_percent=10.0, window_minutes=60)
-        assert w.window_label == "1h"
-
-    def test_window_label_hours_with_minutes(self):
-        w = CodexRateLimitWindow(used_percent=10.0, window_minutes=90)
-        assert w.window_label == "1h30m"
-
-    def test_window_label_unknown(self):
-        w = CodexRateLimitWindow(used_percent=10.0, window_minutes=None)
-        assert w.window_label == "unknown"
-
-    def test_seconds_until_reset_future(self):
-        future = int(time.time()) + 3600
-        w = CodexRateLimitWindow(used_percent=10.0, resets_at=future)
-        secs = w.seconds_until_reset
-        assert secs is not None
-        assert 3590 <= secs <= 3600
-
-    def test_seconds_until_reset_past(self):
-        past = int(time.time()) - 100
-        w = CodexRateLimitWindow(used_percent=10.0, resets_at=past)
-        assert w.seconds_until_reset == 0
-
-    def test_seconds_until_reset_none(self):
-        w = CodexRateLimitWindow(used_percent=10.0, resets_at=None)
-        assert w.seconds_until_reset is None
-
-    def test_to_dict_keys(self):
-        w = CodexRateLimitWindow(used_percent=42.5, window_minutes=60, resets_at=9999999)
-        d = w.to_dict()
-        assert set(d.keys()) == {
-            "used_percent",
-            "window_minutes",
-            "window_label",
-            "resets_at",
-            "seconds_until_reset",
-        }
-        assert d["used_percent"] == 42.5
-        assert d["window_label"] == "1h"
-
-
-# ---------------------------------------------------------------------------
-# parse_codex_rate_limits
-# ---------------------------------------------------------------------------
-
-
-class TestParseCodexRateLimits:
-    def test_returns_none_for_empty_headers(self):
-        assert parse_codex_rate_limits({}) is None
-
-    def test_returns_none_for_non_codex_headers(self):
-        headers = {"content-type": "application/json", "x-request-id": "abc"}
-        assert parse_codex_rate_limits(headers) is None
-
-    def test_parses_primary_window(self):
-        headers = {
-            "x-codex-primary-used-percent": "35.5",
-            "x-codex-primary-window-minutes": "60",
-            "x-codex-primary-reset-at": "1704069000",
-        }
-        snap = parse_codex_rate_limits(headers)
-        assert snap is not None
-        assert snap.limit_id == "codex"
-        assert snap.primary is not None
-        assert snap.primary.used_percent == 35.5
-        assert snap.primary.window_minutes == 60
-        assert snap.primary.resets_at == 1704069000
-        assert snap.secondary is None
-
-    def test_parses_secondary_window(self):
-        headers = {
-            "x-codex-primary-used-percent": "10.0",
-            "x-codex-secondary-used-percent": "80.0",
-            "x-codex-secondary-window-minutes": "1440",
-            "x-codex-secondary-reset-at": "1704100000",
-        }
-        snap = parse_codex_rate_limits(headers)
-        assert snap is not None
-        assert snap.secondary is not None
-        assert snap.secondary.used_percent == 80.0
-        assert snap.secondary.window_minutes == 1440
-
-    def test_parses_credits(self):
-        headers = {
-            "x-codex-primary-used-percent": "5.0",
-            "x-codex-credits-has-credits": "true",
-            "x-codex-credits-unlimited": "false",
-            "x-codex-credits-balance": "$12.50",
-        }
-        snap = parse_codex_rate_limits(headers)
-        assert snap is not None
-        assert snap.credits is not None
-        assert snap.credits.has_credits is True
-        assert snap.credits.unlimited is False
-        assert snap.credits.balance == "$12.50"
-
-    def test_parses_unlimited_credits(self):
-        headers = {
-            "x-codex-primary-used-percent": "0.0",
-            "x-codex-credits-has-credits": "true",
-            "x-codex-credits-unlimited": "true",
-        }
-        snap = parse_codex_rate_limits(headers)
-        assert snap is not None
-        assert snap.credits is not None
-        assert snap.credits.unlimited is True
-        assert snap.credits.balance is None
-
-    def test_parses_limit_name(self):
-        headers = {
-            "x-codex-primary-used-percent": "20.0",
-            "x-codex-limit-name": "gpt-5.2-codex-sonic",
-        }
-        snap = parse_codex_rate_limits(headers)
-        assert snap is not None
-        assert snap.limit_name == "gpt-5.2-codex-sonic"
-
-    def test_parses_promo_message(self):
-        headers = {
-            "x-codex-primary-used-percent": "50.0",
-            "x-codex-promo-message": "Try our new model!",
-        }
-        snap = parse_codex_rate_limits(headers)
-        assert snap is not None
-        assert snap.promo_message == "Try our new model!"
-
-    def test_only_credits_header_triggers_parse(self):
-        headers = {
-            "x-codex-credits-has-credits": "true",
-            "x-codex-credits-unlimited": "false",
-        }
-        snap = parse_codex_rate_limits(headers)
-        assert snap is not None
-        assert snap.primary is None
-        assert snap.credits is not None
-
-    def test_invalid_float_ignored(self):
-        headers = {"x-codex-primary-used-percent": "not_a_number"}
-        assert parse_codex_rate_limits(headers) is None
-
-    def test_to_dict_structure(self):
-        headers = {
-            "x-codex-primary-used-percent": "42.0",
-            "x-codex-primary-window-minutes": "60",
-        }
-        snap = parse_codex_rate_limits(headers)
-        assert snap is not None
-        d = snap.to_dict()
-        assert "limit_id" in d
-        assert "primary" in d
-        assert "secondary" in d
-        assert "credits" in d
-        assert "captured_at" in d
-
-
-# ---------------------------------------------------------------------------
-# CodexRateLimitState
-# ---------------------------------------------------------------------------
-
-
-class TestCodexRateLimitState:
-    def test_initial_state_is_none(self):
-        state = CodexRateLimitState()
-        assert state.latest is None
-        assert state.get_stats() is None
-
-    def test_update_from_headers_stores_snapshot(self):
-        state = CodexRateLimitState()
-        headers = {
-            "x-codex-primary-used-percent": "55.0",
-            "x-codex-primary-window-minutes": "60",
-        }
-        state.update_from_headers(headers)
-        snap = state.latest
-        assert snap is not None
-        assert snap.primary is not None
-        assert snap.primary.used_percent == 55.0
-
-    def test_update_from_empty_headers_is_noop(self):
-        state = CodexRateLimitState()
-        state.update_from_headers({})
-        assert state.latest is None
-
-    def test_update_from_non_codex_headers_is_noop(self):
-        state = CodexRateLimitState()
-        state.update_from_headers({"content-type": "application/json"})
-        assert state.latest is None
-
-    def test_get_stats_returns_dict_when_data_present(self):
-        state = CodexRateLimitState()
-        state.update_from_headers({"x-codex-primary-used-percent": "10.0"})
-        stats = state.get_stats()
-        assert stats is not None
-        assert isinstance(stats, dict)
-        assert stats["limit_id"] == "codex"
-
-    def test_update_overwrites_previous_snapshot(self):
-        state = CodexRateLimitState()
-        state.update_from_headers({"x-codex-primary-used-percent": "10.0"})
-        state.update_from_headers({"x-codex-primary-used-percent": "90.0"})
-        snap = state.latest
-        assert snap is not None
-        assert snap.primary is not None
-        assert snap.primary.used_percent == 90.0
+"""Unit tests for headroom.subscription.codex_rate_limits."""
+
+from __future__ import annotations
+
+import time
+
+from headroom.subscription.codex_rate_limits import (
+    CodexRateLimitState,
+    CodexRateLimitWindow,
+    parse_codex_rate_limits,
+)
+
+# ---------------------------------------------------------------------------
+# CodexRateLimitWindow helpers
+# ---------------------------------------------------------------------------
+
+
+class TestCodexRateLimitWindow:
+    def test_window_label_minutes(self):
+        w = CodexRateLimitWindow(used_percent=10.0, window_minutes=45)
+        assert w.window_label == "45m"
+
+    def test_window_label_hours(self):
+        w = CodexRateLimitWindow(used_percent=10.0, window_minutes=60)
+        assert w.window_label == "1h"
+
+    def test_window_label_hours_with_minutes(self):
+        w = CodexRateLimitWindow(used_percent=10.0, window_minutes=90)
+        assert w.window_label == "1h30m"
+
+    def test_window_label_unknown(self):
+        w = CodexRateLimitWindow(used_percent=10.0, window_minutes=None)
+        assert w.window_label == "unknown"
+
+    def test_seconds_until_reset_future(self):
+        future = int(time.time()) + 3600
+        w = CodexRateLimitWindow(used_percent=10.0, resets_at=future)
+        secs = w.seconds_until_reset
+        assert secs is not None
+        assert 3590 <= secs <= 3600
+
+    def test_seconds_until_reset_past(self):
+        past = int(time.time()) - 100
+        w = CodexRateLimitWindow(used_percent=10.0, resets_at=past)
+        assert w.seconds_until_reset == 0
+
+    def test_seconds_until_reset_none(self):
+        w = CodexRateLimitWindow(used_percent=10.0, resets_at=None)
+        assert w.seconds_until_reset is None
+
+    def test_to_dict_keys(self):
+        w = CodexRateLimitWindow(used_percent=42.5, window_minutes=60, resets_at=9999999)
+        d = w.to_dict()
+        assert set(d.keys()) == {
+            "used_percent",
+            "window_minutes",
+            "window_label",
+            "resets_at",
+            "seconds_until_reset",
+        }
+        assert d["used_percent"] == 42.5
+        assert d["window_label"] == "1h"
+
+
+# ---------------------------------------------------------------------------
+# parse_codex_rate_limits
+# ---------------------------------------------------------------------------
+
+
+class TestParseCodexRateLimits:
+    def test_returns_none_for_empty_headers(self):
+        assert parse_codex_rate_limits({}) is None
+
+    def test_returns_none_for_non_codex_headers(self):
+        headers = {"content-type": "application/json", "x-request-id": "abc"}
+        assert parse_codex_rate_limits(headers) is None
+
+    def test_parses_primary_window(self):
+        headers = {
+            "x-codex-primary-used-percent": "35.5",
+            "x-codex-primary-window-minutes": "60",
+            "x-codex-primary-reset-at": "1704069000",
+        }
+        snap = parse_codex_rate_limits(headers)
+        assert snap is not None
+        assert snap.limit_id == "codex"
+        assert snap.primary is not None
+        assert snap.primary.used_percent == 35.5
+        assert snap.primary.window_minutes == 60
+        assert snap.primary.resets_at == 1704069000
+        assert snap.secondary is None
+
+    def test_parses_secondary_window(self):
+        headers = {
+            "x-codex-primary-used-percent": "10.0",
+            "x-codex-secondary-used-percent": "80.0",
+            "x-codex-secondary-window-minutes": "1440",
+            "x-codex-secondary-reset-at": "1704100000",
+        }
+        snap = parse_codex_rate_limits(headers)
+        assert snap is not None
+        assert snap.secondary is not None
+        assert snap.secondary.used_percent == 80.0
+        assert snap.secondary.window_minutes == 1440
+
+    def test_parses_credits(self):
+        headers = {
+            "x-codex-primary-used-percent": "5.0",
+            "x-codex-credits-has-credits": "true",
+            "x-codex-credits-unlimited": "false",
+            "x-codex-credits-balance": "$12.50",
+        }
+        snap = parse_codex_rate_limits(headers)
+        assert snap is not None
+        assert snap.credits is not None
+        assert snap.credits.has_credits is True
+        assert snap.credits.unlimited is False
+        assert snap.credits.balance == "$12.50"
+
+    def test_parses_unlimited_credits(self):
+        headers = {
+            "x-codex-primary-used-percent": "0.0",
+            "x-codex-credits-has-credits": "true",
+            "x-codex-credits-unlimited": "true",
+        }
+        snap = parse_codex_rate_limits(headers)
+        assert snap is not None
+        assert snap.credits is not None
+        assert snap.credits.unlimited is True
+        assert snap.credits.balance is None
+
+    def test_parses_limit_name(self):
+        headers = {
+            "x-codex-primary-used-percent": "20.0",
+            "x-codex-limit-name": "gpt-5.2-codex-sonic",
+        }
+        snap = parse_codex_rate_limits(headers)
+        assert snap is not None
+        assert snap.limit_name == "gpt-5.2-codex-sonic"
+
+    def test_parses_promo_message(self):
+        headers = {
+            "x-codex-primary-used-percent": "50.0",
+            "x-codex-promo-message": "Try our new model!",
+        }
+        snap = parse_codex_rate_limits(headers)
+        assert snap is not None
+        assert snap.promo_message == "Try our new model!"
+
+    def test_only_credits_header_triggers_parse(self):
+        headers = {
+            "x-codex-credits-has-credits": "true",
+            "x-codex-credits-unlimited": "false",
+        }
+        snap = parse_codex_rate_limits(headers)
+        assert snap is not None
+        assert snap.primary is None
+        assert snap.credits is not None
+
+    def test_invalid_float_ignored(self):
+        headers = {"x-codex-primary-used-percent": "not_a_number"}
+        assert parse_codex_rate_limits(headers) is None
+
+    def test_to_dict_structure(self):
+        headers = {
+            "x-codex-primary-used-percent": "42.0",
+            "x-codex-primary-window-minutes": "60",
+        }
+        snap = parse_codex_rate_limits(headers)
+        assert snap is not None
+        d = snap.to_dict()
+        assert "limit_id" in d
+        assert "primary" in d
+        assert "secondary" in d
+        assert "credits" in d
+        assert "captured_at" in d
+
+
+# ---------------------------------------------------------------------------
+# CodexRateLimitState
+# ---------------------------------------------------------------------------
+
+
+class TestCodexRateLimitState:
+    def test_initial_state_is_none(self):
+        state = CodexRateLimitState()
+        assert state.latest is None
+        assert state.get_stats() is None
+
+    def test_update_from_headers_stores_snapshot(self):
+        state = CodexRateLimitState()
+        headers = {
+            "x-codex-primary-used-percent": "55.0",
+            "x-codex-primary-window-minutes": "60",
+        }
+        state.update_from_headers(headers)
+        snap = state.latest
+        assert snap is not None
+        assert snap.primary is not None
+        assert snap.primary.used_percent == 55.0
+
+    def test_update_from_empty_headers_is_noop(self):
+        state = CodexRateLimitState()
+        state.update_from_headers({})
+        assert state.latest is None
+
+    def test_update_from_non_codex_headers_is_noop(self):
+        state = CodexRateLimitState()
+        state.update_from_headers({"content-type": "application/json"})
+        assert state.latest is None
+
+    def test_get_stats_returns_dict_when_data_present(self):
+        state = CodexRateLimitState()
+        state.update_from_headers({"x-codex-primary-used-percent": "10.0"})
+        stats = state.get_stats()
+        assert stats is not None
+        assert isinstance(stats, dict)
+        assert stats["limit_id"] == "codex"
+
+    def test_update_overwrites_previous_snapshot(self):
+        state = CodexRateLimitState()
+        state.update_from_headers({"x-codex-primary-used-percent": "10.0"})
+        state.update_from_headers({"x-codex-primary-used-percent": "90.0"})
+        snap = state.latest
+        assert snap is not None
+        assert snap.primary is not None
+        assert snap.primary.used_percent == 90.0
diff --git a/tests/test_compress_api.py b/tests/test_compress_api.py
index 0ce8442434bf893645664109c8829a0f8dd6860a..7f9956b538be02653a346033da35bf15463a1873 100644
--- a/tests/test_compress_api.py
+++ b/tests/test_compress_api.py
@@ -1,274 +1,274 @@
-"""Tests for the one-function compress() API and integrations."""
-
-import json
-
-import pytest
-
-from headroom.compress import CompressResult, compress
-from headroom.hooks import CompressionHooks
-
-try:
-    from starlette.applications import Starlette
-    from starlette.requests import Request
-    from starlette.responses import JSONResponse
-    from starlette.routing import Route
-    from starlette.testclient import TestClient
-
-    from headroom.integrations.asgi import CompressionMiddleware
-
-    HAS_STARLETTE = True
-except ImportError:
-    HAS_STARLETTE = False
-
-
-# =============================================================================
-# Tests: compress() function
-# =============================================================================
-
-
-class TestCompressFunction:
-    def test_empty_messages(self):
-        result = compress([], model="test")
-        assert result.messages == []
-        assert result.tokens_saved == 0
-
-    def test_small_messages_passthrough(self):
-        """Small messages below compression threshold pass through unchanged."""
-        messages = [{"role": "user", "content": "hello"}]
-        result = compress(messages, model="gpt-4o")
-        assert result.messages[0]["content"] == "hello"
-        assert result.tokens_saved == 0
-
-    def test_returns_compress_result(self):
-        result = compress([{"role": "user", "content": "hi"}])
-        assert isinstance(result, CompressResult)
-        assert hasattr(result, "messages")
-        assert hasattr(result, "tokens_saved")
-        assert hasattr(result, "compression_ratio")
-        assert hasattr(result, "transforms_applied")
-
-    def test_large_tool_output_compressed(self):
-        """Large JSON tool output should be compressed."""
-        big_data = json.dumps(
-            [
-                {"id": i, "status": "active", "name": f"item_{i}", "value": i * 17}
-                for i in range(200)
-            ]
-        )
-        messages = [
-            {"role": "user", "content": "What are the top items?"},
-            {"role": "tool", "content": big_data, "tool_call_id": "call_1"},
-        ]
-        result = compress(messages, model="gpt-4o")
-        assert result.tokens_after <= result.tokens_before
-        assert len(result.messages) == 2
-
-    def test_compact_json_counts_tokens_not_whitespace(self):
-        """Compact JSON arrays should still compress under token thresholds."""
-        numbers = [42.0 + i * 0.1 for i in range(200)]
-        messages = [
-            {"role": "system", "content": "You are helpful."},
-            {"role": "user", "content": "Show metrics"},
-            {
-                "role": "assistant",
-                "content": None,
-                "tool_calls": [
-                    {
-                        "id": "call_1",
-                        "type": "function",
-                        "function": {"name": "get_metrics", "arguments": "{}"},
-                    }
-                ],
-            },
-            {"role": "tool", "tool_call_id": "call_1", "content": json.dumps(numbers)},
-        ]
-
-        result = compress(messages, min_tokens_to_compress=250)
-
-        assert result.tokens_saved > 0
-        assert any(
-            transform.startswith("router:smart_crusher") for transform in result.transforms_applied
-        )
-
-    def test_optimize_false_passthrough(self):
-        """optimize=False returns messages unchanged."""
-        messages = [{"role": "user", "content": "hello world " * 100}]
-        result = compress(messages, optimize=False)
-        assert result.messages is messages
-        assert result.tokens_saved == 0
-
-    def test_with_custom_hooks(self):
-        """Hooks are called when provided."""
-        calls = []
-
-        class TrackingHooks(CompressionHooks):
-            def pre_compress(self, messages, ctx):
-                calls.append(("pre", len(messages)))
-                return messages
-
-            def compute_biases(self, messages, ctx):
-                calls.append(("biases", len(messages)))
-                return {}
-
-            def post_compress(self, event):
-                calls.append(("post", event.tokens_saved))
-
-        big_data = json.dumps([{"id": i, "status": "active"} for i in range(100)])
-        messages = [
-            {"role": "user", "content": "analyze"},
-            {"role": "tool", "content": big_data, "tool_call_id": "c1"},
-        ]
-        compress(messages, hooks=TrackingHooks())
-
-        assert any(c[0] == "pre" for c in calls)
-        assert any(c[0] == "biases" for c in calls)
-
-
-class TestCompressResultFields:
-    def test_fields_populated(self):
-        big_data = json.dumps([{"id": i, "type": "log"} for i in range(100)])
-        messages = [
-            {"role": "user", "content": "summarize"},
-            {"role": "tool", "content": big_data, "tool_call_id": "c1"},
-        ]
-        result = compress(messages, model="claude-sonnet-4-5-20250929")
-        assert result.tokens_before > 0
-        assert result.tokens_after >= 0
-        assert result.tokens_saved >= 0
-        assert 0.0 <= result.compression_ratio <= 1.0
-
-
-# =============================================================================
-# Tests: ASGI CompressionMiddleware (requires starlette)
-# =============================================================================
-
-
-def _make_asgi_app(middleware_kwargs=None):
-    """Create a test ASGI app with CompressionMiddleware."""
-
-    async def chat_endpoint(request: Request) -> JSONResponse:
-        body = await request.json()
-        return JSONResponse(
-            {
-                "model": "gpt-4o",
-                "choices": [{"message": {"content": "response"}}],
-                "usage": {"prompt_tokens": 10, "completion_tokens": 5},
-                "_message_count": len(body.get("messages", [])),
-            }
-        )
-
-    async def health(request: Request) -> JSONResponse:
-        return JSONResponse({"status": "ok"})
-
-    app = Starlette(
-        routes=[
-            Route("/health", health),
-            Route("/v1/chat/completions", chat_endpoint, methods=["POST"]),
-            Route("/v1/messages", chat_endpoint, methods=["POST"]),
-        ]
-    )
-    app.add_middleware(CompressionMiddleware, **(middleware_kwargs or {}))
-    return app
-
-
-@pytest.mark.skipif(not HAS_STARLETTE, reason="starlette not installed")
-class TestASGIMiddleware:
-    def test_non_llm_paths_passthrough(self):
-        app = _make_asgi_app()
-        client = TestClient(app)
-        resp = client.get("/health")
-        assert resp.status_code == 200
-        assert resp.json()["status"] == "ok"
-
-    def test_small_messages_passthrough(self):
-        app = _make_asgi_app()
-        client = TestClient(app)
-        resp = client.post(
-            "/v1/chat/completions",
-            json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]},
-        )
-        assert resp.status_code == 200
-
-    def test_large_messages_compressed(self):
-        """Large tool output should be compressed by middleware."""
-        app = _make_asgi_app()
-        client = TestClient(app)
-
-        big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])
-        resp = client.post(
-            "/v1/chat/completions",
-            json={
-                "model": "gpt-4o",
-                "messages": [
-                    {"role": "user", "content": "analyze"},
-                    {"role": "tool", "content": big_data, "tool_call_id": "c1"},
-                ],
-            },
-        )
-        assert resp.status_code == 200
-
-    def test_anthropic_path(self):
-        """Works with Anthropic /v1/messages path."""
-        app = _make_asgi_app()
-        client = TestClient(app)
-        resp = client.post(
-            "/v1/messages",
-            json={
-                "model": "claude-sonnet-4-5-20250929",
-                "messages": [{"role": "user", "content": "hello"}],
-            },
-        )
-        assert resp.status_code == 200
-
-    def test_get_requests_passthrough(self):
-        """GET requests to LLM paths pass through."""
-        app = _make_asgi_app()
-        client = TestClient(app)
-        resp = client.get("/v1/chat/completions")
-        assert resp.status_code in (200, 405)
-
-
-# =============================================================================
-# Tests: LiteLLM Callback
-# =============================================================================
-
-
-class TestLiteLLMCallback:
-    def test_callback_imports(self):
-        """Verify the callback can be imported."""
-        from headroom.integrations.litellm_callback import HeadroomCallback
-
-        callback = HeadroomCallback()
-        assert callback.total_tokens_saved == 0
-
-    def test_callback_compresses_messages(self):
-        """Callback compresses messages in pre_call_hook."""
-        import asyncio
-
-        from headroom.integrations.litellm_callback import HeadroomCallback
-
-        callback = HeadroomCallback()
-
-        big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])
-        data = {
-            "model": "gpt-4o",
-            "messages": [
-                {"role": "user", "content": "analyze"},
-                {"role": "tool", "content": big_data, "tool_call_id": "c1"},
-            ],
-        }
-
-        result = asyncio.run(callback.async_pre_call_hook("key", data, "completion"))
-        assert result is data
-
-    def test_callback_ignores_non_completion(self):
-        """Non-completion calls are passed through."""
-        import asyncio
-
-        from headroom.integrations.litellm_callback import HeadroomCallback
-
-        callback = HeadroomCallback()
-        data = {"messages": [{"role": "user", "content": "hi"}]}
-
-        result = asyncio.run(callback.async_pre_call_hook("key", data, "embedding"))
-        assert result is data
+"""Tests for the one-function compress() API and integrations."""
+
+import json
+
+import pytest
+
+from headroom.compress import CompressResult, compress
+from headroom.hooks import CompressionHooks
+
+try:
+    from starlette.applications import Starlette
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse
+    from starlette.routing import Route
+    from starlette.testclient import TestClient
+
+    from headroom.integrations.asgi import CompressionMiddleware
+
+    HAS_STARLETTE = True
+except ImportError:
+    HAS_STARLETTE = False
+
+
+# =============================================================================
+# Tests: compress() function
+# =============================================================================
+
+
+class TestCompressFunction:
+    def test_empty_messages(self):
+        result = compress([], model="test")
+        assert result.messages == []
+        assert result.tokens_saved == 0
+
+    def test_small_messages_passthrough(self):
+        """Small messages below compression threshold pass through unchanged."""
+        messages = [{"role": "user", "content": "hello"}]
+        result = compress(messages, model="gpt-4o")
+        assert result.messages[0]["content"] == "hello"
+        assert result.tokens_saved == 0
+
+    def test_returns_compress_result(self):
+        result = compress([{"role": "user", "content": "hi"}])
+        assert isinstance(result, CompressResult)
+        assert hasattr(result, "messages")
+        assert hasattr(result, "tokens_saved")
+        assert hasattr(result, "compression_ratio")
+        assert hasattr(result, "transforms_applied")
+
+    def test_large_tool_output_compressed(self):
+        """Large JSON tool output should be compressed."""
+        big_data = json.dumps(
+            [
+                {"id": i, "status": "active", "name": f"item_{i}", "value": i * 17}
+                for i in range(200)
+            ]
+        )
+        messages = [
+            {"role": "user", "content": "What are the top items?"},
+            {"role": "tool", "content": big_data, "tool_call_id": "call_1"},
+        ]
+        result = compress(messages, model="gpt-4o")
+        assert result.tokens_after <= result.tokens_before
+        assert len(result.messages) == 2
+
+    def test_compact_json_counts_tokens_not_whitespace(self):
+        """Compact JSON arrays should still compress under token thresholds."""
+        numbers = [42.0 + i * 0.1 for i in range(200)]
+        messages = [
+            {"role": "system", "content": "You are helpful."},
+            {"role": "user", "content": "Show metrics"},
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "get_metrics", "arguments": "{}"},
+                    }
+                ],
+            },
+            {"role": "tool", "tool_call_id": "call_1", "content": json.dumps(numbers)},
+        ]
+
+        result = compress(messages, min_tokens_to_compress=250)
+
+        assert result.tokens_saved > 0
+        assert any(
+            transform.startswith("router:smart_crusher") for transform in result.transforms_applied
+        )
+
+    def test_optimize_false_passthrough(self):
+        """optimize=False returns messages unchanged."""
+        messages = [{"role": "user", "content": "hello world " * 100}]
+        result = compress(messages, optimize=False)
+        assert result.messages is messages
+        assert result.tokens_saved == 0
+
+    def test_with_custom_hooks(self):
+        """Hooks are called when provided."""
+        calls = []
+
+        class TrackingHooks(CompressionHooks):
+            def pre_compress(self, messages, ctx):
+                calls.append(("pre", len(messages)))
+                return messages
+
+            def compute_biases(self, messages, ctx):
+                calls.append(("biases", len(messages)))
+                return {}
+
+            def post_compress(self, event):
+                calls.append(("post", event.tokens_saved))
+
+        big_data = json.dumps([{"id": i, "status": "active"} for i in range(100)])
+        messages = [
+            {"role": "user", "content": "analyze"},
+            {"role": "tool", "content": big_data, "tool_call_id": "c1"},
+        ]
+        compress(messages, hooks=TrackingHooks())
+
+        assert any(c[0] == "pre" for c in calls)
+        assert any(c[0] == "biases" for c in calls)
+
+
+class TestCompressResultFields:
+    def test_fields_populated(self):
+        big_data = json.dumps([{"id": i, "type": "log"} for i in range(100)])
+        messages = [
+            {"role": "user", "content": "summarize"},
+            {"role": "tool", "content": big_data, "tool_call_id": "c1"},
+        ]
+        result = compress(messages, model="claude-sonnet-4-5-20250929")
+        assert result.tokens_before > 0
+        assert result.tokens_after >= 0
+        assert result.tokens_saved >= 0
+        assert 0.0 <= result.compression_ratio <= 1.0
+
+
+# =============================================================================
+# Tests: ASGI CompressionMiddleware (requires starlette)
+# =============================================================================
+
+
+def _make_asgi_app(middleware_kwargs=None):
+    """Create a test ASGI app with CompressionMiddleware."""
+
+    async def chat_endpoint(request: Request) -> JSONResponse:
+        body = await request.json()
+        return JSONResponse(
+            {
+                "model": "gpt-4o",
+                "choices": [{"message": {"content": "response"}}],
+                "usage": {"prompt_tokens": 10, "completion_tokens": 5},
+                "_message_count": len(body.get("messages", [])),
+            }
+        )
+
+    async def health(request: Request) -> JSONResponse:
+        return JSONResponse({"status": "ok"})
+
+    app = Starlette(
+        routes=[
+            Route("/health", health),
+            Route("/v1/chat/completions", chat_endpoint, methods=["POST"]),
+            Route("/v1/messages", chat_endpoint, methods=["POST"]),
+        ]
+    )
+    app.add_middleware(CompressionMiddleware, **(middleware_kwargs or {}))
+    return app
+
+
+@pytest.mark.skipif(not HAS_STARLETTE, reason="starlette not installed")
+class TestASGIMiddleware:
+    def test_non_llm_paths_passthrough(self):
+        app = _make_asgi_app()
+        client = TestClient(app)
+        resp = client.get("/health")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"
+
+    def test_small_messages_passthrough(self):
+        app = _make_asgi_app()
+        client = TestClient(app)
+        resp = client.post(
+            "/v1/chat/completions",
+            json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]},
+        )
+        assert resp.status_code == 200
+
+    def test_large_messages_compressed(self):
+        """Large tool output should be compressed by middleware."""
+        app = _make_asgi_app()
+        client = TestClient(app)
+
+        big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])
+        resp = client.post(
+            "/v1/chat/completions",
+            json={
+                "model": "gpt-4o",
+                "messages": [
+                    {"role": "user", "content": "analyze"},
+                    {"role": "tool", "content": big_data, "tool_call_id": "c1"},
+                ],
+            },
+        )
+        assert resp.status_code == 200
+
+    def test_anthropic_path(self):
+        """Works with Anthropic /v1/messages path."""
+        app = _make_asgi_app()
+        client = TestClient(app)
+        resp = client.post(
+            "/v1/messages",
+            json={
+                "model": "claude-sonnet-4-5-20250929",
+                "messages": [{"role": "user", "content": "hello"}],
+            },
+        )
+        assert resp.status_code == 200
+
+    def test_get_requests_passthrough(self):
+        """GET requests to LLM paths pass through."""
+        app = _make_asgi_app()
+        client = TestClient(app)
+        resp = client.get("/v1/chat/completions")
+        assert resp.status_code in (200, 405)
+
+
+# =============================================================================
+# Tests: LiteLLM Callback
+# =============================================================================
+
+
+class TestLiteLLMCallback:
+    def test_callback_imports(self):
+        """Verify the callback can be imported."""
+        from headroom.integrations.litellm_callback import HeadroomCallback
+
+        callback = HeadroomCallback()
+        assert callback.total_tokens_saved == 0
+
+    def test_callback_compresses_messages(self):
+        """Callback compresses messages in pre_call_hook."""
+        import asyncio
+
+        from headroom.integrations.litellm_callback import HeadroomCallback
+
+        callback = HeadroomCallback()
+
+        big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])
+        data = {
+            "model": "gpt-4o",
+            "messages": [
+                {"role": "user", "content": "analyze"},
+                {"role": "tool", "content": big_data, "tool_call_id": "c1"},
+            ],
+        }
+
+        result = asyncio.run(callback.async_pre_call_hook("key", data, "completion"))
+        assert result is data
+
+    def test_callback_ignores_non_completion(self):
+        """Non-completion calls are passed through."""
+        import asyncio
+
+        from headroom.integrations.litellm_callback import HeadroomCallback
+
+        callback = HeadroomCallback()
+        data = {"messages": [{"role": "user", "content": "hi"}]}
+
+        result = asyncio.run(callback.async_pre_call_hook("key", data, "embedding"))
+        assert result is data
diff --git a/tests/test_compress_failure.py b/tests/test_compress_failure.py
index 985bfddbd631ac80dfa488ac4f822f2ccd5ceb1e..be510c9877c54732430808814fc69fa130dd6b59 100644
--- a/tests/test_compress_failure.py
+++ b/tests/test_compress_failure.py
@@ -1,39 +1,39 @@
-from __future__ import annotations
-
-import importlib
-from types import SimpleNamespace
-
-from headroom.compress import compress
-
-
-class _FailingPipeline:
-    def apply(self, **kwargs):  # noqa: ANN003, ANN201
-        raise RuntimeError("boom")
-
-
-def test_compress_returns_original_messages_when_pipeline_fails(monkeypatch) -> None:
-    metrics: list[dict[str, str]] = []
-    compress_module = importlib.import_module("headroom.compress")
-    monkeypatch.setattr(compress_module, "_get_pipeline", lambda: _FailingPipeline())
-    monkeypatch.setattr(
-        compress_module,
-        "get_otel_metrics",
-        lambda: SimpleNamespace(
-            record_compression_failure=lambda **kwargs: metrics.append(kwargs),
-        ),
-    )
-
-    messages = [{"role": "user", "content": "hello world " * 100}]
-    result = compress(messages, model="gpt-4o")
-
-    assert result.messages == messages
-    assert result.tokens_before == 0
-    assert result.tokens_after == 0
-    assert result.tokens_saved == 0
-    assert metrics == [
-        {
-            "model": "gpt-4o",
-            "operation": "compress",
-            "error_type": "RuntimeError",
-        }
-    ]
+from __future__ import annotations
+
+import importlib
+from types import SimpleNamespace
+
+from headroom.compress import compress
+
+
+class _FailingPipeline:
+    def apply(self, **kwargs):  # noqa: ANN003, ANN201
+        raise RuntimeError("boom")
+
+
+def test_compress_returns_original_messages_when_pipeline_fails(monkeypatch) -> None:
+    metrics: list[dict[str, str]] = []
+    compress_module = importlib.import_module("headroom.compress")
+    monkeypatch.setattr(compress_module, "_get_pipeline", lambda: _FailingPipeline())
+    monkeypatch.setattr(
+        compress_module,
+        "get_otel_metrics",
+        lambda: SimpleNamespace(
+            record_compression_failure=lambda **kwargs: metrics.append(kwargs),
+        ),
+    )
+
+    messages = [{"role": "user", "content": "hello world " * 100}]
+    result = compress(messages, model="gpt-4o")
+
+    assert result.messages == messages
+    assert result.tokens_before == 0
+    assert result.tokens_after == 0
+    assert result.tokens_saved == 0
+    assert metrics == [
+        {
+            "model": "gpt-4o",
+            "operation": "compress",
+            "error_type": "RuntimeError",
+        }
+    ]
diff --git a/tests/test_copilot_quota.py b/tests/test_copilot_quota.py
index 7ec51ab8adaa6e6ee6f376f60572f2fd75a113b3..09c97420b956f5c831875c9fed5b831c42b1c608 100644
--- a/tests/test_copilot_quota.py
+++ b/tests/test_copilot_quota.py
@@ -1,331 +1,331 @@
-"""Unit tests for headroom.subscription.copilot_quota."""
-
-from __future__ import annotations
-
-import time
-
-import pytest
-
-from headroom.subscription.copilot_quota import (
-    CopilotQuotaCategory,
-    CopilotQuotaSnapshot,
-    discover_github_token,
-    parse_copilot_quota,
-)
-
-# ---------------------------------------------------------------------------
-# CopilotQuotaCategory helpers
-# ---------------------------------------------------------------------------
-
-
-class TestCopilotQuotaCategory:
-    def test_used_computed_from_entitlement_and_remaining(self):
-        cat = CopilotQuotaCategory(name="chat", entitlement=300, remaining=120)
-        assert cat.used == 180
-
-    def test_used_percent_computed(self):
-        cat = CopilotQuotaCategory(name="chat", entitlement=100, remaining=25)
-        assert cat.used_percent == pytest.approx(75.0)
-
-    def test_used_percent_from_percent_remaining(self):
-        cat = CopilotQuotaCategory(name="completions", percent_remaining=40.0)
-        assert cat.used_percent == pytest.approx(60.0)
-
-    def test_unlimited_used_percent_is_zero(self):
-        cat = CopilotQuotaCategory(name="premium_interactions", unlimited=True)
-        assert cat.used_percent == 0.0
-
-    def test_used_none_when_entitlement_missing(self):
-        cat = CopilotQuotaCategory(name="chat", remaining=50)
-        assert cat.used is None
-
-    def test_to_dict_keys(self):
-        cat = CopilotQuotaCategory(
-            name="chat",
-            entitlement=100,
-            remaining=60,
-            percent_remaining=60.0,
-            overage_count=2,
-            overage_permitted=True,
-            unlimited=False,
-            timestamp_utc="2025-01-01T00:00:00Z",
-        )
-        d = cat.to_dict()
-        assert d["name"] == "chat"
-        assert d["entitlement"] == 100
-        assert d["remaining"] == 60
-        assert d["used"] == 40
-        assert d["used_percent"] == pytest.approx(40.0)
-        assert d["overage_count"] == 2
-        assert d["overage_permitted"] is True
-        assert d["unlimited"] is False
-
-    def test_used_percent_clipped_at_zero(self):
-        # percent_remaining > 100 should not produce negative used_percent
-        cat = CopilotQuotaCategory(name="chat", percent_remaining=110.0)
-        assert cat.used_percent == pytest.approx(0.0)
-
-
-# ---------------------------------------------------------------------------
-# parse_copilot_quota
-# ---------------------------------------------------------------------------
-
-
-_SAMPLE_RESPONSE = {
-    "login": "octocat",
-    "copilot_plan": "individual",
-    "access_type_sku": "copilot_for_individuals",
-    "quota_reset_date_utc": "2025-02-01",
-    "quota_snapshots": {
-        "chat": {
-            "entitlement": 50,
-            "remaining": 30,
-            "quota_remaining": 30,
-            "percent_remaining": 60.0,
-            "overage_count": 0,
-            "overage_permitted": False,
-            "unlimited": False,
-            "timestamp_utc": "2025-01-15T10:00:00Z",
-        },
-        "completions": {
-            "entitlement": 2000,
-            "remaining": 1500,
-            "percent_remaining": 75.0,
-            "overage_count": 0,
-            "overage_permitted": True,
-            "unlimited": False,
-            "timestamp_utc": "2025-01-15T10:00:00Z",
-        },
-        "premium_interactions": {
-            "entitlement": 300,
-            "remaining": 298,
-            "percent_remaining": 99.3,
-            "overage_count": 2,
-            "overage_permitted": True,
-            "unlimited": False,
-            "timestamp_utc": "2025-01-15T10:00:00Z",
-        },
-    },
-}
-
-
-class TestParseCopilotQuota:
-    def test_basic_fields(self):
-        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
-        assert snap.login == "octocat"
-        assert snap.copilot_plan == "individual"
-        assert snap.access_type_sku == "copilot_for_individuals"
-        assert snap.quota_reset_date_utc == "2025-02-01"
-
-    def test_all_categories_parsed(self):
-        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
-        assert set(snap.categories.keys()) == {"chat", "completions", "premium_interactions"}
-
-    def test_chat_category(self):
-        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
-        chat = snap.categories["chat"]
-        assert chat.entitlement == 50
-        assert chat.remaining == 30
-        assert chat.percent_remaining == pytest.approx(60.0)
-        assert chat.unlimited is False
-        assert chat.overage_count == 0
-
-    def test_premium_interactions_overage(self):
-        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
-        prem = snap.categories["premium_interactions"]
-        assert prem.overage_count == 2
-        assert prem.overage_permitted is True
-
-    def test_quota_remaining_alias(self):
-        """quota_remaining should be used when remaining is absent."""
-        data = {
-            "quota_snapshots": {
-                "chat": {
-                    "entitlement": 100,
-                    "quota_remaining": 75,
-                }
-            }
-        }
-        snap = parse_copilot_quota(data)
-        assert snap.categories["chat"].remaining == 75
-
-    def test_unlimited_category(self):
-        data = {"quota_snapshots": {"completions": {"unlimited": True}}}
-        snap = parse_copilot_quota(data)
-        assert snap.categories["completions"].unlimited is True
-
-    def test_empty_quota_snapshots(self):
-        snap = parse_copilot_quota({"login": "ghost"})
-        assert snap.login == "ghost"
-        assert snap.categories == {}
-
-    def test_quota_reset_date_fallback(self):
-        data = {"quota_reset_date": "2025-03-01"}
-        snap = parse_copilot_quota(data)
-        assert snap.quota_reset_date_utc == "2025-03-01"
-
-    def test_fetched_at_is_recent(self):
-        before = time.time()
-        snap = parse_copilot_quota({})
-        after = time.time()
-        assert before <= snap.fetched_at <= after
-
-    def test_to_dict_structure(self):
-        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
-        d = snap.to_dict()
-        assert "login" in d
-        assert "categories" in d
-        assert "chat" in d["categories"]
-        assert "used_percent" in d["categories"]["chat"]
-
-    def test_missing_categories_skipped(self):
-        data = {
-            "quota_snapshots": {
-                "chat": {"remaining": 10},
-                # completions and premium_interactions absent
-            }
-        }
-        snap = parse_copilot_quota(data)
-        assert "chat" in snap.categories
-        assert "completions" not in snap.categories
-        assert "premium_interactions" not in snap.categories
-
-    def test_free_plan(self):
-        data = {"copilot_plan": "free", "quota_snapshots": {}}
-        snap = parse_copilot_quota(data)
-        assert snap.copilot_plan == "free"
-
-
-# ---------------------------------------------------------------------------
-# discover_github_token
-# ---------------------------------------------------------------------------
-
-
-class TestDiscoverGithubToken:
-    def test_returns_none_when_no_env_vars(self, monkeypatch):
-        for var in [
-            "GITHUB_COPILOT_GITHUB_TOKEN",
-            "GITHUB_TOKEN",
-            "COPILOT_GITHUB_TOKEN",
-            "GITHUB_COPILOT_API_TOKEN",
-        ]:
-            monkeypatch.delenv(var, raising=False)
-        assert discover_github_token() is None
-
-    def test_picks_up_github_token(self, monkeypatch):
-        for var in [
-            "GITHUB_COPILOT_GITHUB_TOKEN",
-            "GITHUB_TOKEN",
-            "COPILOT_GITHUB_TOKEN",
-            "GITHUB_COPILOT_API_TOKEN",
-        ]:
-            monkeypatch.delenv(var, raising=False)
-        monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken123")
-        assert discover_github_token() == "ghp_testtoken123"
-
-    def test_prefers_copilot_specific_token(self, monkeypatch):
-        for var in [
-            "GITHUB_COPILOT_GITHUB_TOKEN",
-            "GITHUB_TOKEN",
-            "COPILOT_GITHUB_TOKEN",
-            "GITHUB_COPILOT_API_TOKEN",
-        ]:
-            monkeypatch.delenv(var, raising=False)
-        monkeypatch.setenv("GITHUB_COPILOT_GITHUB_TOKEN", "ghp_copilot_specific")
-        monkeypatch.setenv("GITHUB_TOKEN", "ghp_generic")
-        assert discover_github_token() == "ghp_copilot_specific"
-
-    def test_falls_through_to_next_env_var(self, monkeypatch):
-        for var in [
-            "GITHUB_COPILOT_GITHUB_TOKEN",
-            "GITHUB_TOKEN",
-            "COPILOT_GITHUB_TOKEN",
-            "GITHUB_COPILOT_API_TOKEN",
-        ]:
-            monkeypatch.delenv(var, raising=False)
-        monkeypatch.setenv("COPILOT_GITHUB_TOKEN", "ghp_copilot")
-        assert discover_github_token() == "ghp_copilot"
-
-    def test_ignores_empty_strings(self, monkeypatch):
-        for var in [
-            "GITHUB_COPILOT_GITHUB_TOKEN",
-            "GITHUB_TOKEN",
-            "COPILOT_GITHUB_TOKEN",
-            "GITHUB_COPILOT_API_TOKEN",
-        ]:
-            monkeypatch.delenv(var, raising=False)
-        monkeypatch.setenv("GITHUB_COPILOT_GITHUB_TOKEN", "")
-        monkeypatch.setenv("GITHUB_TOKEN", "ghp_valid")
-        assert discover_github_token() == "ghp_valid"
-
-
-# ---------------------------------------------------------------------------
-# CopilotQuotaSnapshot.to_dict
-# ---------------------------------------------------------------------------
-
-
-class TestCopilotQuotaSnapshot:
-    def test_to_dict_complete(self):
-        snap = CopilotQuotaSnapshot(
-            login="user1",
-            copilot_plan="business",
-            access_type_sku="copilot_enterprise",
-            quota_reset_date_utc="2025-02-01",
-        )
-        snap.categories["chat"] = CopilotQuotaCategory(name="chat", entitlement=50, remaining=25)
-        d = snap.to_dict()
-        assert d["login"] == "user1"
-        assert d["copilot_plan"] == "business"
-        assert "chat" in d["categories"]
-        assert d["categories"]["chat"]["entitlement"] == 50
-
-
-# ---------------------------------------------------------------------------
-# Poll-loop task-leak regression
-# ---------------------------------------------------------------------------
-
-
-class TestCopilotQuotaPollLoopLeak:
-    @pytest.mark.asyncio
-    async def test_poll_loop_does_not_leak_event_wait_tasks(self, monkeypatch):
-        """Regression for the ``asyncio.shield(event.wait())`` pattern.
-
-        Matches the equivalent guard in ``tests/test_subscription_tracker.py``:
-        every poll interval the loop previously leaked one Event.wait
-        waiter because ``asyncio.shield`` prevented ``wait_for`` from
-        cancelling the inner wait on timeout.
-        """
-        import asyncio
-
-        from headroom.subscription.copilot_quota import _CopilotQuotaTracker
-
-        # No token configured → _maybe_poll returns immediately each cycle.
-        for var in ("GITHUB_COPILOT_GITHUB_TOKEN", "GITHUB_TOKEN"):
-            monkeypatch.delenv(var, raising=False)
-
-        tracker = _CopilotQuotaTracker(poll_interval_s=0.05)
-
-        def _count_event_wait() -> int:
-            return sum(
-                1
-                for t in asyncio.all_tasks()
-                if (t.get_coro().__qualname__ if t.get_coro() else "") == "Event.wait"
-            )
-
-        baseline = _count_event_wait()
-        await tracker.start()
-        try:
-            await asyncio.sleep(0.3)  # ~6 poll cycles
-            peak = _count_event_wait()
-        finally:
-            await tracker.stop()
-
-        await asyncio.sleep(0.05)
-        residual = _count_event_wait()
-
-        assert peak - baseline <= 1, (
-            f"CopilotQuotaTracker leaked Event.wait: baseline={baseline} peak={peak}"
-        )
-        assert residual <= baseline, (
-            f"CopilotQuotaTracker left residual Event.wait: baseline={baseline} residual={residual}"
-        )
+"""Unit tests for headroom.subscription.copilot_quota."""
+
+from __future__ import annotations
+
+import time
+
+import pytest
+
+from headroom.subscription.copilot_quota import (
+    CopilotQuotaCategory,
+    CopilotQuotaSnapshot,
+    discover_github_token,
+    parse_copilot_quota,
+)
+
+# ---------------------------------------------------------------------------
+# CopilotQuotaCategory helpers
+# ---------------------------------------------------------------------------
+
+
+class TestCopilotQuotaCategory:
+    def test_used_computed_from_entitlement_and_remaining(self):
+        cat = CopilotQuotaCategory(name="chat", entitlement=300, remaining=120)
+        assert cat.used == 180
+
+    def test_used_percent_computed(self):
+        cat = CopilotQuotaCategory(name="chat", entitlement=100, remaining=25)
+        assert cat.used_percent == pytest.approx(75.0)
+
+    def test_used_percent_from_percent_remaining(self):
+        cat = CopilotQuotaCategory(name="completions", percent_remaining=40.0)
+        assert cat.used_percent == pytest.approx(60.0)
+
+    def test_unlimited_used_percent_is_zero(self):
+        cat = CopilotQuotaCategory(name="premium_interactions", unlimited=True)
+        assert cat.used_percent == 0.0
+
+    def test_used_none_when_entitlement_missing(self):
+        cat = CopilotQuotaCategory(name="chat", remaining=50)
+        assert cat.used is None
+
+    def test_to_dict_keys(self):
+        cat = CopilotQuotaCategory(
+            name="chat",
+            entitlement=100,
+            remaining=60,
+            percent_remaining=60.0,
+            overage_count=2,
+            overage_permitted=True,
+            unlimited=False,
+            timestamp_utc="2025-01-01T00:00:00Z",
+        )
+        d = cat.to_dict()
+        assert d["name"] == "chat"
+        assert d["entitlement"] == 100
+        assert d["remaining"] == 60
+        assert d["used"] == 40
+        assert d["used_percent"] == pytest.approx(40.0)
+        assert d["overage_count"] == 2
+        assert d["overage_permitted"] is True
+        assert d["unlimited"] is False
+
+    def test_used_percent_clipped_at_zero(self):
+        # percent_remaining > 100 should not produce negative used_percent
+        cat = CopilotQuotaCategory(name="chat", percent_remaining=110.0)
+        assert cat.used_percent == pytest.approx(0.0)
+
+
+# ---------------------------------------------------------------------------
+# parse_copilot_quota
+# ---------------------------------------------------------------------------
+
+
+_SAMPLE_RESPONSE = {
+    "login": "octocat",
+    "copilot_plan": "individual",
+    "access_type_sku": "copilot_for_individuals",
+    "quota_reset_date_utc": "2025-02-01",
+    "quota_snapshots": {
+        "chat": {
+            "entitlement": 50,
+            "remaining": 30,
+            "quota_remaining": 30,
+            "percent_remaining": 60.0,
+            "overage_count": 0,
+            "overage_permitted": False,
+            "unlimited": False,
+            "timestamp_utc": "2025-01-15T10:00:00Z",
+        },
+        "completions": {
+            "entitlement": 2000,
+            "remaining": 1500,
+            "percent_remaining": 75.0,
+            "overage_count": 0,
+            "overage_permitted": True,
+            "unlimited": False,
+            "timestamp_utc": "2025-01-15T10:00:00Z",
+        },
+        "premium_interactions": {
+            "entitlement": 300,
+            "remaining": 298,
+            "percent_remaining": 99.3,
+            "overage_count": 2,
+            "overage_permitted": True,
+            "unlimited": False,
+            "timestamp_utc": "2025-01-15T10:00:00Z",
+        },
+    },
+}
+
+
+class TestParseCopilotQuota:
+    def test_basic_fields(self):
+        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
+        assert snap.login == "octocat"
+        assert snap.copilot_plan == "individual"
+        assert snap.access_type_sku == "copilot_for_individuals"
+        assert snap.quota_reset_date_utc == "2025-02-01"
+
+    def test_all_categories_parsed(self):
+        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
+        assert set(snap.categories.keys()) == {"chat", "completions", "premium_interactions"}
+
+    def test_chat_category(self):
+        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
+        chat = snap.categories["chat"]
+        assert chat.entitlement == 50
+        assert chat.remaining == 30
+        assert chat.percent_remaining == pytest.approx(60.0)
+        assert chat.unlimited is False
+        assert chat.overage_count == 0
+
+    def test_premium_interactions_overage(self):
+        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
+        prem = snap.categories["premium_interactions"]
+        assert prem.overage_count == 2
+        assert prem.overage_permitted is True
+
+    def test_quota_remaining_alias(self):
+        """quota_remaining should be used when remaining is absent."""
+        data = {
+            "quota_snapshots": {
+                "chat": {
+                    "entitlement": 100,
+                    "quota_remaining": 75,
+                }
+            }
+        }
+        snap = parse_copilot_quota(data)
+        assert snap.categories["chat"].remaining == 75
+
+    def test_unlimited_category(self):
+        data = {"quota_snapshots": {"completions": {"unlimited": True}}}
+        snap = parse_copilot_quota(data)
+        assert snap.categories["completions"].unlimited is True
+
+    def test_empty_quota_snapshots(self):
+        snap = parse_copilot_quota({"login": "ghost"})
+        assert snap.login == "ghost"
+        assert snap.categories == {}
+
+    def test_quota_reset_date_fallback(self):
+        data = {"quota_reset_date": "2025-03-01"}
+        snap = parse_copilot_quota(data)
+        assert snap.quota_reset_date_utc == "2025-03-01"
+
+    def test_fetched_at_is_recent(self):
+        before = time.time()
+        snap = parse_copilot_quota({})
+        after = time.time()
+        assert before <= snap.fetched_at <= after
+
+    def test_to_dict_structure(self):
+        snap = parse_copilot_quota(_SAMPLE_RESPONSE)
+        d = snap.to_dict()
+        assert "login" in d
+        assert "categories" in d
+        assert "chat" in d["categories"]
+        assert "used_percent" in d["categories"]["chat"]
+
+    def test_missing_categories_skipped(self):
+        data = {
+            "quota_snapshots": {
+                "chat": {"remaining": 10},
+                # completions and premium_interactions absent
+            }
+        }
+        snap = parse_copilot_quota(data)
+        assert "chat" in snap.categories
+        assert "completions" not in snap.categories
+        assert "premium_interactions" not in snap.categories
+
+    def test_free_plan(self):
+        data = {"copilot_plan": "free", "quota_snapshots": {}}
+        snap = parse_copilot_quota(data)
+        assert snap.copilot_plan == "free"
+
+
+# ---------------------------------------------------------------------------
+# discover_github_token
+# ---------------------------------------------------------------------------
+
+
+class TestDiscoverGithubToken:
+    def test_returns_none_when_no_env_vars(self, monkeypatch):
+        for var in [
+            "GITHUB_COPILOT_GITHUB_TOKEN",
+            "GITHUB_TOKEN",
+            "COPILOT_GITHUB_TOKEN",
+            "GITHUB_COPILOT_API_TOKEN",
+        ]:
+            monkeypatch.delenv(var, raising=False)
+        assert discover_github_token() is None
+
+    def test_picks_up_github_token(self, monkeypatch):
+        for var in [
+            "GITHUB_COPILOT_GITHUB_TOKEN",
+            "GITHUB_TOKEN",
+            "COPILOT_GITHUB_TOKEN",
+            "GITHUB_COPILOT_API_TOKEN",
+        ]:
+            monkeypatch.delenv(var, raising=False)
+        monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken123")
+        assert discover_github_token() == "ghp_testtoken123"
+
+    def test_prefers_copilot_specific_token(self, monkeypatch):
+        for var in [
+            "GITHUB_COPILOT_GITHUB_TOKEN",
+            "GITHUB_TOKEN",
+            "COPILOT_GITHUB_TOKEN",
+            "GITHUB_COPILOT_API_TOKEN",
+        ]:
+            monkeypatch.delenv(var, raising=False)
+        monkeypatch.setenv("GITHUB_COPILOT_GITHUB_TOKEN", "ghp_copilot_specific")
+        monkeypatch.setenv("GITHUB_TOKEN", "ghp_generic")
+        assert discover_github_token() == "ghp_copilot_specific"
+
+    def test_falls_through_to_next_env_var(self, monkeypatch):
+        for var in [
+            "GITHUB_COPILOT_GITHUB_TOKEN",
+            "GITHUB_TOKEN",
+            "COPILOT_GITHUB_TOKEN",
+            "GITHUB_COPILOT_API_TOKEN",
+        ]:
+            monkeypatch.delenv(var, raising=False)
+        monkeypatch.setenv("COPILOT_GITHUB_TOKEN", "ghp_copilot")
+        assert discover_github_token() == "ghp_copilot"
+
+    def test_ignores_empty_strings(self, monkeypatch):
+        for var in [
+            "GITHUB_COPILOT_GITHUB_TOKEN",
+            "GITHUB_TOKEN",
+            "COPILOT_GITHUB_TOKEN",
+            "GITHUB_COPILOT_API_TOKEN",
+        ]:
+            monkeypatch.delenv(var, raising=False)
+        monkeypatch.setenv("GITHUB_COPILOT_GITHUB_TOKEN", "")
+        monkeypatch.setenv("GITHUB_TOKEN", "ghp_valid")
+        assert discover_github_token() == "ghp_valid"
+
+
+# ---------------------------------------------------------------------------
+# CopilotQuotaSnapshot.to_dict
+# ---------------------------------------------------------------------------
+
+
+class TestCopilotQuotaSnapshot:
+    def test_to_dict_complete(self):
+        snap = CopilotQuotaSnapshot(
+            login="user1",
+            copilot_plan="business",
+            access_type_sku="copilot_enterprise",
+            quota_reset_date_utc="2025-02-01",
+        )
+        snap.categories["chat"] = CopilotQuotaCategory(name="chat", entitlement=50, remaining=25)
+        d = snap.to_dict()
+        assert d["login"] == "user1"
+        assert d["copilot_plan"] == "business"
+        assert "chat" in d["categories"]
+        assert d["categories"]["chat"]["entitlement"] == 50
+
+
+# ---------------------------------------------------------------------------
+# Poll-loop task-leak regression
+# ---------------------------------------------------------------------------
+
+
+class TestCopilotQuotaPollLoopLeak:
+    @pytest.mark.asyncio
+    async def test_poll_loop_does_not_leak_event_wait_tasks(self, monkeypatch):
+        """Regression for the ``asyncio.shield(event.wait())`` pattern.
+
+        Matches the equivalent guard in ``tests/test_subscription_tracker.py``:
+        every poll interval the loop previously leaked one Event.wait
+        waiter because ``asyncio.shield`` prevented ``wait_for`` from
+        cancelling the inner wait on timeout.
+        """
+        import asyncio
+
+        from headroom.subscription.copilot_quota import _CopilotQuotaTracker
+
+        # No token configured → _maybe_poll returns immediately each cycle.
+        for var in ("GITHUB_COPILOT_GITHUB_TOKEN", "GITHUB_TOKEN"):
+            monkeypatch.delenv(var, raising=False)
+
+        tracker = _CopilotQuotaTracker(poll_interval_s=0.05)
+
+        def _count_event_wait() -> int:
+            return sum(
+                1
+                for t in asyncio.all_tasks()
+                if (t.get_coro().__qualname__ if t.get_coro() else "") == "Event.wait"
+            )
+
+        baseline = _count_event_wait()
+        await tracker.start()
+        try:
+            await asyncio.sleep(0.3)  # ~6 poll cycles
+            peak = _count_event_wait()
+        finally:
+            await tracker.stop()
+
+        await asyncio.sleep(0.05)
+        residual = _count_event_wait()
+
+        assert peak - baseline <= 1, (
+            f"CopilotQuotaTracker leaked Event.wait: baseline={baseline} peak={peak}"
+        )
+        assert residual <= baseline, (
+            f"CopilotQuotaTracker left residual Event.wait: baseline={baseline} residual={residual}"
+        )
diff --git a/tests/test_evals_datasets.py b/tests/test_evals_datasets.py
index 74dbfd849440c752b06aa1873825299cc05822ab..9f116f36543a4fec3f1c2d0ffe12f7c74b3edc8e 100644
--- a/tests/test_evals_datasets.py
+++ b/tests/test_evals_datasets.py
@@ -1,538 +1,538 @@
-from __future__ import annotations
-
-import json
-import sys
-import urllib.request
-from types import SimpleNamespace
-from urllib.error import URLError
-
-import pytest
-
-from headroom.evals import datasets
-
-
-def install_fake_datasets(
-    monkeypatch: pytest.MonkeyPatch,
-    mapping: dict[tuple[str, str | None, str | None], list[dict[str, object]]],
-) -> list[tuple[str, str | None, str | None]]:
-    calls: list[tuple[str, str | None, str | None]] = []
-
-    def fake_load_dataset(name: str, subset: str | None = None, split: str | None = None):
-        key = (name, subset, split)
-        calls.append(key)
-        return mapping[key]
-
-    monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))
-    return calls
-
-
-def test_check_datasets_installed_errors_without_dependency(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.delitem(sys.modules, "datasets", raising=False)
-
-    import builtins
-
-    real_import = builtins.__import__
-
-    def fake_import(name, globals=None, locals=None, fromlist=(), level=0):  # noqa: ANN001
-        if name == "datasets":
-            raise ImportError("missing")
-        return real_import(name, globals, locals, fromlist, level)
-
-    monkeypatch.setattr(builtins, "__import__", fake_import)
-
-    with pytest.raises(ImportError, match="HuggingFace datasets required"):
-        datasets._check_datasets_installed()
-
-
-def test_load_hotpotqa_and_natural_questions(monkeypatch: pytest.MonkeyPatch) -> None:
-    calls = install_fake_datasets(
-        monkeypatch,
-        {
-            ("hotpotqa/hotpot_qa", "fullwiki", "validation"): [
-                {
-                    "context": {"title": ["Page A"], "sentences": [["Line 1", "Line 2"]]},
-                    "question": "Who?",
-                    "answer": "Alice",
-                    "type": "bridge",
-                    "level": "easy",
-                }
-            ],
-            ("google-research-datasets/natural_questions", "default", "validation"): [
-                {"document": {}, "question": {"text": "skip me"}},
-                {
-                    "document": {
-                        "tokens": {
-                            "token": ["<p>", "Ada", "Lovelace", "wrote", "notes"],
-                            "is_html": [True, False, False, False, False],
-                        }
-                    },
-                    "question": {"text": "Who wrote notes?"},
-                    "annotations": {"short_answers": [[{"start_token": 1, "end_token": 3}]]},
-                },
-            ],
-        },
-    )
-
-    hotpot = datasets.load_hotpotqa(n=1)
-    natural = datasets.load_natural_questions(n=1)
-
-    assert calls == [
-        ("hotpotqa/hotpot_qa", "fullwiki", "validation"),
-        ("google-research-datasets/natural_questions", "default", "validation"),
-    ]
-    assert hotpot.name == "HotpotQA"
-    assert hotpot.cases[0].context == "## Page A\nLine 1\nLine 2"
-    assert hotpot.cases[0].metadata["type"] == "bridge"
-    assert natural.name == "Natural_Questions"
-    assert natural.cases[0].context == "Ada Lovelace wrote notes"
-    assert natural.cases[0].ground_truth == "Ada Lovelace"
-
-
-def test_load_triviaqa_msmarco_and_squad(monkeypatch: pytest.MonkeyPatch) -> None:
-    install_fake_datasets(
-        monkeypatch,
-        {
-            ("trivia_qa", "rc", "validation"): [
-                {"question": "", "search_results": {"search_context": ["unused"]}},
-                {
-                    "question": "Question 1",
-                    "search_results": {"search_context": ["A", "B"]},
-                    "answer": {"value": "Answer", "aliases": ["Alias"]},
-                },
-                {
-                    "question": "Question 2",
-                    "search_results": {"search_context": []},
-                    "entity_pages": {"wiki_context": ["Wiki 1", "Wiki 2"]},
-                    "answer": {"normalized_value": "Normalized"},
-                },
-            ],
-            ("microsoft/ms_marco", "v2.1", "validation"): [
-                {"query": "", "passages": {"passage_text": ["skip"], "is_selected": [True]}},
-                {
-                    "query": "Find docs",
-                    "passages": {"passage_text": ["Doc 1", "Doc 2"], "is_selected": [True, False]},
-                    "answers": ["Primary answer"],
-                    "query_type": "description",
-                },
-            ],
-            ("rajpurkar/squad_v2", None, "validation"): [
-                {"answers": {"text": []}, "context": "skip", "question": "skip"},
-                {
-                    "context": "Context",
-                    "question": "Question",
-                    "answers": {"text": ["First answer"]},
-                    "title": "Title",
-                },
-            ],
-        },
-    )
-
-    trivia = datasets.load_triviaqa(n=2)
-    msmarco = datasets.load_msmarco(n=1)
-    squad = datasets.load_squad(n=1)
-
-    assert len(trivia.cases) == 2
-    assert trivia.cases[0].context == "A\n\nB"
-    assert trivia.cases[1].ground_truth == "Normalized"
-    assert trivia.cases[1].metadata["aliases"] == []
-    assert msmarco.cases[0].context.startswith("[RELEVANT] Passage 1: Doc 1")
-    assert msmarco.cases[0].metadata["num_passages"] == 2
-    assert squad.cases[0].ground_truth == "First answer"
-    assert squad.cases[0].metadata["title"] == "Title"
-
-
-def test_load_longbench_narrativeqa_toolbench_codesearchnet_and_humaneval(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    install_fake_datasets(
-        monkeypatch,
-        {
-            ("THUDM/LongBench", "qasper", "test"): [
-                {"context": "", "input": "skip"},
-                {"context": "Long context", "input": "Question", "answers": ["Truth"]},
-            ],
-            ("deepmind/narrativeqa", None, "test"): [
-                {
-                    "document": {"summary": {"text": "Story summary"}, "kind": "movie"},
-                    "question": {"text": "What happened?"},
-                    "answers": [{"text": "A"}, {"text": "B"}],
-                }
-            ],
-            ("ToolBench/ToolBench", "G1", "test"): [
-                {"api_list": [], "query": "skip"},
-                {
-                    "api_list": [
-                        {
-                            "api_name": "weather",
-                            "api_description": "Get weather",
-                            "required_parameters": [{"name": "city"}],
-                            "optional_parameters": [{"name": "unit"}],
-                        }
-                    ],
-                    "query": "Weather in SF?",
-                    "answer": "Call weather",
-                },
-            ],
-            ("code_search_net", "python", "test"): [
-                {"func_code_string": "", "func_documentation_string": "skip"},
-                {
-                    "func_code_string": "def add(a, b): return a + b",
-                    "func_documentation_string": "Add two numbers.",
-                    "func_name": "add",
-                    "repository_name": "repo",
-                },
-            ],
-            ("openai_humaneval", None, "test"): [
-                {"prompt": "", "canonical_solution": "skip"},
-                {
-                    "task_id": "HumanEval/1",
-                    "prompt": "def solve(x):",
-                    "canonical_solution": "return x",
-                    "entry_point": "solve",
-                    "test": "assert solve(1) == 1",
-                },
-            ],
-        },
-    )
-
-    longbench = datasets.load_longbench(n=2, task="qasper")
-    narrative = datasets.load_narrativeqa(n=1)
-    toolbench = datasets.load_toolbench(n=1, category="G1")
-    codesearchnet = datasets.load_codesearchnet(n=1, language="python")
-    humaneval = datasets.load_humaneval(n=2)
-
-    assert longbench.name == "LongBench_qasper"
-    assert longbench.cases[0].metadata["context_length"] == len("Long context")
-    assert narrative.cases[0].metadata["all_answers"] == ["A", "B"]
-    assert toolbench.cases[0].metadata["num_tools"] == 1
-    assert '"name": "weather"' in toolbench.cases[0].context
-    assert codesearchnet.cases[0].ground_truth == "Add two numbers."
-    assert humaneval.cases[0].id == "humaneval_HumanEval/1"
-    assert humaneval.cases[0].metadata["entry_point"] == "solve"
-
-
-def test_load_longbench_toolbench_and_codesearchnet_wrap_loader_errors(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    def fake_load_dataset(name: str, subset: str | None = None, split: str | None = None):  # noqa: ANN001
-        raise RuntimeError(f"broken {name}:{subset}:{split}")
-
-    monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))
-
-    with pytest.raises(ValueError, match="Failed to load LongBench task 'gov_report'"):
-        datasets.load_longbench(task="gov_report")
-    with pytest.raises(ValueError, match="Failed to load ToolBench category 'G2'"):
-        datasets.load_toolbench(category="G2")
-    with pytest.raises(ValueError, match="Failed to load CodeSearchNet for 'go'"):
-        datasets.load_codesearchnet(language="go")
-
-
-def test_load_bfcl_success_and_download_failure(monkeypatch: pytest.MonkeyPatch) -> None:
-    data_lines = "\n".join(
-        [
-            json.dumps(
-                {
-                    "id": "case-1",
-                    "question": [[{"role": "user", "content": "How is the weather?"}]],
-                    "function": [{"name": "weather"}],
-                }
-            ),
-            json.dumps({"question": [123], "function": []}),
-        ]
-    )
-    gt_lines = json.dumps({"id": "case-1", "ground_truth": [{"name": "weather"}]})
-
-    def fake_urlopen(url: str):  # noqa: ANN001
-        if "possible_answer/BFCL_v3_simple.json" in url:
-            return SimpleNamespace(read=lambda: gt_lines.encode("utf-8"))
-        if "BFCL_v3_simple.json" in url:
-            return SimpleNamespace(read=lambda: data_lines.encode("utf-8"))
-        raise URLError("missing")
-
-    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
-
-    suite = datasets.load_bfcl(n=2, category="simple")
-    assert suite.name == "BFCL_simple"
-    assert suite.cases[0].query == "How is the weather?"
-    assert suite.cases[0].ground_truth == '[{"name": "weather"}]'
-    assert suite.cases[0].metadata["num_functions"] == 1
-
-    def failing_urlopen(url: str):  # noqa: ANN001
-        raise URLError("offline")
-
-    monkeypatch.setattr(urllib.request, "urlopen", failing_urlopen)
-    with pytest.raises(ValueError, match="Failed to download BFCL dataset 'BFCL_v3_parallel.json'"):
-        datasets.load_bfcl(category="parallel")
-
-
-def test_tool_output_samples_custom_dataset_and_probe_generation(tmp_path) -> None:
-    tool_outputs = datasets.load_tool_output_samples()
-    assert tool_outputs.name == "ToolOutputSamples"
-    assert len(tool_outputs.cases) >= 8
-    assert tool_outputs.cases[0].ground_truth == "prompt-optimizer"
-
-    custom_path = tmp_path / "custom.jsonl"
-    custom_path.write_text(
-        json.dumps(
-            {"id": "case1", "context": "Context", "query": "Question", "ground_truth": "Answer"}
-        )
-        + "\n",
-        encoding="utf-8",
-    )
-    custom_suite = datasets.load_custom_dataset(custom_path)
-    assert custom_suite.cases[0].id == "case1"
-
-    probes = datasets.generate_retrieval_probes(
-        'Alice Smith deployed API on 2024-01-15 at 99.9% confidence for "Launch Ready" and build_id',
-        n_probes=5,
-    )
-    assert "Alice Smith" in probes
-    assert "2024-01-15" in probes
-    assert "API" in probes
-    assert "99.9" in probes
-    assert "Launch Ready" in probes
-
-
-def test_dataset_registry_helpers(monkeypatch: pytest.MonkeyPatch) -> None:
-    categories = datasets.list_available_datasets()
-    assert "hotpotqa" in categories["rag"]
-    assert "tool_outputs" in categories["tool_use"]
-
-    seen: list[tuple[str, dict[str, object]]] = []
-
-    def fake_loader(*, n: int = 0, **kwargs):  # noqa: ANN003
-        seen.append(("with-n", {"n": n, **kwargs}))
-        return "with-n-result"
-
-    def fixed_loader(**kwargs):  # noqa: ANN003
-        seen.append(("fixed", kwargs))
-        return "fixed-result"
-
-    original_registry = dict(datasets.DATASET_REGISTRY)
-    monkeypatch.setattr(
-        datasets,
-        "DATASET_REGISTRY",
-        {
-            **original_registry,
-            "fake_n": {"loader": fake_loader, "category": "x", "description": "", "default_n": 3},
-            "fake_fixed": {
-                "loader": fixed_loader,
-                "category": "x",
-                "description": "",
-                "default_n": None,
-            },
-        },
-    )
-
-    assert datasets.load_dataset_by_name("fake_n") == "with-n-result"
-    assert datasets.load_dataset_by_name("fake_n", n=7, split="test") == "with-n-result"
-    assert datasets.load_dataset_by_name("fake_fixed", path="x") == "fixed-result"
-    assert seen == [
-        ("with-n", {"n": 3}),
-        ("with-n", {"n": 7, "split": "test"}),
-        ("fixed", {"path": "x"}),
-    ]
-
-    with pytest.raises(ValueError, match="Unknown dataset 'missing'"):
-        datasets.load_dataset_by_name("missing")
-
-
-def test_dataset_loaders_cover_skip_and_limit_branches(monkeypatch: pytest.MonkeyPatch) -> None:
-    install_fake_datasets(
-        monkeypatch,
-        {
-            ("hotpotqa/hotpot_qa", "fullwiki", "validation"): [
-                {
-                    "context": {"title": ["Page A"], "sentences": [["Line 1"]]},
-                    "question": "Q1",
-                    "answer": "A1",
-                },
-                {
-                    "context": {"title": ["Page B"], "sentences": [["Line 2"]]},
-                    "question": "Q2",
-                    "answer": "A2",
-                },
-            ],
-            ("google-research-datasets/natural_questions", "default", "validation"): [
-                {
-                    "document": {"tokens": {"token": ["x"], "is_html": [False]}},
-                    "question": {"text": ""},
-                },
-                {
-                    "document": {"tokens": {"token": ["<b>"], "is_html": [True]}},
-                    "question": {"text": "blank context"},
-                },
-                {
-                    "document": {"tokens": {"token": ["Ada", "wrote"], "is_html": [False, False]}},
-                    "question": {"text": "Who?"},
-                    "annotations": {"short_answers": [[{"start_token": 1, "end_token": 1}]]},
-                },
-                {
-                    "document": {"tokens": {"token": ["Grace"], "is_html": [False]}},
-                    "question": {"text": "Ignored by limit"},
-                },
-            ],
-            ("trivia_qa", "rc", "validation"): [
-                {"question": "skip", "search_results": {"search_context": []}, "entity_pages": {}},
-                {"question": "blank", "search_results": {"search_context": [""]}},
-                {
-                    "question": "Good 1",
-                    "search_results": {"search_context": ["Context 1"]},
-                    "answer": {"value": "A1"},
-                },
-                {
-                    "question": "Good 2",
-                    "search_results": {"search_context": ["Context 2"]},
-                    "answer": {"value": "A2"},
-                },
-            ],
-            ("microsoft/ms_marco", "v2.1", "validation"): [
-                {"query": "skip", "passages": {"passage_text": [], "is_selected": []}},
-                {
-                    "query": "Find one",
-                    "passages": {"passage_text": ["Doc 1"], "is_selected": [False]},
-                    "answers": [],
-                },
-                {
-                    "query": "Find two",
-                    "passages": {"passage_text": ["Doc 2"], "is_selected": [True]},
-                    "answers": ["A2"],
-                },
-            ],
-            ("rajpurkar/squad_v2", None, "validation"): [
-                {
-                    "context": "Context 1",
-                    "question": "Q1",
-                    "answers": {"text": ["A1"]},
-                },
-                {
-                    "context": "Context 2",
-                    "question": "Q2",
-                    "answers": {"text": ["A2"]},
-                },
-            ],
-            ("THUDM/LongBench", "qasper", "test"): [
-                {"context": "Context 1", "input": "Q1", "answers": ["A1"]},
-                {"context": "Has context", "input": ""},
-                {"context": "Context 2", "input": "Q2", "answers": ["A2"]},
-            ],
-            ("deepmind/narrativeqa", None, "test"): [
-                {"document": {"summary": {"text": ""}}, "question": {"text": "skip"}},
-                {"document": {"summary": {"text": "Story"}}, "question": {"text": ""}},
-                {
-                    "document": {"summary": {"text": "Story 1"}, "kind": "book"},
-                    "question": {"text": "Q1"},
-                    "answers": [{"text": "A1"}],
-                },
-                {
-                    "document": {"summary": {"text": "Story 2"}, "kind": "movie"},
-                    "question": {"text": "Q2"},
-                    "answers": [{"text": "A2"}],
-                },
-            ],
-            ("ToolBench/ToolBench", "G1", "test"): [
-                {"api_list": [], "query": "skip"},
-                {
-                    "api_list": [
-                        {
-                            "api_name": "weather",
-                            "required_parameters": [],
-                            "optional_parameters": [],
-                        }
-                    ],
-                    "query": "",
-                },
-                {
-                    "api_list": [
-                        {"api_name": "calc", "required_parameters": [], "optional_parameters": []}
-                    ],
-                    "query": "Good",
-                },
-            ],
-            ("code_search_net", "python", "test"): [
-                {
-                    "func_code_string": "",
-                    "whole_func_string": "",
-                    "func_documentation_string": "skip",
-                },
-                {"whole_func_string": "def alt(): pass", "func_documentation_string": ""},
-                {
-                    "whole_func_string": "def good(): pass",
-                    "func_documentation_string": "Good doc",
-                    "func_name": "good",
-                    "repository_name": "repo",
-                },
-                {
-                    "whole_func_string": "def ignored(): pass",
-                    "func_documentation_string": "Ignored by limit",
-                },
-            ],
-            ("openai_humaneval", None, "test"): [
-                {
-                    "task_id": "Task/1",
-                    "prompt": "def solve():",
-                    "canonical_solution": "return 1",
-                    "test": "assert solve() == 1",
-                },
-                {
-                    "task_id": "Task/2",
-                    "prompt": "def other():",
-                    "canonical_solution": "return 2",
-                    "test": "assert other() == 2",
-                },
-            ],
-        },
-    )
-
-    assert len(datasets.load_hotpotqa(n=1).cases) == 1
-    natural = datasets.load_natural_questions(n=1)
-    assert len(natural.cases) == 1
-    assert natural.cases[0].ground_truth is None
-    assert len(datasets.load_triviaqa(n=1).cases) == 1
-    msmarco = datasets.load_msmarco(n=1)
-    assert len(msmarco.cases) == 1
-    assert msmarco.cases[0].ground_truth is None
-    assert len(datasets.load_squad(n=1).cases) == 1
-    assert len(datasets.load_longbench(n=2, task="qasper").cases) == 1
-    assert len(datasets.load_narrativeqa(n=1).cases) == 1
-    assert len(datasets.load_toolbench(n=1, category="G1").cases) == 1
-    assert len(datasets.load_codesearchnet(n=1, language="python").cases) == 1
-    assert len(datasets.load_humaneval(n=1).cases) == 1
-
-
-def test_load_bfcl_handles_optional_ground_truth_and_question_fallback(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    data_lines = "\n".join(
-        [
-            json.dumps(
-                {
-                    "id": "case-1",
-                    "question": [123],
-                    "function": [{"name": "weather"}],
-                }
-            ),
-            json.dumps({"id": "skip", "function": []}),
-            json.dumps(
-                {
-                    "id": "case-2",
-                    "question": [[{"role": "user", "content": "Ignored by limit"}]],
-                    "function": [{"name": "time"}],
-                }
-            ),
-        ]
-    )
-
-    def fake_urlopen(url: str):  # noqa: ANN001
-        if "possible_answer" in url:
-            raise URLError("missing ground truth")
-        return SimpleNamespace(read=lambda: data_lines.encode("utf-8"))
-
-    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
-
-    suite = datasets.load_bfcl(n=2, category="simple")
-    assert len(suite.cases) == 1
-    assert suite.cases[0].query == "[123]"
-    assert suite.cases[0].ground_truth is None
+from __future__ import annotations
+
+import json
+import sys
+import urllib.request
+from types import SimpleNamespace
+from urllib.error import URLError
+
+import pytest
+
+from headroom.evals import datasets
+
+
+def install_fake_datasets(
+    monkeypatch: pytest.MonkeyPatch,
+    mapping: dict[tuple[str, str | None, str | None], list[dict[str, object]]],
+) -> list[tuple[str, str | None, str | None]]:
+    calls: list[tuple[str, str | None, str | None]] = []
+
+    def fake_load_dataset(name: str, subset: str | None = None, split: str | None = None):
+        key = (name, subset, split)
+        calls.append(key)
+        return mapping[key]
+
+    monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))
+    return calls
+
+
+def test_check_datasets_installed_errors_without_dependency(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delitem(sys.modules, "datasets", raising=False)
+
+    import builtins
+
+    real_import = builtins.__import__
+
+    def fake_import(name, globals=None, locals=None, fromlist=(), level=0):  # noqa: ANN001
+        if name == "datasets":
+            raise ImportError("missing")
+        return real_import(name, globals, locals, fromlist, level)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    with pytest.raises(ImportError, match="HuggingFace datasets required"):
+        datasets._check_datasets_installed()
+
+
+def test_load_hotpotqa_and_natural_questions(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = install_fake_datasets(
+        monkeypatch,
+        {
+            ("hotpotqa/hotpot_qa", "fullwiki", "validation"): [
+                {
+                    "context": {"title": ["Page A"], "sentences": [["Line 1", "Line 2"]]},
+                    "question": "Who?",
+                    "answer": "Alice",
+                    "type": "bridge",
+                    "level": "easy",
+                }
+            ],
+            ("google-research-datasets/natural_questions", "default", "validation"): [
+                {"document": {}, "question": {"text": "skip me"}},
+                {
+                    "document": {
+                        "tokens": {
+                            "token": ["<p>", "Ada", "Lovelace", "wrote", "notes"],
+                            "is_html": [True, False, False, False, False],
+                        }
+                    },
+                    "question": {"text": "Who wrote notes?"},
+                    "annotations": {"short_answers": [[{"start_token": 1, "end_token": 3}]]},
+                },
+            ],
+        },
+    )
+
+    hotpot = datasets.load_hotpotqa(n=1)
+    natural = datasets.load_natural_questions(n=1)
+
+    assert calls == [
+        ("hotpotqa/hotpot_qa", "fullwiki", "validation"),
+        ("google-research-datasets/natural_questions", "default", "validation"),
+    ]
+    assert hotpot.name == "HotpotQA"
+    assert hotpot.cases[0].context == "## Page A\nLine 1\nLine 2"
+    assert hotpot.cases[0].metadata["type"] == "bridge"
+    assert natural.name == "Natural_Questions"
+    assert natural.cases[0].context == "Ada Lovelace wrote notes"
+    assert natural.cases[0].ground_truth == "Ada Lovelace"
+
+
+def test_load_triviaqa_msmarco_and_squad(monkeypatch: pytest.MonkeyPatch) -> None:
+    install_fake_datasets(
+        monkeypatch,
+        {
+            ("trivia_qa", "rc", "validation"): [
+                {"question": "", "search_results": {"search_context": ["unused"]}},
+                {
+                    "question": "Question 1",
+                    "search_results": {"search_context": ["A", "B"]},
+                    "answer": {"value": "Answer", "aliases": ["Alias"]},
+                },
+                {
+                    "question": "Question 2",
+                    "search_results": {"search_context": []},
+                    "entity_pages": {"wiki_context": ["Wiki 1", "Wiki 2"]},
+                    "answer": {"normalized_value": "Normalized"},
+                },
+            ],
+            ("microsoft/ms_marco", "v2.1", "validation"): [
+                {"query": "", "passages": {"passage_text": ["skip"], "is_selected": [True]}},
+                {
+                    "query": "Find docs",
+                    "passages": {"passage_text": ["Doc 1", "Doc 2"], "is_selected": [True, False]},
+                    "answers": ["Primary answer"],
+                    "query_type": "description",
+                },
+            ],
+            ("rajpurkar/squad_v2", None, "validation"): [
+                {"answers": {"text": []}, "context": "skip", "question": "skip"},
+                {
+                    "context": "Context",
+                    "question": "Question",
+                    "answers": {"text": ["First answer"]},
+                    "title": "Title",
+                },
+            ],
+        },
+    )
+
+    trivia = datasets.load_triviaqa(n=2)
+    msmarco = datasets.load_msmarco(n=1)
+    squad = datasets.load_squad(n=1)
+
+    assert len(trivia.cases) == 2
+    assert trivia.cases[0].context == "A\n\nB"
+    assert trivia.cases[1].ground_truth == "Normalized"
+    assert trivia.cases[1].metadata["aliases"] == []
+    assert msmarco.cases[0].context.startswith("[RELEVANT] Passage 1: Doc 1")
+    assert msmarco.cases[0].metadata["num_passages"] == 2
+    assert squad.cases[0].ground_truth == "First answer"
+    assert squad.cases[0].metadata["title"] == "Title"
+
+
+def test_load_longbench_narrativeqa_toolbench_codesearchnet_and_humaneval(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    install_fake_datasets(
+        monkeypatch,
+        {
+            ("THUDM/LongBench", "qasper", "test"): [
+                {"context": "", "input": "skip"},
+                {"context": "Long context", "input": "Question", "answers": ["Truth"]},
+            ],
+            ("deepmind/narrativeqa", None, "test"): [
+                {
+                    "document": {"summary": {"text": "Story summary"}, "kind": "movie"},
+                    "question": {"text": "What happened?"},
+                    "answers": [{"text": "A"}, {"text": "B"}],
+                }
+            ],
+            ("ToolBench/ToolBench", "G1", "test"): [
+                {"api_list": [], "query": "skip"},
+                {
+                    "api_list": [
+                        {
+                            "api_name": "weather",
+                            "api_description": "Get weather",
+                            "required_parameters": [{"name": "city"}],
+                            "optional_parameters": [{"name": "unit"}],
+                        }
+                    ],
+                    "query": "Weather in SF?",
+                    "answer": "Call weather",
+                },
+            ],
+            ("code_search_net", "python", "test"): [
+                {"func_code_string": "", "func_documentation_string": "skip"},
+                {
+                    "func_code_string": "def add(a, b): return a + b",
+                    "func_documentation_string": "Add two numbers.",
+                    "func_name": "add",
+                    "repository_name": "repo",
+                },
+            ],
+            ("openai_humaneval", None, "test"): [
+                {"prompt": "", "canonical_solution": "skip"},
+                {
+                    "task_id": "HumanEval/1",
+                    "prompt": "def solve(x):",
+                    "canonical_solution": "return x",
+                    "entry_point": "solve",
+                    "test": "assert solve(1) == 1",
+                },
+            ],
+        },
+    )
+
+    longbench = datasets.load_longbench(n=2, task="qasper")
+    narrative = datasets.load_narrativeqa(n=1)
+    toolbench = datasets.load_toolbench(n=1, category="G1")
+    codesearchnet = datasets.load_codesearchnet(n=1, language="python")
+    humaneval = datasets.load_humaneval(n=2)
+
+    assert longbench.name == "LongBench_qasper"
+    assert longbench.cases[0].metadata["context_length"] == len("Long context")
+    assert narrative.cases[0].metadata["all_answers"] == ["A", "B"]
+    assert toolbench.cases[0].metadata["num_tools"] == 1
+    assert '"name": "weather"' in toolbench.cases[0].context
+    assert codesearchnet.cases[0].ground_truth == "Add two numbers."
+    assert humaneval.cases[0].id == "humaneval_HumanEval/1"
+    assert humaneval.cases[0].metadata["entry_point"] == "solve"
+
+
+def test_load_longbench_toolbench_and_codesearchnet_wrap_loader_errors(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fake_load_dataset(name: str, subset: str | None = None, split: str | None = None):  # noqa: ANN001
+        raise RuntimeError(f"broken {name}:{subset}:{split}")
+
+    monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))
+
+    with pytest.raises(ValueError, match="Failed to load LongBench task 'gov_report'"):
+        datasets.load_longbench(task="gov_report")
+    with pytest.raises(ValueError, match="Failed to load ToolBench category 'G2'"):
+        datasets.load_toolbench(category="G2")
+    with pytest.raises(ValueError, match="Failed to load CodeSearchNet for 'go'"):
+        datasets.load_codesearchnet(language="go")
+
+
+def test_load_bfcl_success_and_download_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+    data_lines = "\n".join(
+        [
+            json.dumps(
+                {
+                    "id": "case-1",
+                    "question": [[{"role": "user", "content": "How is the weather?"}]],
+                    "function": [{"name": "weather"}],
+                }
+            ),
+            json.dumps({"question": [123], "function": []}),
+        ]
+    )
+    gt_lines = json.dumps({"id": "case-1", "ground_truth": [{"name": "weather"}]})
+
+    def fake_urlopen(url: str):  # noqa: ANN001
+        if "possible_answer/BFCL_v3_simple.json" in url:
+            return SimpleNamespace(read=lambda: gt_lines.encode("utf-8"))
+        if "BFCL_v3_simple.json" in url:
+            return SimpleNamespace(read=lambda: data_lines.encode("utf-8"))
+        raise URLError("missing")
+
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+
+    suite = datasets.load_bfcl(n=2, category="simple")
+    assert suite.name == "BFCL_simple"
+    assert suite.cases[0].query == "How is the weather?"
+    assert suite.cases[0].ground_truth == '[{"name": "weather"}]'
+    assert suite.cases[0].metadata["num_functions"] == 1
+
+    def failing_urlopen(url: str):  # noqa: ANN001
+        raise URLError("offline")
+
+    monkeypatch.setattr(urllib.request, "urlopen", failing_urlopen)
+    with pytest.raises(ValueError, match="Failed to download BFCL dataset 'BFCL_v3_parallel.json'"):
+        datasets.load_bfcl(category="parallel")
+
+
+def test_tool_output_samples_custom_dataset_and_probe_generation(tmp_path) -> None:
+    tool_outputs = datasets.load_tool_output_samples()
+    assert tool_outputs.name == "ToolOutputSamples"
+    assert len(tool_outputs.cases) >= 8
+    assert tool_outputs.cases[0].ground_truth == "prompt-optimizer"
+
+    custom_path = tmp_path / "custom.jsonl"
+    custom_path.write_text(
+        json.dumps(
+            {"id": "case1", "context": "Context", "query": "Question", "ground_truth": "Answer"}
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    custom_suite = datasets.load_custom_dataset(custom_path)
+    assert custom_suite.cases[0].id == "case1"
+
+    probes = datasets.generate_retrieval_probes(
+        'Alice Smith deployed API on 2024-01-15 at 99.9% confidence for "Launch Ready" and build_id',
+        n_probes=5,
+    )
+    assert "Alice Smith" in probes
+    assert "2024-01-15" in probes
+    assert "API" in probes
+    assert "99.9" in probes
+    assert "Launch Ready" in probes
+
+
+def test_dataset_registry_helpers(monkeypatch: pytest.MonkeyPatch) -> None:
+    categories = datasets.list_available_datasets()
+    assert "hotpotqa" in categories["rag"]
+    assert "tool_outputs" in categories["tool_use"]
+
+    seen: list[tuple[str, dict[str, object]]] = []
+
+    def fake_loader(*, n: int = 0, **kwargs):  # noqa: ANN003
+        seen.append(("with-n", {"n": n, **kwargs}))
+        return "with-n-result"
+
+    def fixed_loader(**kwargs):  # noqa: ANN003
+        seen.append(("fixed", kwargs))
+        return "fixed-result"
+
+    original_registry = dict(datasets.DATASET_REGISTRY)
+    monkeypatch.setattr(
+        datasets,
+        "DATASET_REGISTRY",
+        {
+            **original_registry,
+            "fake_n": {"loader": fake_loader, "category": "x", "description": "", "default_n": 3},
+            "fake_fixed": {
+                "loader": fixed_loader,
+                "category": "x",
+                "description": "",
+                "default_n": None,
+            },
+        },
+    )
+
+    assert datasets.load_dataset_by_name("fake_n") == "with-n-result"
+    assert datasets.load_dataset_by_name("fake_n", n=7, split="test") == "with-n-result"
+    assert datasets.load_dataset_by_name("fake_fixed", path="x") == "fixed-result"
+    assert seen == [
+        ("with-n", {"n": 3}),
+        ("with-n", {"n": 7, "split": "test"}),
+        ("fixed", {"path": "x"}),
+    ]
+
+    with pytest.raises(ValueError, match="Unknown dataset 'missing'"):
+        datasets.load_dataset_by_name("missing")
+
+
+def test_dataset_loaders_cover_skip_and_limit_branches(monkeypatch: pytest.MonkeyPatch) -> None:
+    install_fake_datasets(
+        monkeypatch,
+        {
+            ("hotpotqa/hotpot_qa", "fullwiki", "validation"): [
+                {
+                    "context": {"title": ["Page A"], "sentences": [["Line 1"]]},
+                    "question": "Q1",
+                    "answer": "A1",
+                },
+                {
+                    "context": {"title": ["Page B"], "sentences": [["Line 2"]]},
+                    "question": "Q2",
+                    "answer": "A2",
+                },
+            ],
+            ("google-research-datasets/natural_questions", "default", "validation"): [
+                {
+                    "document": {"tokens": {"token": ["x"], "is_html": [False]}},
+                    "question": {"text": ""},
+                },
+                {
+                    "document": {"tokens": {"token": ["<b>"], "is_html": [True]}},
+                    "question": {"text": "blank context"},
+                },
+                {
+                    "document": {"tokens": {"token": ["Ada", "wrote"], "is_html": [False, False]}},
+                    "question": {"text": "Who?"},
+                    "annotations": {"short_answers": [[{"start_token": 1, "end_token": 1}]]},
+                },
+                {
+                    "document": {"tokens": {"token": ["Grace"], "is_html": [False]}},
+                    "question": {"text": "Ignored by limit"},
+                },
+            ],
+            ("trivia_qa", "rc", "validation"): [
+                {"question": "skip", "search_results": {"search_context": []}, "entity_pages": {}},
+                {"question": "blank", "search_results": {"search_context": [""]}},
+                {
+                    "question": "Good 1",
+                    "search_results": {"search_context": ["Context 1"]},
+                    "answer": {"value": "A1"},
+                },
+                {
+                    "question": "Good 2",
+                    "search_results": {"search_context": ["Context 2"]},
+                    "answer": {"value": "A2"},
+                },
+            ],
+            ("microsoft/ms_marco", "v2.1", "validation"): [
+                {"query": "skip", "passages": {"passage_text": [], "is_selected": []}},
+                {
+                    "query": "Find one",
+                    "passages": {"passage_text": ["Doc 1"], "is_selected": [False]},
+                    "answers": [],
+                },
+                {
+                    "query": "Find two",
+                    "passages": {"passage_text": ["Doc 2"], "is_selected": [True]},
+                    "answers": ["A2"],
+                },
+            ],
+            ("rajpurkar/squad_v2", None, "validation"): [
+                {
+                    "context": "Context 1",
+                    "question": "Q1",
+                    "answers": {"text": ["A1"]},
+                },
+                {
+                    "context": "Context 2",
+                    "question": "Q2",
+                    "answers": {"text": ["A2"]},
+                },
+            ],
+            ("THUDM/LongBench", "qasper", "test"): [
+                {"context": "Context 1", "input": "Q1", "answers": ["A1"]},
+                {"context": "Has context", "input": ""},
+                {"context": "Context 2", "input": "Q2", "answers": ["A2"]},
+            ],
+            ("deepmind/narrativeqa", None, "test"): [
+                {"document": {"summary": {"text": ""}}, "question": {"text": "skip"}},
+                {"document": {"summary": {"text": "Story"}}, "question": {"text": ""}},
+                {
+                    "document": {"summary": {"text": "Story 1"}, "kind": "book"},
+                    "question": {"text": "Q1"},
+                    "answers": [{"text": "A1"}],
+                },
+                {
+                    "document": {"summary": {"text": "Story 2"}, "kind": "movie"},
+                    "question": {"text": "Q2"},
+                    "answers": [{"text": "A2"}],
+                },
+            ],
+            ("ToolBench/ToolBench", "G1", "test"): [
+                {"api_list": [], "query": "skip"},
+                {
+                    "api_list": [
+                        {
+                            "api_name": "weather",
+                            "required_parameters": [],
+                            "optional_parameters": [],
+                        }
+                    ],
+                    "query": "",
+                },
+                {
+                    "api_list": [
+                        {"api_name": "calc", "required_parameters": [], "optional_parameters": []}
+                    ],
+                    "query": "Good",
+                },
+            ],
+            ("code_search_net", "python", "test"): [
+                {
+                    "func_code_string": "",
+                    "whole_func_string": "",
+                    "func_documentation_string": "skip",
+                },
+                {"whole_func_string": "def alt(): pass", "func_documentation_string": ""},
+                {
+                    "whole_func_string": "def good(): pass",
+                    "func_documentation_string": "Good doc",
+                    "func_name": "good",
+                    "repository_name": "repo",
+                },
+                {
+                    "whole_func_string": "def ignored(): pass",
+                    "func_documentation_string": "Ignored by limit",
+                },
+            ],
+            ("openai_humaneval", None, "test"): [
+                {
+                    "task_id": "Task/1",
+                    "prompt": "def solve():",
+                    "canonical_solution": "return 1",
+                    "test": "assert solve() == 1",
+                },
+                {
+                    "task_id": "Task/2",
+                    "prompt": "def other():",
+                    "canonical_solution": "return 2",
+                    "test": "assert other() == 2",
+                },
+            ],
+        },
+    )
+
+    assert len(datasets.load_hotpotqa(n=1).cases) == 1
+    natural = datasets.load_natural_questions(n=1)
+    assert len(natural.cases) == 1
+    assert natural.cases[0].ground_truth is None
+    assert len(datasets.load_triviaqa(n=1).cases) == 1
+    msmarco = datasets.load_msmarco(n=1)
+    assert len(msmarco.cases) == 1
+    assert msmarco.cases[0].ground_truth is None
+    assert len(datasets.load_squad(n=1).cases) == 1
+    assert len(datasets.load_longbench(n=2, task="qasper").cases) == 1
+    assert len(datasets.load_narrativeqa(n=1).cases) == 1
+    assert len(datasets.load_toolbench(n=1, category="G1").cases) == 1
+    assert len(datasets.load_codesearchnet(n=1, language="python").cases) == 1
+    assert len(datasets.load_humaneval(n=1).cases) == 1
+
+
+def test_load_bfcl_handles_optional_ground_truth_and_question_fallback(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    data_lines = "\n".join(
+        [
+            json.dumps(
+                {
+                    "id": "case-1",
+                    "question": [123],
+                    "function": [{"name": "weather"}],
+                }
+            ),
+            json.dumps({"id": "skip", "function": []}),
+            json.dumps(
+                {
+                    "id": "case-2",
+                    "question": [[{"role": "user", "content": "Ignored by limit"}]],
+                    "function": [{"name": "time"}],
+                }
+            ),
+        ]
+    )
+
+    def fake_urlopen(url: str):  # noqa: ANN001
+        if "possible_answer" in url:
+            raise URLError("missing ground truth")
+        return SimpleNamespace(read=lambda: data_lines.encode("utf-8"))
+
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+
+    suite = datasets.load_bfcl(n=2, category="simple")
+    assert len(suite.cases) == 1
+    assert suite.cases[0].query == "[123]"
+    assert suite.cases[0].ground_truth is None
diff --git a/tests/test_evals_metrics.py b/tests/test_evals_metrics.py
index 8406be8ee28fb46a41c20ce81d8efbc62e155a42..371e369515d2e4bf55d9a83867acb7d742eb2cf9 100644
--- a/tests/test_evals_metrics.py
+++ b/tests/test_evals_metrics.py
@@ -1,132 +1,132 @@
-from __future__ import annotations
-
-import math
-import sys
-from types import SimpleNamespace
-
-import pytest
-
-from headroom.evals import metrics
-
-
-def test_normalize_tokenize_and_exact_match() -> None:
-    assert metrics.normalize_text("  Hello,\nWORLD  ") == "hello, world"
-    assert metrics.tokenize("Hello, world! API_v2") == ["hello", "world", "api_v2"]
-    assert metrics.compute_exact_match(" Hello World ", "hello\nworld") is True
-    assert metrics.compute_exact_match("hello", "world") is False
-
-
-def test_f1_bleu_and_rouge_cover_edge_cases() -> None:
-    assert metrics.compute_f1("", "value") == 0.0
-    assert metrics.compute_f1("alpha beta", "gamma delta") == 0.0
-    assert metrics.compute_f1("alpha beta gamma", "alpha gamma") == pytest.approx(0.8)
-
-    assert metrics.compute_bleu("", "value") == 0.0
-    assert metrics.compute_bleu("one", "one") == pytest.approx(1.0)
-    assert metrics.compute_bleu("alpha beta", "gamma delta") == 0.0
-    assert metrics.compute_bleu("alpha beta", "alpha beta gamma", max_n=4) == pytest.approx(1.0)
-
-    assert metrics.compute_rouge_l("", "value") == 0.0
-    assert metrics.compute_rouge_l("alpha beta", "gamma delta") == 0.0
-    assert metrics.compute_rouge_l("alpha beta gamma", "alpha gamma") == pytest.approx(0.8)
-
-
-def test_compute_semantic_similarity_and_zero_norm(monkeypatch: pytest.MonkeyPatch) -> None:
-    fake_numpy = SimpleNamespace(
-        dot=lambda a, b: sum(x * y for x, y in zip(a, b)),
-        linalg=SimpleNamespace(norm=lambda a: math.sqrt(sum(x * x for x in a))),
-    )
-    monkeypatch.setitem(sys.modules, "numpy", fake_numpy)
-
-    class FakeModel:
-        def __init__(self, embeddings: list[list[float]]) -> None:
-            self.embeddings = embeddings
-
-        def encode(self, values: list[str]) -> list[list[float]]:
-            assert values == ["first", "second"]
-            return self.embeddings
-
-    monkeypatch.setattr(
-        "headroom.models.ml_models.MLModelRegistry.get_sentence_transformer",
-        lambda model_name=None: FakeModel([[1.0, 0.0], [1.0, 0.0]]),
-    )
-    assert metrics.compute_semantic_similarity("first", "second") == 1.0
-
-    monkeypatch.setattr(
-        "headroom.models.ml_models.MLModelRegistry.get_sentence_transformer",
-        lambda model_name=None: FakeModel([[0.0, 0.0], [1.0, 0.0]]),
-    )
-    assert metrics.compute_semantic_similarity("first", "second") == 0.0
-
-
-def test_compute_answer_equivalence_uses_multiple_paths(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.2)
-    exact = metrics.compute_answer_equivalence("Answer", "answer", ground_truth="missing")
-    assert exact["exact_match"] is True
-    assert exact["equivalent"] is True
-    assert exact["ground_truth_in_a"] is False
-    assert exact["ground_truth_in_b"] is False
-
-    monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.1)
-    high_f1 = metrics.compute_answer_equivalence(
-        "alpha beta gamma",
-        "alpha gamma",
-        semantic_threshold=0.95,
-        f1_threshold=0.75,
-    )
-    assert high_f1["equivalent"] is True
-    assert high_f1["semantic_similarity"] == 0.1
-
-    monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.95)
-    semantic = metrics.compute_answer_equivalence(
-        "completely different",
-        "nothing in common",
-        semantic_threshold=0.9,
-        f1_threshold=0.99,
-    )
-    assert semantic["equivalent"] is True
-    assert semantic["semantic_similarity"] == 0.95
-
-    def raise_import_error(a: str, b: str) -> float:
-        raise ImportError("missing dependency")
-
-    monkeypatch.setattr(metrics, "compute_semantic_similarity", raise_import_error)
-    ground_truth = metrics.compute_answer_equivalence(
-        "The capital is Paris.",
-        "Paris is definitely the capital city.",
-        ground_truth="paris",
-        semantic_threshold=0.99,
-        f1_threshold=0.99,
-    )
-    assert ground_truth["semantic_similarity"] is None
-    assert ground_truth["ground_truth_in_a"] is True
-    assert ground_truth["ground_truth_in_b"] is True
-    assert ground_truth["equivalent"] is True
-
-    not_equivalent = metrics.compute_answer_equivalence(
-        "alpha beta",
-        "gamma delta",
-        ground_truth="omega",
-        semantic_threshold=0.99,
-        f1_threshold=0.99,
-    )
-    assert not_equivalent["equivalent"] is False
-
-
-def test_information_recall_reports_preserved_and_missing_facts() -> None:
-    result = metrics.compute_information_recall(
-        "Alice likes pizza and Bob likes ramen.",
-        "Alice likes pizza.",
-        ["Alice", "Bob", "ramen", "Carol"],
-    )
-    assert result == {
-        "total_probes": 4,
-        "facts_in_original": 3,
-        "facts_preserved": 1,
-        "facts_lost": ["Bob", "ramen"],
-        "recall": pytest.approx(1 / 3),
-    }
-
-    empty_original = metrics.compute_information_recall("No facts here", "Still none", ["Alice"])
-    assert empty_original["facts_in_original"] == 0
-    assert empty_original["recall"] == 1.0
+from __future__ import annotations
+
+import math
+import sys
+from types import SimpleNamespace
+
+import pytest
+
+from headroom.evals import metrics
+
+
+def test_normalize_tokenize_and_exact_match() -> None:
+    assert metrics.normalize_text("  Hello,\nWORLD  ") == "hello, world"
+    assert metrics.tokenize("Hello, world! API_v2") == ["hello", "world", "api_v2"]
+    assert metrics.compute_exact_match(" Hello World ", "hello\nworld") is True
+    assert metrics.compute_exact_match("hello", "world") is False
+
+
+def test_f1_bleu_and_rouge_cover_edge_cases() -> None:
+    assert metrics.compute_f1("", "value") == 0.0
+    assert metrics.compute_f1("alpha beta", "gamma delta") == 0.0
+    assert metrics.compute_f1("alpha beta gamma", "alpha gamma") == pytest.approx(0.8)
+
+    assert metrics.compute_bleu("", "value") == 0.0
+    assert metrics.compute_bleu("one", "one") == pytest.approx(1.0)
+    assert metrics.compute_bleu("alpha beta", "gamma delta") == 0.0
+    assert metrics.compute_bleu("alpha beta", "alpha beta gamma", max_n=4) == pytest.approx(1.0)
+
+    assert metrics.compute_rouge_l("", "value") == 0.0
+    assert metrics.compute_rouge_l("alpha beta", "gamma delta") == 0.0
+    assert metrics.compute_rouge_l("alpha beta gamma", "alpha gamma") == pytest.approx(0.8)
+
+
+def test_compute_semantic_similarity_and_zero_norm(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake_numpy = SimpleNamespace(
+        dot=lambda a, b: sum(x * y for x, y in zip(a, b)),
+        linalg=SimpleNamespace(norm=lambda a: math.sqrt(sum(x * x for x in a))),
+    )
+    monkeypatch.setitem(sys.modules, "numpy", fake_numpy)
+
+    class FakeModel:
+        def __init__(self, embeddings: list[list[float]]) -> None:
+            self.embeddings = embeddings
+
+        def encode(self, values: list[str]) -> list[list[float]]:
+            assert values == ["first", "second"]
+            return self.embeddings
+
+    monkeypatch.setattr(
+        "headroom.models.ml_models.MLModelRegistry.get_sentence_transformer",
+        lambda model_name=None: FakeModel([[1.0, 0.0], [1.0, 0.0]]),
+    )
+    assert metrics.compute_semantic_similarity("first", "second") == 1.0
+
+    monkeypatch.setattr(
+        "headroom.models.ml_models.MLModelRegistry.get_sentence_transformer",
+        lambda model_name=None: FakeModel([[0.0, 0.0], [1.0, 0.0]]),
+    )
+    assert metrics.compute_semantic_similarity("first", "second") == 0.0
+
+
+def test_compute_answer_equivalence_uses_multiple_paths(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.2)
+    exact = metrics.compute_answer_equivalence("Answer", "answer", ground_truth="missing")
+    assert exact["exact_match"] is True
+    assert exact["equivalent"] is True
+    assert exact["ground_truth_in_a"] is False
+    assert exact["ground_truth_in_b"] is False
+
+    monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.1)
+    high_f1 = metrics.compute_answer_equivalence(
+        "alpha beta gamma",
+        "alpha gamma",
+        semantic_threshold=0.95,
+        f1_threshold=0.75,
+    )
+    assert high_f1["equivalent"] is True
+    assert high_f1["semantic_similarity"] == 0.1
+
+    monkeypatch.setattr(metrics, "compute_semantic_similarity", lambda a, b: 0.95)
+    semantic = metrics.compute_answer_equivalence(
+        "completely different",
+        "nothing in common",
+        semantic_threshold=0.9,
+        f1_threshold=0.99,
+    )
+    assert semantic["equivalent"] is True
+    assert semantic["semantic_similarity"] == 0.95
+
+    def raise_import_error(a: str, b: str) -> float:
+        raise ImportError("missing dependency")
+
+    monkeypatch.setattr(metrics, "compute_semantic_similarity", raise_import_error)
+    ground_truth = metrics.compute_answer_equivalence(
+        "The capital is Paris.",
+        "Paris is definitely the capital city.",
+        ground_truth="paris",
+        semantic_threshold=0.99,
+        f1_threshold=0.99,
+    )
+    assert ground_truth["semantic_similarity"] is None
+    assert ground_truth["ground_truth_in_a"] is True
+    assert ground_truth["ground_truth_in_b"] is True
+    assert ground_truth["equivalent"] is True
+
+    not_equivalent = metrics.compute_answer_equivalence(
+        "alpha beta",
+        "gamma delta",
+        ground_truth="omega",
+        semantic_threshold=0.99,
+        f1_threshold=0.99,
+    )
+    assert not_equivalent["equivalent"] is False
+
+
+def test_information_recall_reports_preserved_and_missing_facts() -> None:
+    result = metrics.compute_information_recall(
+        "Alice likes pizza and Bob likes ramen.",
+        "Alice likes pizza.",
+        ["Alice", "Bob", "ramen", "Carol"],
+    )
+    assert result == {
+        "total_probes": 4,
+        "facts_in_original": 3,
+        "facts_preserved": 1,
+        "facts_lost": ["Bob", "ramen"],
+        "recall": pytest.approx(1 / 3),
+    }
+
+    empty_original = metrics.compute_information_recall("No facts here", "Still none", ["Alice"])
+    assert empty_original["facts_in_original"] == 0
+    assert empty_original["recall"] == 1.0
diff --git a/tests/test_exceptions.py b/tests/test_exceptions.py
index 938cb219f454f53f460239d41e47895f92ae778b..5061ea2d6b0f85eda339f8f8e656c839265ca558 100644
--- a/tests/test_exceptions.py
+++ b/tests/test_exceptions.py
@@ -1,40 +1,40 @@
-from __future__ import annotations
-
-from headroom.exceptions import (
-    CacheError,
-    CompressionError,
-    ConfigurationError,
-    HeadroomError,
-    ProviderError,
-    StorageError,
-    TokenizationError,
-    TransformError,
-    ValidationError,
-)
-
-
-def test_headroom_error_formats_details() -> None:
-    err = HeadroomError("bad config", details={"mode": "foo", "valid": "bar"})
-    assert err.message == "bad config"
-    assert err.details == {"mode": "foo", "valid": "bar"}
-    assert str(err) == "bad config (mode=foo, valid=bar)"
-
-    plain = HeadroomError("just bad")
-    assert plain.details == {}
-    assert str(plain) == "just bad"
-
-
-def test_specialized_exceptions_inherit_headroom_error() -> None:
-    for exc_type in (
-        ConfigurationError,
-        ProviderError,
-        StorageError,
-        CompressionError,
-        TokenizationError,
-        CacheError,
-        ValidationError,
-        TransformError,
-    ):
-        err = exc_type("problem", details={"kind": exc_type.__name__})
-        assert isinstance(err, HeadroomError)
-        assert str(err) == f"problem (kind={exc_type.__name__})"
+from __future__ import annotations
+
+from headroom.exceptions import (
+    CacheError,
+    CompressionError,
+    ConfigurationError,
+    HeadroomError,
+    ProviderError,
+    StorageError,
+    TokenizationError,
+    TransformError,
+    ValidationError,
+)
+
+
+def test_headroom_error_formats_details() -> None:
+    err = HeadroomError("bad config", details={"mode": "foo", "valid": "bar"})
+    assert err.message == "bad config"
+    assert err.details == {"mode": "foo", "valid": "bar"}
+    assert str(err) == "bad config (mode=foo, valid=bar)"
+
+    plain = HeadroomError("just bad")
+    assert plain.details == {}
+    assert str(plain) == "just bad"
+
+
+def test_specialized_exceptions_inherit_headroom_error() -> None:
+    for exc_type in (
+        ConfigurationError,
+        ProviderError,
+        StorageError,
+        CompressionError,
+        TokenizationError,
+        CacheError,
+        ValidationError,
+        TransformError,
+    ):
+        err = exc_type("problem", details={"kind": exc_type.__name__})
+        assert isinstance(err, HeadroomError)
+        assert str(err) == f"problem (kind={exc_type.__name__})"
diff --git a/tests/test_graph.py b/tests/test_graph.py
index 693f7dd13488265e725c1b44380f2c23edbad56d..4eca7c4f57c0fa2410918b948326ee2a37dade13 100644
--- a/tests/test_graph.py
+++ b/tests/test_graph.py
@@ -1,352 +1,352 @@
-from __future__ import annotations
-
-import io
-import json
-import subprocess
-import tarfile
-from pathlib import Path
-from types import ModuleType, SimpleNamespace
-
-import pytest
-
-from headroom.graph import installer, watcher
-
-
-def _build_archive(member_name: str = installer.CBM_BIN_NAME) -> bytes:
-    payload = io.BytesIO()
-    with tarfile.open(fileobj=payload, mode="w:gz") as tar:
-        data = b"#!/bin/sh\necho version\n"
-        info = tarfile.TarInfo(name=member_name)
-        info.size = len(data)
-        tar.addfile(info, io.BytesIO(data))
-    return payload.getvalue()
-
-
-class FakeResponse:
-    def __init__(self, data: bytes) -> None:
-        self._data = data
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, exc_type, exc, tb) -> None:
-        return None
-
-    def read(self) -> bytes:
-        return self._data
-
-
-@pytest.mark.parametrize(
-    ("system", "machine", "expected"),
-    [
-        ("Darwin", "arm64", "darwin-arm64"),
-        ("Darwin", "x86_64", "darwin-amd64"),
-        ("Linux", "aarch64", "linux-arm64"),
-        ("Linux", "arm64", "linux-arm64"),
-        ("Linux", "x86_64", "linux-amd64"),
-        ("Windows", "AMD64", "windows-amd64"),
-    ],
-)
-def test_detect_platform_variants(monkeypatch, system: str, machine: str, expected: str) -> None:
-    monkeypatch.setattr(installer.platform, "system", lambda: system)
-    monkeypatch.setattr(installer.platform, "machine", lambda: machine)
-    assert installer._detect_platform() == expected
-
-
-def test_detect_platform_rejects_unknown_system(monkeypatch) -> None:
-    monkeypatch.setattr(installer.platform, "system", lambda: "Solaris")
-    monkeypatch.setattr(installer.platform, "machine", lambda: "sparc")
-    with pytest.raises(RuntimeError, match="Unsupported platform"):
-        installer._detect_platform()
-
-
-def test_get_cbm_path_prefers_path_then_install_dir(monkeypatch, tmp_path: Path) -> None:
-    on_path = tmp_path / "on-path"
-    installed = tmp_path / installer.CBM_BIN_NAME
-    installed.write_text("bin")
-    monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
-    monkeypatch.setattr(installer.shutil, "which", lambda name: str(on_path))
-    assert installer.get_cbm_path() == on_path
-
-    monkeypatch.setattr(installer.shutil, "which", lambda name: None)
-    assert installer.get_cbm_path() == installed
-
-    installed.unlink()
-    assert installer.get_cbm_path() is None
-
-
-def test_download_cbm_success_and_verification_paths(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
-    monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")
-    monkeypatch.setattr(
-        installer, "urlopen", lambda url, timeout=60: FakeResponse(_build_archive())
-    )
-
-    run_calls: list[list[str]] = []
-
-    def fake_run(command, **kwargs):
-        run_calls.append(command)
-        return SimpleNamespace(returncode=1, stdout="")
-
-    monkeypatch.setattr("subprocess.run", fake_run)
-    path = installer.download_cbm(version="v1.2.3")
-    assert path == tmp_path / installer.CBM_BIN_NAME
-    assert path.exists()
-    assert run_calls == [[str(path), "--version"]]
-
-    monkeypatch.setattr(
-        "subprocess.run", lambda *args, **kwargs: (_ for _ in ()).throw(RuntimeError("boom"))
-    )
-    assert installer.download_cbm(version="v1.2.3") == path
-
-    monkeypatch.setattr(
-        "subprocess.run",
-        lambda *args, **kwargs: SimpleNamespace(returncode=0, stdout="cbm v1.2.3\n"),
-    )
-    assert installer.download_cbm(version="v1.2.3") == path
-
-
-def test_download_cbm_invalid_url_download_failure_and_extract_errors(
-    monkeypatch, tmp_path: Path
-) -> None:
-    monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
-    monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")
-
-    monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "ftp://example.test/releases")
-    with pytest.raises(RuntimeError, match="Invalid URL"):
-        installer.download_cbm()
-
-    monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "https://example.test/releases")
-    monkeypatch.setattr(
-        installer,
-        "urlopen",
-        lambda url, timeout=60: (_ for _ in ()).throw(OSError("network down")),
-    )
-    with pytest.raises(RuntimeError, match="Failed to download codebase-memory-mcp"):
-        installer.download_cbm()
-
-    monkeypatch.setattr(
-        installer,
-        "urlopen",
-        lambda url, timeout=60: FakeResponse(_build_archive("some/other-binary")),
-    )
-    with pytest.raises(RuntimeError, match="binary not found in archive"):
-        installer.download_cbm()
-
-    monkeypatch.setattr(installer, "urlopen", lambda url, timeout=60: FakeResponse(b"not a tar"))
-    with pytest.raises(RuntimeError, match="Failed to extract archive"):
-        installer.download_cbm()
-
-
-def test_ensure_cbm_uses_existing_or_returns_none_on_failure(monkeypatch, tmp_path: Path) -> None:
-    existing = tmp_path / installer.CBM_BIN_NAME
-    monkeypatch.setattr(installer, "get_cbm_path", lambda: existing)
-    assert installer.ensure_cbm() == existing
-
-    monkeypatch.setattr(installer, "get_cbm_path", lambda: None)
-    monkeypatch.setattr(
-        installer, "download_cbm", lambda: (_ for _ in ()).throw(RuntimeError("nope"))
-    )
-    assert installer.ensure_cbm() is None
-
-
-def test_code_graph_watcher_init_start_stop_and_event_filtering(
-    monkeypatch, tmp_path: Path
-) -> None:
-    monkeypatch.setattr("headroom.graph.installer.get_cbm_path", lambda: tmp_path / "cbm")
-    graph_watcher = watcher.CodeGraphWatcher(tmp_path)
-    assert graph_watcher.cbm_binary == str(tmp_path / "cbm")
-
-    explicit = watcher.CodeGraphWatcher(tmp_path, cbm_binary="explicit-cbm")
-    assert explicit.cbm_binary == "explicit-cbm"
-
-    missing = watcher.CodeGraphWatcher(tmp_path, cbm_binary=None)
-    missing.cbm_binary = None
-    assert missing.start() is False
-
-    watchdog_mod = ModuleType("watchdog")
-    events_mod = ModuleType("watchdog.events")
-    observers_mod = ModuleType("watchdog.observers")
-
-    class FileSystemEventHandler:
-        pass
-
-    class FakeObserver:
-        def __init__(self) -> None:
-            self.scheduled = None
-            self.daemon = False
-            self.started = False
-            self.stopped = False
-            self.join_timeout = None
-
-        def schedule(self, handler, project_dir, recursive=True) -> None:
-            self.scheduled = (handler, project_dir, recursive)
-
-        def start(self) -> None:
-            self.started = True
-
-        def stop(self) -> None:
-            self.stopped = True
-
-        def join(self, timeout=None) -> None:
-            self.join_timeout = timeout
-
-    events_mod.FileSystemEventHandler = FileSystemEventHandler
-    observers_mod.Observer = FakeObserver
-    monkeypatch.setitem(__import__("sys").modules, "watchdog", watchdog_mod)
-    monkeypatch.setitem(__import__("sys").modules, "watchdog.events", events_mod)
-    monkeypatch.setitem(__import__("sys").modules, "watchdog.observers", observers_mod)
-
-    scheduled: list[str] = []
-    monkeypatch.setattr(graph_watcher, "_schedule_reindex", lambda: scheduled.append("reindex"))
-
-    assert graph_watcher.start() is True
-    handler, project_dir, recursive = graph_watcher._observer.scheduled
-    assert project_dir == str(tmp_path)
-    assert recursive is True
-
-    handler.on_any_event(SimpleNamespace(src_path=""))
-    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / ".git" / "config")))
-    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "notes.txt")))
-    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / ".temp.py")))
-    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "main.py~")))
-    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "main.py")))
-    assert scheduled == ["reindex"]
-
-    class FakeTimer:
-        def __init__(self) -> None:
-            self.cancelled = False
-
-        def cancel(self) -> None:
-            self.cancelled = True
-
-    timer = FakeTimer()
-    graph_watcher._debounce_timer = timer
-    graph_watcher._reindex_count = 1
-    graph_watcher.stop()
-    assert timer.cancelled is True
-    assert graph_watcher._observer is None
-
-
-def test_code_graph_watcher_start_returns_false_without_watchdog(
-    monkeypatch, tmp_path: Path
-) -> None:
-    graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")
-
-    import builtins
-
-    real_import = builtins.__import__
-
-    def fake_import(name, globals=None, locals=None, fromlist=(), level=0):
-        if name.startswith("watchdog"):
-            raise ImportError("missing watchdog")
-        return real_import(name, globals, locals, fromlist, level)
-
-    monkeypatch.setattr(builtins, "__import__", fake_import)
-    assert graph_watcher.start() is False
-
-
-def test_code_graph_watcher_stop_handles_missing_timer_and_observer_methods(tmp_path: Path) -> None:
-    graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")
-    graph_watcher._observer = object()
-    graph_watcher.stop()
-    assert graph_watcher._observer is None
-
-    graph_watcher.stop()
-
-
-def test_schedule_reindex_replaces_existing_timer(monkeypatch, tmp_path: Path) -> None:
-    graph_watcher = watcher.CodeGraphWatcher(tmp_path, debounce_seconds=3.5, cbm_binary="cbm")
-    timers: list[FakeTimer] = []
-
-    class FakeTimer:
-        def __init__(self, interval, callback) -> None:
-            self.interval = interval
-            self.callback = callback
-            self.daemon = False
-            self.started = False
-            self.cancelled = False
-            timers.append(self)
-
-        def start(self) -> None:
-            self.started = True
-
-        def cancel(self) -> None:
-            self.cancelled = True
-
-    monkeypatch.setattr(watcher.threading, "Timer", FakeTimer)
-    graph_watcher._schedule_reindex()
-    graph_watcher._schedule_reindex()
-
-    assert len(timers) == 2
-    assert timers[0].cancelled is True
-    assert timers[1].started is True
-    assert timers[1].daemon is True
-    assert timers[1].interval == 3.5
-
-
-def test_do_reindex_success_failure_timeout_and_stats(monkeypatch, tmp_path: Path) -> None:
-    graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")
-    graph_watcher._running = True
-
-    monotonic_values = iter([10.0, 10.4, 20.0, 20.5, 30.0, 30.5, 40.0, 40.5])
-    monkeypatch.setattr(watcher.time, "monotonic", lambda: next(monotonic_values))
-    monkeypatch.setattr(watcher.time, "time", lambda: 1234.0)
-
-    run_calls: list[list[str]] = []
-
-    def success_run(command, **kwargs):
-        run_calls.append(command)
-        return SimpleNamespace(returncode=0, stderr="indexed\nchanged=7 files\n")
-
-    monkeypatch.setattr(watcher.subprocess, "run", success_run)
-    graph_watcher._do_reindex()
-    assert graph_watcher.stats == {
-        "running": True,
-        "project_dir": str(tmp_path),
-        "reindex_count": 1,
-        "last_reindex": 1234.0,
-        "debounce_seconds": 2.0,
-    }
-    assert run_calls == [
-        ["cbm", "cli", "index_repository", json.dumps({"repo_path": str(tmp_path), "mode": "fast"})]
-    ]
-
-    monkeypatch.setattr(
-        watcher.subprocess,
-        "run",
-        lambda command, **kwargs: SimpleNamespace(returncode=1, stderr="failed"),
-    )
-    graph_watcher._do_reindex()
-    assert graph_watcher._reindex_count == 2
-
-    monkeypatch.setattr(
-        watcher.subprocess,
-        "run",
-        lambda command, **kwargs: SimpleNamespace(
-            returncode=0, stderr="indexed\nchanged=oops\nstill running\n"
-        ),
-    )
-    graph_watcher._do_reindex()
-    assert graph_watcher._reindex_count == 3
-
-    monkeypatch.setattr(
-        watcher.subprocess,
-        "run",
-        lambda command, **kwargs: (_ for _ in ()).throw(subprocess.TimeoutExpired(command, 30)),
-    )
-    graph_watcher._do_reindex()
-
-    monkeypatch.setattr(
-        watcher.subprocess,
-        "run",
-        lambda command, **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),
-    )
-    graph_watcher._do_reindex()
-
-    graph_watcher._running = False
-    graph_watcher._do_reindex()
-
-    graph_watcher._running = True
-    graph_watcher.cbm_binary = None
-    graph_watcher._do_reindex()
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+import tarfile
+from pathlib import Path
+from types import ModuleType, SimpleNamespace
+
+import pytest
+
+from headroom.graph import installer, watcher
+
+
+def _build_archive(member_name: str = installer.CBM_BIN_NAME) -> bytes:
+    payload = io.BytesIO()
+    with tarfile.open(fileobj=payload, mode="w:gz") as tar:
+        data = b"#!/bin/sh\necho version\n"
+        info = tarfile.TarInfo(name=member_name)
+        info.size = len(data)
+        tar.addfile(info, io.BytesIO(data))
+    return payload.getvalue()
+
+
+class FakeResponse:
+    def __init__(self, data: bytes) -> None:
+        self._data = data
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        return None
+
+    def read(self) -> bytes:
+        return self._data
+
+
+@pytest.mark.parametrize(
+    ("system", "machine", "expected"),
+    [
+        ("Darwin", "arm64", "darwin-arm64"),
+        ("Darwin", "x86_64", "darwin-amd64"),
+        ("Linux", "aarch64", "linux-arm64"),
+        ("Linux", "arm64", "linux-arm64"),
+        ("Linux", "x86_64", "linux-amd64"),
+        ("Windows", "AMD64", "windows-amd64"),
+    ],
+)
+def test_detect_platform_variants(monkeypatch, system: str, machine: str, expected: str) -> None:
+    monkeypatch.setattr(installer.platform, "system", lambda: system)
+    monkeypatch.setattr(installer.platform, "machine", lambda: machine)
+    assert installer._detect_platform() == expected
+
+
+def test_detect_platform_rejects_unknown_system(monkeypatch) -> None:
+    monkeypatch.setattr(installer.platform, "system", lambda: "Solaris")
+    monkeypatch.setattr(installer.platform, "machine", lambda: "sparc")
+    with pytest.raises(RuntimeError, match="Unsupported platform"):
+        installer._detect_platform()
+
+
+def test_get_cbm_path_prefers_path_then_install_dir(monkeypatch, tmp_path: Path) -> None:
+    on_path = tmp_path / "on-path"
+    installed = tmp_path / installer.CBM_BIN_NAME
+    installed.write_text("bin")
+    monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
+    monkeypatch.setattr(installer.shutil, "which", lambda name: str(on_path))
+    assert installer.get_cbm_path() == on_path
+
+    monkeypatch.setattr(installer.shutil, "which", lambda name: None)
+    assert installer.get_cbm_path() == installed
+
+    installed.unlink()
+    assert installer.get_cbm_path() is None
+
+
+def test_download_cbm_success_and_verification_paths(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
+    monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")
+    monkeypatch.setattr(
+        installer, "urlopen", lambda url, timeout=60: FakeResponse(_build_archive())
+    )
+
+    run_calls: list[list[str]] = []
+
+    def fake_run(command, **kwargs):
+        run_calls.append(command)
+        return SimpleNamespace(returncode=1, stdout="")
+
+    monkeypatch.setattr("subprocess.run", fake_run)
+    path = installer.download_cbm(version="v1.2.3")
+    assert path == tmp_path / installer.CBM_BIN_NAME
+    assert path.exists()
+    assert run_calls == [[str(path), "--version"]]
+
+    monkeypatch.setattr(
+        "subprocess.run", lambda *args, **kwargs: (_ for _ in ()).throw(RuntimeError("boom"))
+    )
+    assert installer.download_cbm(version="v1.2.3") == path
+
+    monkeypatch.setattr(
+        "subprocess.run",
+        lambda *args, **kwargs: SimpleNamespace(returncode=0, stdout="cbm v1.2.3\n"),
+    )
+    assert installer.download_cbm(version="v1.2.3") == path
+
+
+def test_download_cbm_invalid_url_download_failure_and_extract_errors(
+    monkeypatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(installer, "CBM_BIN_DIR", tmp_path)
+    monkeypatch.setattr(installer, "_detect_platform", lambda: "linux-amd64")
+
+    monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "ftp://example.test/releases")
+    with pytest.raises(RuntimeError, match="Invalid URL"):
+        installer.download_cbm()
+
+    monkeypatch.setattr(installer, "GITHUB_RELEASE_URL", "https://example.test/releases")
+    monkeypatch.setattr(
+        installer,
+        "urlopen",
+        lambda url, timeout=60: (_ for _ in ()).throw(OSError("network down")),
+    )
+    with pytest.raises(RuntimeError, match="Failed to download codebase-memory-mcp"):
+        installer.download_cbm()
+
+    monkeypatch.setattr(
+        installer,
+        "urlopen",
+        lambda url, timeout=60: FakeResponse(_build_archive("some/other-binary")),
+    )
+    with pytest.raises(RuntimeError, match="binary not found in archive"):
+        installer.download_cbm()
+
+    monkeypatch.setattr(installer, "urlopen", lambda url, timeout=60: FakeResponse(b"not a tar"))
+    with pytest.raises(RuntimeError, match="Failed to extract archive"):
+        installer.download_cbm()
+
+
+def test_ensure_cbm_uses_existing_or_returns_none_on_failure(monkeypatch, tmp_path: Path) -> None:
+    existing = tmp_path / installer.CBM_BIN_NAME
+    monkeypatch.setattr(installer, "get_cbm_path", lambda: existing)
+    assert installer.ensure_cbm() == existing
+
+    monkeypatch.setattr(installer, "get_cbm_path", lambda: None)
+    monkeypatch.setattr(
+        installer, "download_cbm", lambda: (_ for _ in ()).throw(RuntimeError("nope"))
+    )
+    assert installer.ensure_cbm() is None
+
+
+def test_code_graph_watcher_init_start_stop_and_event_filtering(
+    monkeypatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr("headroom.graph.installer.get_cbm_path", lambda: tmp_path / "cbm")
+    graph_watcher = watcher.CodeGraphWatcher(tmp_path)
+    assert graph_watcher.cbm_binary == str(tmp_path / "cbm")
+
+    explicit = watcher.CodeGraphWatcher(tmp_path, cbm_binary="explicit-cbm")
+    assert explicit.cbm_binary == "explicit-cbm"
+
+    missing = watcher.CodeGraphWatcher(tmp_path, cbm_binary=None)
+    missing.cbm_binary = None
+    assert missing.start() is False
+
+    watchdog_mod = ModuleType("watchdog")
+    events_mod = ModuleType("watchdog.events")
+    observers_mod = ModuleType("watchdog.observers")
+
+    class FileSystemEventHandler:
+        pass
+
+    class FakeObserver:
+        def __init__(self) -> None:
+            self.scheduled = None
+            self.daemon = False
+            self.started = False
+            self.stopped = False
+            self.join_timeout = None
+
+        def schedule(self, handler, project_dir, recursive=True) -> None:
+            self.scheduled = (handler, project_dir, recursive)
+
+        def start(self) -> None:
+            self.started = True
+
+        def stop(self) -> None:
+            self.stopped = True
+
+        def join(self, timeout=None) -> None:
+            self.join_timeout = timeout
+
+    events_mod.FileSystemEventHandler = FileSystemEventHandler
+    observers_mod.Observer = FakeObserver
+    monkeypatch.setitem(__import__("sys").modules, "watchdog", watchdog_mod)
+    monkeypatch.setitem(__import__("sys").modules, "watchdog.events", events_mod)
+    monkeypatch.setitem(__import__("sys").modules, "watchdog.observers", observers_mod)
+
+    scheduled: list[str] = []
+    monkeypatch.setattr(graph_watcher, "_schedule_reindex", lambda: scheduled.append("reindex"))
+
+    assert graph_watcher.start() is True
+    handler, project_dir, recursive = graph_watcher._observer.scheduled
+    assert project_dir == str(tmp_path)
+    assert recursive is True
+
+    handler.on_any_event(SimpleNamespace(src_path=""))
+    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / ".git" / "config")))
+    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "notes.txt")))
+    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / ".temp.py")))
+    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "main.py~")))
+    handler.on_any_event(SimpleNamespace(src_path=str(tmp_path / "main.py")))
+    assert scheduled == ["reindex"]
+
+    class FakeTimer:
+        def __init__(self) -> None:
+            self.cancelled = False
+
+        def cancel(self) -> None:
+            self.cancelled = True
+
+    timer = FakeTimer()
+    graph_watcher._debounce_timer = timer
+    graph_watcher._reindex_count = 1
+    graph_watcher.stop()
+    assert timer.cancelled is True
+    assert graph_watcher._observer is None
+
+
+def test_code_graph_watcher_start_returns_false_without_watchdog(
+    monkeypatch, tmp_path: Path
+) -> None:
+    graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")
+
+    import builtins
+
+    real_import = builtins.__import__
+
+    def fake_import(name, globals=None, locals=None, fromlist=(), level=0):
+        if name.startswith("watchdog"):
+            raise ImportError("missing watchdog")
+        return real_import(name, globals, locals, fromlist, level)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+    assert graph_watcher.start() is False
+
+
+def test_code_graph_watcher_stop_handles_missing_timer_and_observer_methods(tmp_path: Path) -> None:
+    graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")
+    graph_watcher._observer = object()
+    graph_watcher.stop()
+    assert graph_watcher._observer is None
+
+    graph_watcher.stop()
+
+
+def test_schedule_reindex_replaces_existing_timer(monkeypatch, tmp_path: Path) -> None:
+    graph_watcher = watcher.CodeGraphWatcher(tmp_path, debounce_seconds=3.5, cbm_binary="cbm")
+    timers: list[FakeTimer] = []
+
+    class FakeTimer:
+        def __init__(self, interval, callback) -> None:
+            self.interval = interval
+            self.callback = callback
+            self.daemon = False
+            self.started = False
+            self.cancelled = False
+            timers.append(self)
+
+        def start(self) -> None:
+            self.started = True
+
+        def cancel(self) -> None:
+            self.cancelled = True
+
+    monkeypatch.setattr(watcher.threading, "Timer", FakeTimer)
+    graph_watcher._schedule_reindex()
+    graph_watcher._schedule_reindex()
+
+    assert len(timers) == 2
+    assert timers[0].cancelled is True
+    assert timers[1].started is True
+    assert timers[1].daemon is True
+    assert timers[1].interval == 3.5
+
+
+def test_do_reindex_success_failure_timeout_and_stats(monkeypatch, tmp_path: Path) -> None:
+    graph_watcher = watcher.CodeGraphWatcher(tmp_path, cbm_binary="cbm")
+    graph_watcher._running = True
+
+    monotonic_values = iter([10.0, 10.4, 20.0, 20.5, 30.0, 30.5, 40.0, 40.5])
+    monkeypatch.setattr(watcher.time, "monotonic", lambda: next(monotonic_values))
+    monkeypatch.setattr(watcher.time, "time", lambda: 1234.0)
+
+    run_calls: list[list[str]] = []
+
+    def success_run(command, **kwargs):
+        run_calls.append(command)
+        return SimpleNamespace(returncode=0, stderr="indexed\nchanged=7 files\n")
+
+    monkeypatch.setattr(watcher.subprocess, "run", success_run)
+    graph_watcher._do_reindex()
+    assert graph_watcher.stats == {
+        "running": True,
+        "project_dir": str(tmp_path),
+        "reindex_count": 1,
+        "last_reindex": 1234.0,
+        "debounce_seconds": 2.0,
+    }
+    assert run_calls == [
+        ["cbm", "cli", "index_repository", json.dumps({"repo_path": str(tmp_path), "mode": "fast"})]
+    ]
+
+    monkeypatch.setattr(
+        watcher.subprocess,
+        "run",
+        lambda command, **kwargs: SimpleNamespace(returncode=1, stderr="failed"),
+    )
+    graph_watcher._do_reindex()
+    assert graph_watcher._reindex_count == 2
+
+    monkeypatch.setattr(
+        watcher.subprocess,
+        "run",
+        lambda command, **kwargs: SimpleNamespace(
+            returncode=0, stderr="indexed\nchanged=oops\nstill running\n"
+        ),
+    )
+    graph_watcher._do_reindex()
+    assert graph_watcher._reindex_count == 3
+
+    monkeypatch.setattr(
+        watcher.subprocess,
+        "run",
+        lambda command, **kwargs: (_ for _ in ()).throw(subprocess.TimeoutExpired(command, 30)),
+    )
+    graph_watcher._do_reindex()
+
+    monkeypatch.setattr(
+        watcher.subprocess,
+        "run",
+        lambda command, **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),
+    )
+    graph_watcher._do_reindex()
+
+    graph_watcher._running = False
+    graph_watcher._do_reindex()
+
+    graph_watcher._running = True
+    graph_watcher.cbm_binary = None
+    graph_watcher._do_reindex()
diff --git a/tests/test_install/test_paths.py b/tests/test_install/test_paths.py
index 0d44734f27ec9576934c589308f9bd8b8245a6e4..821dfc15a8271af29a89330a2b60043edcf345b8 100644
--- a/tests/test_install/test_paths.py
+++ b/tests/test_install/test_paths.py
@@ -1,68 +1,68 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-import click
-import pytest
-
-from headroom.install import paths as install_paths
-
-
-def test_validate_profile_name_accepts_and_rejects_values() -> None:
-    assert install_paths.validate_profile_name("good.profile-1_2") == "good.profile-1_2"
-
-    for value in (".", "..", "bad/name", "bad space", ""):
-        with pytest.raises(click.ClickException, match="Invalid profile name"):
-            install_paths.validate_profile_name(value)
-
-
-def test_profile_and_artifact_paths(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr("headroom.install.paths._paths.deploy_root", lambda: tmp_path / "deploy")
-
-    assert install_paths.deploy_root() == tmp_path / "deploy"
-    assert install_paths.profile_root("demo") == tmp_path / "deploy" / "demo"
-    assert install_paths.manifest_path("demo") == tmp_path / "deploy" / "demo" / "manifest.json"
-    assert install_paths.log_path("demo") == tmp_path / "deploy" / "demo" / "runner.log"
-    assert install_paths.pid_path("demo") == tmp_path / "deploy" / "demo" / "runner.pid"
-    assert (
-        install_paths.unix_run_script_path("demo")
-        == tmp_path / "deploy" / "demo" / "run-headroom.sh"
-    )
-    assert install_paths.unix_ensure_script_path("demo") == (
-        tmp_path / "deploy" / "demo" / "ensure-headroom.sh"
-    )
-    assert install_paths.windows_run_script_path("demo") == (
-        tmp_path / "deploy" / "demo" / "run-headroom.ps1"
-    )
-    assert install_paths.windows_run_cmd_path("demo") == (
-        tmp_path / "deploy" / "demo" / "run-headroom.cmd"
-    )
-    assert install_paths.windows_ensure_script_path("demo") == (
-        tmp_path / "deploy" / "demo" / "ensure-headroom.ps1"
-    )
-    assert install_paths.windows_ensure_cmd_path("demo") == (
-        tmp_path / "deploy" / "demo" / "ensure-headroom.cmd"
-    )
-
-
-def test_env_target_and_config_paths(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    monkeypatch.setattr("headroom.install.paths.sys.platform", "linux")
-
-    assert install_paths.unix_user_env_targets() == [
-        tmp_path / ".bashrc",
-        tmp_path / ".zshrc",
-        tmp_path / ".profile",
-    ]
-    assert install_paths.unix_system_env_targets() == [Path("/etc/profile.d/headroom.sh")]
-
-    monkeypatch.setattr("headroom.install.paths.sys.platform", "darwin")
-    assert install_paths.unix_system_env_targets() == [
-        Path("/etc/profile"),
-        Path("/etc/zprofile"),
-        Path("/etc/bashrc"),
-    ]
-
-    assert install_paths.claude_settings_path() == tmp_path / ".claude" / "settings.json"
-    assert install_paths.codex_config_path() == tmp_path / ".codex" / "config.toml"
-    assert install_paths.openclaw_config_path() == tmp_path / ".openclaw" / "openclaw.json"
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import pytest
+
+from headroom.install import paths as install_paths
+
+
+def test_validate_profile_name_accepts_and_rejects_values() -> None:
+    assert install_paths.validate_profile_name("good.profile-1_2") == "good.profile-1_2"
+
+    for value in (".", "..", "bad/name", "bad space", ""):
+        with pytest.raises(click.ClickException, match="Invalid profile name"):
+            install_paths.validate_profile_name(value)
+
+
+def test_profile_and_artifact_paths(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr("headroom.install.paths._paths.deploy_root", lambda: tmp_path / "deploy")
+
+    assert install_paths.deploy_root() == tmp_path / "deploy"
+    assert install_paths.profile_root("demo") == tmp_path / "deploy" / "demo"
+    assert install_paths.manifest_path("demo") == tmp_path / "deploy" / "demo" / "manifest.json"
+    assert install_paths.log_path("demo") == tmp_path / "deploy" / "demo" / "runner.log"
+    assert install_paths.pid_path("demo") == tmp_path / "deploy" / "demo" / "runner.pid"
+    assert (
+        install_paths.unix_run_script_path("demo")
+        == tmp_path / "deploy" / "demo" / "run-headroom.sh"
+    )
+    assert install_paths.unix_ensure_script_path("demo") == (
+        tmp_path / "deploy" / "demo" / "ensure-headroom.sh"
+    )
+    assert install_paths.windows_run_script_path("demo") == (
+        tmp_path / "deploy" / "demo" / "run-headroom.ps1"
+    )
+    assert install_paths.windows_run_cmd_path("demo") == (
+        tmp_path / "deploy" / "demo" / "run-headroom.cmd"
+    )
+    assert install_paths.windows_ensure_script_path("demo") == (
+        tmp_path / "deploy" / "demo" / "ensure-headroom.ps1"
+    )
+    assert install_paths.windows_ensure_cmd_path("demo") == (
+        tmp_path / "deploy" / "demo" / "ensure-headroom.cmd"
+    )
+
+
+def test_env_target_and_config_paths(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setattr("headroom.install.paths.sys.platform", "linux")
+
+    assert install_paths.unix_user_env_targets() == [
+        tmp_path / ".bashrc",
+        tmp_path / ".zshrc",
+        tmp_path / ".profile",
+    ]
+    assert install_paths.unix_system_env_targets() == [Path("/etc/profile.d/headroom.sh")]
+
+    monkeypatch.setattr("headroom.install.paths.sys.platform", "darwin")
+    assert install_paths.unix_system_env_targets() == [
+        Path("/etc/profile"),
+        Path("/etc/zprofile"),
+        Path("/etc/bashrc"),
+    ]
+
+    assert install_paths.claude_settings_path() == tmp_path / ".claude" / "settings.json"
+    assert install_paths.codex_config_path() == tmp_path / ".codex" / "config.toml"
+    assert install_paths.openclaw_config_path() == tmp_path / ".openclaw" / "openclaw.json"
diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.py
index 481c632659478fcf7160a47e9def75b5706de7e5..e50cf29b01f783f9eef1c672e91d14a1e8d7fe9f 100644
--- a/tests/test_install/test_runtime.py
+++ b/tests/test_install/test_runtime.py
@@ -1,468 +1,468 @@
-from __future__ import annotations
-
-import signal
-from pathlib import Path
-
-from headroom.install.models import DeploymentManifest, InstallPreset
-from headroom.install.runtime import (
-    _clear_pid,
-    _deployment_env,
-    _mount_source,
-    _read_pid,
-    _runtime_env,
-    _write_pid,
-    build_runtime_command,
-    resolve_headroom_command,
-    run_foreground,
-    runtime_status,
-    start_detached_agent,
-    start_persistent_docker,
-    stop_runtime,
-    wait_ready,
-)
-
-
-def test_build_runtime_command_for_docker_includes_deployment_env(
-    monkeypatch, tmp_path: Path
-) -> None:
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-docker",
-        runtime_kind="docker",
-        supervisor_kind="none",
-        scope="user",
-        provider_mode="manual",
-        targets=["claude"],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        image="ghcr.io/chopratejas/headroom:latest",
-        base_env={"HEADROOM_PORT": "8787"},
-        proxy_args=["--host", "127.0.0.1", "--port", "8787"],
-    )
-
-    command = build_runtime_command(manifest)
-
-    joined = " ".join(command)
-    assert command[:3] == ["docker", "run", "--rm"]
-    assert "HEADROOM_DEPLOYMENT_PROFILE=default" in joined
-    assert "HEADROOM_DEPLOYMENT_PRESET=persistent-docker" in joined
-    assert "127.0.0.1:8787:8787" in joined
-    assert "ghcr.io/chopratejas/headroom:latest" in command
-    # Canonical Headroom filesystem contract (issue #175) forwarded into
-    # the container.
-    assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in command
-    assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in command
-
-
-def test_build_runtime_command_for_docker_matches_wrapper_parity(
-    monkeypatch, tmp_path: Path
-) -> None:
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
-    monkeypatch.setenv("OPENAI_API_KEY", "test-openai")
-    manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-docker",
-        runtime_kind="docker",
-        supervisor_kind="none",
-        scope="user",
-        provider_mode="manual",
-        targets=["claude"],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        image="ghcr.io/chopratejas/headroom:latest",
-        base_env={"HEADROOM_PORT": "8787"},
-        proxy_args=["--host", "127.0.0.1", "--port", "8787"],
-    )
-
-    command = build_runtime_command(manifest)
-
-    assert (tmp_path / ".headroom").is_dir()
-    assert (tmp_path / ".claude").is_dir()
-    assert (tmp_path / ".codex").is_dir()
-    assert (tmp_path / ".gemini").is_dir()
-    assert "--env" in command
-    joined = " ".join(command)
-    assert "ANTHROPIC_API_KEY" in joined
-    assert "OPENAI_API_KEY" in joined
-
-
-def test_resolve_headroom_command_prefers_headroom_binary(monkeypatch) -> None:
-    monkeypatch.setattr(
-        "shutil.which", lambda name: "/usr/bin/headroom" if name == "headroom" else None
-    )
-
-    assert resolve_headroom_command() == ["/usr/bin/headroom"]
-
-
-def test_resolve_headroom_command_falls_back_to_python_module(monkeypatch) -> None:
-    monkeypatch.setattr("shutil.which", lambda name: None)
-    monkeypatch.setattr("headroom.install.runtime.sys.executable", "/usr/bin/python")
-    assert resolve_headroom_command() == ["/usr/bin/python", "-m", "headroom.cli"]
-
-
-def test_runtime_env_and_mount_source(monkeypatch) -> None:
-    manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-service",
-        runtime_kind="python",
-        supervisor_kind="service",
-        scope="user",
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        base_env={"EXTRA": "1"},
-    )
-    monkeypatch.setattr("headroom.install.runtime.os.environ", {"BASE": "x"})
-
-    assert _deployment_env(manifest) == {
-        "HEADROOM_DEPLOYMENT_PROFILE": "default",
-        "HEADROOM_DEPLOYMENT_PRESET": "persistent-service",
-        "HEADROOM_DEPLOYMENT_RUNTIME": "python",
-        "HEADROOM_DEPLOYMENT_SUPERVISOR": "service",
-        "HEADROOM_DEPLOYMENT_SCOPE": "user",
-    }
-    assert _runtime_env(manifest)["BASE"] == "x"
-    assert _runtime_env(manifest)["EXTRA"] == "1"
-    assert _runtime_env(manifest)["HEADROOM_DEPLOYMENT_PROFILE"] == "default"
-
-    monkeypatch.setattr("headroom.install.runtime.sys.platform", "win32")
-    assert _mount_source("C:\\Users\\me", ".headroom") == "C:\\Users\\me\\.headroom"
-    monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")
-    assert _mount_source("/home/me", ".headroom") == "/home/me/.headroom"
-
-
-def test_build_runtime_command_python_and_docker_user(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr("headroom.install.runtime.sys.executable", "/usr/bin/python")
-    manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-service",
-        runtime_kind="python",
-        supervisor_kind="service",
-        scope="user",
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        proxy_args=["--host", "127.0.0.1", "--port", "8787"],
-    )
-    assert build_runtime_command(manifest) == [
-        "/usr/bin/python",
-        "-m",
-        "headroom.cli",
-        "proxy",
-        "--host",
-        "127.0.0.1",
-        "--port",
-        "8787",
-    ]
-
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")
-    monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: 1000, raising=False)
-    monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: 1001, raising=False)
-    docker_manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-docker",
-        runtime_kind="docker",
-        supervisor_kind="none",
-        scope="user",
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        image="ghcr.io/chopratejas/headroom:latest",
-        base_env={"HEADROOM_PORT": "8787"},
-        proxy_args=["--host", "127.0.0.1", "--port", "8787"],
-    )
-    command = build_runtime_command(docker_manifest)
-    assert "--user" in command
-    assert "1000:1001" in command
-
-
-def test_read_pid_handles_invalid_content(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    pid_file = tmp_path / ".headroom" / "deploy" / "default" / "runner.pid"
-    pid_file.parent.mkdir(parents=True)
-    pid_file.write_text("not-a-pid", encoding="utf-8")
-
-    assert _read_pid("default") is None
-    _clear_pid("default")
-    assert not pid_file.exists()
-
-
-def test_write_read_and_clear_pid(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    _write_pid("default", 456)
-    assert _read_pid("default") == 456
-    _clear_pid("default")
-    assert _read_pid("default") is None
-
-
-def test_run_foreground_and_detached_helpers(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    monkeypatch.setattr(
-        "headroom.install.runtime.build_runtime_command", lambda manifest: ["headroom", "proxy"]
-    )
-    monkeypatch.setattr("headroom.install.runtime._runtime_env", lambda manifest: {"ENV": "1"})
-    signal_calls: list[int] = []
-    monkeypatch.setattr(
-        "headroom.install.runtime.signal.signal", lambda sig, fn: signal_calls.append(sig)
-    )
-
-    class FakeProc:
-        def __init__(self, returncode: int = 0, pid: int = 321) -> None:
-            self.returncode = returncode
-            self.pid = pid
-            self.terminated = False
-            self.killed = False
-
-        def wait(self, timeout: int | None = None) -> int:
-            return self.returncode
-
-        def poll(self):
-            return None if not self.terminated else self.returncode
-
-        def terminate(self) -> None:
-            self.terminated = True
-
-        def kill(self) -> None:
-            self.killed = True
-
-    fake_proc = FakeProc(returncode=7)
-    popen_calls: list[tuple[list[str], dict]] = []
-
-    def fake_popen(command: list[str], **kwargs):
-        popen_calls.append((command, kwargs))
-        return fake_proc
-
-    monkeypatch.setattr("headroom.install.runtime.subprocess.Popen", fake_popen)
-    manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-service",
-        runtime_kind="python",
-        supervisor_kind="service",
-        scope="user",
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-    )
-    assert run_foreground(manifest) == 7
-    assert popen_calls[0][0] == ["headroom", "proxy"]
-    assert signal.SIGINT in signal_calls
-    assert signal.SIGTERM in signal_calls
-    assert _read_pid("default") is None
-
-    monkeypatch.setattr("headroom.install.runtime.resolve_headroom_command", lambda: ["headroom"])
-    monkeypatch.setattr("headroom.install.runtime.sys.platform", "win32")
-    monkeypatch.setattr("headroom.install.runtime.subprocess.DETACHED_PROCESS", 1, raising=False)
-    monkeypatch.setattr(
-        "headroom.install.runtime.subprocess.CREATE_NEW_PROCESS_GROUP", 2, raising=False
-    )
-    fake_proc_nt = FakeProc()
-    monkeypatch.setattr(
-        "headroom.install.runtime.subprocess.Popen", lambda command, **kwargs: fake_proc_nt
-    )
-    assert start_detached_agent("demo") is fake_proc_nt
-
-    monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")
-    fake_proc_posix = FakeProc()
-    monkeypatch.setattr(
-        "headroom.install.runtime.subprocess.Popen", lambda command, **kwargs: fake_proc_posix
-    )
-    assert start_detached_agent("demo") is fake_proc_posix
-
-
-def test_start_stop_wait_and_runtime_status_branches(monkeypatch, tmp_path: Path) -> None:
-    calls: list[list[str]] = []
-    monkeypatch.setattr(
-        "headroom.install.runtime.subprocess.run",
-        lambda command, **kwargs: calls.append(command) or type("Result", (), {"stdout": ""})(),
-    )
-    monkeypatch.setattr(
-        "headroom.install.runtime.build_runtime_command",
-        lambda manifest: [
-            "docker",
-            "run",
-            "--rm",
-            "--name",
-            "demo",
-            "-p",
-            "127.0.0.1:8787:8787",
-            "image",
-        ],
-    )
-    manifest = DeploymentManifest(
-        profile="default",
-        preset=InstallPreset.PERSISTENT_DOCKER.value,
-        runtime_kind="docker",
-        supervisor_kind="none",
-        scope="user",
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        container_name="headroom-default",
-    )
-    start_persistent_docker(manifest)
-    assert calls == [
-        ["docker", "rm", "-f", "headroom-default"],
-        [
-            "docker",
-            "run",
-            "-d",
-            "--restart",
-            "unless-stopped",
-            "--name",
-            "headroom-default",
-            "-p",
-            "127.0.0.1:8787:8787",
-            "image",
-        ],
-    ]
-
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    python_manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-service",
-        runtime_kind="python",
-        supervisor_kind="service",
-        scope="user",
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        health_url="http://127.0.0.1:8787/health",
-    )
-    _write_pid("default", 123)
-    killed: list[tuple[int, int]] = []
-    monkeypatch.setattr(
-        "headroom.install.runtime.os.kill", lambda pid, sig: killed.append((pid, sig))
-    )
-    stop_runtime(python_manifest)
-    assert killed == [(123, signal.SIGTERM)]
-    assert _read_pid("default") is None
-
-    _write_pid("default", 124)
-    monkeypatch.setattr(
-        "headroom.install.runtime.os.kill",
-        lambda pid, sig: (_ for _ in ()).throw(OSError("gone")),
-    )
-    stop_runtime(python_manifest)
-    assert _read_pid("default") is None
-
-    probe_results = iter([False, False, True])
-    sleeps: list[int] = []
-    monkeypatch.setattr("headroom.install.runtime.probe_ready", lambda url: next(probe_results))
-    monkeypatch.setattr(
-        "headroom.install.runtime.time.sleep", lambda seconds: sleeps.append(seconds)
-    )
-    assert wait_ready(python_manifest, timeout_seconds=3) is True
-    assert sleeps == [1, 1]
-
-    monkeypatch.setattr("headroom.install.runtime.probe_ready", lambda url: False)
-    sleeps.clear()
-    assert wait_ready(python_manifest, timeout_seconds=2) is False
-    assert sleeps == [1, 1]
-
-    class Result:
-        def __init__(self, stdout: str = "") -> None:
-            self.stdout = stdout
-
-    monkeypatch.setattr(
-        "headroom.install.runtime.subprocess.run",
-        lambda command, **kwargs: Result(stdout=""),
-    )
-    assert runtime_status(manifest) == "stopped"
-    assert runtime_status(python_manifest) == "stopped"
-
-    _write_pid("default", 125)
-    monkeypatch.setattr(
-        "headroom.install.runtime.os.kill", lambda pid, sig: (_ for _ in ()).throw(OSError())
-    )
-    assert runtime_status(python_manifest) == "stopped"
-
-
-def test_stop_runtime_for_docker_stops_and_removes_container(monkeypatch) -> None:
-    calls: list[list[str]] = []
-    manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-docker",
-        runtime_kind="docker",
-        supervisor_kind="none",
-        scope="user",
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        container_name="headroom-default",
-    )
-
-    monkeypatch.setattr(
-        "headroom.install.runtime.subprocess.run",
-        lambda command, **kwargs: calls.append(command),
-    )
-
-    stop_runtime(manifest)
-
-    assert calls == [
-        ["docker", "stop", "headroom-default"],
-        ["docker", "rm", "-f", "headroom-default"],
-    ]
-
-
-def test_runtime_status_reads_container_and_pid_state(monkeypatch, tmp_path: Path) -> None:
-    docker_manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-docker",
-        runtime_kind="docker",
-        supervisor_kind="none",
-        scope="user",
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        container_name="headroom-default",
-    )
-
-    class Result:
-        def __init__(self, stdout: str = "") -> None:
-            self.stdout = stdout
-
-    monkeypatch.setattr(
-        "headroom.install.runtime.subprocess.run",
-        lambda command, **kwargs: Result(stdout="headroom-default\n"),
-    )
-    assert runtime_status(docker_manifest) == "running"
-
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    pid_file = tmp_path / ".headroom" / "deploy" / "default" / "runner.pid"
-    pid_file.parent.mkdir(parents=True)
-    pid_file.write_text("123", encoding="utf-8")
-    monkeypatch.setattr("headroom.install.runtime.os.kill", lambda pid, sig: None)
-    python_manifest = DeploymentManifest(
-        profile="default",
-        preset="persistent-service",
-        runtime_kind="python",
-        supervisor_kind="service",
-        scope="user",
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-    )
-    assert runtime_status(python_manifest) == "running"
+from __future__ import annotations
+
+import signal
+from pathlib import Path
+
+from headroom.install.models import DeploymentManifest, InstallPreset
+from headroom.install.runtime import (
+    _clear_pid,
+    _deployment_env,
+    _mount_source,
+    _read_pid,
+    _runtime_env,
+    _write_pid,
+    build_runtime_command,
+    resolve_headroom_command,
+    run_foreground,
+    runtime_status,
+    start_detached_agent,
+    start_persistent_docker,
+    stop_runtime,
+    wait_ready,
+)
+
+
+def test_build_runtime_command_for_docker_includes_deployment_env(
+    monkeypatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-docker",
+        runtime_kind="docker",
+        supervisor_kind="none",
+        scope="user",
+        provider_mode="manual",
+        targets=["claude"],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        image="ghcr.io/chopratejas/headroom:latest",
+        base_env={"HEADROOM_PORT": "8787"},
+        proxy_args=["--host", "127.0.0.1", "--port", "8787"],
+    )
+
+    command = build_runtime_command(manifest)
+
+    joined = " ".join(command)
+    assert command[:3] == ["docker", "run", "--rm"]
+    assert "HEADROOM_DEPLOYMENT_PROFILE=default" in joined
+    assert "HEADROOM_DEPLOYMENT_PRESET=persistent-docker" in joined
+    assert "127.0.0.1:8787:8787" in joined
+    assert "ghcr.io/chopratejas/headroom:latest" in command
+    # Canonical Headroom filesystem contract (issue #175) forwarded into
+    # the container.
+    assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in command
+    assert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in command
+
+
+def test_build_runtime_command_for_docker_matches_wrapper_parity(
+    monkeypatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+    monkeypatch.setenv("OPENAI_API_KEY", "test-openai")
+    manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-docker",
+        runtime_kind="docker",
+        supervisor_kind="none",
+        scope="user",
+        provider_mode="manual",
+        targets=["claude"],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        image="ghcr.io/chopratejas/headroom:latest",
+        base_env={"HEADROOM_PORT": "8787"},
+        proxy_args=["--host", "127.0.0.1", "--port", "8787"],
+    )
+
+    command = build_runtime_command(manifest)
+
+    assert (tmp_path / ".headroom").is_dir()
+    assert (tmp_path / ".claude").is_dir()
+    assert (tmp_path / ".codex").is_dir()
+    assert (tmp_path / ".gemini").is_dir()
+    assert "--env" in command
+    joined = " ".join(command)
+    assert "ANTHROPIC_API_KEY" in joined
+    assert "OPENAI_API_KEY" in joined
+
+
+def test_resolve_headroom_command_prefers_headroom_binary(monkeypatch) -> None:
+    monkeypatch.setattr(
+        "shutil.which", lambda name: "/usr/bin/headroom" if name == "headroom" else None
+    )
+
+    assert resolve_headroom_command() == ["/usr/bin/headroom"]
+
+
+def test_resolve_headroom_command_falls_back_to_python_module(monkeypatch) -> None:
+    monkeypatch.setattr("shutil.which", lambda name: None)
+    monkeypatch.setattr("headroom.install.runtime.sys.executable", "/usr/bin/python")
+    assert resolve_headroom_command() == ["/usr/bin/python", "-m", "headroom.cli"]
+
+
+def test_runtime_env_and_mount_source(monkeypatch) -> None:
+    manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-service",
+        runtime_kind="python",
+        supervisor_kind="service",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        base_env={"EXTRA": "1"},
+    )
+    monkeypatch.setattr("headroom.install.runtime.os.environ", {"BASE": "x"})
+
+    assert _deployment_env(manifest) == {
+        "HEADROOM_DEPLOYMENT_PROFILE": "default",
+        "HEADROOM_DEPLOYMENT_PRESET": "persistent-service",
+        "HEADROOM_DEPLOYMENT_RUNTIME": "python",
+        "HEADROOM_DEPLOYMENT_SUPERVISOR": "service",
+        "HEADROOM_DEPLOYMENT_SCOPE": "user",
+    }
+    assert _runtime_env(manifest)["BASE"] == "x"
+    assert _runtime_env(manifest)["EXTRA"] == "1"
+    assert _runtime_env(manifest)["HEADROOM_DEPLOYMENT_PROFILE"] == "default"
+
+    monkeypatch.setattr("headroom.install.runtime.sys.platform", "win32")
+    assert _mount_source("C:\\Users\\me", ".headroom") == "C:\\Users\\me\\.headroom"
+    monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")
+    assert _mount_source("/home/me", ".headroom") == "/home/me/.headroom"
+
+
+def test_build_runtime_command_python_and_docker_user(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr("headroom.install.runtime.sys.executable", "/usr/bin/python")
+    manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-service",
+        runtime_kind="python",
+        supervisor_kind="service",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        proxy_args=["--host", "127.0.0.1", "--port", "8787"],
+    )
+    assert build_runtime_command(manifest) == [
+        "/usr/bin/python",
+        "-m",
+        "headroom.cli",
+        "proxy",
+        "--host",
+        "127.0.0.1",
+        "--port",
+        "8787",
+    ]
+
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")
+    monkeypatch.setattr("headroom.install.runtime.os.getuid", lambda: 1000, raising=False)
+    monkeypatch.setattr("headroom.install.runtime.os.getgid", lambda: 1001, raising=False)
+    docker_manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-docker",
+        runtime_kind="docker",
+        supervisor_kind="none",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        image="ghcr.io/chopratejas/headroom:latest",
+        base_env={"HEADROOM_PORT": "8787"},
+        proxy_args=["--host", "127.0.0.1", "--port", "8787"],
+    )
+    command = build_runtime_command(docker_manifest)
+    assert "--user" in command
+    assert "1000:1001" in command
+
+
+def test_read_pid_handles_invalid_content(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    pid_file = tmp_path / ".headroom" / "deploy" / "default" / "runner.pid"
+    pid_file.parent.mkdir(parents=True)
+    pid_file.write_text("not-a-pid", encoding="utf-8")
+
+    assert _read_pid("default") is None
+    _clear_pid("default")
+    assert not pid_file.exists()
+
+
+def test_write_read_and_clear_pid(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    _write_pid("default", 456)
+    assert _read_pid("default") == 456
+    _clear_pid("default")
+    assert _read_pid("default") is None
+
+
+def test_run_foreground_and_detached_helpers(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setattr(
+        "headroom.install.runtime.build_runtime_command", lambda manifest: ["headroom", "proxy"]
+    )
+    monkeypatch.setattr("headroom.install.runtime._runtime_env", lambda manifest: {"ENV": "1"})
+    signal_calls: list[int] = []
+    monkeypatch.setattr(
+        "headroom.install.runtime.signal.signal", lambda sig, fn: signal_calls.append(sig)
+    )
+
+    class FakeProc:
+        def __init__(self, returncode: int = 0, pid: int = 321) -> None:
+            self.returncode = returncode
+            self.pid = pid
+            self.terminated = False
+            self.killed = False
+
+        def wait(self, timeout: int | None = None) -> int:
+            return self.returncode
+
+        def poll(self):
+            return None if not self.terminated else self.returncode
+
+        def terminate(self) -> None:
+            self.terminated = True
+
+        def kill(self) -> None:
+            self.killed = True
+
+    fake_proc = FakeProc(returncode=7)
+    popen_calls: list[tuple[list[str], dict]] = []
+
+    def fake_popen(command: list[str], **kwargs):
+        popen_calls.append((command, kwargs))
+        return fake_proc
+
+    monkeypatch.setattr("headroom.install.runtime.subprocess.Popen", fake_popen)
+    manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-service",
+        runtime_kind="python",
+        supervisor_kind="service",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+    )
+    assert run_foreground(manifest) == 7
+    assert popen_calls[0][0] == ["headroom", "proxy"]
+    assert signal.SIGINT in signal_calls
+    assert signal.SIGTERM in signal_calls
+    assert _read_pid("default") is None
+
+    monkeypatch.setattr("headroom.install.runtime.resolve_headroom_command", lambda: ["headroom"])
+    monkeypatch.setattr("headroom.install.runtime.sys.platform", "win32")
+    monkeypatch.setattr("headroom.install.runtime.subprocess.DETACHED_PROCESS", 1, raising=False)
+    monkeypatch.setattr(
+        "headroom.install.runtime.subprocess.CREATE_NEW_PROCESS_GROUP", 2, raising=False
+    )
+    fake_proc_nt = FakeProc()
+    monkeypatch.setattr(
+        "headroom.install.runtime.subprocess.Popen", lambda command, **kwargs: fake_proc_nt
+    )
+    assert start_detached_agent("demo") is fake_proc_nt
+
+    monkeypatch.setattr("headroom.install.runtime.sys.platform", "linux")
+    fake_proc_posix = FakeProc()
+    monkeypatch.setattr(
+        "headroom.install.runtime.subprocess.Popen", lambda command, **kwargs: fake_proc_posix
+    )
+    assert start_detached_agent("demo") is fake_proc_posix
+
+
+def test_start_stop_wait_and_runtime_status_branches(monkeypatch, tmp_path: Path) -> None:
+    calls: list[list[str]] = []
+    monkeypatch.setattr(
+        "headroom.install.runtime.subprocess.run",
+        lambda command, **kwargs: calls.append(command) or type("Result", (), {"stdout": ""})(),
+    )
+    monkeypatch.setattr(
+        "headroom.install.runtime.build_runtime_command",
+        lambda manifest: [
+            "docker",
+            "run",
+            "--rm",
+            "--name",
+            "demo",
+            "-p",
+            "127.0.0.1:8787:8787",
+            "image",
+        ],
+    )
+    manifest = DeploymentManifest(
+        profile="default",
+        preset=InstallPreset.PERSISTENT_DOCKER.value,
+        runtime_kind="docker",
+        supervisor_kind="none",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        container_name="headroom-default",
+    )
+    start_persistent_docker(manifest)
+    assert calls == [
+        ["docker", "rm", "-f", "headroom-default"],
+        [
+            "docker",
+            "run",
+            "-d",
+            "--restart",
+            "unless-stopped",
+            "--name",
+            "headroom-default",
+            "-p",
+            "127.0.0.1:8787:8787",
+            "image",
+        ],
+    ]
+
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    python_manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-service",
+        runtime_kind="python",
+        supervisor_kind="service",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        health_url="http://127.0.0.1:8787/health",
+    )
+    _write_pid("default", 123)
+    killed: list[tuple[int, int]] = []
+    monkeypatch.setattr(
+        "headroom.install.runtime.os.kill", lambda pid, sig: killed.append((pid, sig))
+    )
+    stop_runtime(python_manifest)
+    assert killed == [(123, signal.SIGTERM)]
+    assert _read_pid("default") is None
+
+    _write_pid("default", 124)
+    monkeypatch.setattr(
+        "headroom.install.runtime.os.kill",
+        lambda pid, sig: (_ for _ in ()).throw(OSError("gone")),
+    )
+    stop_runtime(python_manifest)
+    assert _read_pid("default") is None
+
+    probe_results = iter([False, False, True])
+    sleeps: list[int] = []
+    monkeypatch.setattr("headroom.install.runtime.probe_ready", lambda url: next(probe_results))
+    monkeypatch.setattr(
+        "headroom.install.runtime.time.sleep", lambda seconds: sleeps.append(seconds)
+    )
+    assert wait_ready(python_manifest, timeout_seconds=3) is True
+    assert sleeps == [1, 1]
+
+    monkeypatch.setattr("headroom.install.runtime.probe_ready", lambda url: False)
+    sleeps.clear()
+    assert wait_ready(python_manifest, timeout_seconds=2) is False
+    assert sleeps == [1, 1]
+
+    class Result:
+        def __init__(self, stdout: str = "") -> None:
+            self.stdout = stdout
+
+    monkeypatch.setattr(
+        "headroom.install.runtime.subprocess.run",
+        lambda command, **kwargs: Result(stdout=""),
+    )
+    assert runtime_status(manifest) == "stopped"
+    assert runtime_status(python_manifest) == "stopped"
+
+    _write_pid("default", 125)
+    monkeypatch.setattr(
+        "headroom.install.runtime.os.kill", lambda pid, sig: (_ for _ in ()).throw(OSError())
+    )
+    assert runtime_status(python_manifest) == "stopped"
+
+
+def test_stop_runtime_for_docker_stops_and_removes_container(monkeypatch) -> None:
+    calls: list[list[str]] = []
+    manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-docker",
+        runtime_kind="docker",
+        supervisor_kind="none",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        container_name="headroom-default",
+    )
+
+    monkeypatch.setattr(
+        "headroom.install.runtime.subprocess.run",
+        lambda command, **kwargs: calls.append(command),
+    )
+
+    stop_runtime(manifest)
+
+    assert calls == [
+        ["docker", "stop", "headroom-default"],
+        ["docker", "rm", "-f", "headroom-default"],
+    ]
+
+
+def test_runtime_status_reads_container_and_pid_state(monkeypatch, tmp_path: Path) -> None:
+    docker_manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-docker",
+        runtime_kind="docker",
+        supervisor_kind="none",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        container_name="headroom-default",
+    )
+
+    class Result:
+        def __init__(self, stdout: str = "") -> None:
+            self.stdout = stdout
+
+    monkeypatch.setattr(
+        "headroom.install.runtime.subprocess.run",
+        lambda command, **kwargs: Result(stdout="headroom-default\n"),
+    )
+    assert runtime_status(docker_manifest) == "running"
+
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    pid_file = tmp_path / ".headroom" / "deploy" / "default" / "runner.pid"
+    pid_file.parent.mkdir(parents=True)
+    pid_file.write_text("123", encoding="utf-8")
+    monkeypatch.setattr("headroom.install.runtime.os.kill", lambda pid, sig: None)
+    python_manifest = DeploymentManifest(
+        profile="default",
+        preset="persistent-service",
+        runtime_kind="python",
+        supervisor_kind="service",
+        scope="user",
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+    )
+    assert runtime_status(python_manifest) == "running"
diff --git a/tests/test_install/test_supervisors.py b/tests/test_install/test_supervisors.py
index 80af6c9578e4485724059361835b2bab42595165..c77c9b2d67333574499be1561a00c39a05e7a86f 100644
--- a/tests/test_install/test_supervisors.py
+++ b/tests/test_install/test_supervisors.py
@@ -1,471 +1,471 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-import click
-import pytest
-
-from headroom.install.models import DeploymentManifest, SupervisorKind
-from headroom.install.supervisors import (
-    _command_for_script,
-    _linux_service_unit,
-    _linux_task_spec,
-    _macos_launchd_plist,
-    _render_unix_runner,
-    _render_windows_runner,
-    install_supervisor,
-    remove_supervisor,
-    render_runner_scripts,
-    start_supervisor,
-    stop_supervisor,
-)
-
-
-def _manifest(
-    *, profile: str = "default", scope: str = "user", supervisor: str = "service"
-) -> DeploymentManifest:
-    return DeploymentManifest(
-        profile=profile,
-        preset="persistent-service",
-        runtime_kind="python",
-        supervisor_kind=supervisor,
-        scope=scope,
-        provider_mode="manual",
-        targets=[],
-        port=8787,
-        host="127.0.0.1",
-        backend="anthropic",
-        service_name=f"headroom-{profile}",
-    )
-
-
-def test_linux_service_unit_uses_user_systemd_path(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    manifest = _manifest()
-
-    unit_path, content = _linux_service_unit(manifest, tmp_path / "run-headroom.sh")
-
-    assert unit_path == tmp_path / ".config" / "systemd" / "user" / "headroom-default.service"
-    assert "ExecStart=" + str(tmp_path / "run-headroom.sh") in content
-    assert "Restart=on-failure" in content
-
-
-def test_command_for_script_and_unix_runner(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr(
-        "headroom.install.supervisors.resolve_headroom_command",
-        lambda: ["python", "-m", "headroom"],
-    )
-
-    assert _command_for_script("install", "agent", "run") == [
-        "python",
-        "-m",
-        "headroom",
-        "install",
-        "agent",
-        "run",
-    ]
-
-    record = _render_unix_runner(
-        tmp_path / "scripts" / "run-headroom.sh", ["headroom", "run", "--flag"]
-    )
-    assert record.kind == "script"
-    content = Path(record.path).read_text(encoding="utf-8")
-    assert content.startswith("#!/usr/bin/env bash")
-    assert "exec headroom run --flag" in content
-
-
-def test_linux_task_spec_for_user_scope_includes_crontab_markers(tmp_path: Path) -> None:
-    manifest = _manifest(profile="smoke", supervisor=SupervisorKind.TASK.value)
-
-    cron_path, content = _linux_task_spec(manifest, tmp_path / "ensure-headroom.sh")
-
-    assert cron_path is None
-    assert "# >>> headroom smoke >>>" in content
-    assert "# <<< headroom smoke <<<" in content
-    assert "@reboot" in content
-    assert "*/5 * * * *" in content
-
-
-def test_macos_launchd_plist_switches_between_keepalive_and_interval(
-    monkeypatch, tmp_path: Path
-) -> None:
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-
-    service_manifest = _manifest(supervisor=SupervisorKind.SERVICE.value)
-    service_path, service_content = _macos_launchd_plist(
-        service_manifest, tmp_path / "run-headroom.sh"
-    )
-    assert service_path == tmp_path / "Library" / "LaunchAgents" / "com.headroom.default.plist"
-    assert "<key>KeepAlive</key>" in service_content
-    assert "<key>StartInterval</key>" not in service_content
-
-    task_manifest = _manifest(profile="tasky", supervisor=SupervisorKind.TASK.value)
-    task_path, task_content = _macos_launchd_plist(
-        task_manifest, tmp_path / "ensure-headroom.sh", interval=300
-    )
-    assert task_path == tmp_path / "Library" / "LaunchAgents" / "com.headroom.tasky.plist"
-    assert "<key>StartInterval</key>" in task_content
-    assert "<integer>300</integer>" in task_content
-
-
-def test_render_windows_runner_writes_ps1_and_cmd_wrappers(tmp_path: Path) -> None:
-    ps1_path = tmp_path / "run-headroom.ps1"
-    cmd_path = tmp_path / "run-headroom.cmd"
-
-    records = _render_windows_runner(
-        ps1_path,
-        cmd_path,
-        ["C:\\Program Files\\Python\\python.exe", "headroom", "install", "agent", "run"],
-    )
-
-    assert [record.path for record in records] == [str(ps1_path), str(cmd_path)]
-    ps1_content = ps1_path.read_text(encoding="utf-8")
-    cmd_content = cmd_path.read_text(encoding="utf-8")
-    assert '& "C:\\Program Files\\Python\\python.exe" headroom install agent run' in ps1_content
-    assert (
-        'powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0run-headroom.ps1" %*'
-        in cmd_content
-    )
-
-
-def test_render_runner_scripts_writes_unix_scripts(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
-    monkeypatch.setattr(
-        "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom"]
-    )
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    manifest = _manifest()
-
-    records = render_runner_scripts(manifest)
-
-    assert {record.path.split("\\")[-1].split("/")[-1] for record in records} == {
-        "run-headroom.sh",
-        "ensure-headroom.sh",
-    }
-
-
-def test_render_runner_scripts_writes_windows_scripts(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
-    monkeypatch.setattr(
-        "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom.exe"]
-    )
-    monkeypatch.setattr(
-        "headroom.install.supervisors.windows_run_script_path",
-        lambda profile: tmp_path / "run-headroom.ps1",
-    )
-    monkeypatch.setattr(
-        "headroom.install.supervisors.windows_run_cmd_path",
-        lambda profile: tmp_path / "run-headroom.cmd",
-    )
-    monkeypatch.setattr(
-        "headroom.install.supervisors.windows_ensure_script_path",
-        lambda profile: tmp_path / "ensure-headroom.ps1",
-    )
-    monkeypatch.setattr(
-        "headroom.install.supervisors.windows_ensure_cmd_path",
-        lambda profile: tmp_path / "ensure-headroom.cmd",
-    )
-
-    records = render_runner_scripts(_manifest(profile="win"))
-
-    assert [Path(record.path).name for record in records] == [
-        "run-headroom.ps1",
-        "run-headroom.cmd",
-        "ensure-headroom.ps1",
-        "ensure-headroom.cmd",
-    ]
-
-
-def test_install_supervisor_none_returns_runner_records(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
-    monkeypatch.setattr(
-        "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom"]
-    )
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    manifest = _manifest(supervisor=SupervisorKind.NONE.value)
-
-    records = install_supervisor(manifest)
-
-    assert len(records) == 2
-    assert all(record.kind == "script" for record in records)
-
-
-def test_start_and_stop_supervisor_use_linux_systemctl(monkeypatch) -> None:
-    calls: list[list[str]] = []
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
-    monkeypatch.setattr(
-        "headroom.install.supervisors.subprocess.run",
-        lambda command, **kwargs: calls.append(command),
-    )
-    manifest = _manifest()
-
-    start_supervisor(manifest)
-    stop_supervisor(manifest)
-
-    assert calls == [
-        ["systemctl", "--user", "restart", "headroom-default"],
-        ["systemctl", "--user", "stop", "headroom-default"],
-    ]
-
-
-def test_install_supervisor_linux_service_and_tasks(monkeypatch, tmp_path: Path) -> None:
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
-    run_script = tmp_path / "run-headroom.sh"
-    ensure_script = tmp_path / "ensure-headroom.sh"
-    monkeypatch.setattr(
-        "headroom.install.supervisors.render_runner_scripts",
-        lambda manifest: [
-            type("Record", (), {"kind": "script", "path": run_script.as_posix()})(),
-            type("Record", (), {"kind": "script", "path": ensure_script.as_posix()})(),
-        ],
-    )
-    unit_path = tmp_path / "headroom-default.service"
-    monkeypatch.setattr(
-        "headroom.install.supervisors._linux_service_unit",
-        lambda manifest, script: (unit_path, "UNIT"),
-    )
-    calls: list[tuple[list[str], dict]] = []
-
-    def fake_run(command: list[str], **kwargs):
-        calls.append((command, kwargs))
-        return type("Result", (), {"returncode": 0, "stdout": "# old cron\n"})()
-
-    monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)
-
-    service_records = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    assert unit_path.read_text(encoding="utf-8") == "UNIT"
-    assert ["systemctl", "--user", "daemon-reload"] in [call[0] for call in calls]
-    assert ["systemctl", "--user", "enable", "headroom-default"] in [call[0] for call in calls]
-    assert service_records[-1].kind == "service-unit"
-
-    cron_path = tmp_path / "headroom-system"
-    monkeypatch.setattr(
-        "headroom.install.supervisors._linux_task_spec",
-        lambda manifest, script: (cron_path, "@reboot root ensure\n"),
-    )
-    system_task_records = install_supervisor(
-        _manifest(profile="system-task", scope="system", supervisor=SupervisorKind.TASK.value)
-    )
-    assert cron_path.read_text(encoding="utf-8") == "@reboot root ensure\n"
-    assert system_task_records[-1].kind == "cron"
-
-    monkeypatch.setattr(
-        "headroom.install.supervisors._linux_task_spec",
-        lambda manifest, script: (
-            None,
-            "# >>> headroom default >>>\n@reboot ensure\n# <<< headroom default <<<\n",
-        ),
-    )
-    user_task_records = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
-    assert user_task_records[-1].kind == "crontab"
-    assert calls[-1][0] == ["crontab", "-"]
-    assert "@reboot ensure" in calls[-1][1]["input"]
-
-
-def test_install_supervisor_darwin_windows_and_unsupported(monkeypatch, tmp_path: Path) -> None:
-    run_script = tmp_path / "run-headroom.sh"
-    ensure_script = tmp_path / "ensure-headroom.sh"
-    monkeypatch.setattr(
-        "headroom.install.supervisors.render_runner_scripts",
-        lambda manifest: [
-            type("Record", (), {"kind": "script", "path": run_script.as_posix()})(),
-            type("Record", (), {"kind": "script", "path": ensure_script.as_posix()})(),
-        ],
-    )
-    calls: list[list[str]] = []
-    monkeypatch.setattr(
-        "headroom.install.supervisors.subprocess.run",
-        lambda command, **kwargs: calls.append(command),
-    )
-    monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 123, raising=False)
-
-    plist_path = tmp_path / "com.headroom.default.plist"
-    monkeypatch.setattr(
-        "headroom.install.supervisors._macos_launchd_plist",
-        lambda manifest, script, interval=None: (plist_path, f"plist-{interval}"),
-    )
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
-    service_records = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    task_records = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
-    assert plist_path.read_text(encoding="utf-8") == "plist-300"
-    assert service_records[-1].kind == "plist"
-    assert task_records[-1].kind == "plist"
-    assert ["launchctl", "bootstrap", "gui/123", str(plist_path)] in calls
-
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
-    monkeypatch.setattr(
-        "headroom.install.supervisors.windows_run_cmd_path",
-        lambda profile: Path(f"C:\\tmp\\{profile}\\run-headroom.cmd"),
-    )
-    monkeypatch.setattr(
-        "headroom.install.supervisors.windows_ensure_cmd_path",
-        lambda profile: Path(f"C:\\tmp\\{profile}\\ensure-headroom.cmd"),
-    )
-    win_service = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    win_task = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
-    assert win_service[-1].kind == "windows-service"
-    assert win_task[-2].path.endswith("-startup")
-    assert [
-        "sc.exe",
-        "create",
-        "headroom-default",
-        'binPath= cmd.exe /c "C:\\tmp\\default\\run-headroom.cmd"',
-        "start= auto",
-    ] in calls
-    assert [
-        "schtasks",
-        "/Create",
-        "/TN",
-        "headroom-default-health",
-        "/TR",
-        "C:\\tmp\\default\\ensure-headroom.cmd",
-        "/SC",
-        "MINUTE",
-        "/MO",
-        "5",
-        "/F",
-    ] in calls
-
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")
-    with pytest.raises(click.ClickException, match="not supported"):
-        install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-
-
-def test_start_and_stop_supervisor_darwin_windows_and_none(monkeypatch) -> None:
-    calls: list[list[str]] = []
-    monkeypatch.setattr(
-        "headroom.install.supervisors.subprocess.run",
-        lambda command, **kwargs: calls.append(command),
-    )
-    monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 77, raising=False)
-
-    start_supervisor(_manifest(supervisor=SupervisorKind.NONE.value))
-    stop_supervisor(_manifest(supervisor=SupervisorKind.NONE.value))
-    assert calls == []
-
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
-    start_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    assert calls == [
-        ["launchctl", "kickstart", "-k", "gui/77/com.headroom.default"],
-        ["launchctl", "bootout", "gui/77/com.headroom.default"],
-    ]
-
-    calls.clear()
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
-    start_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    assert calls == [
-        ["sc.exe", "start", "headroom-default"],
-        ["sc.exe", "stop", "headroom-default"],
-    ]
-
-
-def test_remove_supervisor_removes_user_crontab_block(monkeypatch) -> None:
-    calls: list[tuple[list[str], str | None]] = []
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
-
-    class Result:
-        def __init__(self, returncode: int = 0, stdout: str = "") -> None:
-            self.returncode = returncode
-            self.stdout = stdout
-
-    def fake_run(command: list[str], **kwargs):
-        calls.append((command, kwargs.get("input")))
-        if command == ["crontab", "-l"]:
-            return Result(
-                stdout="# >>> headroom default >>>\n@reboot /tmp/ensure\n# <<< headroom default <<<\n"
-            )
-        return Result()
-
-    monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)
-    manifest = _manifest(supervisor=SupervisorKind.TASK.value)
-
-    remove_supervisor(manifest)
-
-    assert calls[0][0] == ["crontab", "-l"]
-    assert calls[1][0] == ["crontab", "-"]
-
-
-def test_remove_supervisor_linux_service_cron_path_and_missing_crontab(
-    monkeypatch, tmp_path: Path
-) -> None:
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
-    calls: list[list[str]] = []
-
-    def fake_run(command: list[str], **kwargs):
-        calls.append(command)
-        return type("Result", (), {"returncode": 1, "stdout": ""})()
-
-    monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)
-    unit_path = tmp_path / "headroom-default.service"
-    unit_path.write_text("unit", encoding="utf-8")
-    monkeypatch.setattr(
-        "headroom.install.supervisors._linux_service_unit",
-        lambda manifest, script: (unit_path, "unit"),
-    )
-    remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    assert not unit_path.exists()
-    assert ["systemctl", "--user", "disable", "--now", "headroom-default"] in calls
-    assert ["systemctl", "--user", "daemon-reload"] in calls
-
-    cron_path = tmp_path / "headroom-task"
-    cron_path.write_text("cron", encoding="utf-8")
-    monkeypatch.setattr(
-        "headroom.install.supervisors._linux_task_spec",
-        lambda manifest, script: (cron_path, "cron"),
-    )
-    remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
-    assert not cron_path.exists()
-
-    monkeypatch.setattr(
-        "headroom.install.supervisors._linux_task_spec",
-        lambda manifest, script: (None, "cron"),
-    )
-    remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
-    assert calls[-1] == ["crontab", "-l"]
-
-
-def test_remove_supervisor_darwin_and_windows(monkeypatch, tmp_path: Path) -> None:
-    calls: list[list[str]] = []
-    monkeypatch.setattr(
-        "headroom.install.supervisors.subprocess.run",
-        lambda command, **kwargs: calls.append(command),
-    )
-    monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 55, raising=False)
-
-    plist_path = tmp_path / "com.headroom.default.plist"
-    plist_path.write_text("plist", encoding="utf-8")
-    monkeypatch.setattr(
-        "headroom.install.supervisors.unix_run_script_path",
-        lambda profile: tmp_path / "run-headroom.sh",
-    )
-    monkeypatch.setattr(
-        "headroom.install.supervisors.unix_ensure_script_path",
-        lambda profile: tmp_path / "ensure-headroom.sh",
-    )
-    monkeypatch.setattr(
-        "headroom.install.supervisors._macos_launchd_plist",
-        lambda manifest, script, interval=None: (plist_path, "plist"),
-    )
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
-    remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    assert not plist_path.exists()
-    assert calls[0] == ["launchctl", "bootout", "gui/55/com.headroom.default"]
-
-    calls.clear()
-    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
-    remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
-    remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
-    assert calls == [
-        ["sc.exe", "stop", "headroom-default"],
-        ["sc.exe", "delete", "headroom-default"],
-        ["schtasks", "/Delete", "/TN", "headroom-default-startup", "/F"],
-        ["schtasks", "/Delete", "/TN", "headroom-default-health", "/F"],
-    ]
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import pytest
+
+from headroom.install.models import DeploymentManifest, SupervisorKind
+from headroom.install.supervisors import (
+    _command_for_script,
+    _linux_service_unit,
+    _linux_task_spec,
+    _macos_launchd_plist,
+    _render_unix_runner,
+    _render_windows_runner,
+    install_supervisor,
+    remove_supervisor,
+    render_runner_scripts,
+    start_supervisor,
+    stop_supervisor,
+)
+
+
+def _manifest(
+    *, profile: str = "default", scope: str = "user", supervisor: str = "service"
+) -> DeploymentManifest:
+    return DeploymentManifest(
+        profile=profile,
+        preset="persistent-service",
+        runtime_kind="python",
+        supervisor_kind=supervisor,
+        scope=scope,
+        provider_mode="manual",
+        targets=[],
+        port=8787,
+        host="127.0.0.1",
+        backend="anthropic",
+        service_name=f"headroom-{profile}",
+    )
+
+
+def test_linux_service_unit_uses_user_systemd_path(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    manifest = _manifest()
+
+    unit_path, content = _linux_service_unit(manifest, tmp_path / "run-headroom.sh")
+
+    assert unit_path == tmp_path / ".config" / "systemd" / "user" / "headroom-default.service"
+    assert "ExecStart=" + str(tmp_path / "run-headroom.sh") in content
+    assert "Restart=on-failure" in content
+
+
+def test_command_for_script_and_unix_runner(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(
+        "headroom.install.supervisors.resolve_headroom_command",
+        lambda: ["python", "-m", "headroom"],
+    )
+
+    assert _command_for_script("install", "agent", "run") == [
+        "python",
+        "-m",
+        "headroom",
+        "install",
+        "agent",
+        "run",
+    ]
+
+    record = _render_unix_runner(
+        tmp_path / "scripts" / "run-headroom.sh", ["headroom", "run", "--flag"]
+    )
+    assert record.kind == "script"
+    content = Path(record.path).read_text(encoding="utf-8")
+    assert content.startswith("#!/usr/bin/env bash")
+    assert "exec headroom run --flag" in content
+
+
+def test_linux_task_spec_for_user_scope_includes_crontab_markers(tmp_path: Path) -> None:
+    manifest = _manifest(profile="smoke", supervisor=SupervisorKind.TASK.value)
+
+    cron_path, content = _linux_task_spec(manifest, tmp_path / "ensure-headroom.sh")
+
+    assert cron_path is None
+    assert "# >>> headroom smoke >>>" in content
+    assert "# <<< headroom smoke <<<" in content
+    assert "@reboot" in content
+    assert "*/5 * * * *" in content
+
+
+def test_macos_launchd_plist_switches_between_keepalive_and_interval(
+    monkeypatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+    service_manifest = _manifest(supervisor=SupervisorKind.SERVICE.value)
+    service_path, service_content = _macos_launchd_plist(
+        service_manifest, tmp_path / "run-headroom.sh"
+    )
+    assert service_path == tmp_path / "Library" / "LaunchAgents" / "com.headroom.default.plist"
+    assert "<key>KeepAlive</key>" in service_content
+    assert "<key>StartInterval</key>" not in service_content
+
+    task_manifest = _manifest(profile="tasky", supervisor=SupervisorKind.TASK.value)
+    task_path, task_content = _macos_launchd_plist(
+        task_manifest, tmp_path / "ensure-headroom.sh", interval=300
+    )
+    assert task_path == tmp_path / "Library" / "LaunchAgents" / "com.headroom.tasky.plist"
+    assert "<key>StartInterval</key>" in task_content
+    assert "<integer>300</integer>" in task_content
+
+
+def test_render_windows_runner_writes_ps1_and_cmd_wrappers(tmp_path: Path) -> None:
+    ps1_path = tmp_path / "run-headroom.ps1"
+    cmd_path = tmp_path / "run-headroom.cmd"
+
+    records = _render_windows_runner(
+        ps1_path,
+        cmd_path,
+        ["C:\\Program Files\\Python\\python.exe", "headroom", "install", "agent", "run"],
+    )
+
+    assert [record.path for record in records] == [str(ps1_path), str(cmd_path)]
+    ps1_content = ps1_path.read_text(encoding="utf-8")
+    cmd_content = cmd_path.read_text(encoding="utf-8")
+    assert '& "C:\\Program Files\\Python\\python.exe" headroom install agent run' in ps1_content
+    assert (
+        'powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0run-headroom.ps1" %*'
+        in cmd_content
+    )
+
+
+def test_render_runner_scripts_writes_unix_scripts(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
+    monkeypatch.setattr(
+        "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom"]
+    )
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    manifest = _manifest()
+
+    records = render_runner_scripts(manifest)
+
+    assert {record.path.split("\\")[-1].split("/")[-1] for record in records} == {
+        "run-headroom.sh",
+        "ensure-headroom.sh",
+    }
+
+
+def test_render_runner_scripts_writes_windows_scripts(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
+    monkeypatch.setattr(
+        "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom.exe"]
+    )
+    monkeypatch.setattr(
+        "headroom.install.supervisors.windows_run_script_path",
+        lambda profile: tmp_path / "run-headroom.ps1",
+    )
+    monkeypatch.setattr(
+        "headroom.install.supervisors.windows_run_cmd_path",
+        lambda profile: tmp_path / "run-headroom.cmd",
+    )
+    monkeypatch.setattr(
+        "headroom.install.supervisors.windows_ensure_script_path",
+        lambda profile: tmp_path / "ensure-headroom.ps1",
+    )
+    monkeypatch.setattr(
+        "headroom.install.supervisors.windows_ensure_cmd_path",
+        lambda profile: tmp_path / "ensure-headroom.cmd",
+    )
+
+    records = render_runner_scripts(_manifest(profile="win"))
+
+    assert [Path(record.path).name for record in records] == [
+        "run-headroom.ps1",
+        "run-headroom.cmd",
+        "ensure-headroom.ps1",
+        "ensure-headroom.cmd",
+    ]
+
+
+def test_install_supervisor_none_returns_runner_records(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
+    monkeypatch.setattr(
+        "headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom"]
+    )
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    manifest = _manifest(supervisor=SupervisorKind.NONE.value)
+
+    records = install_supervisor(manifest)
+
+    assert len(records) == 2
+    assert all(record.kind == "script" for record in records)
+
+
+def test_start_and_stop_supervisor_use_linux_systemctl(monkeypatch) -> None:
+    calls: list[list[str]] = []
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
+    monkeypatch.setattr(
+        "headroom.install.supervisors.subprocess.run",
+        lambda command, **kwargs: calls.append(command),
+    )
+    manifest = _manifest()
+
+    start_supervisor(manifest)
+    stop_supervisor(manifest)
+
+    assert calls == [
+        ["systemctl", "--user", "restart", "headroom-default"],
+        ["systemctl", "--user", "stop", "headroom-default"],
+    ]
+
+
+def test_install_supervisor_linux_service_and_tasks(monkeypatch, tmp_path: Path) -> None:
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
+    run_script = tmp_path / "run-headroom.sh"
+    ensure_script = tmp_path / "ensure-headroom.sh"
+    monkeypatch.setattr(
+        "headroom.install.supervisors.render_runner_scripts",
+        lambda manifest: [
+            type("Record", (), {"kind": "script", "path": run_script.as_posix()})(),
+            type("Record", (), {"kind": "script", "path": ensure_script.as_posix()})(),
+        ],
+    )
+    unit_path = tmp_path / "headroom-default.service"
+    monkeypatch.setattr(
+        "headroom.install.supervisors._linux_service_unit",
+        lambda manifest, script: (unit_path, "UNIT"),
+    )
+    calls: list[tuple[list[str], dict]] = []
+
+    def fake_run(command: list[str], **kwargs):
+        calls.append((command, kwargs))
+        return type("Result", (), {"returncode": 0, "stdout": "# old cron\n"})()
+
+    monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)
+
+    service_records = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    assert unit_path.read_text(encoding="utf-8") == "UNIT"
+    assert ["systemctl", "--user", "daemon-reload"] in [call[0] for call in calls]
+    assert ["systemctl", "--user", "enable", "headroom-default"] in [call[0] for call in calls]
+    assert service_records[-1].kind == "service-unit"
+
+    cron_path = tmp_path / "headroom-system"
+    monkeypatch.setattr(
+        "headroom.install.supervisors._linux_task_spec",
+        lambda manifest, script: (cron_path, "@reboot root ensure\n"),
+    )
+    system_task_records = install_supervisor(
+        _manifest(profile="system-task", scope="system", supervisor=SupervisorKind.TASK.value)
+    )
+    assert cron_path.read_text(encoding="utf-8") == "@reboot root ensure\n"
+    assert system_task_records[-1].kind == "cron"
+
+    monkeypatch.setattr(
+        "headroom.install.supervisors._linux_task_spec",
+        lambda manifest, script: (
+            None,
+            "# >>> headroom default >>>\n@reboot ensure\n# <<< headroom default <<<\n",
+        ),
+    )
+    user_task_records = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
+    assert user_task_records[-1].kind == "crontab"
+    assert calls[-1][0] == ["crontab", "-"]
+    assert "@reboot ensure" in calls[-1][1]["input"]
+
+
+def test_install_supervisor_darwin_windows_and_unsupported(monkeypatch, tmp_path: Path) -> None:
+    run_script = tmp_path / "run-headroom.sh"
+    ensure_script = tmp_path / "ensure-headroom.sh"
+    monkeypatch.setattr(
+        "headroom.install.supervisors.render_runner_scripts",
+        lambda manifest: [
+            type("Record", (), {"kind": "script", "path": run_script.as_posix()})(),
+            type("Record", (), {"kind": "script", "path": ensure_script.as_posix()})(),
+        ],
+    )
+    calls: list[list[str]] = []
+    monkeypatch.setattr(
+        "headroom.install.supervisors.subprocess.run",
+        lambda command, **kwargs: calls.append(command),
+    )
+    monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 123, raising=False)
+
+    plist_path = tmp_path / "com.headroom.default.plist"
+    monkeypatch.setattr(
+        "headroom.install.supervisors._macos_launchd_plist",
+        lambda manifest, script, interval=None: (plist_path, f"plist-{interval}"),
+    )
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
+    service_records = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    task_records = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
+    assert plist_path.read_text(encoding="utf-8") == "plist-300"
+    assert service_records[-1].kind == "plist"
+    assert task_records[-1].kind == "plist"
+    assert ["launchctl", "bootstrap", "gui/123", str(plist_path)] in calls
+
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
+    monkeypatch.setattr(
+        "headroom.install.supervisors.windows_run_cmd_path",
+        lambda profile: Path(f"C:\\tmp\\{profile}\\run-headroom.cmd"),
+    )
+    monkeypatch.setattr(
+        "headroom.install.supervisors.windows_ensure_cmd_path",
+        lambda profile: Path(f"C:\\tmp\\{profile}\\ensure-headroom.cmd"),
+    )
+    win_service = install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    win_task = install_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
+    assert win_service[-1].kind == "windows-service"
+    assert win_task[-2].path.endswith("-startup")
+    assert [
+        "sc.exe",
+        "create",
+        "headroom-default",
+        'binPath= cmd.exe /c "C:\\tmp\\default\\run-headroom.cmd"',
+        "start= auto",
+    ] in calls
+    assert [
+        "schtasks",
+        "/Create",
+        "/TN",
+        "headroom-default-health",
+        "/TR",
+        "C:\\tmp\\default\\ensure-headroom.cmd",
+        "/SC",
+        "MINUTE",
+        "/MO",
+        "5",
+        "/F",
+    ] in calls
+
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "plan9")
+    with pytest.raises(click.ClickException, match="not supported"):
+        install_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+
+
+def test_start_and_stop_supervisor_darwin_windows_and_none(monkeypatch) -> None:
+    calls: list[list[str]] = []
+    monkeypatch.setattr(
+        "headroom.install.supervisors.subprocess.run",
+        lambda command, **kwargs: calls.append(command),
+    )
+    monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 77, raising=False)
+
+    start_supervisor(_manifest(supervisor=SupervisorKind.NONE.value))
+    stop_supervisor(_manifest(supervisor=SupervisorKind.NONE.value))
+    assert calls == []
+
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
+    start_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    assert calls == [
+        ["launchctl", "kickstart", "-k", "gui/77/com.headroom.default"],
+        ["launchctl", "bootout", "gui/77/com.headroom.default"],
+    ]
+
+    calls.clear()
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
+    start_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    stop_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    assert calls == [
+        ["sc.exe", "start", "headroom-default"],
+        ["sc.exe", "stop", "headroom-default"],
+    ]
+
+
+def test_remove_supervisor_removes_user_crontab_block(monkeypatch) -> None:
+    calls: list[tuple[list[str], str | None]] = []
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
+
+    class Result:
+        def __init__(self, returncode: int = 0, stdout: str = "") -> None:
+            self.returncode = returncode
+            self.stdout = stdout
+
+    def fake_run(command: list[str], **kwargs):
+        calls.append((command, kwargs.get("input")))
+        if command == ["crontab", "-l"]:
+            return Result(
+                stdout="# >>> headroom default >>>\n@reboot /tmp/ensure\n# <<< headroom default <<<\n"
+            )
+        return Result()
+
+    monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)
+    manifest = _manifest(supervisor=SupervisorKind.TASK.value)
+
+    remove_supervisor(manifest)
+
+    assert calls[0][0] == ["crontab", "-l"]
+    assert calls[1][0] == ["crontab", "-"]
+
+
+def test_remove_supervisor_linux_service_cron_path_and_missing_crontab(
+    monkeypatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
+    calls: list[list[str]] = []
+
+    def fake_run(command: list[str], **kwargs):
+        calls.append(command)
+        return type("Result", (), {"returncode": 1, "stdout": ""})()
+
+    monkeypatch.setattr("headroom.install.supervisors.subprocess.run", fake_run)
+    unit_path = tmp_path / "headroom-default.service"
+    unit_path.write_text("unit", encoding="utf-8")
+    monkeypatch.setattr(
+        "headroom.install.supervisors._linux_service_unit",
+        lambda manifest, script: (unit_path, "unit"),
+    )
+    remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    assert not unit_path.exists()
+    assert ["systemctl", "--user", "disable", "--now", "headroom-default"] in calls
+    assert ["systemctl", "--user", "daemon-reload"] in calls
+
+    cron_path = tmp_path / "headroom-task"
+    cron_path.write_text("cron", encoding="utf-8")
+    monkeypatch.setattr(
+        "headroom.install.supervisors._linux_task_spec",
+        lambda manifest, script: (cron_path, "cron"),
+    )
+    remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
+    assert not cron_path.exists()
+
+    monkeypatch.setattr(
+        "headroom.install.supervisors._linux_task_spec",
+        lambda manifest, script: (None, "cron"),
+    )
+    remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
+    assert calls[-1] == ["crontab", "-l"]
+
+
+def test_remove_supervisor_darwin_and_windows(monkeypatch, tmp_path: Path) -> None:
+    calls: list[list[str]] = []
+    monkeypatch.setattr(
+        "headroom.install.supervisors.subprocess.run",
+        lambda command, **kwargs: calls.append(command),
+    )
+    monkeypatch.setattr("headroom.install.supervisors.os.getuid", lambda: 55, raising=False)
+
+    plist_path = tmp_path / "com.headroom.default.plist"
+    plist_path.write_text("plist", encoding="utf-8")
+    monkeypatch.setattr(
+        "headroom.install.supervisors.unix_run_script_path",
+        lambda profile: tmp_path / "run-headroom.sh",
+    )
+    monkeypatch.setattr(
+        "headroom.install.supervisors.unix_ensure_script_path",
+        lambda profile: tmp_path / "ensure-headroom.sh",
+    )
+    monkeypatch.setattr(
+        "headroom.install.supervisors._macos_launchd_plist",
+        lambda manifest, script, interval=None: (plist_path, "plist"),
+    )
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "darwin")
+    remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    assert not plist_path.exists()
+    assert calls[0] == ["launchctl", "bootout", "gui/55/com.headroom.default"]
+
+    calls.clear()
+    monkeypatch.setattr("headroom.install.supervisors.sys.platform", "win32")
+    remove_supervisor(_manifest(supervisor=SupervisorKind.SERVICE.value))
+    remove_supervisor(_manifest(supervisor=SupervisorKind.TASK.value))
+    assert calls == [
+        ["sc.exe", "stop", "headroom-default"],
+        ["sc.exe", "delete", "headroom-default"],
+        ["schtasks", "/Delete", "/TN", "headroom-default-startup", "/F"],
+        ["schtasks", "/Delete", "/TN", "headroom-default-health", "/F"],
+    ]
diff --git a/tests/test_plugin_manifests.py b/tests/test_plugin_manifests.py
index 1a80c45d21f5426983577857668fb8c8482dd735..578f4f279746532f244ba0a69c11bcb23de8d9c3 100644
--- a/tests/test_plugin_manifests.py
+++ b/tests/test_plugin_manifests.py
@@ -1,55 +1,55 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-
-
-def _load_json(relative_path: str) -> object:
-    return json.loads((REPO_ROOT / relative_path).read_text(encoding="utf-8"))
-
-
-def test_marketplace_manifests_match() -> None:
-    assert _load_json(".claude-plugin/marketplace.json") == _load_json(
-        ".github/plugin/marketplace.json"
-    )
-
-
-def test_plugin_manifests_share_core_metadata() -> None:
-    claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")
-    copilot = _load_json("plugins/headroom-agent-hooks/.github/plugin/plugin.json")
-    assert isinstance(claude, dict)
-    assert isinstance(copilot, dict)
-    for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):
-        assert claude[key] == copilot[key]
-    assert "hooks" not in claude
-    assert copilot["hooks"] == "./hooks"
-
-
-def test_marketplace_entry_points_to_plugin_root() -> None:
-    marketplace = _load_json(".claude-plugin/marketplace.json")
-    assert isinstance(marketplace, dict)
-    plugins = marketplace["plugins"]
-    assert isinstance(plugins, list)
-    plugin = plugins[0]
-    assert plugin["name"] == "headroom"
-    plugin_root = (REPO_ROOT / plugin["source"]).resolve()
-    assert plugin_root.is_dir()
-    assert (plugin_root / ".claude-plugin" / "plugin.json").is_file()
-    assert (plugin_root / "hooks" / "hooks.json").is_file()
-
-
-def test_plugin_metadata_points_to_upstream_repo() -> None:
-    expected_repo = "https://github.com/chopratejas/headroom"
-    marketplace = _load_json(".claude-plugin/marketplace.json")
-    claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")
-    assert isinstance(marketplace, dict)
-    assert isinstance(claude, dict)
-    plugin = marketplace["plugins"][0]
-    assert plugin["author"]["url"] == expected_repo
-    assert plugin["homepage"] == expected_repo
-    assert plugin["repository"] == expected_repo
-    assert claude["author"]["url"] == expected_repo
-    assert claude["homepage"] == expected_repo
-    assert claude["repository"] == expected_repo
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def _load_json(relative_path: str) -> object:
+    return json.loads((REPO_ROOT / relative_path).read_text(encoding="utf-8"))
+
+
+def test_marketplace_manifests_match() -> None:
+    assert _load_json(".claude-plugin/marketplace.json") == _load_json(
+        ".github/plugin/marketplace.json"
+    )
+
+
+def test_plugin_manifests_share_core_metadata() -> None:
+    claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")
+    copilot = _load_json("plugins/headroom-agent-hooks/.github/plugin/plugin.json")
+    assert isinstance(claude, dict)
+    assert isinstance(copilot, dict)
+    for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):
+        assert claude[key] == copilot[key]
+    assert "hooks" not in claude
+    assert copilot["hooks"] == "./hooks"
+
+
+def test_marketplace_entry_points_to_plugin_root() -> None:
+    marketplace = _load_json(".claude-plugin/marketplace.json")
+    assert isinstance(marketplace, dict)
+    plugins = marketplace["plugins"]
+    assert isinstance(plugins, list)
+    plugin = plugins[0]
+    assert plugin["name"] == "headroom"
+    plugin_root = (REPO_ROOT / plugin["source"]).resolve()
+    assert plugin_root.is_dir()
+    assert (plugin_root / ".claude-plugin" / "plugin.json").is_file()
+    assert (plugin_root / "hooks" / "hooks.json").is_file()
+
+
+def test_plugin_metadata_points_to_upstream_repo() -> None:
+    expected_repo = "https://github.com/chopratejas/headroom"
+    marketplace = _load_json(".claude-plugin/marketplace.json")
+    claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")
+    assert isinstance(marketplace, dict)
+    assert isinstance(claude, dict)
+    plugin = marketplace["plugins"][0]
+    assert plugin["author"]["url"] == expected_repo
+    assert plugin["homepage"] == expected_repo
+    assert plugin["repository"] == expected_repo
+    assert claude["author"]["url"] == expected_repo
+    assert claude["homepage"] == expected_repo
+    assert claude["repository"] == expected_repo
diff --git a/tests/test_pricing.py b/tests/test_pricing.py
index b3b94d3d1f5ecac2c9aece3968e9a557967719e3..616650cd6c57f3a9e50eb97a6921faff9f85a021 100644
--- a/tests/test_pricing.py
+++ b/tests/test_pricing.py
@@ -1,130 +1,130 @@
-from __future__ import annotations
-
-from dataclasses import FrozenInstanceError
-from datetime import date, timedelta
-
-import pytest
-
-import headroom.pricing as pricing
-from headroom.pricing.anthropic_prices import ANTHROPIC_PRICES, get_anthropic_registry
-from headroom.pricing.openai_prices import OPENAI_PRICES, get_openai_registry
-from headroom.pricing.registry import ModelPricing, PricingRegistry
-
-
-def test_pricing_public_exports_and_provider_registries() -> None:
-    assert pricing.ModelPricing is ModelPricing
-    assert pricing.PricingRegistry is PricingRegistry
-    assert "get_openai_registry" in pricing.__all__
-    assert "get_anthropic_registry" in pricing.__all__
-    assert "estimate_cost" in pricing.__all__
-
-    openai_registry = get_openai_registry()
-    anthropic_registry = get_anthropic_registry()
-    assert openai_registry.source_url == "https://openai.com/api/pricing/"
-    assert anthropic_registry.source_url == "https://www.anthropic.com/pricing"
-    assert openai_registry.prices["gpt-4o"] == OPENAI_PRICES["gpt-4o"]
-    assert (
-        anthropic_registry.prices["claude-3-5-sonnet-20241022"]
-        == ANTHROPIC_PRICES["claude-3-5-sonnet-20241022"]
-    )
-
-    openai_registry.prices.pop("gpt-4o")
-    anthropic_registry.prices.pop("claude-3-5-sonnet-20241022")
-    assert "gpt-4o" in OPENAI_PRICES
-    assert "claude-3-5-sonnet-20241022" in ANTHROPIC_PRICES
-
-
-def test_model_pricing_is_frozen() -> None:
-    model = ModelPricing(model="demo", provider="test", input_per_1m=1.5, output_per_1m=2.5)
-    with pytest.raises(FrozenInstanceError):
-        model.model = "other"  # type: ignore[misc]
-
-
-def test_registry_staleness_and_warning() -> None:
-    fresh = PricingRegistry(last_updated=date.today() - timedelta(days=30))
-    assert fresh.is_stale() is False
-    assert fresh.staleness_warning() is None
-
-    stale = PricingRegistry(
-        last_updated=date.today() - timedelta(days=31),
-        source_url="https://example.test/pricing",
-    )
-    assert stale.is_stale() is True
-    assert stale.staleness_warning() == (
-        f"Pricing data is 31 days old (last updated: {stale.last_updated})."
-        " Please verify at: https://example.test/pricing"
-    )
-
-
-def test_registry_estimate_cost_with_all_token_types() -> None:
-    registry = PricingRegistry(
-        last_updated=date.today() - timedelta(days=31),
-        prices={
-            "demo": ModelPricing(
-                model="demo",
-                provider="test",
-                input_per_1m=2.0,
-                output_per_1m=4.0,
-                cached_input_per_1m=1.0,
-                batch_input_per_1m=0.5,
-                batch_output_per_1m=0.25,
-            )
-        },
-    )
-
-    estimate = registry.estimate_cost(
-        "demo",
-        input_tokens=1_000_000,
-        output_tokens=500_000,
-        cached_input_tokens=250_000,
-        batch_input_tokens=200_000,
-        batch_output_tokens=100_000,
-    )
-
-    assert estimate.cost_usd == pytest.approx(4.375)
-    assert estimate.breakdown == {
-        "input": {"tokens": 1_000_000, "rate_per_1m": 2.0, "cost_usd": 2.0},
-        "output": {"tokens": 500_000, "rate_per_1m": 4.0, "cost_usd": 2.0},
-        "cached_input": {"tokens": 250_000, "rate_per_1m": 1.0, "cost_usd": 0.25},
-        "batch_input": {"tokens": 200_000, "rate_per_1m": 0.5, "cost_usd": 0.1},
-        "batch_output": {"tokens": 100_000, "rate_per_1m": 0.25, "cost_usd": 0.025},
-    }
-    assert estimate.pricing_date == registry.last_updated
-    assert estimate.is_stale is True
-    assert estimate.warning == (
-        f"Pricing data is 31 days old (last updated: {registry.last_updated})."
-    )
-
-
-def test_registry_estimate_cost_zero_usage_returns_empty_breakdown() -> None:
-    registry = PricingRegistry(
-        last_updated=date.today(),
-        prices={
-            "demo": ModelPricing(model="demo", provider="test", input_per_1m=1.0, output_per_1m=2.0)
-        },
-    )
-    estimate = registry.estimate_cost("demo")
-    assert estimate.cost_usd == 0.0
-    assert estimate.breakdown == {}
-    assert estimate.is_stale is False
-    assert estimate.warning is None
-
-
-@pytest.mark.parametrize(
-    ("kwargs", "message"),
-    [
-        ({}, "Model 'missing' not found in registry"),
-        ({"cached_input_tokens": 1}, "Model 'demo' does not have cached input pricing"),
-        ({"batch_input_tokens": 1}, "Model 'demo' does not have batch input pricing"),
-        ({"batch_output_tokens": 1}, "Model 'demo' does not have batch output pricing"),
-    ],
-)
-def test_registry_estimate_cost_error_paths(kwargs: dict[str, int], message: str) -> None:
-    registry = PricingRegistry(
-        last_updated=date.today(),
-        prices={
-            "demo": ModelPricing(model="demo", provider="test", input_per_1m=1.0, output_per_1m=2.0)
-        },
-    )
-    with pytest.raises(ValueError, match=message):
-        registry.estimate_cost("missing" if not kwargs else "demo", **kwargs)
+from __future__ import annotations
+
+from dataclasses import FrozenInstanceError
+from datetime import date, timedelta
+
+import pytest
+
+import headroom.pricing as pricing
+from headroom.pricing.anthropic_prices import ANTHROPIC_PRICES, get_anthropic_registry
+from headroom.pricing.openai_prices import OPENAI_PRICES, get_openai_registry
+from headroom.pricing.registry import ModelPricing, PricingRegistry
+
+
+def test_pricing_public_exports_and_provider_registries() -> None:
+    assert pricing.ModelPricing is ModelPricing
+    assert pricing.PricingRegistry is PricingRegistry
+    assert "get_openai_registry" in pricing.__all__
+    assert "get_anthropic_registry" in pricing.__all__
+    assert "estimate_cost" in pricing.__all__
+
+    openai_registry = get_openai_registry()
+    anthropic_registry = get_anthropic_registry()
+    assert openai_registry.source_url == "https://openai.com/api/pricing/"
+    assert anthropic_registry.source_url == "https://www.anthropic.com/pricing"
+    assert openai_registry.prices["gpt-4o"] == OPENAI_PRICES["gpt-4o"]
+    assert (
+        anthropic_registry.prices["claude-3-5-sonnet-20241022"]
+        == ANTHROPIC_PRICES["claude-3-5-sonnet-20241022"]
+    )
+
+    openai_registry.prices.pop("gpt-4o")
+    anthropic_registry.prices.pop("claude-3-5-sonnet-20241022")
+    assert "gpt-4o" in OPENAI_PRICES
+    assert "claude-3-5-sonnet-20241022" in ANTHROPIC_PRICES
+
+
+def test_model_pricing_is_frozen() -> None:
+    model = ModelPricing(model="demo", provider="test", input_per_1m=1.5, output_per_1m=2.5)
+    with pytest.raises(FrozenInstanceError):
+        model.model = "other"  # type: ignore[misc]
+
+
+def test_registry_staleness_and_warning() -> None:
+    fresh = PricingRegistry(last_updated=date.today() - timedelta(days=30))
+    assert fresh.is_stale() is False
+    assert fresh.staleness_warning() is None
+
+    stale = PricingRegistry(
+        last_updated=date.today() - timedelta(days=31),
+        source_url="https://example.test/pricing",
+    )
+    assert stale.is_stale() is True
+    assert stale.staleness_warning() == (
+        f"Pricing data is 31 days old (last updated: {stale.last_updated})."
+        " Please verify at: https://example.test/pricing"
+    )
+
+
+def test_registry_estimate_cost_with_all_token_types() -> None:
+    registry = PricingRegistry(
+        last_updated=date.today() - timedelta(days=31),
+        prices={
+            "demo": ModelPricing(
+                model="demo",
+                provider="test",
+                input_per_1m=2.0,
+                output_per_1m=4.0,
+                cached_input_per_1m=1.0,
+                batch_input_per_1m=0.5,
+                batch_output_per_1m=0.25,
+            )
+        },
+    )
+
+    estimate = registry.estimate_cost(
+        "demo",
+        input_tokens=1_000_000,
+        output_tokens=500_000,
+        cached_input_tokens=250_000,
+        batch_input_tokens=200_000,
+        batch_output_tokens=100_000,
+    )
+
+    assert estimate.cost_usd == pytest.approx(4.375)
+    assert estimate.breakdown == {
+        "input": {"tokens": 1_000_000, "rate_per_1m": 2.0, "cost_usd": 2.0},
+        "output": {"tokens": 500_000, "rate_per_1m": 4.0, "cost_usd": 2.0},
+        "cached_input": {"tokens": 250_000, "rate_per_1m": 1.0, "cost_usd": 0.25},
+        "batch_input": {"tokens": 200_000, "rate_per_1m": 0.5, "cost_usd": 0.1},
+        "batch_output": {"tokens": 100_000, "rate_per_1m": 0.25, "cost_usd": 0.025},
+    }
+    assert estimate.pricing_date == registry.last_updated
+    assert estimate.is_stale is True
+    assert estimate.warning == (
+        f"Pricing data is 31 days old (last updated: {registry.last_updated})."
+    )
+
+
+def test_registry_estimate_cost_zero_usage_returns_empty_breakdown() -> None:
+    registry = PricingRegistry(
+        last_updated=date.today(),
+        prices={
+            "demo": ModelPricing(model="demo", provider="test", input_per_1m=1.0, output_per_1m=2.0)
+        },
+    )
+    estimate = registry.estimate_cost("demo")
+    assert estimate.cost_usd == 0.0
+    assert estimate.breakdown == {}
+    assert estimate.is_stale is False
+    assert estimate.warning is None
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "message"),
+    [
+        ({}, "Model 'missing' not found in registry"),
+        ({"cached_input_tokens": 1}, "Model 'demo' does not have cached input pricing"),
+        ({"batch_input_tokens": 1}, "Model 'demo' does not have batch input pricing"),
+        ({"batch_output_tokens": 1}, "Model 'demo' does not have batch output pricing"),
+    ],
+)
+def test_registry_estimate_cost_error_paths(kwargs: dict[str, int], message: str) -> None:
+    registry = PricingRegistry(
+        last_updated=date.today(),
+        prices={
+            "demo": ModelPricing(model="demo", provider="test", input_per_1m=1.0, output_per_1m=2.0)
+        },
+    )
+    with pytest.raises(ValueError, match=message):
+        registry.estimate_cost("missing" if not kwargs else "demo", **kwargs)
diff --git a/tests/test_pricing_litellm.py b/tests/test_pricing_litellm.py
index 1abde321d7d5ab477ee856626d7aa91698b63673..19b0646f7a8c660250366e696a71aee295399a4c 100644
--- a/tests/test_pricing_litellm.py
+++ b/tests/test_pricing_litellm.py
@@ -1,97 +1,97 @@
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-from headroom.pricing import litellm_pricing
-
-
-def test_litellm_helpers_when_dependency_is_unavailable(monkeypatch) -> None:
-    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", False)
-    monkeypatch.setattr(litellm_pricing, "litellm", None)
-
-    assert litellm_pricing.get_litellm_model_cost() == {}
-    assert litellm_pricing.get_model_pricing("gpt-4o") is None
-    assert litellm_pricing.estimate_cost("gpt-4o", input_tokens=1, output_tokens=1) is None
-    assert litellm_pricing.list_available_models() == []
-
-
-def test_litellm_model_pricing_exact_match_and_defaults(monkeypatch) -> None:
-    fake_litellm = SimpleNamespace(
-        model_cost={
-            "gpt-4o": {
-                "input_cost_per_token": 0.0000025,
-                "output_cost_per_token": 0.00001,
-                "max_tokens": 128000,
-            }
-        }
-    )
-    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)
-    monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)
-
-    assert litellm_pricing.get_litellm_model_cost() == fake_litellm.model_cost
-    pricing = litellm_pricing.get_model_pricing("gpt-4o")
-    assert pricing is not None
-    assert pricing.model == "gpt-4o"
-    assert pricing.input_cost_per_1m == 2.5
-    assert pricing.output_cost_per_1m == 10.0
-    assert pricing.max_tokens == 128000
-    assert pricing.max_input_tokens is None
-    assert pricing.max_output_tokens is None
-    assert pricing.supports_vision is False
-    assert pricing.supports_function_calling is False
-    assert (
-        litellm_pricing.estimate_cost("gpt-4o", input_tokens=200_000, output_tokens=300_000) == 3.5
-    )
-    assert litellm_pricing.list_available_models() == ["gpt-4o"]
-
-
-def test_litellm_model_pricing_uses_provider_prefixes(monkeypatch) -> None:
-    fake_litellm = SimpleNamespace(
-        model_cost={
-            "openai/gpt-4o-mini": {
-                "input_cost_per_token": 0.00000015,
-                "output_cost_per_token": 0.0000006,
-                "supports_vision": True,
-                "supports_function_calling": True,
-                "max_input_tokens": 64000,
-                "max_output_tokens": 16000,
-            }
-        }
-    )
-    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)
-    monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)
-
-    pricing = litellm_pricing.get_model_pricing("gpt-4o-mini")
-    assert pricing is not None
-    assert pricing.input_cost_per_1m == 0.15
-    assert pricing.output_cost_per_1m == 0.6
-    assert pricing.max_input_tokens == 64000
-    assert pricing.max_output_tokens == 16000
-    assert pricing.supports_vision is True
-    assert pricing.supports_function_calling is True
-
-
-def test_litellm_model_pricing_uses_aliases_and_zero_cost_defaults(monkeypatch) -> None:
-    fake_litellm = SimpleNamespace(
-        model_cost={
-            "claude-sonnet-4-20250514": {
-                "input_cost_per_token": None,
-                "output_cost_per_token": None,
-            }
-        }
-    )
-    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)
-    monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)
-
-    pricing = litellm_pricing.get_model_pricing("claude-3-5-sonnet-20241022")
-    assert pricing is not None
-    assert pricing.model == "claude-3-5-sonnet-20241022"
-    assert pricing.input_cost_per_1m == 0
-    assert pricing.output_cost_per_1m == 0
-    assert litellm_pricing.estimate_cost("claude-3-5-sonnet-20241022", input_tokens=1) == 0
-
-
-def test_litellm_model_pricing_returns_none_for_unknown_models(monkeypatch) -> None:
-    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)
-    monkeypatch.setattr(litellm_pricing, "litellm", SimpleNamespace(model_cost={}))
-    assert litellm_pricing.get_model_pricing("missing") is None
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from headroom.pricing import litellm_pricing
+
+
+def test_litellm_helpers_when_dependency_is_unavailable(monkeypatch) -> None:
+    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", False)
+    monkeypatch.setattr(litellm_pricing, "litellm", None)
+
+    assert litellm_pricing.get_litellm_model_cost() == {}
+    assert litellm_pricing.get_model_pricing("gpt-4o") is None
+    assert litellm_pricing.estimate_cost("gpt-4o", input_tokens=1, output_tokens=1) is None
+    assert litellm_pricing.list_available_models() == []
+
+
+def test_litellm_model_pricing_exact_match_and_defaults(monkeypatch) -> None:
+    fake_litellm = SimpleNamespace(
+        model_cost={
+            "gpt-4o": {
+                "input_cost_per_token": 0.0000025,
+                "output_cost_per_token": 0.00001,
+                "max_tokens": 128000,
+            }
+        }
+    )
+    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)
+    monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)
+
+    assert litellm_pricing.get_litellm_model_cost() == fake_litellm.model_cost
+    pricing = litellm_pricing.get_model_pricing("gpt-4o")
+    assert pricing is not None
+    assert pricing.model == "gpt-4o"
+    assert pricing.input_cost_per_1m == 2.5
+    assert pricing.output_cost_per_1m == 10.0
+    assert pricing.max_tokens == 128000
+    assert pricing.max_input_tokens is None
+    assert pricing.max_output_tokens is None
+    assert pricing.supports_vision is False
+    assert pricing.supports_function_calling is False
+    assert (
+        litellm_pricing.estimate_cost("gpt-4o", input_tokens=200_000, output_tokens=300_000) == 3.5
+    )
+    assert litellm_pricing.list_available_models() == ["gpt-4o"]
+
+
+def test_litellm_model_pricing_uses_provider_prefixes(monkeypatch) -> None:
+    fake_litellm = SimpleNamespace(
+        model_cost={
+            "openai/gpt-4o-mini": {
+                "input_cost_per_token": 0.00000015,
+                "output_cost_per_token": 0.0000006,
+                "supports_vision": True,
+                "supports_function_calling": True,
+                "max_input_tokens": 64000,
+                "max_output_tokens": 16000,
+            }
+        }
+    )
+    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)
+    monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)
+
+    pricing = litellm_pricing.get_model_pricing("gpt-4o-mini")
+    assert pricing is not None
+    assert pricing.input_cost_per_1m == 0.15
+    assert pricing.output_cost_per_1m == 0.6
+    assert pricing.max_input_tokens == 64000
+    assert pricing.max_output_tokens == 16000
+    assert pricing.supports_vision is True
+    assert pricing.supports_function_calling is True
+
+
+def test_litellm_model_pricing_uses_aliases_and_zero_cost_defaults(monkeypatch) -> None:
+    fake_litellm = SimpleNamespace(
+        model_cost={
+            "claude-sonnet-4-20250514": {
+                "input_cost_per_token": None,
+                "output_cost_per_token": None,
+            }
+        }
+    )
+    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)
+    monkeypatch.setattr(litellm_pricing, "litellm", fake_litellm)
+
+    pricing = litellm_pricing.get_model_pricing("claude-3-5-sonnet-20241022")
+    assert pricing is not None
+    assert pricing.model == "claude-3-5-sonnet-20241022"
+    assert pricing.input_cost_per_1m == 0
+    assert pricing.output_cost_per_1m == 0
+    assert litellm_pricing.estimate_cost("claude-3-5-sonnet-20241022", input_tokens=1) == 0
+
+
+def test_litellm_model_pricing_returns_none_for_unknown_models(monkeypatch) -> None:
+    monkeypatch.setattr(litellm_pricing, "LITELLM_AVAILABLE", True)
+    monkeypatch.setattr(litellm_pricing, "litellm", SimpleNamespace(model_cost={}))
+    assert litellm_pricing.get_model_pricing("missing") is None
diff --git a/tests/test_provider_aider.py b/tests/test_provider_aider.py
index 80626ccff0d774bf59a7ea37c6203d600266257b..542edab627518234c9317c50030171f6662378c8 100644
--- a/tests/test_provider_aider.py
+++ b/tests/test_provider_aider.py
@@ -1,33 +1,33 @@
-from __future__ import annotations
-
-from headroom.providers.aider.install import build_install_env
-from headroom.providers.aider.runtime import build_launch_env
-
-
-def test_aider_build_launch_env_sets_proxy_urls_without_mutating_input() -> None:
-    # Arrange
-    source_env = {"EXISTING": "value"}
-
-    # Act
-    env, lines = build_launch_env(port=9999, environ=source_env)
-
-    # Assert
-    assert source_env == {"EXISTING": "value"}
-    assert env["EXISTING"] == "value"
-    assert env["OPENAI_API_BASE"] == "http://127.0.0.1:9999/v1"
-    assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9999"
-    assert lines == [
-        "OPENAI_API_BASE=http://127.0.0.1:9999/v1",
-        "ANTHROPIC_BASE_URL=http://127.0.0.1:9999",
-    ]
-
-
-def test_aider_build_install_env_returns_only_persistent_proxy_variables() -> None:
-    # Arrange / Act
-    env = build_install_env(port=8787, backend="ignored")
-
-    # Assert
-    assert env == {
-        "OPENAI_API_BASE": "http://127.0.0.1:8787/v1",
-        "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
-    }
+from __future__ import annotations
+
+from headroom.providers.aider.install import build_install_env
+from headroom.providers.aider.runtime import build_launch_env
+
+
+def test_aider_build_launch_env_sets_proxy_urls_without_mutating_input() -> None:
+    # Arrange
+    source_env = {"EXISTING": "value"}
+
+    # Act
+    env, lines = build_launch_env(port=9999, environ=source_env)
+
+    # Assert
+    assert source_env == {"EXISTING": "value"}
+    assert env["EXISTING"] == "value"
+    assert env["OPENAI_API_BASE"] == "http://127.0.0.1:9999/v1"
+    assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9999"
+    assert lines == [
+        "OPENAI_API_BASE=http://127.0.0.1:9999/v1",
+        "ANTHROPIC_BASE_URL=http://127.0.0.1:9999",
+    ]
+
+
+def test_aider_build_install_env_returns_only_persistent_proxy_variables() -> None:
+    # Arrange / Act
+    env = build_install_env(port=8787, backend="ignored")
+
+    # Assert
+    assert env == {
+        "OPENAI_API_BASE": "http://127.0.0.1:8787/v1",
+        "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
+    }
diff --git a/tests/test_provider_claude.py b/tests/test_provider_claude.py
index 8dab41989e063df8113301b5a221ed251f1202dd..14ed3f55d221b9e30bfb63c1019c33d611f1f536 100644
--- a/tests/test_provider_claude.py
+++ b/tests/test_provider_claude.py
@@ -1,9 +1,9 @@
-from __future__ import annotations
-
-from headroom.providers.claude import DEFAULT_API_URL, proxy_base_url
-
-
-def test_claude_runtime_exposes_default_api_and_local_proxy_url() -> None:
-    # Arrange / Act / Assert
-    assert DEFAULT_API_URL == "https://api.anthropic.com"
-    assert proxy_base_url(4321) == "http://127.0.0.1:4321"
+from __future__ import annotations
+
+from headroom.providers.claude import DEFAULT_API_URL, proxy_base_url
+
+
+def test_claude_runtime_exposes_default_api_and_local_proxy_url() -> None:
+    # Arrange / Act / Assert
+    assert DEFAULT_API_URL == "https://api.anthropic.com"
+    assert proxy_base_url(4321) == "http://127.0.0.1:4321"
diff --git a/tests/test_provider_codex_runtime.py b/tests/test_provider_codex_runtime.py
index fb41d1ba6a3c6dd4f6530f8ed289109ad954c73b..1c3859e74e8ac474a21099928db504380cb73a2c 100644
--- a/tests/test_provider_codex_runtime.py
+++ b/tests/test_provider_codex_runtime.py
@@ -1,12 +1,12 @@
-from __future__ import annotations
-
-from headroom.providers.codex import build_launch_env, proxy_base_url
-
-
-def test_codex_proxy_base_url_and_launch_env() -> None:
-    env, lines = build_launch_env(9999, {"OPENAI_API_KEY": "sk-test"})
-
-    assert proxy_base_url(9999) == "http://127.0.0.1:9999/v1"
-    assert env["OPENAI_API_KEY"] == "sk-test"
-    assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9999/v1"
-    assert lines == ["OPENAI_BASE_URL=http://127.0.0.1:9999/v1"]
+from __future__ import annotations
+
+from headroom.providers.codex import build_launch_env, proxy_base_url
+
+
+def test_codex_proxy_base_url_and_launch_env() -> None:
+    env, lines = build_launch_env(9999, {"OPENAI_API_KEY": "sk-test"})
+
+    assert proxy_base_url(9999) == "http://127.0.0.1:9999/v1"
+    assert env["OPENAI_API_KEY"] == "sk-test"
+    assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9999/v1"
+    assert lines == ["OPENAI_BASE_URL=http://127.0.0.1:9999/v1"]
diff --git a/tests/test_provider_copilot_wrap.py b/tests/test_provider_copilot_wrap.py
index ff0707ab3d88850570b93abc78c50a8db0385678..5895ab0ac6c49dab8b60efed8ce83d5843051b1f 100644
--- a/tests/test_provider_copilot_wrap.py
+++ b/tests/test_provider_copilot_wrap.py
@@ -1,124 +1,124 @@
-from __future__ import annotations
-
-import io
-import json
-import urllib.error
-from unittest.mock import patch
-
-import click
-import pytest
-
-from headroom.providers.copilot.wrap import (
-    build_launch_env,
-    detect_running_proxy_backend,
-    model_configured,
-    provider_key_source,
-    query_proxy_config,
-    resolve_provider_type,
-    validate_configuration,
-)
-
-
-def test_query_proxy_config_handles_success_and_invalid_payload() -> None:
-    payload = io.BytesIO(json.dumps({"config": {"backend": "anyllm"}}).encode("utf-8"))
-    payload_missing = io.BytesIO(json.dumps({"status": "ok"}).encode("utf-8"))
-
-    with patch("urllib.request.urlopen", return_value=payload):
-        assert query_proxy_config(8787) == {"backend": "anyllm"}
-    with patch("urllib.request.urlopen", return_value=payload_missing):
-        assert query_proxy_config(8787) is None
-    with patch("urllib.request.urlopen", side_effect=urllib.error.URLError("down")):
-        assert query_proxy_config(8787) is None
-
-
-def test_detect_running_proxy_backend_requires_string_backend(monkeypatch) -> None:
-    monkeypatch.setattr(
-        "headroom.providers.copilot.wrap.query_proxy_config",
-        lambda port: {"backend": 123} if port == 8787 else None,
-    )
-
-    assert detect_running_proxy_backend(8787) is None
-    assert detect_running_proxy_backend(9999) is None
-
-
-def test_resolve_provider_type_prefers_explicit_and_env() -> None:
-    assert resolve_provider_type("anthropic", "openai") == "openai"
-    assert resolve_provider_type(None, "auto", {"HEADROOM_BACKEND": "anthropic"}) == "anthropic"
-    assert resolve_provider_type(None, "auto", {"HEADROOM_BACKEND": "anyllm"}) == "openai"
-
-
-def test_validate_configuration_accepts_supported_combinations() -> None:
-    validate_configuration(provider_type="openai", wire_api="responses", backend=None)
-    validate_configuration(provider_type="openai", wire_api="completions", backend="anyllm")
-
-
-def test_validate_configuration_rejects_invalid_combinations() -> None:
-    with pytest.raises(click.ClickException, match="--wire-api is only valid"):
-        validate_configuration(provider_type="anthropic", wire_api="responses", backend=None)
-
-    with pytest.raises(click.ClickException, match="not supported with translated backends"):
-        validate_configuration(provider_type="openai", wire_api="responses", backend="anyllm")
-
-
-def test_provider_key_source_and_build_launch_env_cover_anthropic_and_openai() -> None:
-    assert provider_key_source("anthropic") == "ANTHROPIC_API_KEY"
-    assert provider_key_source("openai") == "OPENAI_API_KEY"
-
-    anthropic_env, anthropic_lines = build_launch_env(
-        port=8787,
-        provider_type="anthropic",
-        wire_api="responses",
-        environ={
-            "ANTHROPIC_API_KEY": "sk-ant-test",
-            "COPILOT_PROVIDER_WIRE_API": "stale",
-        },
-    )
-    openai_env, openai_lines = build_launch_env(
-        port=8787,
-        provider_type="openai",
-        wire_api=None,
-        environ={"OPENAI_API_KEY": "sk-proj-test"},
-    )
-
-    assert anthropic_env["COPILOT_PROVIDER_TYPE"] == "anthropic"
-    assert anthropic_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787"
-    assert anthropic_env["COPILOT_PROVIDER_API_KEY"] == "sk-ant-test"
-    assert "COPILOT_PROVIDER_WIRE_API" not in anthropic_env
-    assert anthropic_lines == [
-        "COPILOT_PROVIDER_TYPE=anthropic",
-        "COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:8787",
-    ]
-
-    assert openai_env["COPILOT_PROVIDER_TYPE"] == "openai"
-    assert openai_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"
-    assert openai_env["COPILOT_PROVIDER_WIRE_API"] == "completions"
-    assert openai_env["COPILOT_PROVIDER_API_KEY"] == "sk-proj-test"
-    assert openai_lines[-1] == "COPILOT_PROVIDER_WIRE_API=completions"
-
-
-def test_build_launch_env_keeps_existing_provider_key_and_allows_missing_source_key() -> None:
-    existing_env, _existing_lines = build_launch_env(
-        port=8787,
-        provider_type="openai",
-        wire_api="responses",
-        environ={
-            "COPILOT_PROVIDER_API_KEY": "existing-provider-key",
-            "OPENAI_API_KEY": "sk-proj-test",
-        },
-    )
-    missing_env, _missing_lines = build_launch_env(
-        port=8787,
-        provider_type="openai",
-        wire_api="responses",
-        environ={},
-    )
-
-    assert existing_env["COPILOT_PROVIDER_API_KEY"] == "existing-provider-key"
-    assert "COPILOT_PROVIDER_API_KEY" not in missing_env
-
-
-def test_model_configured_detects_env_and_cli_variants() -> None:
-    assert model_configured((), {"COPILOT_MODEL": "gpt-4o"}) is True
-    assert model_configured(("--model", "gpt-4o"), {}) is True
-    assert model_configured(("--model=gpt-4o",), {}) is True
-    assert model_configured(("--other", "value"), {}) is False
+from __future__ import annotations
+
+import io
+import json
+import urllib.error
+from unittest.mock import patch
+
+import click
+import pytest
+
+from headroom.providers.copilot.wrap import (
+    build_launch_env,
+    detect_running_proxy_backend,
+    model_configured,
+    provider_key_source,
+    query_proxy_config,
+    resolve_provider_type,
+    validate_configuration,
+)
+
+
+def test_query_proxy_config_handles_success_and_invalid_payload() -> None:
+    payload = io.BytesIO(json.dumps({"config": {"backend": "anyllm"}}).encode("utf-8"))
+    payload_missing = io.BytesIO(json.dumps({"status": "ok"}).encode("utf-8"))
+
+    with patch("urllib.request.urlopen", return_value=payload):
+        assert query_proxy_config(8787) == {"backend": "anyllm"}
+    with patch("urllib.request.urlopen", return_value=payload_missing):
+        assert query_proxy_config(8787) is None
+    with patch("urllib.request.urlopen", side_effect=urllib.error.URLError("down")):
+        assert query_proxy_config(8787) is None
+
+
+def test_detect_running_proxy_backend_requires_string_backend(monkeypatch) -> None:
+    monkeypatch.setattr(
+        "headroom.providers.copilot.wrap.query_proxy_config",
+        lambda port: {"backend": 123} if port == 8787 else None,
+    )
+
+    assert detect_running_proxy_backend(8787) is None
+    assert detect_running_proxy_backend(9999) is None
+
+
+def test_resolve_provider_type_prefers_explicit_and_env() -> None:
+    assert resolve_provider_type("anthropic", "openai") == "openai"
+    assert resolve_provider_type(None, "auto", {"HEADROOM_BACKEND": "anthropic"}) == "anthropic"
+    assert resolve_provider_type(None, "auto", {"HEADROOM_BACKEND": "anyllm"}) == "openai"
+
+
+def test_validate_configuration_accepts_supported_combinations() -> None:
+    validate_configuration(provider_type="openai", wire_api="responses", backend=None)
+    validate_configuration(provider_type="openai", wire_api="completions", backend="anyllm")
+
+
+def test_validate_configuration_rejects_invalid_combinations() -> None:
+    with pytest.raises(click.ClickException, match="--wire-api is only valid"):
+        validate_configuration(provider_type="anthropic", wire_api="responses", backend=None)
+
+    with pytest.raises(click.ClickException, match="not supported with translated backends"):
+        validate_configuration(provider_type="openai", wire_api="responses", backend="anyllm")
+
+
+def test_provider_key_source_and_build_launch_env_cover_anthropic_and_openai() -> None:
+    assert provider_key_source("anthropic") == "ANTHROPIC_API_KEY"
+    assert provider_key_source("openai") == "OPENAI_API_KEY"
+
+    anthropic_env, anthropic_lines = build_launch_env(
+        port=8787,
+        provider_type="anthropic",
+        wire_api="responses",
+        environ={
+            "ANTHROPIC_API_KEY": "sk-ant-test",
+            "COPILOT_PROVIDER_WIRE_API": "stale",
+        },
+    )
+    openai_env, openai_lines = build_launch_env(
+        port=8787,
+        provider_type="openai",
+        wire_api=None,
+        environ={"OPENAI_API_KEY": "sk-proj-test"},
+    )
+
+    assert anthropic_env["COPILOT_PROVIDER_TYPE"] == "anthropic"
+    assert anthropic_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787"
+    assert anthropic_env["COPILOT_PROVIDER_API_KEY"] == "sk-ant-test"
+    assert "COPILOT_PROVIDER_WIRE_API" not in anthropic_env
+    assert anthropic_lines == [
+        "COPILOT_PROVIDER_TYPE=anthropic",
+        "COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:8787",
+    ]
+
+    assert openai_env["COPILOT_PROVIDER_TYPE"] == "openai"
+    assert openai_env["COPILOT_PROVIDER_BASE_URL"] == "http://127.0.0.1:8787/v1"
+    assert openai_env["COPILOT_PROVIDER_WIRE_API"] == "completions"
+    assert openai_env["COPILOT_PROVIDER_API_KEY"] == "sk-proj-test"
+    assert openai_lines[-1] == "COPILOT_PROVIDER_WIRE_API=completions"
+
+
+def test_build_launch_env_keeps_existing_provider_key_and_allows_missing_source_key() -> None:
+    existing_env, _existing_lines = build_launch_env(
+        port=8787,
+        provider_type="openai",
+        wire_api="responses",
+        environ={
+            "COPILOT_PROVIDER_API_KEY": "existing-provider-key",
+            "OPENAI_API_KEY": "sk-proj-test",
+        },
+    )
+    missing_env, _missing_lines = build_launch_env(
+        port=8787,
+        provider_type="openai",
+        wire_api="responses",
+        environ={},
+    )
+
+    assert existing_env["COPILOT_PROVIDER_API_KEY"] == "existing-provider-key"
+    assert "COPILOT_PROVIDER_API_KEY" not in missing_env
+
+
+def test_model_configured_detects_env_and_cli_variants() -> None:
+    assert model_configured((), {"COPILOT_MODEL": "gpt-4o"}) is True
+    assert model_configured(("--model", "gpt-4o"), {}) is True
+    assert model_configured(("--model=gpt-4o",), {}) is True
+    assert model_configured(("--other", "value"), {}) is False
diff --git a/tests/test_provider_openclaw_wrap.py b/tests/test_provider_openclaw_wrap.py
index 2de40eba0013ca3e0c3d4f9711ab81d91e10c426..5025aa6e047060756dfab3ce98ba7f55279df19c 100644
--- a/tests/test_provider_openclaw_wrap.py
+++ b/tests/test_provider_openclaw_wrap.py
@@ -1,119 +1,119 @@
-from __future__ import annotations
-
-from headroom.providers.openclaw.wrap import (
-    DEFAULT_GATEWAY_PROVIDER_IDS,
-    build_plugin_entry,
-    build_unwrap_entry,
-    decode_entry_json,
-    normalize_gateway_provider_ids,
-)
-
-
-def test_normalize_gateway_provider_ids_trims_deduplicates_and_defaults() -> None:
-    # Arrange / Act / Assert
-    assert normalize_gateway_provider_ids((" openai-codex ", "anthropic", "anthropic", "")) == [
-        "openai-codex",
-        "anthropic",
-    ]
-    assert normalize_gateway_provider_ids(None) == DEFAULT_GATEWAY_PROVIDER_IDS
-
-
-def test_decode_entry_json_handles_empty_valid_and_invalid_payloads() -> None:
-    # Arrange / Act / Assert
-    assert decode_entry_json(None) is None
-    assert decode_entry_json("") is None
-    assert decode_entry_json('{"enabled": true}') == {"enabled": True}
-    assert decode_entry_json("{not-json}") == "{not-json}"
-
-
-def test_build_plugin_entry_preserves_unmanaged_values_and_removes_empty_python_path() -> None:
-    # Arrange
-    existing_entry = {
-        "enabled": False,
-        "name": "headroom",
-        "config": {
-            "keep": "value",
-            "proxyUrl": "https://user.example",
-            "pythonPath": "/old/python",
-        },
-    }
-
-    # Act
-    entry = build_plugin_entry(
-        existing_entry=existing_entry,
-        proxy_port=8787,
-        startup_timeout_ms=1500,
-        python_path=None,
-        no_auto_start=True,
-        gateway_provider_ids=(" openai-codex ", "anthropic", "anthropic"),
-        enabled=True,
-    )
-
-    # Assert
-    assert entry["enabled"] is True
-    assert entry["name"] == "headroom"
-    assert entry["config"] == {
-        "keep": "value",
-        "proxyUrl": "https://user.example",
-        "proxyPort": 8787,
-        "autoStart": False,
-        "startupTimeoutMs": 1500,
-        "gatewayProviderIds": ["openai-codex", "anthropic"],
-    }
-
-
-def test_build_plugin_entry_creates_managed_defaults_for_non_mapping_input() -> None:
-    # Arrange / Act
-    entry = build_plugin_entry(
-        existing_entry="not-a-dict",
-        proxy_port=9000,
-        startup_timeout_ms=2500,
-        python_path="/usr/bin/python",
-        no_auto_start=False,
-        gateway_provider_ids=None,
-        enabled=False,
-    )
-
-    # Assert
-    assert entry == {
-        "enabled": False,
-        "config": {
-            "proxyPort": 9000,
-            "autoStart": True,
-            "startupTimeoutMs": 2500,
-            "gatewayProviderIds": ["openai-codex"],
-            "pythonPath": "/usr/bin/python",
-        },
-    }
-
-
-def test_build_unwrap_entry_disables_plugin_and_removes_managed_keys_only() -> None:
-    # Arrange
-    existing_entry = {
-        "enabled": True,
-        "name": "headroom",
-        "config": {
-            "keep": "value",
-            "gatewayProviderIds": ["openai-codex"],
-            "proxyUrl": "https://managed.example",
-            "proxyPort": 8787,
-            "autoStart": True,
-            "startupTimeoutMs": 1000,
-            "pythonPath": "/usr/bin/python",
-        },
-    }
-
-    # Act
-    entry = build_unwrap_entry(existing_entry)
-
-    # Assert
-    assert entry == {
-        "enabled": False,
-        "name": "headroom",
-        "config": {"keep": "value"},
-    }
-
-
-def test_build_unwrap_entry_handles_non_mapping_input() -> None:
-    # Arrange / Act / Assert
-    assert build_unwrap_entry("not-a-dict") == {"enabled": False, "config": {}}
+from __future__ import annotations
+
+from headroom.providers.openclaw.wrap import (
+    DEFAULT_GATEWAY_PROVIDER_IDS,
+    build_plugin_entry,
+    build_unwrap_entry,
+    decode_entry_json,
+    normalize_gateway_provider_ids,
+)
+
+
+def test_normalize_gateway_provider_ids_trims_deduplicates_and_defaults() -> None:
+    # Arrange / Act / Assert
+    assert normalize_gateway_provider_ids((" openai-codex ", "anthropic", "anthropic", "")) == [
+        "openai-codex",
+        "anthropic",
+    ]
+    assert normalize_gateway_provider_ids(None) == DEFAULT_GATEWAY_PROVIDER_IDS
+
+
+def test_decode_entry_json_handles_empty_valid_and_invalid_payloads() -> None:
+    # Arrange / Act / Assert
+    assert decode_entry_json(None) is None
+    assert decode_entry_json("") is None
+    assert decode_entry_json('{"enabled": true}') == {"enabled": True}
+    assert decode_entry_json("{not-json}") == "{not-json}"
+
+
+def test_build_plugin_entry_preserves_unmanaged_values_and_removes_empty_python_path() -> None:
+    # Arrange
+    existing_entry = {
+        "enabled": False,
+        "name": "headroom",
+        "config": {
+            "keep": "value",
+            "proxyUrl": "https://user.example",
+            "pythonPath": "/old/python",
+        },
+    }
+
+    # Act
+    entry = build_plugin_entry(
+        existing_entry=existing_entry,
+        proxy_port=8787,
+        startup_timeout_ms=1500,
+        python_path=None,
+        no_auto_start=True,
+        gateway_provider_ids=(" openai-codex ", "anthropic", "anthropic"),
+        enabled=True,
+    )
+
+    # Assert
+    assert entry["enabled"] is True
+    assert entry["name"] == "headroom"
+    assert entry["config"] == {
+        "keep": "value",
+        "proxyUrl": "https://user.example",
+        "proxyPort": 8787,
+        "autoStart": False,
+        "startupTimeoutMs": 1500,
+        "gatewayProviderIds": ["openai-codex", "anthropic"],
+    }
+
+
+def test_build_plugin_entry_creates_managed_defaults_for_non_mapping_input() -> None:
+    # Arrange / Act
+    entry = build_plugin_entry(
+        existing_entry="not-a-dict",
+        proxy_port=9000,
+        startup_timeout_ms=2500,
+        python_path="/usr/bin/python",
+        no_auto_start=False,
+        gateway_provider_ids=None,
+        enabled=False,
+    )
+
+    # Assert
+    assert entry == {
+        "enabled": False,
+        "config": {
+            "proxyPort": 9000,
+            "autoStart": True,
+            "startupTimeoutMs": 2500,
+            "gatewayProviderIds": ["openai-codex"],
+            "pythonPath": "/usr/bin/python",
+        },
+    }
+
+
+def test_build_unwrap_entry_disables_plugin_and_removes_managed_keys_only() -> None:
+    # Arrange
+    existing_entry = {
+        "enabled": True,
+        "name": "headroom",
+        "config": {
+            "keep": "value",
+            "gatewayProviderIds": ["openai-codex"],
+            "proxyUrl": "https://managed.example",
+            "proxyPort": 8787,
+            "autoStart": True,
+            "startupTimeoutMs": 1000,
+            "pythonPath": "/usr/bin/python",
+        },
+    }
+
+    # Act
+    entry = build_unwrap_entry(existing_entry)
+
+    # Assert
+    assert entry == {
+        "enabled": False,
+        "name": "headroom",
+        "config": {"keep": "value"},
+    }
+
+
+def test_build_unwrap_entry_handles_non_mapping_input() -> None:
+    # Arrange / Act / Assert
+    assert build_unwrap_entry("not-a-dict") == {"enabled": False, "config": {}}
diff --git a/tests/test_provider_package_init.py b/tests/test_provider_package_init.py
index d1f32b4f894003dbd7f5dc59ff051c3d624e6859..f6cb294b69168538905923c982639643e0e3375f 100644
--- a/tests/test_provider_package_init.py
+++ b/tests/test_provider_package_init.py
@@ -1,111 +1,111 @@
-from __future__ import annotations
-
-import importlib
-import types
-
-import pytest
-
-import headroom.providers as providers
-from headroom.install.models import ManagedMutation
-from headroom.providers import install_registry
-
-
-def test_providers_package_resolves_exports_lazily_and_caches_them(monkeypatch) -> None:
-    module = importlib.reload(providers)
-    module.__dict__.pop("OpenAIProvider", None)
-    sentinel = object()
-    import_calls: list[str] = []
-
-    def fake_import_module(name: str):
-        import_calls.append(name)
-        return types.SimpleNamespace(OpenAIProvider=sentinel)
-
-    monkeypatch.setattr(module, "import_module", fake_import_module)
-
-    try:
-        assert module.OpenAIProvider is sentinel
-        assert module.OpenAIProvider is sentinel
-        assert import_calls == ["headroom.providers.openai"]
-        assert "OpenAIProvider" in module.__dir__()
-    finally:
-        module.__dict__.pop("OpenAIProvider", None)
-
-
-def test_providers_package_rejects_missing_and_dunder_path_attributes() -> None:
-    module = importlib.reload(providers)
-
-    with pytest.raises(AttributeError, match="__path__"):
-        module.__getattr__("__path__")
-
-    with pytest.raises(AttributeError, match="does_not_exist"):
-        module.__getattribute__("does_not_exist")
-
-
-def test_install_registry_build_install_target_envs_uses_known_targets_only(monkeypatch) -> None:
-    monkeypatch.setattr(
-        install_registry,
-        "_ENV_BUILDERS",
-        {
-            "claude": lambda *, port, backend: {"CLAUDE_PORT": f"{port}:{backend}"},
-            "cursor": lambda *, port, backend: {"CURSOR_PORT": f"{port}:{backend}"},
-        },
-    )
-
-    envs = install_registry.build_install_target_envs(
-        port=8787,
-        backend="anthropic",
-        targets=["claude", "unknown", "cursor"],
-    )
-
-    assert envs == {
-        "claude": {"CLAUDE_PORT": "8787:anthropic"},
-        "cursor": {"CURSOR_PORT": "8787:anthropic"},
-    }
-
-
-def test_install_registry_apply_provider_scope_mutations_skips_missing_and_none(
-    monkeypatch,
-) -> None:
-    manifest = types.SimpleNamespace(targets=["claude", "codex", "unknown"])
-    codex_mutation = ManagedMutation(target="codex", kind="toml-block")
-
-    monkeypatch.setattr(
-        install_registry,
-        "_PROVIDER_SCOPE_HANDLERS",
-        {
-            "claude": (lambda _manifest: None, lambda mutation, manifest: None),
-            "codex": (lambda _manifest: codex_mutation, lambda mutation, manifest: None),
-        },
-    )
-
-    mutations = install_registry.apply_provider_scope_mutations(manifest)
-
-    assert mutations == [codex_mutation]
-
-
-def test_install_registry_revert_provider_scope_mutation_dispatches_known_targets(
-    monkeypatch,
-) -> None:
-    manifest = types.SimpleNamespace()
-    mutation = ManagedMutation(target="codex", kind="toml-block")
-    recorded: list[tuple[ManagedMutation, object]] = []
-
-    monkeypatch.setattr(
-        install_registry,
-        "_PROVIDER_SCOPE_HANDLERS",
-        {
-            "codex": (
-                lambda _manifest: None,
-                lambda incoming_mutation, incoming_manifest: recorded.append(
-                    (incoming_mutation, incoming_manifest)
-                ),
-            )
-        },
-    )
-
-    install_registry.revert_provider_scope_mutation(manifest, mutation)
-    install_registry.revert_provider_scope_mutation(
-        manifest, ManagedMutation(target="unknown", kind="noop")
-    )
-
-    assert recorded == [(mutation, manifest)]
+from __future__ import annotations
+
+import importlib
+import types
+
+import pytest
+
+import headroom.providers as providers
+from headroom.install.models import ManagedMutation
+from headroom.providers import install_registry
+
+
+def test_providers_package_resolves_exports_lazily_and_caches_them(monkeypatch) -> None:
+    module = importlib.reload(providers)
+    module.__dict__.pop("OpenAIProvider", None)
+    sentinel = object()
+    import_calls: list[str] = []
+
+    def fake_import_module(name: str):
+        import_calls.append(name)
+        return types.SimpleNamespace(OpenAIProvider=sentinel)
+
+    monkeypatch.setattr(module, "import_module", fake_import_module)
+
+    try:
+        assert module.OpenAIProvider is sentinel
+        assert module.OpenAIProvider is sentinel
+        assert import_calls == ["headroom.providers.openai"]
+        assert "OpenAIProvider" in module.__dir__()
+    finally:
+        module.__dict__.pop("OpenAIProvider", None)
+
+
+def test_providers_package_rejects_missing_and_dunder_path_attributes() -> None:
+    module = importlib.reload(providers)
+
+    with pytest.raises(AttributeError, match="__path__"):
+        module.__getattr__("__path__")
+
+    with pytest.raises(AttributeError, match="does_not_exist"):
+        module.__getattribute__("does_not_exist")
+
+
+def test_install_registry_build_install_target_envs_uses_known_targets_only(monkeypatch) -> None:
+    monkeypatch.setattr(
+        install_registry,
+        "_ENV_BUILDERS",
+        {
+            "claude": lambda *, port, backend: {"CLAUDE_PORT": f"{port}:{backend}"},
+            "cursor": lambda *, port, backend: {"CURSOR_PORT": f"{port}:{backend}"},
+        },
+    )
+
+    envs = install_registry.build_install_target_envs(
+        port=8787,
+        backend="anthropic",
+        targets=["claude", "unknown", "cursor"],
+    )
+
+    assert envs == {
+        "claude": {"CLAUDE_PORT": "8787:anthropic"},
+        "cursor": {"CURSOR_PORT": "8787:anthropic"},
+    }
+
+
+def test_install_registry_apply_provider_scope_mutations_skips_missing_and_none(
+    monkeypatch,
+) -> None:
+    manifest = types.SimpleNamespace(targets=["claude", "codex", "unknown"])
+    codex_mutation = ManagedMutation(target="codex", kind="toml-block")
+
+    monkeypatch.setattr(
+        install_registry,
+        "_PROVIDER_SCOPE_HANDLERS",
+        {
+            "claude": (lambda _manifest: None, lambda mutation, manifest: None),
+            "codex": (lambda _manifest: codex_mutation, lambda mutation, manifest: None),
+        },
+    )
+
+    mutations = install_registry.apply_provider_scope_mutations(manifest)
+
+    assert mutations == [codex_mutation]
+
+
+def test_install_registry_revert_provider_scope_mutation_dispatches_known_targets(
+    monkeypatch,
+) -> None:
+    manifest = types.SimpleNamespace()
+    mutation = ManagedMutation(target="codex", kind="toml-block")
+    recorded: list[tuple[ManagedMutation, object]] = []
+
+    monkeypatch.setattr(
+        install_registry,
+        "_PROVIDER_SCOPE_HANDLERS",
+        {
+            "codex": (
+                lambda _manifest: None,
+                lambda incoming_mutation, incoming_manifest: recorded.append(
+                    (incoming_mutation, incoming_manifest)
+                ),
+            )
+        },
+    )
+
+    install_registry.revert_provider_scope_mutation(manifest, mutation)
+    install_registry.revert_provider_scope_mutation(
+        manifest, ManagedMutation(target="unknown", kind="noop")
+    )
+
+    assert recorded == [(mutation, manifest)]
diff --git a/tests/test_provider_proxy_routes.py b/tests/test_provider_proxy_routes.py
index 6e90ca5e8310f43e43dd96229ef6e473e5e43ecc..3f4b7fae68a9b617aaca958c10c1c812186266c9 100644
--- a/tests/test_provider_proxy_routes.py
+++ b/tests/test_provider_proxy_routes.py
@@ -1,340 +1,340 @@
-from __future__ import annotations
-
-import importlib
-from typing import Any
-
-import httpx
-from fastapi.responses import JSONResponse
-from fastapi.testclient import TestClient
-
-from headroom.proxy.server import HeadroomProxy, ProxyConfig, create_app
-
-
-def _app() -> Any:
-    return create_app(
-        ProxyConfig(
-            optimize=False,
-            cache_enabled=False,
-            rate_limit_enabled=False,
-            anthropic_api_url="https://api.anthropic.test",
-            openai_api_url="https://api.openai.test",
-            gemini_api_url="https://api.gemini.test",
-            cloudcode_api_url="https://cloudcode.test",
-        )
-    )
-
-
-def test_provider_passthrough_routes_forward_expected_targets(monkeypatch) -> None:
-    calls: list[tuple[str, str, str, str]] = []
-
-    async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""):  # type: ignore[no-untyped-def]
-        calls.append((request.method, request.url.path, base_url, provider_name))
-        return JSONResponse(
-            {
-                "method": request.method,
-                "path": request.url.path,
-                "base_url": base_url,
-                "sub_path": sub_path,
-                "provider": provider_name,
-            }
-        )
-
-    monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)
-
-    with TestClient(_app()) as client:
-        assert client.post("/v1/messages/count_tokens").json()["base_url"] == (
-            "https://api.anthropic.test"
-        )
-        assert client.get("/v1/models", headers={"x-goog-api-key": "test"}).json()["base_url"] == (
-            "https://api.openai.test"
-        )
-        assert client.get("/v1/models/demo").json()["sub_path"] == "models"
-        assert (
-            client.get(
-                "/azure/models",
-                headers={
-                    "api-key": "azure-key",
-                    "x-headroom-base-url": "https://azure.example/openai/",
-                },
-            ).json()["base_url"]
-            == "https://azure.example/openai"
-        )
-        assert client.post("/v1/embeddings").json()["provider"] == "openai"
-        assert client.post("/v1/moderations").json()["sub_path"] == "moderations"
-        assert client.post("/v1/images/generations").json()["sub_path"] == "images/generations"
-        assert client.post("/v1/audio/transcriptions").json()["sub_path"] == "audio/transcriptions"
-        assert client.post("/v1/audio/speech").json()["sub_path"] == "audio/speech"
-        assert client.get("/v1beta/models").json()["provider"] == "gemini"
-        assert client.get("/v1beta/models/demo").json()["sub_path"] == "models"
-        assert client.post("/v1beta/models/demo:embedContent").json()["sub_path"] == "embedContent"
-        assert client.post("/v1beta/cachedContents").json()["sub_path"] == "cachedContents"
-        assert client.get("/v1beta/cachedContents").json()["sub_path"] == "cachedContents"
-        assert client.get("/v1beta/cachedContents/cache-1").json()["sub_path"] == "cachedContents"
-        assert client.delete("/v1beta/cachedContents/cache-1").json()["sub_path"] == (
-            "cachedContents"
-        )
-        assert (
-            client.get(
-                "/unhandled/path",
-                headers={"x-headroom-base-url": "https://custom.example/base/"},
-            ).json()["base_url"]
-            == "https://custom.example/base"
-        )
-        assert client.get("/another/path", headers={"x-goog-api-key": "test"}).json()[
-            "base_url"
-        ] == ("https://api.gemini.test")
-
-    assert len(calls) >= 16
-
-
-def test_proxy_route_helpers_prefer_legacy_targets_and_gemini_passthrough() -> None:
-    proxy_routes = importlib.import_module("headroom.providers.proxy_routes")
-    proxy = type(
-        "Proxy",
-        (),
-        {
-            "ANTHROPIC_API_URL": "https://legacy.anthropic.test",
-            "OPENAI_API_URL": "https://legacy.openai.test",
-            "GEMINI_API_URL": "https://legacy.gemini.test",
-            "provider_runtime": type(
-                "Runtime",
-                (),
-                {
-                    "api_target": staticmethod(lambda provider: f"https://runtime.{provider}.test"),
-                    "model_metadata_provider": staticmethod(lambda headers: "anthropic"),
-                },
-            )(),
-        },
-    )()
-
-    assert proxy_routes._api_target(proxy, "anthropic") == "https://legacy.anthropic.test"
-    assert proxy_routes._select_passthrough_base_url(proxy, {"x-goog-api-key": "test"}) == (
-        "https://legacy.gemini.test"
-    )
-    assert (
-        proxy_routes._select_passthrough_base_url(
-            proxy, {"api-key": "azure", "x-headroom-base-url": "https://azure.example/base/"}
-        )
-        == "https://azure.example/base"
-    )
-    assert proxy_routes._select_passthrough_base_url(proxy, {"api-key": "azure"}) == (
-        "https://legacy.anthropic.test"
-    )
-    assert proxy_routes._select_passthrough_base_url(proxy, {}) == "https://legacy.anthropic.test"
-
-
-def test_provider_specific_routes_delegate_to_expected_proxy_handlers(monkeypatch) -> None:
-    delegated: list[tuple[str, str, tuple[str, ...]]] = []
-
-    def install(name: str) -> None:
-        async def fake(self, request, *args):  # type: ignore[no-untyped-def]
-            delegated.append((name, request.url.path, tuple(str(arg) for arg in args)))
-            return JSONResponse({"handler": name, "path": request.url.path, "args": list(args)})
-
-        monkeypatch.setattr(HeadroomProxy, name, fake)
-
-    for handler_name in (
-        "handle_anthropic_messages",
-        "handle_anthropic_batch_create",
-        "handle_anthropic_batch_passthrough",
-        "handle_anthropic_batch_results",
-        "handle_openai_chat",
-        "handle_openai_responses",
-        "handle_batch_create",
-        "handle_batch_list",
-        "handle_batch_get",
-        "handle_batch_cancel",
-        "handle_gemini_generate_content",
-        "handle_gemini_stream_generate_content",
-        "handle_gemini_count_tokens",
-        "handle_google_cloudcode_stream",
-        "handle_databricks_invocations",
-        "handle_google_batch_create",
-        "handle_google_batch_results",
-        "handle_google_batch_passthrough",
-    ):
-        install(handler_name)
-
-    with TestClient(_app()) as client:
-        assert client.post("/v1/messages").json()["handler"] == "handle_anthropic_messages"
-        assert (
-            client.post("/v1/messages/batches").json()["handler"] == "handle_anthropic_batch_create"
-        )
-        assert client.get("/v1/messages/batches").json()["handler"] == (
-            "handle_anthropic_batch_passthrough"
-        )
-        assert client.get("/v1/messages/batches/b1").json()["args"] == ["b1"]
-        assert client.get("/v1/messages/batches/b1/results").json()["handler"] == (
-            "handle_anthropic_batch_results"
-        )
-        assert client.post("/v1/messages/batches/b1/cancel").json()["handler"] == (
-            "handle_anthropic_batch_passthrough"
-        )
-        assert client.post("/v1/chat/completions").json()["handler"] == "handle_openai_chat"
-        assert client.post("/v1/responses").json()["handler"] == "handle_openai_responses"
-        assert client.post("/v1/codex/responses").json()["handler"] == "handle_openai_responses"
-        assert client.post("/backend-api/responses").json()["handler"] == "handle_openai_responses"
-        assert client.post("/backend-api/codex/responses").json()["handler"] == (
-            "handle_openai_responses"
-        )
-        assert client.post("/v1/batches").json()["handler"] == "handle_batch_create"
-        assert client.get("/v1/batches").json()["handler"] == "handle_batch_list"
-        assert client.get("/v1/batches/b1").json()["handler"] == "handle_batch_get"
-        assert client.post("/v1/batches/b1/cancel").json()["handler"] == "handle_batch_cancel"
-        assert client.post("/v1beta/models/demo:generateContent").json()["handler"] == (
-            "handle_gemini_generate_content"
-        )
-        assert client.post("/v1beta/models/demo:streamGenerateContent").json()["handler"] == (
-            "handle_gemini_stream_generate_content"
-        )
-        assert client.post("/v1beta/models/demo:countTokens").json()["handler"] == (
-            "handle_gemini_count_tokens"
-        )
-        assert client.post("/v1internal:streamGenerateContent").json()["handler"] == (
-            "handle_google_cloudcode_stream"
-        )
-        assert client.post("/v1/v1internal:streamGenerateContent").json()["handler"] == (
-            "handle_google_cloudcode_stream"
-        )
-        assert client.post("/serving-endpoints/demo/invocations").json()["handler"] == (
-            "handle_databricks_invocations"
-        )
-        assert client.post("/v1beta/models/demo:batchGenerateContent").json()["handler"] == (
-            "handle_google_batch_create"
-        )
-        assert client.get("/v1beta/batches/b1").json()["handler"] == "handle_google_batch_results"
-        assert client.post("/v1beta/batches/b1:cancel").json()["handler"] == (
-            "handle_google_batch_passthrough"
-        )
-        assert client.delete("/v1beta/batches/b1").json()["handler"] == (
-            "handle_google_batch_passthrough"
-        )
-
-    assert len(delegated) >= 24
-
-
-def test_openai_response_websocket_aliases_delegate_to_openai_ws_handler(monkeypatch) -> None:
-    seen_paths: list[str] = []
-
-    async def fake_ws(self, websocket):  # type: ignore[no-untyped-def]
-        seen_paths.append(websocket.url.path)
-        await websocket.accept()
-        await websocket.send_json({"path": websocket.url.path})
-        await websocket.close()
-
-    monkeypatch.setattr(HeadroomProxy, "handle_openai_responses_ws", fake_ws)
-
-    with TestClient(_app()) as client:
-        for path in (
-            "/v1/responses",
-            "/v1/codex/responses",
-            "/backend-api/responses",
-            "/backend-api/codex/responses",
-        ):
-            with client.websocket_connect(path) as websocket:
-                assert websocket.receive_json() == {"path": path}
-
-    assert seen_paths == [
-        "/v1/responses",
-        "/v1/codex/responses",
-        "/backend-api/responses",
-        "/backend-api/codex/responses",
-    ]
-
-
-def test_openai_response_subpath_passthrough_returns_502_on_http_failure() -> None:
-    class FailingAsyncClient:
-        async def request(self, method, url, **kwargs):  # type: ignore[no-untyped-def]
-            raise RuntimeError(f"boom: {method} {url}")
-
-        async def aclose(self) -> None:
-            return None
-
-    with TestClient(_app()) as client:
-        client.app.state.proxy.http_client = FailingAsyncClient()
-        response = client.post("/v1/responses/compact?trace=1", json={"model": "gpt-4o"})
-
-    assert response.status_code == 502
-    assert "boom: POST https://api.openai.test/v1/responses/compact?trace=1" in response.text
-
-
-def test_openai_response_subpath_passthrough_uses_openai_target() -> None:
-    class FakeAsyncClient:
-        def __init__(self) -> None:
-            self.calls: list[tuple[str, str, dict[str, str]]] = []
-
-        async def request(self, method, url, **kwargs):  # type: ignore[no-untyped-def]
-            self.calls.append((method, url, dict(kwargs.get("headers", {}))))
-            return httpx.Response(200, json={"url": url})
-
-        async def aclose(self) -> None:
-            return None
-
-    with TestClient(_app()) as client:
-        fake = FakeAsyncClient()
-        client.app.state.proxy.http_client = fake
-        response = client.delete(
-            "/v1/responses/items/resp_123?trace=7",
-            headers={"Authorization": "Bearer sk-proj-test"},
-        )
-
-    assert response.status_code == 200
-    assert len(fake.calls) == 1
-    method, url, headers = fake.calls[0]
-    assert method == "DELETE"
-    assert url == "https://api.openai.test/v1/responses/items/resp_123?trace=7"
-    assert headers["authorization"] == "Bearer sk-proj-test"
-
-
-def test_openai_response_subpath_aliases_and_chatgpt_auth_use_expected_targets(monkeypatch) -> None:
-    monkeypatch.setattr(
-        "headroom.providers.proxy_routes._resolve_codex_routing_headers",
-        lambda headers: (headers, True),
-    )
-
-    class FakeAsyncClient:
-        def __init__(self) -> None:
-            self.calls: list[tuple[str, str]] = []
-
-        async def request(self, method, url, **kwargs):  # type: ignore[no-untyped-def]
-            self.calls.append((method, url))
-            return httpx.Response(200, json={"url": url})
-
-        async def aclose(self) -> None:
-            return None
-
-    with TestClient(_app()) as client:
-        fake = FakeAsyncClient()
-        client.app.state.proxy.http_client = fake
-        assert client.get("/v1/codex/responses/items/resp_1").status_code == 200
-        assert client.post("/backend-api/responses/items/resp_2").status_code == 200
-        assert client.delete("/backend-api/codex/responses/items/resp_3").status_code == 200
-
-    assert fake.calls == [
-        ("GET", "https://chatgpt.com/backend-api/codex/responses/items/resp_1"),
-        ("POST", "https://chatgpt.com/backend-api/codex/responses/items/resp_2"),
-        ("DELETE", "https://chatgpt.com/backend-api/codex/responses/items/resp_3"),
-    ]
-
-
-def test_gemini_batch_embed_contents_passthrough_uses_gemini_target(monkeypatch) -> None:
-    calls: list[tuple[str, str, str]] = []
-
-    async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""):  # type: ignore[no-untyped-def]
-        calls.append((request.url.path, base_url, sub_path))
-        return JSONResponse({"base_url": base_url, "sub_path": sub_path, "provider": provider_name})
-
-    monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)
-
-    with TestClient(_app()) as client:
-        response = client.post("/v1beta/models/demo:batchEmbedContents")
-
-    assert response.status_code == 200
-    assert response.json() == {
-        "base_url": "https://api.gemini.test",
-        "sub_path": "batchEmbedContents",
-        "provider": "gemini",
-    }
-    assert calls == [
-        ("/v1beta/models/demo:batchEmbedContents", "https://api.gemini.test", "batchEmbedContents")
-    ]
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+import httpx
+from fastapi.responses import JSONResponse
+from fastapi.testclient import TestClient
+
+from headroom.proxy.server import HeadroomProxy, ProxyConfig, create_app
+
+
+def _app() -> Any:
+    return create_app(
+        ProxyConfig(
+            optimize=False,
+            cache_enabled=False,
+            rate_limit_enabled=False,
+            anthropic_api_url="https://api.anthropic.test",
+            openai_api_url="https://api.openai.test",
+            gemini_api_url="https://api.gemini.test",
+            cloudcode_api_url="https://cloudcode.test",
+        )
+    )
+
+
+def test_provider_passthrough_routes_forward_expected_targets(monkeypatch) -> None:
+    calls: list[tuple[str, str, str, str]] = []
+
+    async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""):  # type: ignore[no-untyped-def]
+        calls.append((request.method, request.url.path, base_url, provider_name))
+        return JSONResponse(
+            {
+                "method": request.method,
+                "path": request.url.path,
+                "base_url": base_url,
+                "sub_path": sub_path,
+                "provider": provider_name,
+            }
+        )
+
+    monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)
+
+    with TestClient(_app()) as client:
+        assert client.post("/v1/messages/count_tokens").json()["base_url"] == (
+            "https://api.anthropic.test"
+        )
+        assert client.get("/v1/models", headers={"x-goog-api-key": "test"}).json()["base_url"] == (
+            "https://api.openai.test"
+        )
+        assert client.get("/v1/models/demo").json()["sub_path"] == "models"
+        assert (
+            client.get(
+                "/azure/models",
+                headers={
+                    "api-key": "azure-key",
+                    "x-headroom-base-url": "https://azure.example/openai/",
+                },
+            ).json()["base_url"]
+            == "https://azure.example/openai"
+        )
+        assert client.post("/v1/embeddings").json()["provider"] == "openai"
+        assert client.post("/v1/moderations").json()["sub_path"] == "moderations"
+        assert client.post("/v1/images/generations").json()["sub_path"] == "images/generations"
+        assert client.post("/v1/audio/transcriptions").json()["sub_path"] == "audio/transcriptions"
+        assert client.post("/v1/audio/speech").json()["sub_path"] == "audio/speech"
+        assert client.get("/v1beta/models").json()["provider"] == "gemini"
+        assert client.get("/v1beta/models/demo").json()["sub_path"] == "models"
+        assert client.post("/v1beta/models/demo:embedContent").json()["sub_path"] == "embedContent"
+        assert client.post("/v1beta/cachedContents").json()["sub_path"] == "cachedContents"
+        assert client.get("/v1beta/cachedContents").json()["sub_path"] == "cachedContents"
+        assert client.get("/v1beta/cachedContents/cache-1").json()["sub_path"] == "cachedContents"
+        assert client.delete("/v1beta/cachedContents/cache-1").json()["sub_path"] == (
+            "cachedContents"
+        )
+        assert (
+            client.get(
+                "/unhandled/path",
+                headers={"x-headroom-base-url": "https://custom.example/base/"},
+            ).json()["base_url"]
+            == "https://custom.example/base"
+        )
+        assert client.get("/another/path", headers={"x-goog-api-key": "test"}).json()[
+            "base_url"
+        ] == ("https://api.gemini.test")
+
+    assert len(calls) >= 16
+
+
+def test_proxy_route_helpers_prefer_legacy_targets_and_gemini_passthrough() -> None:
+    proxy_routes = importlib.import_module("headroom.providers.proxy_routes")
+    proxy = type(
+        "Proxy",
+        (),
+        {
+            "ANTHROPIC_API_URL": "https://legacy.anthropic.test",
+            "OPENAI_API_URL": "https://legacy.openai.test",
+            "GEMINI_API_URL": "https://legacy.gemini.test",
+            "provider_runtime": type(
+                "Runtime",
+                (),
+                {
+                    "api_target": staticmethod(lambda provider: f"https://runtime.{provider}.test"),
+                    "model_metadata_provider": staticmethod(lambda headers: "anthropic"),
+                },
+            )(),
+        },
+    )()
+
+    assert proxy_routes._api_target(proxy, "anthropic") == "https://legacy.anthropic.test"
+    assert proxy_routes._select_passthrough_base_url(proxy, {"x-goog-api-key": "test"}) == (
+        "https://legacy.gemini.test"
+    )
+    assert (
+        proxy_routes._select_passthrough_base_url(
+            proxy, {"api-key": "azure", "x-headroom-base-url": "https://azure.example/base/"}
+        )
+        == "https://azure.example/base"
+    )
+    assert proxy_routes._select_passthrough_base_url(proxy, {"api-key": "azure"}) == (
+        "https://legacy.anthropic.test"
+    )
+    assert proxy_routes._select_passthrough_base_url(proxy, {}) == "https://legacy.anthropic.test"
+
+
+def test_provider_specific_routes_delegate_to_expected_proxy_handlers(monkeypatch) -> None:
+    delegated: list[tuple[str, str, tuple[str, ...]]] = []
+
+    def install(name: str) -> None:
+        async def fake(self, request, *args):  # type: ignore[no-untyped-def]
+            delegated.append((name, request.url.path, tuple(str(arg) for arg in args)))
+            return JSONResponse({"handler": name, "path": request.url.path, "args": list(args)})
+
+        monkeypatch.setattr(HeadroomProxy, name, fake)
+
+    for handler_name in (
+        "handle_anthropic_messages",
+        "handle_anthropic_batch_create",
+        "handle_anthropic_batch_passthrough",
+        "handle_anthropic_batch_results",
+        "handle_openai_chat",
+        "handle_openai_responses",
+        "handle_batch_create",
+        "handle_batch_list",
+        "handle_batch_get",
+        "handle_batch_cancel",
+        "handle_gemini_generate_content",
+        "handle_gemini_stream_generate_content",
+        "handle_gemini_count_tokens",
+        "handle_google_cloudcode_stream",
+        "handle_databricks_invocations",
+        "handle_google_batch_create",
+        "handle_google_batch_results",
+        "handle_google_batch_passthrough",
+    ):
+        install(handler_name)
+
+    with TestClient(_app()) as client:
+        assert client.post("/v1/messages").json()["handler"] == "handle_anthropic_messages"
+        assert (
+            client.post("/v1/messages/batches").json()["handler"] == "handle_anthropic_batch_create"
+        )
+        assert client.get("/v1/messages/batches").json()["handler"] == (
+            "handle_anthropic_batch_passthrough"
+        )
+        assert client.get("/v1/messages/batches/b1").json()["args"] == ["b1"]
+        assert client.get("/v1/messages/batches/b1/results").json()["handler"] == (
+            "handle_anthropic_batch_results"
+        )
+        assert client.post("/v1/messages/batches/b1/cancel").json()["handler"] == (
+            "handle_anthropic_batch_passthrough"
+        )
+        assert client.post("/v1/chat/completions").json()["handler"] == "handle_openai_chat"
+        assert client.post("/v1/responses").json()["handler"] == "handle_openai_responses"
+        assert client.post("/v1/codex/responses").json()["handler"] == "handle_openai_responses"
+        assert client.post("/backend-api/responses").json()["handler"] == "handle_openai_responses"
+        assert client.post("/backend-api/codex/responses").json()["handler"] == (
+            "handle_openai_responses"
+        )
+        assert client.post("/v1/batches").json()["handler"] == "handle_batch_create"
+        assert client.get("/v1/batches").json()["handler"] == "handle_batch_list"
+        assert client.get("/v1/batches/b1").json()["handler"] == "handle_batch_get"
+        assert client.post("/v1/batches/b1/cancel").json()["handler"] == "handle_batch_cancel"
+        assert client.post("/v1beta/models/demo:generateContent").json()["handler"] == (
+            "handle_gemini_generate_content"
+        )
+        assert client.post("/v1beta/models/demo:streamGenerateContent").json()["handler"] == (
+            "handle_gemini_stream_generate_content"
+        )
+        assert client.post("/v1beta/models/demo:countTokens").json()["handler"] == (
+            "handle_gemini_count_tokens"
+        )
+        assert client.post("/v1internal:streamGenerateContent").json()["handler"] == (
+            "handle_google_cloudcode_stream"
+        )
+        assert client.post("/v1/v1internal:streamGenerateContent").json()["handler"] == (
+            "handle_google_cloudcode_stream"
+        )
+        assert client.post("/serving-endpoints/demo/invocations").json()["handler"] == (
+            "handle_databricks_invocations"
+        )
+        assert client.post("/v1beta/models/demo:batchGenerateContent").json()["handler"] == (
+            "handle_google_batch_create"
+        )
+        assert client.get("/v1beta/batches/b1").json()["handler"] == "handle_google_batch_results"
+        assert client.post("/v1beta/batches/b1:cancel").json()["handler"] == (
+            "handle_google_batch_passthrough"
+        )
+        assert client.delete("/v1beta/batches/b1").json()["handler"] == (
+            "handle_google_batch_passthrough"
+        )
+
+    assert len(delegated) >= 24
+
+
+def test_openai_response_websocket_aliases_delegate_to_openai_ws_handler(monkeypatch) -> None:
+    seen_paths: list[str] = []
+
+    async def fake_ws(self, websocket):  # type: ignore[no-untyped-def]
+        seen_paths.append(websocket.url.path)
+        await websocket.accept()
+        await websocket.send_json({"path": websocket.url.path})
+        await websocket.close()
+
+    monkeypatch.setattr(HeadroomProxy, "handle_openai_responses_ws", fake_ws)
+
+    with TestClient(_app()) as client:
+        for path in (
+            "/v1/responses",
+            "/v1/codex/responses",
+            "/backend-api/responses",
+            "/backend-api/codex/responses",
+        ):
+            with client.websocket_connect(path) as websocket:
+                assert websocket.receive_json() == {"path": path}
+
+    assert seen_paths == [
+        "/v1/responses",
+        "/v1/codex/responses",
+        "/backend-api/responses",
+        "/backend-api/codex/responses",
+    ]
+
+
+def test_openai_response_subpath_passthrough_returns_502_on_http_failure() -> None:
+    class FailingAsyncClient:
+        async def request(self, method, url, **kwargs):  # type: ignore[no-untyped-def]
+            raise RuntimeError(f"boom: {method} {url}")
+
+        async def aclose(self) -> None:
+            return None
+
+    with TestClient(_app()) as client:
+        client.app.state.proxy.http_client = FailingAsyncClient()
+        response = client.post("/v1/responses/compact?trace=1", json={"model": "gpt-4o"})
+
+    assert response.status_code == 502
+    assert "boom: POST https://api.openai.test/v1/responses/compact?trace=1" in response.text
+
+
+def test_openai_response_subpath_passthrough_uses_openai_target() -> None:
+    class FakeAsyncClient:
+        def __init__(self) -> None:
+            self.calls: list[tuple[str, str, dict[str, str]]] = []
+
+        async def request(self, method, url, **kwargs):  # type: ignore[no-untyped-def]
+            self.calls.append((method, url, dict(kwargs.get("headers", {}))))
+            return httpx.Response(200, json={"url": url})
+
+        async def aclose(self) -> None:
+            return None
+
+    with TestClient(_app()) as client:
+        fake = FakeAsyncClient()
+        client.app.state.proxy.http_client = fake
+        response = client.delete(
+            "/v1/responses/items/resp_123?trace=7",
+            headers={"Authorization": "Bearer sk-proj-test"},
+        )
+
+    assert response.status_code == 200
+    assert len(fake.calls) == 1
+    method, url, headers = fake.calls[0]
+    assert method == "DELETE"
+    assert url == "https://api.openai.test/v1/responses/items/resp_123?trace=7"
+    assert headers["authorization"] == "Bearer sk-proj-test"
+
+
+def test_openai_response_subpath_aliases_and_chatgpt_auth_use_expected_targets(monkeypatch) -> None:
+    monkeypatch.setattr(
+        "headroom.providers.proxy_routes._resolve_codex_routing_headers",
+        lambda headers: (headers, True),
+    )
+
+    class FakeAsyncClient:
+        def __init__(self) -> None:
+            self.calls: list[tuple[str, str]] = []
+
+        async def request(self, method, url, **kwargs):  # type: ignore[no-untyped-def]
+            self.calls.append((method, url))
+            return httpx.Response(200, json={"url": url})
+
+        async def aclose(self) -> None:
+            return None
+
+    with TestClient(_app()) as client:
+        fake = FakeAsyncClient()
+        client.app.state.proxy.http_client = fake
+        assert client.get("/v1/codex/responses/items/resp_1").status_code == 200
+        assert client.post("/backend-api/responses/items/resp_2").status_code == 200
+        assert client.delete("/backend-api/codex/responses/items/resp_3").status_code == 200
+
+    assert fake.calls == [
+        ("GET", "https://chatgpt.com/backend-api/codex/responses/items/resp_1"),
+        ("POST", "https://chatgpt.com/backend-api/codex/responses/items/resp_2"),
+        ("DELETE", "https://chatgpt.com/backend-api/codex/responses/items/resp_3"),
+    ]
+
+
+def test_gemini_batch_embed_contents_passthrough_uses_gemini_target(monkeypatch) -> None:
+    calls: list[tuple[str, str, str]] = []
+
+    async def fake_passthrough(self, request, base_url, sub_path="", provider_name=""):  # type: ignore[no-untyped-def]
+        calls.append((request.url.path, base_url, sub_path))
+        return JSONResponse({"base_url": base_url, "sub_path": sub_path, "provider": provider_name})
+
+    monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)
+
+    with TestClient(_app()) as client:
+        response = client.post("/v1beta/models/demo:batchEmbedContents")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "base_url": "https://api.gemini.test",
+        "sub_path": "batchEmbedContents",
+        "provider": "gemini",
+    }
+    assert calls == [
+        ("/v1beta/models/demo:batchEmbedContents", "https://api.gemini.test", "batchEmbedContents")
+    ]
diff --git a/tests/test_provider_registry_extended.py b/tests/test_provider_registry_extended.py
index d584d9caed2cd11f7db8efd1a3572895158a91dc..97f50ab28ea8775a56584a30abcafa23e2b28526 100644
--- a/tests/test_provider_registry_extended.py
+++ b/tests/test_provider_registry_extended.py
@@ -1,239 +1,239 @@
-from __future__ import annotations
-
-import logging
-from types import SimpleNamespace
-from typing import Any
-
-import pytest
-
-from headroom.providers.registry import (
-    ProviderApiTargets,
-    ProxyProviderRuntime,
-    call_client_transport,
-    create_proxy_backend,
-    format_backend_status,
-)
-
-
-class DummyStorage:
-    def __init__(self) -> None:
-        self.saved: list[Any] = []
-
-    def save(self, metrics: Any) -> None:
-        self.saved.append(metrics)
-
-
-class DummyClient:
-    def __init__(self) -> None:
-        self._storage = DummyStorage()
-        self._wrapped_stream: tuple[Any, Any] | None = None
-        self._original = SimpleNamespace(
-            chat=SimpleNamespace(completions=SimpleNamespace(create=self._openai_create)),
-            messages=SimpleNamespace(create=self._anthropic_create, stream=self._anthropic_stream),
-        )
-        self.openai_calls: list[dict[str, Any]] = []
-        self.anthropic_calls: list[dict[str, Any]] = []
-
-    def _openai_create(self, **kwargs: Any) -> Any:
-        self.openai_calls.append(kwargs)
-        if kwargs["stream"]:
-            return iter(["chunk-1", "chunk-2"])
-        return SimpleNamespace(
-            usage=SimpleNamespace(
-                completion_tokens=7,
-                prompt_tokens_details=SimpleNamespace(cached_tokens=3),
-            )
-        )
-
-    def _anthropic_create(self, **kwargs: Any) -> Any:
-        self.anthropic_calls.append(kwargs)
-        return SimpleNamespace(
-            usage=SimpleNamespace(
-                output_tokens=5,
-                cache_read_input_tokens=2,
-            )
-        )
-
-    def _anthropic_stream(self, **kwargs: Any) -> Any:
-        self.anthropic_calls.append(kwargs)
-        return "anthropic-stream"
-
-    def _wrap_stream(self, stream: Any, metrics: Any) -> Any:
-        self._wrapped_stream = (stream, metrics)
-        return ("wrapped", stream)
-
-
-def test_proxy_provider_runtime_selects_targets_and_providers() -> None:
-    runtime = ProxyProviderRuntime(
-        api_targets=ProviderApiTargets(
-            anthropic="https://anthropic.example",
-            openai="https://openai.example",
-            gemini="https://gemini.example",
-            cloudcode="https://cloudcode.example",
-        ),
-        pipeline_providers={
-            "anthropic": SimpleNamespace(name="anthropic"),
-            "openai": SimpleNamespace(name="openai"),
-        },
-    )
-
-    assert runtime.api_target("anthropic") == "https://anthropic.example"
-    assert runtime.pipeline_provider("openai").name == "openai"
-    assert runtime.model_metadata_provider({"Authorization": "Bearer sk-ant-api03-test"}) == (
-        "anthropic"
-    )
-    assert runtime.select_passthrough_base_url({"x-goog-api-key": "test"}) == (
-        "https://gemini.example"
-    )
-    assert (
-        runtime.select_passthrough_base_url(
-            {"api-key": "azure-key", "x-headroom-base-url": "https://azure.example/openai/"}
-        )
-        == "https://azure.example/openai"
-    )
-    assert runtime.select_passthrough_base_url({}) == "https://openai.example"
-
-
-def test_create_proxy_backend_uses_injected_backend_types() -> None:
-    logger = logging.getLogger("test")
-
-    anyllm = create_proxy_backend(
-        backend="anyllm",
-        anyllm_provider="groq",
-        bedrock_region=None,
-        logger=logger,
-        anyllm_backend_cls=lambda provider: {"kind": "anyllm", "provider": provider},
-    )
-    litellm = create_proxy_backend(
-        backend="bedrock",
-        anyllm_provider="ignored",
-        bedrock_region="us-east-1",
-        logger=logger,
-        litellm_backend_cls=lambda provider, region: {
-            "kind": "litellm",
-            "provider": provider,
-            "region": region,
-        },
-    )
-
-    assert anyllm == {"kind": "anyllm", "provider": "groq"}
-    assert litellm == {"kind": "litellm", "provider": "bedrock", "region": "us-east-1"}
-
-
-def test_create_proxy_backend_handles_missing_or_direct_backends(
-    caplog: pytest.LogCaptureFixture,
-) -> None:
-    logger = logging.getLogger("test")
-
-    direct = create_proxy_backend(
-        backend="anthropic",
-        anyllm_provider="ignored",
-        bedrock_region=None,
-        logger=logger,
-    )
-
-    with caplog.at_level(logging.WARNING):
-        missing = create_proxy_backend(
-            backend="anyllm",
-            anyllm_provider="groq",
-            bedrock_region=None,
-            logger=logger,
-            anyllm_backend_cls=lambda provider: (_ for _ in ()).throw(ImportError("missing")),
-        )
-
-    assert direct is None
-    assert missing is None
-    assert "any-llm backend not available" in caplog.text
-
-
-def test_format_backend_status_uses_litellm_provider_metadata(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.setattr(
-        "headroom.backends.litellm.get_provider_config",
-        lambda provider: SimpleNamespace(
-            display_name=provider.upper(),
-            uses_region=(provider == "bedrock"),
-        ),
-    )
-
-    assert (
-        format_backend_status(
-            backend="litellm-bedrock",
-            anyllm_provider="ignored",
-            bedrock_region="us-west-2",
-        )
-        == "BEDROCK via LiteLLM (region=us-west-2)"
-    )
-    assert (
-        format_backend_status(
-            backend="litellm-openai",
-            anyllm_provider="ignored",
-            bedrock_region=None,
-        )
-        == "OPENAI via LiteLLM"
-    )
-
-
-def test_call_client_transport_covers_openai_and_anthropic_paths() -> None:
-    client = DummyClient()
-    openai_metrics = SimpleNamespace(tokens_output=0, cached_tokens=0)
-    anthropic_metrics = SimpleNamespace(tokens_output=0, cached_tokens=0)
-
-    openai_response = call_client_transport(
-        "openai",
-        client,
-        model="gpt-4o",
-        messages=[{"role": "user", "content": "hello"}],
-        stream=False,
-        metrics=openai_metrics,
-        temperature=0,
-    )
-    openai_stream = call_client_transport(
-        "openai",
-        client,
-        model="gpt-4o",
-        messages=[{"role": "user", "content": "hello"}],
-        stream=True,
-        metrics=openai_metrics,
-    )
-    anthropic_response = call_client_transport(
-        "anthropic",
-        client,
-        model="claude-sonnet",
-        messages=[{"role": "user", "content": "hello"}],
-        stream=False,
-        metrics=anthropic_metrics,
-        max_tokens=32,
-    )
-    anthropic_stream = call_client_transport(
-        "anthropic",
-        client,
-        model="claude-sonnet",
-        messages=[{"role": "user", "content": "hello"}],
-        stream=True,
-        metrics=anthropic_metrics,
-        max_tokens=32,
-    )
-
-    assert openai_response.usage.completion_tokens == 7
-    assert openai_metrics.tokens_output == 7
-    assert openai_metrics.cached_tokens == 3
-    assert openai_stream == ("wrapped", client._wrapped_stream[0])
-    assert anthropic_response.usage.output_tokens == 5
-    assert anthropic_metrics.tokens_output == 5
-    assert anthropic_metrics.cached_tokens == 2
-    assert anthropic_stream == "anthropic-stream"
-    assert len(client._storage.saved) == 3
-
-
-def test_call_client_transport_rejects_unknown_api_style() -> None:
-    with pytest.raises(ValueError, match="Unsupported api_style"):
-        call_client_transport(
-            "unknown",
-            DummyClient(),
-            model="gpt-4o",
-            messages=[],
-            stream=False,
-            metrics=SimpleNamespace(),
-        )
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from headroom.providers.registry import (
+    ProviderApiTargets,
+    ProxyProviderRuntime,
+    call_client_transport,
+    create_proxy_backend,
+    format_backend_status,
+)
+
+
+class DummyStorage:
+    def __init__(self) -> None:
+        self.saved: list[Any] = []
+
+    def save(self, metrics: Any) -> None:
+        self.saved.append(metrics)
+
+
+class DummyClient:
+    def __init__(self) -> None:
+        self._storage = DummyStorage()
+        self._wrapped_stream: tuple[Any, Any] | None = None
+        self._original = SimpleNamespace(
+            chat=SimpleNamespace(completions=SimpleNamespace(create=self._openai_create)),
+            messages=SimpleNamespace(create=self._anthropic_create, stream=self._anthropic_stream),
+        )
+        self.openai_calls: list[dict[str, Any]] = []
+        self.anthropic_calls: list[dict[str, Any]] = []
+
+    def _openai_create(self, **kwargs: Any) -> Any:
+        self.openai_calls.append(kwargs)
+        if kwargs["stream"]:
+            return iter(["chunk-1", "chunk-2"])
+        return SimpleNamespace(
+            usage=SimpleNamespace(
+                completion_tokens=7,
+                prompt_tokens_details=SimpleNamespace(cached_tokens=3),
+            )
+        )
+
+    def _anthropic_create(self, **kwargs: Any) -> Any:
+        self.anthropic_calls.append(kwargs)
+        return SimpleNamespace(
+            usage=SimpleNamespace(
+                output_tokens=5,
+                cache_read_input_tokens=2,
+            )
+        )
+
+    def _anthropic_stream(self, **kwargs: Any) -> Any:
+        self.anthropic_calls.append(kwargs)
+        return "anthropic-stream"
+
+    def _wrap_stream(self, stream: Any, metrics: Any) -> Any:
+        self._wrapped_stream = (stream, metrics)
+        return ("wrapped", stream)
+
+
+def test_proxy_provider_runtime_selects_targets_and_providers() -> None:
+    runtime = ProxyProviderRuntime(
+        api_targets=ProviderApiTargets(
+            anthropic="https://anthropic.example",
+            openai="https://openai.example",
+            gemini="https://gemini.example",
+            cloudcode="https://cloudcode.example",
+        ),
+        pipeline_providers={
+            "anthropic": SimpleNamespace(name="anthropic"),
+            "openai": SimpleNamespace(name="openai"),
+        },
+    )
+
+    assert runtime.api_target("anthropic") == "https://anthropic.example"
+    assert runtime.pipeline_provider("openai").name == "openai"
+    assert runtime.model_metadata_provider({"Authorization": "Bearer sk-ant-api03-test"}) == (
+        "anthropic"
+    )
+    assert runtime.select_passthrough_base_url({"x-goog-api-key": "test"}) == (
+        "https://gemini.example"
+    )
+    assert (
+        runtime.select_passthrough_base_url(
+            {"api-key": "azure-key", "x-headroom-base-url": "https://azure.example/openai/"}
+        )
+        == "https://azure.example/openai"
+    )
+    assert runtime.select_passthrough_base_url({}) == "https://openai.example"
+
+
+def test_create_proxy_backend_uses_injected_backend_types() -> None:
+    logger = logging.getLogger("test")
+
+    anyllm = create_proxy_backend(
+        backend="anyllm",
+        anyllm_provider="groq",
+        bedrock_region=None,
+        logger=logger,
+        anyllm_backend_cls=lambda provider: {"kind": "anyllm", "provider": provider},
+    )
+    litellm = create_proxy_backend(
+        backend="bedrock",
+        anyllm_provider="ignored",
+        bedrock_region="us-east-1",
+        logger=logger,
+        litellm_backend_cls=lambda provider, region: {
+            "kind": "litellm",
+            "provider": provider,
+            "region": region,
+        },
+    )
+
+    assert anyllm == {"kind": "anyllm", "provider": "groq"}
+    assert litellm == {"kind": "litellm", "provider": "bedrock", "region": "us-east-1"}
+
+
+def test_create_proxy_backend_handles_missing_or_direct_backends(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    logger = logging.getLogger("test")
+
+    direct = create_proxy_backend(
+        backend="anthropic",
+        anyllm_provider="ignored",
+        bedrock_region=None,
+        logger=logger,
+    )
+
+    with caplog.at_level(logging.WARNING):
+        missing = create_proxy_backend(
+            backend="anyllm",
+            anyllm_provider="groq",
+            bedrock_region=None,
+            logger=logger,
+            anyllm_backend_cls=lambda provider: (_ for _ in ()).throw(ImportError("missing")),
+        )
+
+    assert direct is None
+    assert missing is None
+    assert "any-llm backend not available" in caplog.text
+
+
+def test_format_backend_status_uses_litellm_provider_metadata(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        "headroom.backends.litellm.get_provider_config",
+        lambda provider: SimpleNamespace(
+            display_name=provider.upper(),
+            uses_region=(provider == "bedrock"),
+        ),
+    )
+
+    assert (
+        format_backend_status(
+            backend="litellm-bedrock",
+            anyllm_provider="ignored",
+            bedrock_region="us-west-2",
+        )
+        == "BEDROCK via LiteLLM (region=us-west-2)"
+    )
+    assert (
+        format_backend_status(
+            backend="litellm-openai",
+            anyllm_provider="ignored",
+            bedrock_region=None,
+        )
+        == "OPENAI via LiteLLM"
+    )
+
+
+def test_call_client_transport_covers_openai_and_anthropic_paths() -> None:
+    client = DummyClient()
+    openai_metrics = SimpleNamespace(tokens_output=0, cached_tokens=0)
+    anthropic_metrics = SimpleNamespace(tokens_output=0, cached_tokens=0)
+
+    openai_response = call_client_transport(
+        "openai",
+        client,
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "hello"}],
+        stream=False,
+        metrics=openai_metrics,
+        temperature=0,
+    )
+    openai_stream = call_client_transport(
+        "openai",
+        client,
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "hello"}],
+        stream=True,
+        metrics=openai_metrics,
+    )
+    anthropic_response = call_client_transport(
+        "anthropic",
+        client,
+        model="claude-sonnet",
+        messages=[{"role": "user", "content": "hello"}],
+        stream=False,
+        metrics=anthropic_metrics,
+        max_tokens=32,
+    )
+    anthropic_stream = call_client_transport(
+        "anthropic",
+        client,
+        model="claude-sonnet",
+        messages=[{"role": "user", "content": "hello"}],
+        stream=True,
+        metrics=anthropic_metrics,
+        max_tokens=32,
+    )
+
+    assert openai_response.usage.completion_tokens == 7
+    assert openai_metrics.tokens_output == 7
+    assert openai_metrics.cached_tokens == 3
+    assert openai_stream == ("wrapped", client._wrapped_stream[0])
+    assert anthropic_response.usage.output_tokens == 5
+    assert anthropic_metrics.tokens_output == 5
+    assert anthropic_metrics.cached_tokens == 2
+    assert anthropic_stream == "anthropic-stream"
+    assert len(client._storage.saved) == 3
+
+
+def test_call_client_transport_rejects_unknown_api_style() -> None:
+    with pytest.raises(ValueError, match="Unsupported api_style"):
+        call_client_transport(
+            "unknown",
+            DummyClient(),
+            model="gpt-4o",
+            messages=[],
+            stream=False,
+            metrics=SimpleNamespace(),
+        )
diff --git a/tests/test_proxy_copilot_auth_hooks.py b/tests/test_proxy_copilot_auth_hooks.py
index b16f222119b27da5893ddd1d3eceeeee27c8ee21..45eeb3b09df6bb8d3e19ec8c29c7c7c53c454b61 100644
--- a/tests/test_proxy_copilot_auth_hooks.py
+++ b/tests/test_proxy_copilot_auth_hooks.py
@@ -1,199 +1,199 @@
-from __future__ import annotations
-
-import asyncio
-import importlib.util
-import sys
-import types
-from pathlib import Path
-from types import SimpleNamespace
-
-import pytest
-
-ROOT = Path(__file__).resolve().parents[1]
-_ISOLATED_MODULE_NAMES = (
-    "headroom.proxy",
-    "headroom.proxy.handlers",
-    "httpx",
-    "fastapi.responses",
-    "tests.headroom_proxy_handlers_openai",
-    "tests.headroom_proxy_handlers_streaming",
-)
-
-
-@pytest.fixture(autouse=True)
-def restore_isolated_modules() -> None:
-    saved_modules = {name: sys.modules.get(name) for name in _ISOLATED_MODULE_NAMES}
-    try:
-        yield
-    finally:
-        for name in _ISOLATED_MODULE_NAMES:
-            sys.modules.pop(name, None)
-        for name, module in saved_modules.items():
-            if module is not None:
-                sys.modules[name] = module
-
-
-def _load_handler_module(monkeypatch: pytest.MonkeyPatch, module_name: str, relative_path: str):
-    proxy_pkg = types.ModuleType("headroom.proxy")
-    proxy_pkg.__path__ = [str(ROOT / "headroom" / "proxy")]
-    monkeypatch.setitem(sys.modules, "headroom.proxy", proxy_pkg)
-
-    handlers_pkg = types.ModuleType("headroom.proxy.handlers")
-    handlers_pkg.__path__ = [str(ROOT / "headroom" / "proxy" / "handlers")]
-    monkeypatch.setitem(sys.modules, "headroom.proxy.handlers", handlers_pkg)
-
-    httpx_mod = types.ModuleType("httpx")
-    httpx_mod.ConnectError = type("ConnectError", (Exception,), {})
-    httpx_mod.ConnectTimeout = type("ConnectTimeout", (Exception,), {})
-    httpx_mod.PoolTimeout = type("PoolTimeout", (Exception,), {})
-    monkeypatch.setitem(sys.modules, "httpx", httpx_mod)
-
-    responses_mod = types.ModuleType("fastapi.responses")
-
-    class Response:
-        def __init__(self, content=None, status_code: int = 200, headers=None, media_type=None):
-            self.content = content
-            self.status_code = status_code
-            self.headers = headers or {}
-            self.media_type = media_type
-
-    class StreamingResponse(Response):
-        pass
-
-    class JSONResponse(Response):
-        pass
-
-    responses_mod.Response = Response
-    responses_mod.StreamingResponse = StreamingResponse
-    responses_mod.JSONResponse = JSONResponse
-    monkeypatch.setitem(sys.modules, "fastapi.responses", responses_mod)
-
-    spec = importlib.util.spec_from_file_location(module_name, ROOT / relative_path)
-    assert spec is not None and spec.loader is not None
-    module = importlib.util.module_from_spec(spec)
-    monkeypatch.setitem(sys.modules, module_name, module)
-    spec.loader.exec_module(module)
-    return module
-
-
-def test_openai_passthrough_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch) -> None:
-    openai_mod = _load_handler_module(
-        monkeypatch,
-        "tests.headroom_proxy_handlers_openai",
-        "headroom/proxy/handlers/openai.py",
-    )
-
-    seen: dict[str, object] = {}
-
-    async def fake_apply(headers: dict[str, str], *, url: str) -> dict[str, str]:
-        seen["headers"] = dict(headers)
-        seen["url"] = url
-        return {"Authorization": "Bearer upstream-token"}
-
-    monkeypatch.setattr(openai_mod, "apply_copilot_api_auth", fake_apply)
-
-    class Dummy(openai_mod.OpenAIHandlerMixin):
-        def __init__(self) -> None:
-            self.metrics = SimpleNamespace(record_request=self._record_request)
-            self.http_client = SimpleNamespace(request=self._request)
-
-        async def _record_request(self, **kwargs) -> None:  # noqa: ANN003
-            return None
-
-        async def _request(self, **kwargs):  # noqa: ANN003
-            seen["request_kwargs"] = kwargs
-            return SimpleNamespace(headers={}, content=b"{}", status_code=200)
-
-    request = SimpleNamespace(
-        url=SimpleNamespace(path="/v1/models", query=""),
-        headers={
-            "authorization": "Bearer downstream",
-            "host": "localhost",
-            "accept-encoding": "gzip",
-        },
-        method="GET",
-        body=lambda: None,
-    )
-
-    async def body() -> bytes:
-        return b""
-
-    request.body = body
-
-    handler = Dummy()
-    response = asyncio.run(
-        handler.handle_passthrough(
-            request,
-            "https://api.githubcopilot.com",
-            "models",
-            "openai",
-        )
-    )
-
-    assert seen["url"] == "https://api.githubcopilot.com/models"
-    assert seen["request_kwargs"]["headers"] == {"Authorization": "Bearer upstream-token"}
-    assert response.status_code == 200
-
-
-def test_streaming_response_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch) -> None:
-    streaming_mod = _load_handler_module(
-        monkeypatch,
-        "tests.headroom_proxy_handlers_streaming",
-        "headroom/proxy/handlers/streaming.py",
-    )
-
-    seen: dict[str, object] = {}
-
-    async def fake_apply(headers: dict[str, str], *, url: str) -> dict[str, str]:
-        seen["headers"] = dict(headers)
-        seen["url"] = url
-        return {"Authorization": "Bearer upstream-token"}
-
-    monkeypatch.setattr(streaming_mod, "apply_copilot_api_auth", fake_apply)
-
-    class Dummy(streaming_mod.StreamingMixin):
-        def __init__(self) -> None:
-            self.memory_handler = None
-            self.config = SimpleNamespace(
-                retry_max_attempts=1,
-                retry_base_delay_ms=1,
-                retry_max_delay_ms=1,
-            )
-            self.http_client = SimpleNamespace(
-                build_request=self._build_request,
-                send=self._send,
-            )
-
-        def _build_request(self, method: str, url: str, json: dict, headers: dict):  # noqa: ANN003, A002
-            seen["request"] = {
-                "method": method,
-                "url": url,
-                "json": json,
-                "headers": headers,
-            }
-            return SimpleNamespace()
-
-        async def _send(self, request, stream: bool):  # noqa: ANN001, ANN003
-            return SimpleNamespace(headers={}, status_code=200)
-
-    handler = Dummy()
-    response = asyncio.run(
-        handler._stream_response(
-            url="https://api.githubcopilot.com/v1/responses",
-            headers={"authorization": "Bearer downstream"},
-            body={"model": "gpt-4o"},
-            provider="openai",
-            model="gpt-4o",
-            request_id="req-test",
-            original_tokens=0,
-            optimized_tokens=0,
-            tokens_saved=0,
-            transforms_applied=[],
-            tags={},
-            optimization_latency=0.0,
-        )
-    )
-
-    assert seen["url"] == "https://api.githubcopilot.com/v1/responses"
-    assert seen["request"]["headers"] == {"Authorization": "Bearer upstream-token"}
-    assert response.status_code == 200
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import sys
+import types
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+_ISOLATED_MODULE_NAMES = (
+    "headroom.proxy",
+    "headroom.proxy.handlers",
+    "httpx",
+    "fastapi.responses",
+    "tests.headroom_proxy_handlers_openai",
+    "tests.headroom_proxy_handlers_streaming",
+)
+
+
+@pytest.fixture(autouse=True)
+def restore_isolated_modules() -> None:
+    saved_modules = {name: sys.modules.get(name) for name in _ISOLATED_MODULE_NAMES}
+    try:
+        yield
+    finally:
+        for name in _ISOLATED_MODULE_NAMES:
+            sys.modules.pop(name, None)
+        for name, module in saved_modules.items():
+            if module is not None:
+                sys.modules[name] = module
+
+
+def _load_handler_module(monkeypatch: pytest.MonkeyPatch, module_name: str, relative_path: str):
+    proxy_pkg = types.ModuleType("headroom.proxy")
+    proxy_pkg.__path__ = [str(ROOT / "headroom" / "proxy")]
+    monkeypatch.setitem(sys.modules, "headroom.proxy", proxy_pkg)
+
+    handlers_pkg = types.ModuleType("headroom.proxy.handlers")
+    handlers_pkg.__path__ = [str(ROOT / "headroom" / "proxy" / "handlers")]
+    monkeypatch.setitem(sys.modules, "headroom.proxy.handlers", handlers_pkg)
+
+    httpx_mod = types.ModuleType("httpx")
+    httpx_mod.ConnectError = type("ConnectError", (Exception,), {})
+    httpx_mod.ConnectTimeout = type("ConnectTimeout", (Exception,), {})
+    httpx_mod.PoolTimeout = type("PoolTimeout", (Exception,), {})
+    monkeypatch.setitem(sys.modules, "httpx", httpx_mod)
+
+    responses_mod = types.ModuleType("fastapi.responses")
+
+    class Response:
+        def __init__(self, content=None, status_code: int = 200, headers=None, media_type=None):
+            self.content = content
+            self.status_code = status_code
+            self.headers = headers or {}
+            self.media_type = media_type
+
+    class StreamingResponse(Response):
+        pass
+
+    class JSONResponse(Response):
+        pass
+
+    responses_mod.Response = Response
+    responses_mod.StreamingResponse = StreamingResponse
+    responses_mod.JSONResponse = JSONResponse
+    monkeypatch.setitem(sys.modules, "fastapi.responses", responses_mod)
+
+    spec = importlib.util.spec_from_file_location(module_name, ROOT / relative_path)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    monkeypatch.setitem(sys.modules, module_name, module)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_openai_passthrough_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch) -> None:
+    openai_mod = _load_handler_module(
+        monkeypatch,
+        "tests.headroom_proxy_handlers_openai",
+        "headroom/proxy/handlers/openai.py",
+    )
+
+    seen: dict[str, object] = {}
+
+    async def fake_apply(headers: dict[str, str], *, url: str) -> dict[str, str]:
+        seen["headers"] = dict(headers)
+        seen["url"] = url
+        return {"Authorization": "Bearer upstream-token"}
+
+    monkeypatch.setattr(openai_mod, "apply_copilot_api_auth", fake_apply)
+
+    class Dummy(openai_mod.OpenAIHandlerMixin):
+        def __init__(self) -> None:
+            self.metrics = SimpleNamespace(record_request=self._record_request)
+            self.http_client = SimpleNamespace(request=self._request)
+
+        async def _record_request(self, **kwargs) -> None:  # noqa: ANN003
+            return None
+
+        async def _request(self, **kwargs):  # noqa: ANN003
+            seen["request_kwargs"] = kwargs
+            return SimpleNamespace(headers={}, content=b"{}", status_code=200)
+
+    request = SimpleNamespace(
+        url=SimpleNamespace(path="/v1/models", query=""),
+        headers={
+            "authorization": "Bearer downstream",
+            "host": "localhost",
+            "accept-encoding": "gzip",
+        },
+        method="GET",
+        body=lambda: None,
+    )
+
+    async def body() -> bytes:
+        return b""
+
+    request.body = body
+
+    handler = Dummy()
+    response = asyncio.run(
+        handler.handle_passthrough(
+            request,
+            "https://api.githubcopilot.com",
+            "models",
+            "openai",
+        )
+    )
+
+    assert seen["url"] == "https://api.githubcopilot.com/models"
+    assert seen["request_kwargs"]["headers"] == {"Authorization": "Bearer upstream-token"}
+    assert response.status_code == 200
+
+
+def test_streaming_response_applies_copilot_auth(monkeypatch: pytest.MonkeyPatch) -> None:
+    streaming_mod = _load_handler_module(
+        monkeypatch,
+        "tests.headroom_proxy_handlers_streaming",
+        "headroom/proxy/handlers/streaming.py",
+    )
+
+    seen: dict[str, object] = {}
+
+    async def fake_apply(headers: dict[str, str], *, url: str) -> dict[str, str]:
+        seen["headers"] = dict(headers)
+        seen["url"] = url
+        return {"Authorization": "Bearer upstream-token"}
+
+    monkeypatch.setattr(streaming_mod, "apply_copilot_api_auth", fake_apply)
+
+    class Dummy(streaming_mod.StreamingMixin):
+        def __init__(self) -> None:
+            self.memory_handler = None
+            self.config = SimpleNamespace(
+                retry_max_attempts=1,
+                retry_base_delay_ms=1,
+                retry_max_delay_ms=1,
+            )
+            self.http_client = SimpleNamespace(
+                build_request=self._build_request,
+                send=self._send,
+            )
+
+        def _build_request(self, method: str, url: str, json: dict, headers: dict):  # noqa: ANN003, A002
+            seen["request"] = {
+                "method": method,
+                "url": url,
+                "json": json,
+                "headers": headers,
+            }
+            return SimpleNamespace()
+
+        async def _send(self, request, stream: bool):  # noqa: ANN001, ANN003
+            return SimpleNamespace(headers={}, status_code=200)
+
+    handler = Dummy()
+    response = asyncio.run(
+        handler._stream_response(
+            url="https://api.githubcopilot.com/v1/responses",
+            headers={"authorization": "Bearer downstream"},
+            body={"model": "gpt-4o"},
+            provider="openai",
+            model="gpt-4o",
+            request_id="req-test",
+            original_tokens=0,
+            optimized_tokens=0,
+            tokens_saved=0,
+            transforms_applied=[],
+            tags={},
+            optimization_latency=0.0,
+        )
+    )
+
+    assert seen["url"] == "https://api.githubcopilot.com/v1/responses"
+    assert seen["request"]["headers"] == {"Authorization": "Bearer upstream-token"}
+    assert response.status_code == 200
diff --git a/tests/test_proxy_handler_helpers.py b/tests/test_proxy_handler_helpers.py
index 53d3087e328391b09defc463697a3496a0cbe95a..9a87da187acd53180895ecde801f676f5df34883 100644
--- a/tests/test_proxy_handler_helpers.py
+++ b/tests/test_proxy_handler_helpers.py
@@ -1,214 +1,214 @@
-from __future__ import annotations
-
-import base64
-import json
-
-from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
-from headroom.proxy.handlers.openai import OpenAIHandlerMixin, _decode_openai_bearer_payload
-
-
-def _jwt(payload: object) -> str:
-    header = {"alg": "none", "typ": "JWT"}
-
-    def encode(part: object) -> str:
-        raw = json.dumps(part, separators=(",", ":")).encode("utf-8")
-        return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
-
-    return f"{encode(header)}.{encode(payload)}."
-
-
-class _ImageCompressor:
-    def __init__(self, compressed_message):
-        self._compressed_message = compressed_message
-
-    def compress(self, messages, provider):  # noqa: ANN001, ANN201
-        assert provider == "anthropic"
-        return [self._compressed_message]
-
-
-def test_decode_openai_bearer_payload_handles_missing_and_non_mapping_payloads() -> None:
-    assert _decode_openai_bearer_payload({}) is None
-    assert _decode_openai_bearer_payload({"authorization": "Basic abc"}) is None
-    assert (
-        _decode_openai_bearer_payload({"authorization": f"Bearer {_jwt(['not', 'a', 'dict'])}"})
-        is None
-    )
-
-
-def test_openai_handler_prefix_helpers_cover_edge_cases() -> None:
-    assert OpenAIHandlerMixin._strict_previous_turn_frozen_count([], 2) == 2
-    assert (
-        OpenAIHandlerMixin._strict_previous_turn_frozen_count(
-            [{"role": "assistant"}, {"role": "user"}],
-            0,
-        )
-        == 1
-    )
-    assert (
-        OpenAIHandlerMixin._strict_previous_turn_frozen_count(
-            [{"role": "user"}, {"role": "assistant"}],
-            0,
-        )
-        == 2
-    )
-
-    original = [{"role": "system", "content": "keep"}, {"role": "user", "content": "hello"}]
-    restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(
-        original,
-        [],
-        frozen_message_count=1,
-    )
-    assert restored == [{"role": "system", "content": "keep"}]
-    assert changed == 1
-
-    restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(
-        original,
-        [{"role": "system", "content": "changed"}, {"role": "user", "content": "hello"}],
-        frozen_message_count=1,
-    )
-    assert restored == original
-    assert changed == 1
-
-
-def test_anthropic_tool_sort_and_context_append_helpers() -> None:
-    tools = [
-        {"type": "function", "function": {"name": "beta"}},
-        {"name": "alpha"},
-        {"type": "tool"},
-    ]
-
-    sorted_tools = AnthropicHandlerMixin._sort_tools_deterministically(tools)
-
-    assert [AnthropicHandlerMixin._tool_sort_key(tool)[0] for tool in sorted_tools] == [
-        "alpha",
-        "beta",
-        "tool",
-    ]
-    assert AnthropicHandlerMixin._sort_tools_deterministically(None) is None
-    assert (
-        AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
-            [], "ctx", frozen_message_count=0
-        )
-        == []
-    )
-    assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
-        [{"role": "user", "content": "hello"}],
-        "ctx",
-        frozen_message_count=0,
-    ) == [{"role": "user", "content": "hello\n\nctx"}]
-    assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
-        [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],
-        "ctx",
-        frozen_message_count=0,
-    ) == [{"role": "user", "content": [{"type": "text", "text": "hello"}]}]
-
-
-def test_anthropic_image_compression_helper_only_rewrites_latest_eligible_turn() -> None:
-    image_message = {
-        "role": "user",
-        "content": [{"type": "image", "source": {"type": "base64", "data": "abc"}}],
-    }
-    compressed = {
-        "role": "user",
-        "content": [{"type": "image", "source": {"type": "base64", "data": "xyz"}}],
-    }
-
-    assert (
-        AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
-            [],
-            frozen_message_count=0,
-            compressor=_ImageCompressor(compressed),
-        )
-        == []
-    )
-    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
-        [image_message],
-        frozen_message_count=1,
-        compressor=_ImageCompressor(compressed),
-    ) == [image_message]
-    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
-        [{"role": "assistant", "content": image_message["content"]}],
-        frozen_message_count=0,
-        compressor=_ImageCompressor(compressed),
-    ) == [{"role": "assistant", "content": image_message["content"]}]
-    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
-        [{"role": "user", "content": "no-image"}],
-        frozen_message_count=0,
-        compressor=_ImageCompressor(compressed),
-    ) == [{"role": "user", "content": "no-image"}]
-    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
-        [image_message],
-        frozen_message_count=0,
-        compressor=_ImageCompressor(image_message),
-    ) == [image_message]
-    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
-        [image_message],
-        frozen_message_count=0,
-        compressor=_ImageCompressor(compressed),
-    ) == [compressed]
-
-
-def test_anthropic_cache_delta_helpers_cover_string_list_and_role_mismatch() -> None:
-    previous_original = [{"role": "user", "content": "hello"}]
-    previous_forwarded = [{"role": "user", "content": "HELLO"}]
-
-    assert AnthropicHandlerMixin._extract_cache_stable_delta(
-        [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "next"}],
-        previous_original,
-        previous_forwarded,
-    ) == (previous_forwarded, [{"role": "assistant", "content": "next"}])
-    assert (
-        AnthropicHandlerMixin._extract_cache_stable_delta(
-            [{"role": "assistant", "content": "hello"}],
-            previous_original,
-            previous_forwarded,
-        )
-        is None
-    )
-
-    string_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(
-        [{"role": "user", "content": "hello world"}],
-        previous_original,
-        previous_forwarded,
-    )
-    assert string_suffix == ([], previous_forwarded[0], [{"role": "user", "content": " world"}])
-
-    list_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(
-        [
-            {
-                "role": "user",
-                "content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}],
-            }
-        ],
-        [{"role": "user", "content": [{"type": "text", "text": "a"}]}],
-        [{"role": "user", "content": [{"type": "text", "text": "A"}]}],
-    )
-    assert list_suffix == (
-        [],
-        {"role": "user", "content": [{"type": "text", "text": "A"}]},
-        [{"role": "user", "content": [{"type": "text", "text": "b"}]}],
-    )
-
-    assert AnthropicHandlerMixin._merge_appended_message_delta(
-        {"role": "user", "content": "HELLO"},
-        {"role": "user", "content": " world"},
-    ) == {"role": "user", "content": "HELLO world"}
-    assert AnthropicHandlerMixin._merge_appended_message_delta(
-        {"role": "user", "content": [{"type": "text", "text": "A"}]},
-        {"role": "user", "content": [{"type": "text", "text": "b"}]},
-    ) == {"role": "user", "content": [{"type": "text", "text": "A"}, {"type": "text", "text": "b"}]}
-    assert (
-        AnthropicHandlerMixin._merge_appended_message_delta(
-            {"role": "user", "content": "A"},
-            {"role": "assistant", "content": "B"},
-        )
-        is None
-    )
-
-
-def test_anthropic_assistant_message_helper_requires_assistant_role() -> None:
-    assert AnthropicHandlerMixin._assistant_message_from_response_json(None) is None
-    assert AnthropicHandlerMixin._assistant_message_from_response_json({"role": "user"}) is None
-    assert AnthropicHandlerMixin._assistant_message_from_response_json(
-        {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}
-    ) == {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}
+from __future__ import annotations
+
+import base64
+import json
+
+from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
+from headroom.proxy.handlers.openai import OpenAIHandlerMixin, _decode_openai_bearer_payload
+
+
+def _jwt(payload: object) -> str:
+    header = {"alg": "none", "typ": "JWT"}
+
+    def encode(part: object) -> str:
+        raw = json.dumps(part, separators=(",", ":")).encode("utf-8")
+        return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+    return f"{encode(header)}.{encode(payload)}."
+
+
+class _ImageCompressor:
+    def __init__(self, compressed_message):
+        self._compressed_message = compressed_message
+
+    def compress(self, messages, provider):  # noqa: ANN001, ANN201
+        assert provider == "anthropic"
+        return [self._compressed_message]
+
+
+def test_decode_openai_bearer_payload_handles_missing_and_non_mapping_payloads() -> None:
+    assert _decode_openai_bearer_payload({}) is None
+    assert _decode_openai_bearer_payload({"authorization": "Basic abc"}) is None
+    assert (
+        _decode_openai_bearer_payload({"authorization": f"Bearer {_jwt(['not', 'a', 'dict'])}"})
+        is None
+    )
+
+
+def test_openai_handler_prefix_helpers_cover_edge_cases() -> None:
+    assert OpenAIHandlerMixin._strict_previous_turn_frozen_count([], 2) == 2
+    assert (
+        OpenAIHandlerMixin._strict_previous_turn_frozen_count(
+            [{"role": "assistant"}, {"role": "user"}],
+            0,
+        )
+        == 1
+    )
+    assert (
+        OpenAIHandlerMixin._strict_previous_turn_frozen_count(
+            [{"role": "user"}, {"role": "assistant"}],
+            0,
+        )
+        == 2
+    )
+
+    original = [{"role": "system", "content": "keep"}, {"role": "user", "content": "hello"}]
+    restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(
+        original,
+        [],
+        frozen_message_count=1,
+    )
+    assert restored == [{"role": "system", "content": "keep"}]
+    assert changed == 1
+
+    restored, changed = OpenAIHandlerMixin._restore_frozen_prefix(
+        original,
+        [{"role": "system", "content": "changed"}, {"role": "user", "content": "hello"}],
+        frozen_message_count=1,
+    )
+    assert restored == original
+    assert changed == 1
+
+
+def test_anthropic_tool_sort_and_context_append_helpers() -> None:
+    tools = [
+        {"type": "function", "function": {"name": "beta"}},
+        {"name": "alpha"},
+        {"type": "tool"},
+    ]
+
+    sorted_tools = AnthropicHandlerMixin._sort_tools_deterministically(tools)
+
+    assert [AnthropicHandlerMixin._tool_sort_key(tool)[0] for tool in sorted_tools] == [
+        "alpha",
+        "beta",
+        "tool",
+    ]
+    assert AnthropicHandlerMixin._sort_tools_deterministically(None) is None
+    assert (
+        AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
+            [], "ctx", frozen_message_count=0
+        )
+        == []
+    )
+    assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
+        [{"role": "user", "content": "hello"}],
+        "ctx",
+        frozen_message_count=0,
+    ) == [{"role": "user", "content": "hello\n\nctx"}]
+    assert AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
+        [{"role": "user", "content": [{"type": "text", "text": "hello"}]}],
+        "ctx",
+        frozen_message_count=0,
+    ) == [{"role": "user", "content": [{"type": "text", "text": "hello"}]}]
+
+
+def test_anthropic_image_compression_helper_only_rewrites_latest_eligible_turn() -> None:
+    image_message = {
+        "role": "user",
+        "content": [{"type": "image", "source": {"type": "base64", "data": "abc"}}],
+    }
+    compressed = {
+        "role": "user",
+        "content": [{"type": "image", "source": {"type": "base64", "data": "xyz"}}],
+    }
+
+    assert (
+        AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
+            [],
+            frozen_message_count=0,
+            compressor=_ImageCompressor(compressed),
+        )
+        == []
+    )
+    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
+        [image_message],
+        frozen_message_count=1,
+        compressor=_ImageCompressor(compressed),
+    ) == [image_message]
+    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
+        [{"role": "assistant", "content": image_message["content"]}],
+        frozen_message_count=0,
+        compressor=_ImageCompressor(compressed),
+    ) == [{"role": "assistant", "content": image_message["content"]}]
+    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
+        [{"role": "user", "content": "no-image"}],
+        frozen_message_count=0,
+        compressor=_ImageCompressor(compressed),
+    ) == [{"role": "user", "content": "no-image"}]
+    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
+        [image_message],
+        frozen_message_count=0,
+        compressor=_ImageCompressor(image_message),
+    ) == [image_message]
+    assert AnthropicHandlerMixin._compress_latest_user_turn_images_cache_safe(
+        [image_message],
+        frozen_message_count=0,
+        compressor=_ImageCompressor(compressed),
+    ) == [compressed]
+
+
+def test_anthropic_cache_delta_helpers_cover_string_list_and_role_mismatch() -> None:
+    previous_original = [{"role": "user", "content": "hello"}]
+    previous_forwarded = [{"role": "user", "content": "HELLO"}]
+
+    assert AnthropicHandlerMixin._extract_cache_stable_delta(
+        [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "next"}],
+        previous_original,
+        previous_forwarded,
+    ) == (previous_forwarded, [{"role": "assistant", "content": "next"}])
+    assert (
+        AnthropicHandlerMixin._extract_cache_stable_delta(
+            [{"role": "assistant", "content": "hello"}],
+            previous_original,
+            previous_forwarded,
+        )
+        is None
+    )
+
+    string_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(
+        [{"role": "user", "content": "hello world"}],
+        previous_original,
+        previous_forwarded,
+    )
+    assert string_suffix == ([], previous_forwarded[0], [{"role": "user", "content": " world"}])
+
+    list_suffix = AnthropicHandlerMixin._extract_cache_stable_last_message_suffix(
+        [
+            {
+                "role": "user",
+                "content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}],
+            }
+        ],
+        [{"role": "user", "content": [{"type": "text", "text": "a"}]}],
+        [{"role": "user", "content": [{"type": "text", "text": "A"}]}],
+    )
+    assert list_suffix == (
+        [],
+        {"role": "user", "content": [{"type": "text", "text": "A"}]},
+        [{"role": "user", "content": [{"type": "text", "text": "b"}]}],
+    )
+
+    assert AnthropicHandlerMixin._merge_appended_message_delta(
+        {"role": "user", "content": "HELLO"},
+        {"role": "user", "content": " world"},
+    ) == {"role": "user", "content": "HELLO world"}
+    assert AnthropicHandlerMixin._merge_appended_message_delta(
+        {"role": "user", "content": [{"type": "text", "text": "A"}]},
+        {"role": "user", "content": [{"type": "text", "text": "b"}]},
+    ) == {"role": "user", "content": [{"type": "text", "text": "A"}, {"type": "text", "text": "b"}]}
+    assert (
+        AnthropicHandlerMixin._merge_appended_message_delta(
+            {"role": "user", "content": "A"},
+            {"role": "assistant", "content": "B"},
+        )
+        is None
+    )
+
+
+def test_anthropic_assistant_message_helper_requires_assistant_role() -> None:
+    assert AnthropicHandlerMixin._assistant_message_from_response_json(None) is None
+    assert AnthropicHandlerMixin._assistant_message_from_response_json({"role": "user"}) is None
+    assert AnthropicHandlerMixin._assistant_message_from_response_json(
+        {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}
+    ) == {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}
diff --git a/tests/test_proxy_pipeline_lifecycle.py b/tests/test_proxy_pipeline_lifecycle.py
index fde19d8e1fd3272c3fd1b5cd154d11aa9b97e380..aea3ec06d1784f399e0fd236d9b14a456db7f4d7 100644
--- a/tests/test_proxy_pipeline_lifecycle.py
+++ b/tests/test_proxy_pipeline_lifecycle.py
@@ -1,184 +1,184 @@
-from __future__ import annotations
-
-from types import SimpleNamespace
-from unittest.mock import AsyncMock
-
-import httpx
-from fastapi.testclient import TestClient
-
-from headroom.pipeline import PipelineStage
-from headroom.proxy.server import ProxyConfig, create_app
-
-
-class _RecordingExtension:
-    def __init__(self) -> None:
-        self.stages: list[PipelineStage] = []
-
-    def on_pipeline_event(self, event):
-        self.stages.append(event.stage)
-        return None
-
-
-class _DummyTokenizer:
-    def count_messages(self, messages):
-        return len(messages)
-
-
-def _assert_stage_order(stages: list[PipelineStage]) -> None:
-    expected = [
-        PipelineStage.SETUP,
-        PipelineStage.PRE_START,
-        PipelineStage.POST_START,
-        PipelineStage.INPUT_RECEIVED,
-        PipelineStage.INPUT_ROUTED,
-        PipelineStage.INPUT_COMPRESSED,
-        PipelineStage.INPUT_REMEMBERED,
-        PipelineStage.PRE_SEND,
-        PipelineStage.POST_SEND,
-        PipelineStage.RESPONSE_RECEIVED,
-    ]
-    positions = [stages.index(stage) for stage in expected]
-    assert positions == sorted(positions)
-
-
-def test_openai_chat_pipeline_events_cover_proxy_lifecycle(monkeypatch) -> None:
-    recorder = _RecordingExtension()
-    config = ProxyConfig(
-        optimize=True,
-        image_optimize=False,
-        cache_enabled=False,
-        rate_limit_enabled=False,
-        cost_tracking_enabled=False,
-        log_requests=False,
-        ccr_inject_tool=False,
-        ccr_handle_responses=False,
-        ccr_context_tracking=False,
-        pipeline_extensions=[recorder],
-        discover_pipeline_extensions=False,
-    )
-    app = create_app(config)
-
-    with TestClient(app) as client:
-        proxy = client.app.state.proxy
-        proxy.openai_pipeline = SimpleNamespace(
-            apply=lambda messages, model, **kwargs: SimpleNamespace(
-                messages=[
-                    {"role": "system", "content": "memory"},
-                    {"role": "user", "content": "hello"},
-                ],
-                transforms_applied=["router:text:kompress"],
-                tokens_before=10,
-                tokens_after=6,
-            )
-        )
-        proxy.memory_handler = SimpleNamespace(
-            config=SimpleNamespace(inject_context=True, inject_tools=False),
-            search_and_format_context=AsyncMock(return_value="memory"),
-            has_memory_tool_calls=lambda response, provider: False,
-        )
-
-        monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())
-
-        async def _fake_retry(method, url, headers, body, stream=False):  # noqa: ANN001
-            return httpx.Response(
-                200,
-                json={
-                    "id": "chatcmpl_1",
-                    "object": "chat.completion",
-                    "choices": [{"message": {"role": "assistant", "content": "ok"}}],
-                    "usage": {"prompt_tokens": 10, "completion_tokens": 3, "total_tokens": 13},
-                },
-            )
-
-        proxy._retry_request = _fake_retry
-
-        response = client.post(
-            "/v1/chat/completions",
-            headers={"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},
-            json={
-                "model": "gpt-5.4",
-                "messages": [{"role": "user", "content": "hello"}],
-                "tools": [{"type": "function", "function": {"name": "tool_a"}}],
-            },
-        )
-
-    assert response.status_code == 200
-    _assert_stage_order(recorder.stages)
-
-
-def test_anthropic_messages_pipeline_events_cover_proxy_lifecycle(monkeypatch) -> None:
-    recorder = _RecordingExtension()
-    config = ProxyConfig(
-        optimize=True,
-        cache_enabled=False,
-        rate_limit_enabled=False,
-        cost_tracking_enabled=False,
-        log_requests=False,
-        ccr_inject_tool=False,
-        ccr_handle_responses=False,
-        ccr_context_tracking=False,
-        image_optimize=False,
-        pipeline_extensions=[recorder],
-        discover_pipeline_extensions=False,
-    )
-    app = create_app(config)
-
-    with TestClient(app) as client:
-        proxy = client.app.state.proxy
-        proxy.anthropic_pipeline = SimpleNamespace(
-            apply=lambda messages, model, **kwargs: SimpleNamespace(
-                messages=[
-                    {"role": "system", "content": "memory"},
-                    {"role": "user", "content": "hello"},
-                ],
-                transforms_applied=["router:text:kompress"],
-                tokens_before=10,
-                tokens_after=6,
-            )
-        )
-        proxy.memory_handler = SimpleNamespace(
-            config=SimpleNamespace(inject_context=True, inject_tools=False),
-            search_and_format_context=AsyncMock(return_value="memory"),
-            has_memory_tool_calls=lambda response, provider: False,
-        )
-
-        monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())
-
-        async def _fake_retry(method, url, headers, body, stream=False):  # noqa: ANN001
-            return httpx.Response(
-                200,
-                json={
-                    "id": "msg_1",
-                    "type": "message",
-                    "role": "assistant",
-                    "content": [{"type": "text", "text": "ok"}],
-                    "usage": {
-                        "input_tokens": 10,
-                        "output_tokens": 3,
-                        "cache_read_input_tokens": 0,
-                        "cache_creation_input_tokens": 0,
-                    },
-                },
-            )
-
-        proxy._retry_request = _fake_retry
-
-        response = client.post(
-            "/v1/messages",
-            headers={
-                "x-api-key": "test-key",
-                "anthropic-version": "2023-06-01",
-                "x-headroom-user-id": "user-1",
-            },
-            json={
-                "model": "claude-sonnet-4-6",
-                "max_tokens": 128,
-                "messages": [{"role": "user", "content": "hello"}],
-                "tools": [
-                    {"name": "tool_a", "description": "a", "input_schema": {"type": "object"}}
-                ],
-            },
-        )
-
-    assert response.status_code == 200
-    _assert_stage_order(recorder.stages)
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import httpx
+from fastapi.testclient import TestClient
+
+from headroom.pipeline import PipelineStage
+from headroom.proxy.server import ProxyConfig, create_app
+
+
+class _RecordingExtension:
+    def __init__(self) -> None:
+        self.stages: list[PipelineStage] = []
+
+    def on_pipeline_event(self, event):
+        self.stages.append(event.stage)
+        return None
+
+
+class _DummyTokenizer:
+    def count_messages(self, messages):
+        return len(messages)
+
+
+def _assert_stage_order(stages: list[PipelineStage]) -> None:
+    expected = [
+        PipelineStage.SETUP,
+        PipelineStage.PRE_START,
+        PipelineStage.POST_START,
+        PipelineStage.INPUT_RECEIVED,
+        PipelineStage.INPUT_ROUTED,
+        PipelineStage.INPUT_COMPRESSED,
+        PipelineStage.INPUT_REMEMBERED,
+        PipelineStage.PRE_SEND,
+        PipelineStage.POST_SEND,
+        PipelineStage.RESPONSE_RECEIVED,
+    ]
+    positions = [stages.index(stage) for stage in expected]
+    assert positions == sorted(positions)
+
+
+def test_openai_chat_pipeline_events_cover_proxy_lifecycle(monkeypatch) -> None:
+    recorder = _RecordingExtension()
+    config = ProxyConfig(
+        optimize=True,
+        image_optimize=False,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        cost_tracking_enabled=False,
+        log_requests=False,
+        ccr_inject_tool=False,
+        ccr_handle_responses=False,
+        ccr_context_tracking=False,
+        pipeline_extensions=[recorder],
+        discover_pipeline_extensions=False,
+    )
+    app = create_app(config)
+
+    with TestClient(app) as client:
+        proxy = client.app.state.proxy
+        proxy.openai_pipeline = SimpleNamespace(
+            apply=lambda messages, model, **kwargs: SimpleNamespace(
+                messages=[
+                    {"role": "system", "content": "memory"},
+                    {"role": "user", "content": "hello"},
+                ],
+                transforms_applied=["router:text:kompress"],
+                tokens_before=10,
+                tokens_after=6,
+            )
+        )
+        proxy.memory_handler = SimpleNamespace(
+            config=SimpleNamespace(inject_context=True, inject_tools=False),
+            search_and_format_context=AsyncMock(return_value="memory"),
+            has_memory_tool_calls=lambda response, provider: False,
+        )
+
+        monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())
+
+        async def _fake_retry(method, url, headers, body, stream=False):  # noqa: ANN001
+            return httpx.Response(
+                200,
+                json={
+                    "id": "chatcmpl_1",
+                    "object": "chat.completion",
+                    "choices": [{"message": {"role": "assistant", "content": "ok"}}],
+                    "usage": {"prompt_tokens": 10, "completion_tokens": 3, "total_tokens": 13},
+                },
+            )
+
+        proxy._retry_request = _fake_retry
+
+        response = client.post(
+            "/v1/chat/completions",
+            headers={"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},
+            json={
+                "model": "gpt-5.4",
+                "messages": [{"role": "user", "content": "hello"}],
+                "tools": [{"type": "function", "function": {"name": "tool_a"}}],
+            },
+        )
+
+    assert response.status_code == 200
+    _assert_stage_order(recorder.stages)
+
+
+def test_anthropic_messages_pipeline_events_cover_proxy_lifecycle(monkeypatch) -> None:
+    recorder = _RecordingExtension()
+    config = ProxyConfig(
+        optimize=True,
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        cost_tracking_enabled=False,
+        log_requests=False,
+        ccr_inject_tool=False,
+        ccr_handle_responses=False,
+        ccr_context_tracking=False,
+        image_optimize=False,
+        pipeline_extensions=[recorder],
+        discover_pipeline_extensions=False,
+    )
+    app = create_app(config)
+
+    with TestClient(app) as client:
+        proxy = client.app.state.proxy
+        proxy.anthropic_pipeline = SimpleNamespace(
+            apply=lambda messages, model, **kwargs: SimpleNamespace(
+                messages=[
+                    {"role": "system", "content": "memory"},
+                    {"role": "user", "content": "hello"},
+                ],
+                transforms_applied=["router:text:kompress"],
+                tokens_before=10,
+                tokens_after=6,
+            )
+        )
+        proxy.memory_handler = SimpleNamespace(
+            config=SimpleNamespace(inject_context=True, inject_tools=False),
+            search_and_format_context=AsyncMock(return_value="memory"),
+            has_memory_tool_calls=lambda response, provider: False,
+        )
+
+        monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())
+
+        async def _fake_retry(method, url, headers, body, stream=False):  # noqa: ANN001
+            return httpx.Response(
+                200,
+                json={
+                    "id": "msg_1",
+                    "type": "message",
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "ok"}],
+                    "usage": {
+                        "input_tokens": 10,
+                        "output_tokens": 3,
+                        "cache_read_input_tokens": 0,
+                        "cache_creation_input_tokens": 0,
+                    },
+                },
+            )
+
+        proxy._retry_request = _fake_retry
+
+        response = client.post(
+            "/v1/messages",
+            headers={
+                "x-api-key": "test-key",
+                "anthropic-version": "2023-06-01",
+                "x-headroom-user-id": "user-1",
+            },
+            json={
+                "model": "claude-sonnet-4-6",
+                "max_tokens": 128,
+                "messages": [{"role": "user", "content": "hello"}],
+                "tools": [
+                    {"name": "tool_a", "description": "a", "input_schema": {"type": "object"}}
+                ],
+            },
+        )
+
+    assert response.status_code == 200
+    _assert_stage_order(recorder.stages)
diff --git a/tests/test_proxy_savings_history.py b/tests/test_proxy_savings_history.py
index f261c95dc3efb352f9ccb578771abc489d2f007f..e4874f5a67ca86e927de617a033d722ee2047188 100644
--- a/tests/test_proxy_savings_history.py
+++ b/tests/test_proxy_savings_history.py
@@ -1,711 +1,711 @@
-"""Tests for durable proxy savings history."""
-
-from __future__ import annotations
-
-import asyncio
-import json
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-from types import SimpleNamespace
-
-import pytest
-
-pytest.importorskip("fastapi")
-
-from fastapi.testclient import TestClient
-
-import headroom.proxy.savings_tracker as savings_tracker_module
-from headroom.proxy.savings_tracker import HEADROOM_SAVINGS_PATH_ENV_VAR, SavingsTracker
-from headroom.proxy.server import ProxyConfig, create_app
-
-
-def _record_request(
-    client: TestClient,
-    *,
-    model: str,
-    tokens_saved: int,
-    input_tokens: int = 120,
-) -> None:
-    proxy = client.app.state.proxy
-    if proxy.cost_tracker:
-        proxy.cost_tracker.record_tokens(model, tokens_saved, input_tokens)
-    asyncio.run(
-        proxy.metrics.record_request(
-            provider="openai",
-            model=model,
-            input_tokens=input_tokens,
-            output_tokens=24,
-            tokens_saved=tokens_saved,
-            latency_ms=15.0,
-        )
-    )
-
-
-def test_savings_tracker_helpers_normalize_inputs_and_paths(tmp_path, monkeypatch):
-    override_path = tmp_path / "custom-savings.json"
-    monkeypatch.setenv(HEADROOM_SAVINGS_PATH_ENV_VAR, str(override_path))
-    assert savings_tracker_module.get_default_savings_storage_path() == str(override_path)
-
-    monkeypatch.delenv(HEADROOM_SAVINGS_PATH_ENV_VAR, raising=False)
-    default_path = savings_tracker_module.get_default_savings_storage_path()
-    assert Path(default_path).as_posix().endswith(".headroom/proxy_savings.json")
-
-    assert savings_tracker_module._parse_timestamp("") is None
-    assert savings_tracker_module._parse_timestamp("not-a-timestamp") is None
-    assert savings_tracker_module._parse_timestamp("2026-03-27T09:00:00") == datetime(
-        2026, 3, 27, 9, 0, tzinfo=timezone.utc
-    )
-
-    assert savings_tracker_module._coerce_int("7") == 7
-    assert savings_tracker_module._coerce_int(-5) == 0
-    assert savings_tracker_module._coerce_float("0.25") == pytest.approx(0.25)
-    assert savings_tracker_module._coerce_float(-0.25) == 0.0
-
-    assert savings_tracker_module._normalize_history_entry(
-        ["2026-03-27T09:00:00Z", "12", "0.5"]
-    ) == {
-        "timestamp": "2026-03-27T09:00:00Z",
-        "total_tokens_saved": 12,
-        "compression_savings_usd": 0.5,
-        "total_input_tokens": 0,
-        "total_input_cost_usd": 0.0,
-    }
-    assert savings_tracker_module._normalize_history_entry({"timestamp": "bad"}) is None
-    assert savings_tracker_module._normalize_history_entry(object()) is None
-
-
-def test_savings_tracker_sanitizes_legacy_state_and_applies_retention(tmp_path):
-    path = tmp_path / "proxy_savings.json"
-    path.write_text(
-        json.dumps(
-            {
-                "schema_version": 0,
-                "lifetime": {
-                    "tokens_saved": 1,
-                    "compression_savings_usd": 0.001,
-                },
-                "history": [
-                    ["2026-03-24T08:00:00Z", 10, 0.01],
-                    {
-                        "timestamp": "2026-03-26T12:00:00Z",
-                        "total_tokens_saved": 20,
-                        "compression_savings_usd": 0.02,
-                    },
-                    {
-                        "timestamp": "2026-03-27T09:00:00Z",
-                        "total_tokens_saved": 30,
-                        "compression_savings_usd": 0.03,
-                    },
-                    {"timestamp": "bad", "total_tokens_saved": 999},
-                ],
-            }
-        ),
-        encoding="utf-8",
-    )
-
-    tracker = SavingsTracker(
-        path=str(path),
-        max_history_points=1,
-        max_history_age_days=2,
-    )
-    snapshot = tracker.snapshot()
-
-    assert snapshot["schema_version"] == 2
-    assert snapshot["lifetime"] == {
-        "requests": 0,
-        "tokens_saved": 30,
-        "compression_savings_usd": pytest.approx(0.03),
-        "total_input_tokens": 0,
-        "total_input_cost_usd": 0.0,
-    }
-    assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
-    assert snapshot["history"] == [
-        {
-            "timestamp": "2026-03-27T09:00:00Z",
-            "total_tokens_saved": 30,
-            "compression_savings_usd": 0.03,
-            "total_input_tokens": 0,
-            "total_input_cost_usd": 0.0,
-        }
-    ]
-    assert snapshot["retention"] == {
-        "max_history_points": 1,
-        "max_history_age_days": 2,
-        "max_response_history_points": 500,
-    }
-
-
-def test_non_dict_savings_state_resets_to_default(tmp_path):
-    path = tmp_path / "proxy_savings.json"
-    path.write_text("[]", encoding="utf-8")
-
-    tracker = SavingsTracker(path=str(path))
-    snapshot = tracker.snapshot()
-
-    assert snapshot["lifetime"] == {
-        "requests": 0,
-        "tokens_saved": 0,
-        "compression_savings_usd": 0.0,
-        "total_input_tokens": 0,
-        "total_input_cost_usd": 0.0,
-    }
-    assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
-    assert snapshot["history"] == []
-
-
-def test_record_compression_savings_skips_empty_updates_and_normalizes_timestamps(
-    tmp_path, monkeypatch
-):
-    path = tmp_path / "proxy_savings.json"
-    tracker = SavingsTracker(path=str(path))
-    monkeypatch.setattr(
-        savings_tracker_module,
-        "_estimate_compression_savings_usd",
-        lambda model, tokens_saved: tokens_saved / 1000.0,
-    )
-
-    assert tracker.record_compression_savings(model="gpt-4o", tokens_saved=0) is False
-    assert not path.exists()
-
-    local_time = datetime(2026, 3, 27, 10, 0, tzinfo=timezone(timedelta(hours=2)))
-    assert tracker.record_compression_savings(
-        model="gpt-4o",
-        tokens_saved=10,
-        total_input_tokens=120,
-        total_input_cost_usd=0.24,
-        timestamp=local_time,
-    )
-
-    fallback_time = datetime(2026, 3, 27, 12, 34, tzinfo=timezone.utc)
-    monkeypatch.setattr(savings_tracker_module, "_utc_now", lambda: fallback_time)
-    assert tracker.record_compression_savings(
-        model="gpt-4o",
-        tokens_saved=5,
-        total_input_tokens=180,
-        total_input_cost_usd=0.36,
-        timestamp="not-a-timestamp",
-    )
-
-    snapshot = tracker.snapshot()
-    assert snapshot["history"] == [
-        {
-            "timestamp": "2026-03-27T08:00:00Z",
-            "total_tokens_saved": 10,
-            "compression_savings_usd": 0.01,
-            "total_input_tokens": 120,
-            "total_input_cost_usd": 0.24,
-        },
-        {
-            "timestamp": "2026-03-27T12:34:00Z",
-            "total_tokens_saved": 15,
-            "compression_savings_usd": 0.015,
-            "total_input_tokens": 180,
-            "total_input_cost_usd": 0.36,
-        },
-    ]
-
-    persisted = json.loads(path.read_text(encoding="utf-8"))
-    assert persisted["lifetime"]["tokens_saved"] == 15
-    assert persisted["lifetime"]["total_input_tokens"] == 180
-    assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.36)
-    assert persisted["history"][-1]["timestamp"] == "2026-03-27T12:34:00Z"
-
-
-def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):
-    def fake_cost_per_token(*, model, prompt_tokens, completion_tokens):
-        if model in {"gpt-4o", "anthropic/claude-sonnet-4-6"}:
-            return {
-                "model": model,
-                "prompt_tokens": prompt_tokens,
-                "completion_tokens": completion_tokens,
-            }
-        raise RuntimeError("unknown model")
-
-    fake_litellm = SimpleNamespace(
-        cost_per_token=fake_cost_per_token,
-        model_cost={
-            "anthropic/claude-sonnet-4-6": {"input_cost_per_token": 0.002},
-            "gpt-4o": {"input_cost_per_token": 0.001},
-        },
-    )
-    monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", True)
-    monkeypatch.setattr(savings_tracker_module, "litellm", fake_litellm)
-
-    assert savings_tracker_module._resolve_litellm_model("gpt-4o") == "gpt-4o"
-    assert (
-        savings_tracker_module._resolve_litellm_model("claude-sonnet-4-6")
-        == "anthropic/claude-sonnet-4-6"
-    )
-    assert savings_tracker_module._estimate_compression_savings_usd(
-        "claude-sonnet-4-6", 100
-    ) == pytest.approx(0.2)
-    assert savings_tracker_module._estimate_input_cost_usd(
-        "claude-sonnet-4-6",
-        100,
-        cache_read_tokens=10,
-        cache_write_tokens=5,
-        uncached_input_tokens=85,
-    ) == pytest.approx(0.2)
-
-    fake_litellm.model_cost = {}
-    assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
-    assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0
-
-    monkeypatch.setattr(
-        fake_litellm,
-        "cost_per_token",
-        lambda **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),
-    )
-    assert savings_tracker_module._resolve_litellm_model("mystery-model") == "mystery-model"
-    assert savings_tracker_module._estimate_compression_savings_usd("mystery-model", 100) == 0.0
-
-    monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", False)
-    assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
-    assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0
-
-
-def test_display_session_rolls_after_inactivity_and_counts_zero_savings_requests(
-    tmp_path, monkeypatch
-):
-    path = tmp_path / "proxy_savings.json"
-    tracker = SavingsTracker(path=str(path), display_session_inactivity_minutes=30)
-    monkeypatch.setattr(
-        savings_tracker_module,
-        "_estimate_compression_savings_usd",
-        lambda model, tokens_saved: tokens_saved / 1000.0,
-    )
-    monkeypatch.setattr(
-        savings_tracker_module,
-        "_estimate_input_cost_usd",
-        lambda model, input_tokens, **kwargs: input_tokens / 1000.0,
-    )
-
-    tracker.record_request(
-        model="gpt-4o",
-        input_tokens=120,
-        tokens_saved=0,
-        timestamp="2026-03-27T09:00:00Z",
-    )
-    tracker.record_request(
-        model="gpt-4o",
-        input_tokens=80,
-        tokens_saved=20,
-        timestamp="2026-03-27T09:10:00Z",
-    )
-
-    monkeypatch.setattr(
-        savings_tracker_module,
-        "_utc_now",
-        lambda: datetime(2026, 3, 27, 9, 15, tzinfo=timezone.utc),
-    )
-    active_session = tracker.snapshot()["display_session"]
-    assert active_session == {
-        "requests": 2,
-        "tokens_saved": 20,
-        "compression_savings_usd": pytest.approx(0.02),
-        "total_input_tokens": 200,
-        "total_input_cost_usd": pytest.approx(0.2),
-        "savings_percent": pytest.approx(9.09),
-        "started_at": "2026-03-27T09:00:00Z",
-        "last_activity_at": "2026-03-27T09:10:00Z",
-    }
-
-    monkeypatch.setattr(
-        savings_tracker_module,
-        "_utc_now",
-        lambda: datetime(2026, 3, 27, 9, 45, tzinfo=timezone.utc),
-    )
-    assert tracker.snapshot()["display_session"] == savings_tracker_module._empty_display_session()
-
-    tracker.record_request(
-        model="gpt-4o",
-        input_tokens=50,
-        tokens_saved=5,
-        timestamp="2026-03-27T10:05:00Z",
-    )
-
-    monkeypatch.setattr(
-        savings_tracker_module,
-        "_utc_now",
-        lambda: datetime(2026, 3, 27, 10, 10, tzinfo=timezone.utc),
-    )
-    rolled = tracker.snapshot()
-    assert rolled["lifetime"]["requests"] == 3
-    assert rolled["display_session"] == {
-        "requests": 1,
-        "tokens_saved": 5,
-        "compression_savings_usd": pytest.approx(0.005),
-        "total_input_tokens": 50,
-        "total_input_cost_usd": pytest.approx(0.05),
-        "savings_percent": pytest.approx(9.09),
-        "started_at": "2026-03-27T10:05:00Z",
-        "last_activity_at": "2026-03-27T10:05:00Z",
-    }
-
-
-def test_savings_tracker_rollups_preserve_spend_and_input_history(tmp_path, monkeypatch):
-    path = tmp_path / "proxy_savings.json"
-    tracker = SavingsTracker(
-        path=str(path),
-        max_history_points=100,
-        max_history_age_days=30,
-    )
-    monkeypatch.setattr(
-        "headroom.proxy.savings_tracker._estimate_compression_savings_usd",
-        lambda model, tokens_saved: tokens_saved / 1000.0,
-    )
-
-    tracker.record_compression_savings(
-        model="gpt-4o",
-        tokens_saved=100,
-        total_input_tokens=120,
-        total_input_cost_usd=0.24,
-        timestamp="2026-03-27T09:10:00Z",
-    )
-    tracker.record_compression_savings(
-        model="gpt-4o",
-        tokens_saved=50,
-        total_input_tokens=210,
-        total_input_cost_usd=0.42,
-        timestamp="2026-03-27T09:40:00Z",
-    )
-    tracker.record_compression_savings(
-        model="gpt-4o",
-        tokens_saved=25,
-        total_input_tokens=300,
-        total_input_cost_usd=0.63,
-        timestamp="2026-03-27T10:05:00Z",
-    )
-    tracker.record_compression_savings(
-        model="gpt-4o",
-        tokens_saved=10,
-        total_input_tokens=360,
-        total_input_cost_usd=0.75,
-        timestamp="2026-03-28T08:00:00Z",
-    )
-    tracker.record_compression_savings(
-        model="gpt-4o",
-        tokens_saved=20,
-        total_input_tokens=450,
-        total_input_cost_usd=0.93,
-        timestamp="2026-04-02T14:00:00Z",
-    )
-
-    response = tracker.history_response()
-
-    assert response["lifetime"]["tokens_saved"] == 205
-    assert response["lifetime"]["compression_savings_usd"] == pytest.approx(0.205)
-    assert response["lifetime"]["total_input_tokens"] == 450
-    assert response["lifetime"]["total_input_cost_usd"] == pytest.approx(0.93)
-    assert len(response["history"]) == 5
-
-    hourly = response["series"]["hourly"]
-    assert [point["timestamp"] for point in hourly] == [
-        "2026-03-27T09:00:00Z",
-        "2026-03-27T10:00:00Z",
-        "2026-03-28T08:00:00Z",
-        "2026-04-02T14:00:00Z",
-    ]
-    assert hourly[0]["tokens_saved"] == 150
-    assert hourly[0]["total_tokens_saved"] == 150
-    assert hourly[0]["total_input_tokens_delta"] == 210
-    assert hourly[0]["total_input_tokens"] == 210
-    assert hourly[0]["total_input_cost_usd_delta"] == pytest.approx(0.42)
-    assert hourly[0]["total_input_cost_usd"] == pytest.approx(0.42)
-    assert hourly[1]["tokens_saved"] == 25
-    assert hourly[1]["total_tokens_saved"] == 175
-    assert hourly[1]["total_input_tokens_delta"] == 90
-    assert hourly[1]["total_input_tokens"] == 300
-    assert hourly[1]["total_input_cost_usd_delta"] == pytest.approx(0.21)
-    assert hourly[1]["total_input_cost_usd"] == pytest.approx(0.63)
-    assert hourly[2]["tokens_saved"] == 10
-    assert hourly[2]["total_tokens_saved"] == 185
-    assert hourly[2]["total_input_tokens_delta"] == 60
-    assert hourly[2]["total_input_tokens"] == 360
-    assert hourly[2]["total_input_cost_usd_delta"] == pytest.approx(0.12)
-    assert hourly[2]["total_input_cost_usd"] == pytest.approx(0.75)
-    assert hourly[3]["tokens_saved"] == 20
-    assert hourly[3]["total_tokens_saved"] == 205
-    assert hourly[3]["total_input_tokens_delta"] == 90
-    assert hourly[3]["total_input_tokens"] == 450
-    assert hourly[3]["total_input_cost_usd_delta"] == pytest.approx(0.18)
-    assert hourly[3]["total_input_cost_usd"] == pytest.approx(0.93)
-
-    daily = response["series"]["daily"]
-    assert [point["timestamp"] for point in daily] == [
-        "2026-03-27T00:00:00Z",
-        "2026-03-28T00:00:00Z",
-        "2026-04-02T00:00:00Z",
-    ]
-    assert daily[0]["tokens_saved"] == 175
-    assert daily[0]["total_tokens_saved"] == 175
-    assert daily[0]["total_input_tokens_delta"] == 300
-    assert daily[0]["total_input_tokens"] == 300
-    assert daily[0]["total_input_cost_usd_delta"] == pytest.approx(0.63)
-    assert daily[0]["total_input_cost_usd"] == pytest.approx(0.63)
-    assert daily[1]["tokens_saved"] == 10
-    assert daily[1]["total_tokens_saved"] == 185
-    assert daily[1]["total_input_tokens_delta"] == 60
-    assert daily[1]["total_input_tokens"] == 360
-    assert daily[1]["total_input_cost_usd_delta"] == pytest.approx(0.12)
-    assert daily[1]["total_input_cost_usd"] == pytest.approx(0.75)
-    assert daily[2]["tokens_saved"] == 20
-    assert daily[2]["total_tokens_saved"] == 205
-    assert daily[2]["total_input_tokens_delta"] == 90
-    assert daily[2]["total_input_tokens"] == 450
-    assert daily[2]["total_input_cost_usd_delta"] == pytest.approx(0.18)
-    assert daily[2]["total_input_cost_usd"] == pytest.approx(0.93)
-
-    weekly = response["series"]["weekly"]
-    assert [point["timestamp"] for point in weekly] == [
-        "2026-03-23T00:00:00Z",
-        "2026-03-30T00:00:00Z",
-    ]
-    assert weekly[0]["tokens_saved"] == 185
-    assert weekly[0]["total_tokens_saved"] == 185
-    assert weekly[1]["tokens_saved"] == 20
-    assert weekly[1]["total_tokens_saved"] == 205
-
-    monthly = response["series"]["monthly"]
-    assert [point["timestamp"] for point in monthly] == [
-        "2026-03-01T00:00:00Z",
-        "2026-04-01T00:00:00Z",
-    ]
-    assert monthly[0]["tokens_saved"] == 185
-    assert monthly[0]["total_tokens_saved"] == 185
-    assert monthly[1]["tokens_saved"] == 20
-    assert monthly[1]["total_tokens_saved"] == 205
-
-    assert response["exports"]["available_formats"] == ["json", "csv"]
-    assert response["exports"]["available_series"] == [
-        "history",
-        "hourly",
-        "daily",
-        "weekly",
-        "monthly",
-    ]
-
-
-def test_stats_history_defaults_to_compact_history_but_can_return_full_history(
-    tmp_path, monkeypatch
-):
-    path = tmp_path / "proxy_savings.json"
-    tracker = SavingsTracker(
-        path=str(path),
-        max_history_points=100,
-        max_history_age_days=30,
-        max_response_history_points=5,
-    )
-    monkeypatch.setattr(
-        "headroom.proxy.savings_tracker._estimate_compression_savings_usd",
-        lambda model, tokens_saved: tokens_saved / 1000.0,
-    )
-
-    for i in range(8):
-        tracker.record_compression_savings(
-            model="gpt-4o",
-            tokens_saved=10,
-            total_input_tokens=(i + 1) * 100,
-            total_input_cost_usd=(i + 1) * 0.1,
-            timestamp=f"2026-03-27T09:{i:02d}:00Z",
-        )
-
-    compact = tracker.history_response()
-    assert compact["history_summary"] == {
-        "mode": "compact",
-        "stored_points": 8,
-        "returned_points": 5,
-        "compacted": True,
-    }
-    assert len(compact["history"]) == 5
-    assert compact["history"][0]["timestamp"] == "2026-03-27T09:00:00Z"
-    assert compact["history"][-1]["timestamp"] == "2026-03-27T09:07:00Z"
-
-    full = tracker.history_response(history_mode="full")
-    assert full["history_summary"] == {
-        "mode": "full",
-        "stored_points": 8,
-        "returned_points": 8,
-        "compacted": False,
-    }
-    assert len(full["history"]) == 8
-
-    none = tracker.history_response(history_mode="none")
-    assert none["history"] == []
-    assert none["history_summary"] == {
-        "mode": "none",
-        "stored_points": 8,
-        "returned_points": 0,
-        "compacted": True,
-    }
-
-
-def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_path, monkeypatch):
-    savings_path = tmp_path / "proxy_savings.json"
-    monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
-    monkeypatch.setattr(
-        "headroom.proxy.server.CostTracker._get_cache_prices",
-        lambda self, model: (0.001, 0.0015, 0.002),
-    )
-
-    config = ProxyConfig(
-        cache_enabled=False,
-        rate_limit_enabled=False,
-        log_requests=False,
-    )
-
-    with TestClient(create_app(config)) as client:
-        _record_request(client, model="gpt-4o", tokens_saved=40)
-
-        stats = client.get("/stats")
-        assert stats.status_code == 200
-        stats_data = stats.json()
-        assert "savings_history" in stats_data
-        assert "persistent_savings" in stats_data
-        assert all(len(point) == 2 for point in stats_data["savings_history"])
-        assert stats_data["persistent_savings"]["lifetime"]["tokens_saved"] == 40
-        assert stats_data["persistent_savings"]["storage_path"] == str(savings_path)
-
-        history = client.get("/stats-history")
-        assert history.status_code == 200
-        history_data = history.json()
-        assert history_data["schema_version"] == 2
-        assert history_data["storage_path"] == str(savings_path)
-        assert history_data["lifetime"]["tokens_saved"] == 40
-        assert history_data["lifetime"]["total_input_tokens"] == 120
-        assert history_data["lifetime"]["total_input_cost_usd"] == pytest.approx(0.24)
-        assert history_data["display_session"]["requests"] == 1
-        assert history_data["display_session"]["tokens_saved"] == 40
-        assert history_data["display_session"]["total_input_tokens"] == 120
-        assert history_data["display_session"]["savings_percent"] == pytest.approx(25.0)
-        assert list(history_data["series"].keys()) == [
-            "hourly",
-            "daily",
-            "weekly",
-            "monthly",
-        ]
-        assert history_data["exports"]["available_series"][-2:] == ["weekly", "monthly"]
-        assert history_data["series"]["hourly"][0]["total_input_tokens_delta"] == 120
-        assert history_data["series"]["hourly"][0]["total_input_cost_usd_delta"] == pytest.approx(
-            0.24
-        )
-        assert history_data["history_summary"] == {
-            "mode": "compact",
-            "stored_points": 1,
-            "returned_points": 1,
-            "compacted": False,
-        }
-
-        assert stats_data["display_session"] == history_data["display_session"]
-        assert (
-            stats_data["persistent_savings"]["display_session"] == history_data["display_session"]
-        )
-
-    with TestClient(create_app(config)) as client:
-        history = client.get("/stats-history")
-        assert history.status_code == 200
-        assert history.json()["lifetime"]["tokens_saved"] == 40
-        assert history.json()["display_session"]["requests"] == 1
-
-        _record_request(client, model="gpt-4o", tokens_saved=15)
-
-        updated = client.get("/stats-history").json()
-        assert updated["lifetime"]["tokens_saved"] == 55
-        assert updated["lifetime"]["total_input_tokens"] == 240
-        assert updated["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)
-        assert updated["lifetime"]["requests"] == 2
-        assert len(updated["history"]) == 2
-        assert updated["display_session"]["requests"] == 2
-        assert updated["display_session"]["tokens_saved"] == 55
-        assert updated["display_session"]["total_input_tokens"] == 240
-        assert updated["display_session"]["savings_percent"] == pytest.approx(18.64)
-        assert updated["series"]["daily"][0]["total_input_tokens_delta"] == 240
-        assert updated["series"]["daily"][0]["total_input_cost_usd_delta"] == pytest.approx(0.48)
-
-        full = client.get("/stats-history?history_mode=full").json()
-        assert full["history_summary"]["mode"] == "full"
-        assert full["history_summary"]["stored_points"] == 2
-        assert full["history_summary"]["returned_points"] == 2
-
-        persisted = json.loads(savings_path.read_text())
-        assert persisted["lifetime"]["tokens_saved"] == 55
-        assert persisted["lifetime"]["total_input_tokens"] == 240
-        assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)
-        assert persisted["display_session"]["requests"] == 2
-
-
-def test_stats_history_csv_export_is_frontend_friendly(tmp_path, monkeypatch):
-    savings_path = tmp_path / "proxy_savings.json"
-    monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
-    monkeypatch.setattr(
-        "headroom.proxy.server.CostTracker._get_cache_prices",
-        lambda self, model: (0.001, 0.0015, 0.002),
-    )
-
-    config = ProxyConfig(
-        cache_enabled=False,
-        rate_limit_enabled=False,
-        log_requests=False,
-    )
-
-    with TestClient(create_app(config)) as client:
-        _record_request(client, model="gpt-4o", tokens_saved=40)
-        _record_request(client, model="gpt-4o", tokens_saved=10)
-
-        response = client.get("/stats-history?format=csv&series=daily")
-        assert response.status_code == 200
-        assert response.headers["content-type"].startswith("text/csv")
-        assert (
-            'attachment; filename="headroom-stats-history-daily.csv"'
-            == response.headers["content-disposition"]
-        )
-        lines = response.text.strip().splitlines()
-        assert lines[0] == (
-            "timestamp,tokens_saved,compression_savings_usd_delta,total_tokens_saved,"
-            "compression_savings_usd,total_input_tokens_delta,total_input_tokens,"
-            "total_input_cost_usd_delta,total_input_cost_usd"
-        )
-        assert len(lines) >= 2
-        assert "total_tokens_saved" in lines[0]
-        assert "total_input_cost_usd" in lines[0]
-
-
-def test_malformed_savings_state_is_ignored_safely(tmp_path, monkeypatch):
-    savings_path = tmp_path / "proxy_savings.json"
-    savings_path.write_text("{not valid json", encoding="utf-8")
-    monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
-
-    config = ProxyConfig(
-        cache_enabled=False,
-        rate_limit_enabled=False,
-        log_requests=False,
-    )
-
-    with TestClient(create_app(config)) as client:
-        response = client.get("/stats-history")
-        assert response.status_code == 200
-        data = response.json()
-        assert data["lifetime"]["tokens_saved"] == 0
-        assert data["history"] == []
-
-
-def test_dashboard_includes_history_toggle_and_endpoint(tmp_path, monkeypatch):
-    savings_path = tmp_path / "proxy_savings.json"
-    monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
-
-    config = ProxyConfig(
-        cache_enabled=False,
-        rate_limit_enabled=False,
-        log_requests=False,
-    )
-
-    with TestClient(create_app(config)) as client:
-        response = client.get("/dashboard")
-        assert response.status_code == 200
-        html = response.text
-        assert "Session" in html
-        assert "Historical" in html
-        assert "fetch('/stats-history')" in html
-        assert "Export CSV" in html
-        assert "Weekly Savings" in html
-        assert "Monthly Savings" in html
+"""Tests for durable proxy savings history."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient
+
+import headroom.proxy.savings_tracker as savings_tracker_module
+from headroom.proxy.savings_tracker import HEADROOM_SAVINGS_PATH_ENV_VAR, SavingsTracker
+from headroom.proxy.server import ProxyConfig, create_app
+
+
+def _record_request(
+    client: TestClient,
+    *,
+    model: str,
+    tokens_saved: int,
+    input_tokens: int = 120,
+) -> None:
+    proxy = client.app.state.proxy
+    if proxy.cost_tracker:
+        proxy.cost_tracker.record_tokens(model, tokens_saved, input_tokens)
+    asyncio.run(
+        proxy.metrics.record_request(
+            provider="openai",
+            model=model,
+            input_tokens=input_tokens,
+            output_tokens=24,
+            tokens_saved=tokens_saved,
+            latency_ms=15.0,
+        )
+    )
+
+
+def test_savings_tracker_helpers_normalize_inputs_and_paths(tmp_path, monkeypatch):
+    override_path = tmp_path / "custom-savings.json"
+    monkeypatch.setenv(HEADROOM_SAVINGS_PATH_ENV_VAR, str(override_path))
+    assert savings_tracker_module.get_default_savings_storage_path() == str(override_path)
+
+    monkeypatch.delenv(HEADROOM_SAVINGS_PATH_ENV_VAR, raising=False)
+    default_path = savings_tracker_module.get_default_savings_storage_path()
+    assert Path(default_path).as_posix().endswith(".headroom/proxy_savings.json")
+
+    assert savings_tracker_module._parse_timestamp("") is None
+    assert savings_tracker_module._parse_timestamp("not-a-timestamp") is None
+    assert savings_tracker_module._parse_timestamp("2026-03-27T09:00:00") == datetime(
+        2026, 3, 27, 9, 0, tzinfo=timezone.utc
+    )
+
+    assert savings_tracker_module._coerce_int("7") == 7
+    assert savings_tracker_module._coerce_int(-5) == 0
+    assert savings_tracker_module._coerce_float("0.25") == pytest.approx(0.25)
+    assert savings_tracker_module._coerce_float(-0.25) == 0.0
+
+    assert savings_tracker_module._normalize_history_entry(
+        ["2026-03-27T09:00:00Z", "12", "0.5"]
+    ) == {
+        "timestamp": "2026-03-27T09:00:00Z",
+        "total_tokens_saved": 12,
+        "compression_savings_usd": 0.5,
+        "total_input_tokens": 0,
+        "total_input_cost_usd": 0.0,
+    }
+    assert savings_tracker_module._normalize_history_entry({"timestamp": "bad"}) is None
+    assert savings_tracker_module._normalize_history_entry(object()) is None
+
+
+def test_savings_tracker_sanitizes_legacy_state_and_applies_retention(tmp_path):
+    path = tmp_path / "proxy_savings.json"
+    path.write_text(
+        json.dumps(
+            {
+                "schema_version": 0,
+                "lifetime": {
+                    "tokens_saved": 1,
+                    "compression_savings_usd": 0.001,
+                },
+                "history": [
+                    ["2026-03-24T08:00:00Z", 10, 0.01],
+                    {
+                        "timestamp": "2026-03-26T12:00:00Z",
+                        "total_tokens_saved": 20,
+                        "compression_savings_usd": 0.02,
+                    },
+                    {
+                        "timestamp": "2026-03-27T09:00:00Z",
+                        "total_tokens_saved": 30,
+                        "compression_savings_usd": 0.03,
+                    },
+                    {"timestamp": "bad", "total_tokens_saved": 999},
+                ],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    tracker = SavingsTracker(
+        path=str(path),
+        max_history_points=1,
+        max_history_age_days=2,
+    )
+    snapshot = tracker.snapshot()
+
+    assert snapshot["schema_version"] == 2
+    assert snapshot["lifetime"] == {
+        "requests": 0,
+        "tokens_saved": 30,
+        "compression_savings_usd": pytest.approx(0.03),
+        "total_input_tokens": 0,
+        "total_input_cost_usd": 0.0,
+    }
+    assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
+    assert snapshot["history"] == [
+        {
+            "timestamp": "2026-03-27T09:00:00Z",
+            "total_tokens_saved": 30,
+            "compression_savings_usd": 0.03,
+            "total_input_tokens": 0,
+            "total_input_cost_usd": 0.0,
+        }
+    ]
+    assert snapshot["retention"] == {
+        "max_history_points": 1,
+        "max_history_age_days": 2,
+        "max_response_history_points": 500,
+    }
+
+
+def test_non_dict_savings_state_resets_to_default(tmp_path):
+    path = tmp_path / "proxy_savings.json"
+    path.write_text("[]", encoding="utf-8")
+
+    tracker = SavingsTracker(path=str(path))
+    snapshot = tracker.snapshot()
+
+    assert snapshot["lifetime"] == {
+        "requests": 0,
+        "tokens_saved": 0,
+        "compression_savings_usd": 0.0,
+        "total_input_tokens": 0,
+        "total_input_cost_usd": 0.0,
+    }
+    assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
+    assert snapshot["history"] == []
+
+
+def test_record_compression_savings_skips_empty_updates_and_normalizes_timestamps(
+    tmp_path, monkeypatch
+):
+    path = tmp_path / "proxy_savings.json"
+    tracker = SavingsTracker(path=str(path))
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_estimate_compression_savings_usd",
+        lambda model, tokens_saved: tokens_saved / 1000.0,
+    )
+
+    assert tracker.record_compression_savings(model="gpt-4o", tokens_saved=0) is False
+    assert not path.exists()
+
+    local_time = datetime(2026, 3, 27, 10, 0, tzinfo=timezone(timedelta(hours=2)))
+    assert tracker.record_compression_savings(
+        model="gpt-4o",
+        tokens_saved=10,
+        total_input_tokens=120,
+        total_input_cost_usd=0.24,
+        timestamp=local_time,
+    )
+
+    fallback_time = datetime(2026, 3, 27, 12, 34, tzinfo=timezone.utc)
+    monkeypatch.setattr(savings_tracker_module, "_utc_now", lambda: fallback_time)
+    assert tracker.record_compression_savings(
+        model="gpt-4o",
+        tokens_saved=5,
+        total_input_tokens=180,
+        total_input_cost_usd=0.36,
+        timestamp="not-a-timestamp",
+    )
+
+    snapshot = tracker.snapshot()
+    assert snapshot["history"] == [
+        {
+            "timestamp": "2026-03-27T08:00:00Z",
+            "total_tokens_saved": 10,
+            "compression_savings_usd": 0.01,
+            "total_input_tokens": 120,
+            "total_input_cost_usd": 0.24,
+        },
+        {
+            "timestamp": "2026-03-27T12:34:00Z",
+            "total_tokens_saved": 15,
+            "compression_savings_usd": 0.015,
+            "total_input_tokens": 180,
+            "total_input_cost_usd": 0.36,
+        },
+    ]
+
+    persisted = json.loads(path.read_text(encoding="utf-8"))
+    assert persisted["lifetime"]["tokens_saved"] == 15
+    assert persisted["lifetime"]["total_input_tokens"] == 180
+    assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.36)
+    assert persisted["history"][-1]["timestamp"] == "2026-03-27T12:34:00Z"
+
+
+def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):
+    def fake_cost_per_token(*, model, prompt_tokens, completion_tokens):
+        if model in {"gpt-4o", "anthropic/claude-sonnet-4-6"}:
+            return {
+                "model": model,
+                "prompt_tokens": prompt_tokens,
+                "completion_tokens": completion_tokens,
+            }
+        raise RuntimeError("unknown model")
+
+    fake_litellm = SimpleNamespace(
+        cost_per_token=fake_cost_per_token,
+        model_cost={
+            "anthropic/claude-sonnet-4-6": {"input_cost_per_token": 0.002},
+            "gpt-4o": {"input_cost_per_token": 0.001},
+        },
+    )
+    monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", True)
+    monkeypatch.setattr(savings_tracker_module, "litellm", fake_litellm)
+
+    assert savings_tracker_module._resolve_litellm_model("gpt-4o") == "gpt-4o"
+    assert (
+        savings_tracker_module._resolve_litellm_model("claude-sonnet-4-6")
+        == "anthropic/claude-sonnet-4-6"
+    )
+    assert savings_tracker_module._estimate_compression_savings_usd(
+        "claude-sonnet-4-6", 100
+    ) == pytest.approx(0.2)
+    assert savings_tracker_module._estimate_input_cost_usd(
+        "claude-sonnet-4-6",
+        100,
+        cache_read_tokens=10,
+        cache_write_tokens=5,
+        uncached_input_tokens=85,
+    ) == pytest.approx(0.2)
+
+    fake_litellm.model_cost = {}
+    assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
+    assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0
+
+    monkeypatch.setattr(
+        fake_litellm,
+        "cost_per_token",
+        lambda **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),
+    )
+    assert savings_tracker_module._resolve_litellm_model("mystery-model") == "mystery-model"
+    assert savings_tracker_module._estimate_compression_savings_usd("mystery-model", 100) == 0.0
+
+    monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", False)
+    assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
+    assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0
+
+
+def test_display_session_rolls_after_inactivity_and_counts_zero_savings_requests(
+    tmp_path, monkeypatch
+):
+    path = tmp_path / "proxy_savings.json"
+    tracker = SavingsTracker(path=str(path), display_session_inactivity_minutes=30)
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_estimate_compression_savings_usd",
+        lambda model, tokens_saved: tokens_saved / 1000.0,
+    )
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_estimate_input_cost_usd",
+        lambda model, input_tokens, **kwargs: input_tokens / 1000.0,
+    )
+
+    tracker.record_request(
+        model="gpt-4o",
+        input_tokens=120,
+        tokens_saved=0,
+        timestamp="2026-03-27T09:00:00Z",
+    )
+    tracker.record_request(
+        model="gpt-4o",
+        input_tokens=80,
+        tokens_saved=20,
+        timestamp="2026-03-27T09:10:00Z",
+    )
+
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_utc_now",
+        lambda: datetime(2026, 3, 27, 9, 15, tzinfo=timezone.utc),
+    )
+    active_session = tracker.snapshot()["display_session"]
+    assert active_session == {
+        "requests": 2,
+        "tokens_saved": 20,
+        "compression_savings_usd": pytest.approx(0.02),
+        "total_input_tokens": 200,
+        "total_input_cost_usd": pytest.approx(0.2),
+        "savings_percent": pytest.approx(9.09),
+        "started_at": "2026-03-27T09:00:00Z",
+        "last_activity_at": "2026-03-27T09:10:00Z",
+    }
+
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_utc_now",
+        lambda: datetime(2026, 3, 27, 9, 45, tzinfo=timezone.utc),
+    )
+    assert tracker.snapshot()["display_session"] == savings_tracker_module._empty_display_session()
+
+    tracker.record_request(
+        model="gpt-4o",
+        input_tokens=50,
+        tokens_saved=5,
+        timestamp="2026-03-27T10:05:00Z",
+    )
+
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_utc_now",
+        lambda: datetime(2026, 3, 27, 10, 10, tzinfo=timezone.utc),
+    )
+    rolled = tracker.snapshot()
+    assert rolled["lifetime"]["requests"] == 3
+    assert rolled["display_session"] == {
+        "requests": 1,
+        "tokens_saved": 5,
+        "compression_savings_usd": pytest.approx(0.005),
+        "total_input_tokens": 50,
+        "total_input_cost_usd": pytest.approx(0.05),
+        "savings_percent": pytest.approx(9.09),
+        "started_at": "2026-03-27T10:05:00Z",
+        "last_activity_at": "2026-03-27T10:05:00Z",
+    }
+
+
+def test_savings_tracker_rollups_preserve_spend_and_input_history(tmp_path, monkeypatch):
+    path = tmp_path / "proxy_savings.json"
+    tracker = SavingsTracker(
+        path=str(path),
+        max_history_points=100,
+        max_history_age_days=30,
+    )
+    monkeypatch.setattr(
+        "headroom.proxy.savings_tracker._estimate_compression_savings_usd",
+        lambda model, tokens_saved: tokens_saved / 1000.0,
+    )
+
+    tracker.record_compression_savings(
+        model="gpt-4o",
+        tokens_saved=100,
+        total_input_tokens=120,
+        total_input_cost_usd=0.24,
+        timestamp="2026-03-27T09:10:00Z",
+    )
+    tracker.record_compression_savings(
+        model="gpt-4o",
+        tokens_saved=50,
+        total_input_tokens=210,
+        total_input_cost_usd=0.42,
+        timestamp="2026-03-27T09:40:00Z",
+    )
+    tracker.record_compression_savings(
+        model="gpt-4o",
+        tokens_saved=25,
+        total_input_tokens=300,
+        total_input_cost_usd=0.63,
+        timestamp="2026-03-27T10:05:00Z",
+    )
+    tracker.record_compression_savings(
+        model="gpt-4o",
+        tokens_saved=10,
+        total_input_tokens=360,
+        total_input_cost_usd=0.75,
+        timestamp="2026-03-28T08:00:00Z",
+    )
+    tracker.record_compression_savings(
+        model="gpt-4o",
+        tokens_saved=20,
+        total_input_tokens=450,
+        total_input_cost_usd=0.93,
+        timestamp="2026-04-02T14:00:00Z",
+    )
+
+    response = tracker.history_response()
+
+    assert response["lifetime"]["tokens_saved"] == 205
+    assert response["lifetime"]["compression_savings_usd"] == pytest.approx(0.205)
+    assert response["lifetime"]["total_input_tokens"] == 450
+    assert response["lifetime"]["total_input_cost_usd"] == pytest.approx(0.93)
+    assert len(response["history"]) == 5
+
+    hourly = response["series"]["hourly"]
+    assert [point["timestamp"] for point in hourly] == [
+        "2026-03-27T09:00:00Z",
+        "2026-03-27T10:00:00Z",
+        "2026-03-28T08:00:00Z",
+        "2026-04-02T14:00:00Z",
+    ]
+    assert hourly[0]["tokens_saved"] == 150
+    assert hourly[0]["total_tokens_saved"] == 150
+    assert hourly[0]["total_input_tokens_delta"] == 210
+    assert hourly[0]["total_input_tokens"] == 210
+    assert hourly[0]["total_input_cost_usd_delta"] == pytest.approx(0.42)
+    assert hourly[0]["total_input_cost_usd"] == pytest.approx(0.42)
+    assert hourly[1]["tokens_saved"] == 25
+    assert hourly[1]["total_tokens_saved"] == 175
+    assert hourly[1]["total_input_tokens_delta"] == 90
+    assert hourly[1]["total_input_tokens"] == 300
+    assert hourly[1]["total_input_cost_usd_delta"] == pytest.approx(0.21)
+    assert hourly[1]["total_input_cost_usd"] == pytest.approx(0.63)
+    assert hourly[2]["tokens_saved"] == 10
+    assert hourly[2]["total_tokens_saved"] == 185
+    assert hourly[2]["total_input_tokens_delta"] == 60
+    assert hourly[2]["total_input_tokens"] == 360
+    assert hourly[2]["total_input_cost_usd_delta"] == pytest.approx(0.12)
+    assert hourly[2]["total_input_cost_usd"] == pytest.approx(0.75)
+    assert hourly[3]["tokens_saved"] == 20
+    assert hourly[3]["total_tokens_saved"] == 205
+    assert hourly[3]["total_input_tokens_delta"] == 90
+    assert hourly[3]["total_input_tokens"] == 450
+    assert hourly[3]["total_input_cost_usd_delta"] == pytest.approx(0.18)
+    assert hourly[3]["total_input_cost_usd"] == pytest.approx(0.93)
+
+    daily = response["series"]["daily"]
+    assert [point["timestamp"] for point in daily] == [
+        "2026-03-27T00:00:00Z",
+        "2026-03-28T00:00:00Z",
+        "2026-04-02T00:00:00Z",
+    ]
+    assert daily[0]["tokens_saved"] == 175
+    assert daily[0]["total_tokens_saved"] == 175
+    assert daily[0]["total_input_tokens_delta"] == 300
+    assert daily[0]["total_input_tokens"] == 300
+    assert daily[0]["total_input_cost_usd_delta"] == pytest.approx(0.63)
+    assert daily[0]["total_input_cost_usd"] == pytest.approx(0.63)
+    assert daily[1]["tokens_saved"] == 10
+    assert daily[1]["total_tokens_saved"] == 185
+    assert daily[1]["total_input_tokens_delta"] == 60
+    assert daily[1]["total_input_tokens"] == 360
+    assert daily[1]["total_input_cost_usd_delta"] == pytest.approx(0.12)
+    assert daily[1]["total_input_cost_usd"] == pytest.approx(0.75)
+    assert daily[2]["tokens_saved"] == 20
+    assert daily[2]["total_tokens_saved"] == 205
+    assert daily[2]["total_input_tokens_delta"] == 90
+    assert daily[2]["total_input_tokens"] == 450
+    assert daily[2]["total_input_cost_usd_delta"] == pytest.approx(0.18)
+    assert daily[2]["total_input_cost_usd"] == pytest.approx(0.93)
+
+    weekly = response["series"]["weekly"]
+    assert [point["timestamp"] for point in weekly] == [
+        "2026-03-23T00:00:00Z",
+        "2026-03-30T00:00:00Z",
+    ]
+    assert weekly[0]["tokens_saved"] == 185
+    assert weekly[0]["total_tokens_saved"] == 185
+    assert weekly[1]["tokens_saved"] == 20
+    assert weekly[1]["total_tokens_saved"] == 205
+
+    monthly = response["series"]["monthly"]
+    assert [point["timestamp"] for point in monthly] == [
+        "2026-03-01T00:00:00Z",
+        "2026-04-01T00:00:00Z",
+    ]
+    assert monthly[0]["tokens_saved"] == 185
+    assert monthly[0]["total_tokens_saved"] == 185
+    assert monthly[1]["tokens_saved"] == 20
+    assert monthly[1]["total_tokens_saved"] == 205
+
+    assert response["exports"]["available_formats"] == ["json", "csv"]
+    assert response["exports"]["available_series"] == [
+        "history",
+        "hourly",
+        "daily",
+        "weekly",
+        "monthly",
+    ]
+
+
+def test_stats_history_defaults_to_compact_history_but_can_return_full_history(
+    tmp_path, monkeypatch
+):
+    path = tmp_path / "proxy_savings.json"
+    tracker = SavingsTracker(
+        path=str(path),
+        max_history_points=100,
+        max_history_age_days=30,
+        max_response_history_points=5,
+    )
+    monkeypatch.setattr(
+        "headroom.proxy.savings_tracker._estimate_compression_savings_usd",
+        lambda model, tokens_saved: tokens_saved / 1000.0,
+    )
+
+    for i in range(8):
+        tracker.record_compression_savings(
+            model="gpt-4o",
+            tokens_saved=10,
+            total_input_tokens=(i + 1) * 100,
+            total_input_cost_usd=(i + 1) * 0.1,
+            timestamp=f"2026-03-27T09:{i:02d}:00Z",
+        )
+
+    compact = tracker.history_response()
+    assert compact["history_summary"] == {
+        "mode": "compact",
+        "stored_points": 8,
+        "returned_points": 5,
+        "compacted": True,
+    }
+    assert len(compact["history"]) == 5
+    assert compact["history"][0]["timestamp"] == "2026-03-27T09:00:00Z"
+    assert compact["history"][-1]["timestamp"] == "2026-03-27T09:07:00Z"
+
+    full = tracker.history_response(history_mode="full")
+    assert full["history_summary"] == {
+        "mode": "full",
+        "stored_points": 8,
+        "returned_points": 8,
+        "compacted": False,
+    }
+    assert len(full["history"]) == 8
+
+    none = tracker.history_response(history_mode="none")
+    assert none["history"] == []
+    assert none["history_summary"] == {
+        "mode": "none",
+        "stored_points": 8,
+        "returned_points": 0,
+        "compacted": True,
+    }
+
+
+def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_path, monkeypatch):
+    savings_path = tmp_path / "proxy_savings.json"
+    monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
+    monkeypatch.setattr(
+        "headroom.proxy.server.CostTracker._get_cache_prices",
+        lambda self, model: (0.001, 0.0015, 0.002),
+    )
+
+    config = ProxyConfig(
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        log_requests=False,
+    )
+
+    with TestClient(create_app(config)) as client:
+        _record_request(client, model="gpt-4o", tokens_saved=40)
+
+        stats = client.get("/stats")
+        assert stats.status_code == 200
+        stats_data = stats.json()
+        assert "savings_history" in stats_data
+        assert "persistent_savings" in stats_data
+        assert all(len(point) == 2 for point in stats_data["savings_history"])
+        assert stats_data["persistent_savings"]["lifetime"]["tokens_saved"] == 40
+        assert stats_data["persistent_savings"]["storage_path"] == str(savings_path)
+
+        history = client.get("/stats-history")
+        assert history.status_code == 200
+        history_data = history.json()
+        assert history_data["schema_version"] == 2
+        assert history_data["storage_path"] == str(savings_path)
+        assert history_data["lifetime"]["tokens_saved"] == 40
+        assert history_data["lifetime"]["total_input_tokens"] == 120
+        assert history_data["lifetime"]["total_input_cost_usd"] == pytest.approx(0.24)
+        assert history_data["display_session"]["requests"] == 1
+        assert history_data["display_session"]["tokens_saved"] == 40
+        assert history_data["display_session"]["total_input_tokens"] == 120
+        assert history_data["display_session"]["savings_percent"] == pytest.approx(25.0)
+        assert list(history_data["series"].keys()) == [
+            "hourly",
+            "daily",
+            "weekly",
+            "monthly",
+        ]
+        assert history_data["exports"]["available_series"][-2:] == ["weekly", "monthly"]
+        assert history_data["series"]["hourly"][0]["total_input_tokens_delta"] == 120
+        assert history_data["series"]["hourly"][0]["total_input_cost_usd_delta"] == pytest.approx(
+            0.24
+        )
+        assert history_data["history_summary"] == {
+            "mode": "compact",
+            "stored_points": 1,
+            "returned_points": 1,
+            "compacted": False,
+        }
+
+        assert stats_data["display_session"] == history_data["display_session"]
+        assert (
+            stats_data["persistent_savings"]["display_session"] == history_data["display_session"]
+        )
+
+    with TestClient(create_app(config)) as client:
+        history = client.get("/stats-history")
+        assert history.status_code == 200
+        assert history.json()["lifetime"]["tokens_saved"] == 40
+        assert history.json()["display_session"]["requests"] == 1
+
+        _record_request(client, model="gpt-4o", tokens_saved=15)
+
+        updated = client.get("/stats-history").json()
+        assert updated["lifetime"]["tokens_saved"] == 55
+        assert updated["lifetime"]["total_input_tokens"] == 240
+        assert updated["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)
+        assert updated["lifetime"]["requests"] == 2
+        assert len(updated["history"]) == 2
+        assert updated["display_session"]["requests"] == 2
+        assert updated["display_session"]["tokens_saved"] == 55
+        assert updated["display_session"]["total_input_tokens"] == 240
+        assert updated["display_session"]["savings_percent"] == pytest.approx(18.64)
+        assert updated["series"]["daily"][0]["total_input_tokens_delta"] == 240
+        assert updated["series"]["daily"][0]["total_input_cost_usd_delta"] == pytest.approx(0.48)
+
+        full = client.get("/stats-history?history_mode=full").json()
+        assert full["history_summary"]["mode"] == "full"
+        assert full["history_summary"]["stored_points"] == 2
+        assert full["history_summary"]["returned_points"] == 2
+
+        persisted = json.loads(savings_path.read_text())
+        assert persisted["lifetime"]["tokens_saved"] == 55
+        assert persisted["lifetime"]["total_input_tokens"] == 240
+        assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)
+        assert persisted["display_session"]["requests"] == 2
+
+
+def test_stats_history_csv_export_is_frontend_friendly(tmp_path, monkeypatch):
+    savings_path = tmp_path / "proxy_savings.json"
+    monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
+    monkeypatch.setattr(
+        "headroom.proxy.server.CostTracker._get_cache_prices",
+        lambda self, model: (0.001, 0.0015, 0.002),
+    )
+
+    config = ProxyConfig(
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        log_requests=False,
+    )
+
+    with TestClient(create_app(config)) as client:
+        _record_request(client, model="gpt-4o", tokens_saved=40)
+        _record_request(client, model="gpt-4o", tokens_saved=10)
+
+        response = client.get("/stats-history?format=csv&series=daily")
+        assert response.status_code == 200
+        assert response.headers["content-type"].startswith("text/csv")
+        assert (
+            'attachment; filename="headroom-stats-history-daily.csv"'
+            == response.headers["content-disposition"]
+        )
+        lines = response.text.strip().splitlines()
+        assert lines[0] == (
+            "timestamp,tokens_saved,compression_savings_usd_delta,total_tokens_saved,"
+            "compression_savings_usd,total_input_tokens_delta,total_input_tokens,"
+            "total_input_cost_usd_delta,total_input_cost_usd"
+        )
+        assert len(lines) >= 2
+        assert "total_tokens_saved" in lines[0]
+        assert "total_input_cost_usd" in lines[0]
+
+
+def test_malformed_savings_state_is_ignored_safely(tmp_path, monkeypatch):
+    savings_path = tmp_path / "proxy_savings.json"
+    savings_path.write_text("{not valid json", encoding="utf-8")
+    monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
+
+    config = ProxyConfig(
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        log_requests=False,
+    )
+
+    with TestClient(create_app(config)) as client:
+        response = client.get("/stats-history")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["lifetime"]["tokens_saved"] == 0
+        assert data["history"] == []
+
+
+def test_dashboard_includes_history_toggle_and_endpoint(tmp_path, monkeypatch):
+    savings_path = tmp_path / "proxy_savings.json"
+    monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
+
+    config = ProxyConfig(
+        cache_enabled=False,
+        rate_limit_enabled=False,
+        log_requests=False,
+    )
+
+    with TestClient(create_app(config)) as client:
+        response = client.get("/dashboard")
+        assert response.status_code == 200
+        html = response.text
+        assert "Session" in html
+        assert "Historical" in html
+        assert "fetch('/stats-history')" in html
+        assert "Export CSV" in html
+        assert "Weekly Savings" in html
+        assert "Monthly Savings" in html
diff --git a/tests/test_quota_registry.py b/tests/test_quota_registry.py
index 7824c5970a8e8add43c28b82ba805980967b4139..8a3f37bd8ef553a9da18f122bb22f6503eeee81d 100644
--- a/tests/test_quota_registry.py
+++ b/tests/test_quota_registry.py
@@ -1,263 +1,263 @@
-"""Tests for the pluggable QuotaTracker / QuotaTrackerRegistry abstraction."""
-
-from __future__ import annotations
-
-import asyncio
-from typing import Any
-
-import pytest
-
-from headroom.subscription.base import (
-    QuotaTracker,
-    QuotaTrackerRegistry,
-    get_quota_registry,
-    reset_quota_registry,
-)
-
-# ---------------------------------------------------------------------------
-# Minimal concrete trackers for test use
-# ---------------------------------------------------------------------------
-
-
-class _AlwaysOnTracker(QuotaTracker):
-    key = "always_on"
-    label = "AlwaysOn"
-
-    def __init__(self, stats: dict | None = None) -> None:
-        self._stats = stats or {"value": 1}
-        self.started = False
-        self.stopped = False
-
-    async def start(self) -> None:
-        self.started = True
-
-    async def stop(self) -> None:
-        self.stopped = True
-
-    def get_stats(self) -> dict[str, Any] | None:
-        return self._stats
-
-
-class _UnavailableTracker(QuotaTracker):
-    key = "unavailable"
-    label = "Unavailable"
-
-    def is_available(self) -> bool:
-        return False
-
-    def get_stats(self) -> dict[str, Any] | None:
-        return {"should_not_appear": True}
-
-
-class _NoDataTracker(QuotaTracker):
-    key = "no_data"
-    label = "NoData"
-
-    def get_stats(self) -> dict[str, Any] | None:
-        return None
-
-
-class _PassiveTracker(QuotaTracker):
-    """Uses inherited no-op start/stop."""
-
-    key = "passive"
-    label = "Passive"
-
-    def get_stats(self) -> dict[str, Any] | None:
-        return {"passive": True}
-
-
-# ---------------------------------------------------------------------------
-# Fixtures
-# ---------------------------------------------------------------------------
-
-
-@pytest.fixture(autouse=True)
-def fresh_registry():
-    """Reset the global registry before every test."""
-    reset_quota_registry()
-    yield
-    reset_quota_registry()
-
-
-# ---------------------------------------------------------------------------
-# Registration tests
-# ---------------------------------------------------------------------------
-
-
-def test_register_single_tracker():
-    registry = QuotaTrackerRegistry()
-    tracker = _AlwaysOnTracker()
-    registry.register(tracker)
-    assert registry.get("always_on") is tracker
-
-
-def test_register_multiple_trackers():
-    registry = QuotaTrackerRegistry()
-    t1 = _AlwaysOnTracker()
-    t2 = _PassiveTracker()
-    registry.register(t1)
-    registry.register(t2)
-    assert len(registry.trackers) == 2
-
-
-def test_duplicate_key_raises():
-    registry = QuotaTrackerRegistry()
-    registry.register(_AlwaysOnTracker())
-    with pytest.raises(ValueError, match="already registered"):
-        registry.register(_AlwaysOnTracker())
-
-
-def test_get_unknown_key_returns_none():
-    registry = QuotaTrackerRegistry()
-    assert registry.get("nonexistent") is None
-
-
-def test_trackers_property_is_snapshot():
-    registry = QuotaTrackerRegistry()
-    t = _AlwaysOnTracker()
-    registry.register(t)
-    snapshot = registry.trackers
-    # Mutations to the snapshot don't affect the registry
-    snapshot.clear()
-    assert len(registry.trackers) == 1
-
-
-# ---------------------------------------------------------------------------
-# Lifecycle tests
-# ---------------------------------------------------------------------------
-
-
-def test_start_all_calls_available_trackers():
-    registry = QuotaTrackerRegistry()
-    t = _AlwaysOnTracker()
-    registry.register(t)
-    asyncio.run(registry.start_all())
-    assert t.started is True
-
-
-def test_start_all_skips_unavailable_trackers():
-    registry = QuotaTrackerRegistry()
-    unavailable = _UnavailableTracker()
-    registry.register(unavailable)
-
-    # Patch start to detect if it was called
-    called = []
-
-    async def _start() -> None:
-        called.append(True)
-
-    unavailable.start = _start  # type: ignore[method-assign]
-    asyncio.run(registry.start_all())
-    assert called == []
-
-
-def test_stop_all_calls_stop_on_all_registered():
-    registry = QuotaTrackerRegistry()
-    t = _AlwaysOnTracker()
-    unavailable = _UnavailableTracker()
-    registry.register(t)
-    registry.register(unavailable)
-    asyncio.run(registry.stop_all())
-    assert t.stopped is True
-
-
-def test_stop_all_continues_on_exception():
-    registry = QuotaTrackerRegistry()
-
-    class _BrokenTracker(QuotaTracker):
-        key = "broken"
-        label = "Broken"
-
-        async def stop(self) -> None:
-            raise RuntimeError("stop failed")
-
-        def get_stats(self) -> dict | None:
-            return None
-
-    registry.register(_BrokenTracker())
-    # Should not raise
-    asyncio.run(registry.stop_all())
-
-
-def test_passive_tracker_start_stop_are_noops():
-    registry = QuotaTrackerRegistry()
-    t = _PassiveTracker()
-    registry.register(t)
-    asyncio.run(registry.start_all())
-    asyncio.run(registry.stop_all())
-    # No assertions needed — we verify no exception is raised
-
-
-# ---------------------------------------------------------------------------
-# Stats tests
-# ---------------------------------------------------------------------------
-
-
-def test_get_all_stats_includes_available_with_data():
-    registry = QuotaTrackerRegistry()
-    registry.register(_AlwaysOnTracker({"x": 1}))
-    stats = registry.get_all_stats()
-    assert "always_on" in stats
-    assert stats["always_on"] == {"x": 1}
-
-
-def test_get_all_stats_excludes_unavailable():
-    registry = QuotaTrackerRegistry()
-    registry.register(_UnavailableTracker())
-    stats = registry.get_all_stats()
-    assert "unavailable" not in stats
-
-
-def test_get_all_stats_excludes_none_data():
-    registry = QuotaTrackerRegistry()
-    registry.register(_NoDataTracker())
-    stats = registry.get_all_stats()
-    assert "no_data" not in stats
-
-
-def test_get_all_stats_mixed():
-    registry = QuotaTrackerRegistry()
-    registry.register(_AlwaysOnTracker({"ok": True}))
-    registry.register(_UnavailableTracker())
-    registry.register(_NoDataTracker())
-    stats = registry.get_all_stats()
-    assert set(stats.keys()) == {"always_on"}
-
-
-def test_get_stats_single_key():
-    registry = QuotaTrackerRegistry()
-    registry.register(_AlwaysOnTracker({"z": 99}))
-    assert registry.get_stats("always_on") == {"z": 99}
-
-
-def test_get_stats_missing_key_returns_none():
-    registry = QuotaTrackerRegistry()
-    assert registry.get_stats("missing") is None
-
-
-# ---------------------------------------------------------------------------
-# Global singleton tests
-# ---------------------------------------------------------------------------
-
-
-def test_get_quota_registry_returns_same_instance():
-    r1 = get_quota_registry()
-    r2 = get_quota_registry()
-    assert r1 is r2
-
-
-def test_reset_quota_registry_gives_fresh_instance():
-    r1 = get_quota_registry()
-    r1.register(_AlwaysOnTracker())
-    reset_quota_registry()
-    r2 = get_quota_registry()
-    assert r1 is not r2
-    assert len(r2.trackers) == 0
-
-
-def test_reset_quota_registry_clears_registrations():
-    registry = get_quota_registry()
-    registry.register(_AlwaysOnTracker())
-    reset_quota_registry()
-    assert len(get_quota_registry().trackers) == 0
+"""Tests for the pluggable QuotaTracker / QuotaTrackerRegistry abstraction."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import pytest
+
+from headroom.subscription.base import (
+    QuotaTracker,
+    QuotaTrackerRegistry,
+    get_quota_registry,
+    reset_quota_registry,
+)
+
+# ---------------------------------------------------------------------------
+# Minimal concrete trackers for test use
+# ---------------------------------------------------------------------------
+
+
+class _AlwaysOnTracker(QuotaTracker):
+    key = "always_on"
+    label = "AlwaysOn"
+
+    def __init__(self, stats: dict | None = None) -> None:
+        self._stats = stats or {"value": 1}
+        self.started = False
+        self.stopped = False
+
+    async def start(self) -> None:
+        self.started = True
+
+    async def stop(self) -> None:
+        self.stopped = True
+
+    def get_stats(self) -> dict[str, Any] | None:
+        return self._stats
+
+
+class _UnavailableTracker(QuotaTracker):
+    key = "unavailable"
+    label = "Unavailable"
+
+    def is_available(self) -> bool:
+        return False
+
+    def get_stats(self) -> dict[str, Any] | None:
+        return {"should_not_appear": True}
+
+
+class _NoDataTracker(QuotaTracker):
+    key = "no_data"
+    label = "NoData"
+
+    def get_stats(self) -> dict[str, Any] | None:
+        return None
+
+
+class _PassiveTracker(QuotaTracker):
+    """Uses inherited no-op start/stop."""
+
+    key = "passive"
+    label = "Passive"
+
+    def get_stats(self) -> dict[str, Any] | None:
+        return {"passive": True}
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def fresh_registry():
+    """Reset the global registry before every test."""
+    reset_quota_registry()
+    yield
+    reset_quota_registry()
+
+
+# ---------------------------------------------------------------------------
+# Registration tests
+# ---------------------------------------------------------------------------
+
+
+def test_register_single_tracker():
+    registry = QuotaTrackerRegistry()
+    tracker = _AlwaysOnTracker()
+    registry.register(tracker)
+    assert registry.get("always_on") is tracker
+
+
+def test_register_multiple_trackers():
+    registry = QuotaTrackerRegistry()
+    t1 = _AlwaysOnTracker()
+    t2 = _PassiveTracker()
+    registry.register(t1)
+    registry.register(t2)
+    assert len(registry.trackers) == 2
+
+
+def test_duplicate_key_raises():
+    registry = QuotaTrackerRegistry()
+    registry.register(_AlwaysOnTracker())
+    with pytest.raises(ValueError, match="already registered"):
+        registry.register(_AlwaysOnTracker())
+
+
+def test_get_unknown_key_returns_none():
+    registry = QuotaTrackerRegistry()
+    assert registry.get("nonexistent") is None
+
+
+def test_trackers_property_is_snapshot():
+    registry = QuotaTrackerRegistry()
+    t = _AlwaysOnTracker()
+    registry.register(t)
+    snapshot = registry.trackers
+    # Mutations to the snapshot don't affect the registry
+    snapshot.clear()
+    assert len(registry.trackers) == 1
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle tests
+# ---------------------------------------------------------------------------
+
+
+def test_start_all_calls_available_trackers():
+    registry = QuotaTrackerRegistry()
+    t = _AlwaysOnTracker()
+    registry.register(t)
+    asyncio.run(registry.start_all())
+    assert t.started is True
+
+
+def test_start_all_skips_unavailable_trackers():
+    registry = QuotaTrackerRegistry()
+    unavailable = _UnavailableTracker()
+    registry.register(unavailable)
+
+    # Patch start to detect if it was called
+    called = []
+
+    async def _start() -> None:
+        called.append(True)
+
+    unavailable.start = _start  # type: ignore[method-assign]
+    asyncio.run(registry.start_all())
+    assert called == []
+
+
+def test_stop_all_calls_stop_on_all_registered():
+    registry = QuotaTrackerRegistry()
+    t = _AlwaysOnTracker()
+    unavailable = _UnavailableTracker()
+    registry.register(t)
+    registry.register(unavailable)
+    asyncio.run(registry.stop_all())
+    assert t.stopped is True
+
+
+def test_stop_all_continues_on_exception():
+    registry = QuotaTrackerRegistry()
+
+    class _BrokenTracker(QuotaTracker):
+        key = "broken"
+        label = "Broken"
+
+        async def stop(self) -> None:
+            raise RuntimeError("stop failed")
+
+        def get_stats(self) -> dict | None:
+            return None
+
+    registry.register(_BrokenTracker())
+    # Should not raise
+    asyncio.run(registry.stop_all())
+
+
+def test_passive_tracker_start_stop_are_noops():
+    registry = QuotaTrackerRegistry()
+    t = _PassiveTracker()
+    registry.register(t)
+    asyncio.run(registry.start_all())
+    asyncio.run(registry.stop_all())
+    # No assertions needed — we verify no exception is raised
+
+
+# ---------------------------------------------------------------------------
+# Stats tests
+# ---------------------------------------------------------------------------
+
+
+def test_get_all_stats_includes_available_with_data():
+    registry = QuotaTrackerRegistry()
+    registry.register(_AlwaysOnTracker({"x": 1}))
+    stats = registry.get_all_stats()
+    assert "always_on" in stats
+    assert stats["always_on"] == {"x": 1}
+
+
+def test_get_all_stats_excludes_unavailable():
+    registry = QuotaTrackerRegistry()
+    registry.register(_UnavailableTracker())
+    stats = registry.get_all_stats()
+    assert "unavailable" not in stats
+
+
+def test_get_all_stats_excludes_none_data():
+    registry = QuotaTrackerRegistry()
+    registry.register(_NoDataTracker())
+    stats = registry.get_all_stats()
+    assert "no_data" not in stats
+
+
+def test_get_all_stats_mixed():
+    registry = QuotaTrackerRegistry()
+    registry.register(_AlwaysOnTracker({"ok": True}))
+    registry.register(_UnavailableTracker())
+    registry.register(_NoDataTracker())
+    stats = registry.get_all_stats()
+    assert set(stats.keys()) == {"always_on"}
+
+
+def test_get_stats_single_key():
+    registry = QuotaTrackerRegistry()
+    registry.register(_AlwaysOnTracker({"z": 99}))
+    assert registry.get_stats("always_on") == {"z": 99}
+
+
+def test_get_stats_missing_key_returns_none():
+    registry = QuotaTrackerRegistry()
+    assert registry.get_stats("missing") is None
+
+
+# ---------------------------------------------------------------------------
+# Global singleton tests
+# ---------------------------------------------------------------------------
+
+
+def test_get_quota_registry_returns_same_instance():
+    r1 = get_quota_registry()
+    r2 = get_quota_registry()
+    assert r1 is r2
+
+
+def test_reset_quota_registry_gives_fresh_instance():
+    r1 = get_quota_registry()
+    r1.register(_AlwaysOnTracker())
+    reset_quota_registry()
+    r2 = get_quota_registry()
+    assert r1 is not r2
+    assert len(r2.trackers) == 0
+
+
+def test_reset_quota_registry_clears_registrations():
+    registry = get_quota_registry()
+    registry.register(_AlwaysOnTracker())
+    reset_quota_registry()
+    assert len(get_quota_registry().trackers) == 0
diff --git a/tests/test_release_version.py b/tests/test_release_version.py
index 5485eeb2073d8c07100a1c31b8843d459c687e79..4c66afa72301ab13296c82e64235683b7889c977 100644
--- a/tests/test_release_version.py
+++ b/tests/test_release_version.py
@@ -1,186 +1,186 @@
-"""Tests for release version normalization and bumping."""
-
-import os
-import subprocess
-import sys
-from pathlib import Path
-from unittest.mock import Mock
-
-import pytest
-
-from headroom.release_version import (
-    CommitInfo,
-    classify_commit_bump,
-    compute_release_version,
-    determine_bump_level,
-    find_latest_release_tag,
-    get_canonical_version,
-    list_release_commits,
-    normalize_release_tag,
-    parse_release_tag,
-)
-
-ROOT = Path(__file__).resolve().parent.parent
-
-
-def test_normalize_release_tag_preserves_three_part_tag() -> None:
-    assert str(normalize_release_tag("v0.5.20")) == "0.5.20"
-
-
-def test_normalize_release_tag_collapses_four_part_tag() -> None:
-    assert str(normalize_release_tag("v0.5.25.2")) == "0.5.25"
-
-
-def test_compute_patch_release_from_four_part_history() -> None:
-    info = compute_release_version(
-        canonical_version="0.5.25",
-        level="patch",
-        tags=["v0.5.20", "v0.5.25.1", "v0.5.25.2"],
-    )
-
-    assert info.version == "0.5.26"
-    assert info.npm_version == "0.5.26"
-    assert info.previous_tag == "v0.5.25.2"
-    assert info.bump == "patch"
-
-
-def test_compute_minor_release_from_four_part_history() -> None:
-    info = compute_release_version(
-        canonical_version="0.5.25",
-        level="minor",
-        tags=["v0.5.20", "v0.5.25.1", "v0.5.25.2"],
-    )
-
-    assert info.version == "0.6.0"
-    assert info.npm_version == "0.6.0"
-    assert info.previous_tag == "v0.5.25.2"
-    assert info.bump == "minor"
-
-
-def test_compute_patch_release_from_canonical_without_tags() -> None:
-    info = compute_release_version(
-        canonical_version="0.5.25",
-        level="patch",
-        tags=[],
-    )
-
-    assert info.version == "0.5.26"
-    assert info.npm_version == "0.5.26"
-    assert info.previous_tag == ""
-
-
-def test_manual_version_override_uses_single_semver() -> None:
-    info = compute_release_version(
-        canonical_version="0.5.25",
-        level="patch",
-        tags=["v0.5.25.2"],
-        manual_version="0.6.0",
-    )
-
-    assert info.version == "0.6.0"
-    assert info.npm_version == "0.6.0"
-    assert info.previous_tag == ""
-    assert info.bump == "manual"
-
-
-def test_manual_version_override_rejects_legacy_four_part_version() -> None:
-    with pytest.raises(ValueError, match="Invalid semantic version"):
-        compute_release_version(
-            canonical_version="0.5.25",
-            level="patch",
-            tags=["v0.5.25.2"],
-            manual_version="0.5.25.3",
-        )
-
-
-def test_find_latest_release_tag_prefers_highest_normalized_version() -> None:
-    assert find_latest_release_tag(["v0.5.25.2", "v0.5.27", "not-a-tag"]) == "v0.5.27"
-
-
-def test_find_latest_release_tag_prefers_higher_legacy_height_with_same_base() -> None:
-    assert find_latest_release_tag(["v0.5.25.2", "v0.5.25.3", "v0.5.25"]) == "v0.5.25.3"
-
-
-def test_parse_release_tag_preserves_legacy_height_for_sorting() -> None:
-    tag = parse_release_tag("v0.5.25.3")
-    assert str(tag.version) == "0.5.25"
-    assert tag.legacy_height == 3
-
-
-def test_classify_commit_bump_treats_breaking_change_as_major() -> None:
-    assert (
-        classify_commit_bump(
-            CommitInfo(subject="fix(api)!: change response shape", body=""),
-        )
-        == "major"
-    )
-
-
-def test_determine_bump_level_uses_greatest_commit_level() -> None:
-    commits = [
-        CommitInfo(subject="fix: patch one", body=""),
-        CommitInfo(subject="feat: add capability", body=""),
-        CommitInfo(subject="chore: maintenance", body=""),
-    ]
-
-    assert determine_bump_level(commits) == "minor"
-
-
-def test_determine_bump_level_prefers_major_over_minor_and_patch() -> None:
-    commits = [
-        CommitInfo(subject="fix: patch one", body=""),
-        CommitInfo(subject="feat: add capability", body=""),
-        CommitInfo(
-            subject="docs: update migration guide",
-            body="BREAKING CHANGE: the API changed",
-        ),
-    ]
-
-    assert determine_bump_level(commits) == "major"
-
-
-def test_list_release_commits_parses_empty_body_entries(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    run = Mock()
-    run.return_value = Mock(
-        stdout="feat: add capability\x1f\x1efix: patch bug\x1fbody text\x1e",
-    )
-    monkeypatch.setattr("headroom.release_version.subprocess.run", run)
-
-    commits = list_release_commits(ROOT, "")
-
-    assert commits == [
-        CommitInfo(subject="feat: add capability", body=""),
-        CommitInfo(subject="fix: patch bug", body="body text"),
-    ]
-
-
-def test_release_version_script_runs_directly_without_importing_headroom_package(
-    tmp_path: Path,
-) -> None:
-    output_path = tmp_path / "github-output.txt"
-    env = os.environ.copy()
-    env["GITHUB_OUTPUT"] = str(output_path)
-    env["LEVEL"] = "patch"
-    env["MANUAL_VER"] = "0.6.0"
-
-    result = subprocess.run(
-        [sys.executable, str(ROOT / "headroom" / "release_version.py")],
-        cwd=ROOT,
-        capture_output=True,
-        text=True,
-        env=env,
-        check=False,
-    )
-
-    assert result.returncode == 0, result.stderr
-    canonical_version = get_canonical_version(ROOT)
-    assert output_path.read_text(encoding="utf-8").splitlines() == [
-        "version=0.6.0",
-        "npm_version=0.6.0",
-        f"canonical={canonical_version}",
-        "height=0",
-        "bump=manual",
-        "previous_tag=",
-    ]
+"""Tests for release version normalization and bumping."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import Mock
+
+import pytest
+
+from headroom.release_version import (
+    CommitInfo,
+    classify_commit_bump,
+    compute_release_version,
+    determine_bump_level,
+    find_latest_release_tag,
+    get_canonical_version,
+    list_release_commits,
+    normalize_release_tag,
+    parse_release_tag,
+)
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def test_normalize_release_tag_preserves_three_part_tag() -> None:
+    assert str(normalize_release_tag("v0.5.20")) == "0.5.20"
+
+
+def test_normalize_release_tag_collapses_four_part_tag() -> None:
+    assert str(normalize_release_tag("v0.5.25.2")) == "0.5.25"
+
+
+def test_compute_patch_release_from_four_part_history() -> None:
+    info = compute_release_version(
+        canonical_version="0.5.25",
+        level="patch",
+        tags=["v0.5.20", "v0.5.25.1", "v0.5.25.2"],
+    )
+
+    assert info.version == "0.5.26"
+    assert info.npm_version == "0.5.26"
+    assert info.previous_tag == "v0.5.25.2"
+    assert info.bump == "patch"
+
+
+def test_compute_minor_release_from_four_part_history() -> None:
+    info = compute_release_version(
+        canonical_version="0.5.25",
+        level="minor",
+        tags=["v0.5.20", "v0.5.25.1", "v0.5.25.2"],
+    )
+
+    assert info.version == "0.6.0"
+    assert info.npm_version == "0.6.0"
+    assert info.previous_tag == "v0.5.25.2"
+    assert info.bump == "minor"
+
+
+def test_compute_patch_release_from_canonical_without_tags() -> None:
+    info = compute_release_version(
+        canonical_version="0.5.25",
+        level="patch",
+        tags=[],
+    )
+
+    assert info.version == "0.5.26"
+    assert info.npm_version == "0.5.26"
+    assert info.previous_tag == ""
+
+
+def test_manual_version_override_uses_single_semver() -> None:
+    info = compute_release_version(
+        canonical_version="0.5.25",
+        level="patch",
+        tags=["v0.5.25.2"],
+        manual_version="0.6.0",
+    )
+
+    assert info.version == "0.6.0"
+    assert info.npm_version == "0.6.0"
+    assert info.previous_tag == ""
+    assert info.bump == "manual"
+
+
+def test_manual_version_override_rejects_legacy_four_part_version() -> None:
+    with pytest.raises(ValueError, match="Invalid semantic version"):
+        compute_release_version(
+            canonical_version="0.5.25",
+            level="patch",
+            tags=["v0.5.25.2"],
+            manual_version="0.5.25.3",
+        )
+
+
+def test_find_latest_release_tag_prefers_highest_normalized_version() -> None:
+    assert find_latest_release_tag(["v0.5.25.2", "v0.5.27", "not-a-tag"]) == "v0.5.27"
+
+
+def test_find_latest_release_tag_prefers_higher_legacy_height_with_same_base() -> None:
+    assert find_latest_release_tag(["v0.5.25.2", "v0.5.25.3", "v0.5.25"]) == "v0.5.25.3"
+
+
+def test_parse_release_tag_preserves_legacy_height_for_sorting() -> None:
+    tag = parse_release_tag("v0.5.25.3")
+    assert str(tag.version) == "0.5.25"
+    assert tag.legacy_height == 3
+
+
+def test_classify_commit_bump_treats_breaking_change_as_major() -> None:
+    assert (
+        classify_commit_bump(
+            CommitInfo(subject="fix(api)!: change response shape", body=""),
+        )
+        == "major"
+    )
+
+
+def test_determine_bump_level_uses_greatest_commit_level() -> None:
+    commits = [
+        CommitInfo(subject="fix: patch one", body=""),
+        CommitInfo(subject="feat: add capability", body=""),
+        CommitInfo(subject="chore: maintenance", body=""),
+    ]
+
+    assert determine_bump_level(commits) == "minor"
+
+
+def test_determine_bump_level_prefers_major_over_minor_and_patch() -> None:
+    commits = [
+        CommitInfo(subject="fix: patch one", body=""),
+        CommitInfo(subject="feat: add capability", body=""),
+        CommitInfo(
+            subject="docs: update migration guide",
+            body="BREAKING CHANGE: the API changed",
+        ),
+    ]
+
+    assert determine_bump_level(commits) == "major"
+
+
+def test_list_release_commits_parses_empty_body_entries(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    run = Mock()
+    run.return_value = Mock(
+        stdout="feat: add capability\x1f\x1efix: patch bug\x1fbody text\x1e",
+    )
+    monkeypatch.setattr("headroom.release_version.subprocess.run", run)
+
+    commits = list_release_commits(ROOT, "")
+
+    assert commits == [
+        CommitInfo(subject="feat: add capability", body=""),
+        CommitInfo(subject="fix: patch bug", body="body text"),
+    ]
+
+
+def test_release_version_script_runs_directly_without_importing_headroom_package(
+    tmp_path: Path,
+) -> None:
+    output_path = tmp_path / "github-output.txt"
+    env = os.environ.copy()
+    env["GITHUB_OUTPUT"] = str(output_path)
+    env["LEVEL"] = "patch"
+    env["MANUAL_VER"] = "0.6.0"
+
+    result = subprocess.run(
+        [sys.executable, str(ROOT / "headroom" / "release_version.py")],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        env=env,
+        check=False,
+    )
+
+    assert result.returncode == 0, result.stderr
+    canonical_version = get_canonical_version(ROOT)
+    assert output_path.read_text(encoding="utf-8").splitlines() == [
+        "version=0.6.0",
+        "npm_version=0.6.0",
+        f"canonical={canonical_version}",
+        "height=0",
+        "bump=manual",
+        "previous_tag=",
+    ]
diff --git a/tests/test_release_workflows.py b/tests/test_release_workflows.py
index c753ff882028db7ae9a137aa7e9c52fafb3bf021..6cf067e7fa73fbdbfc786db1bc8409ece42ad5bf 100644
--- a/tests/test_release_workflows.py
+++ b/tests/test_release_workflows.py
@@ -1,62 +1,62 @@
-"""Workflow regression tests for release publishing behavior."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-
-
-def test_docker_workflow_normalizes_repository_name_for_signing() -> None:
-    content = (ROOT / ".github" / "workflows" / "docker.yml").read_text(encoding="utf-8")
-
-    assert "id: image-name" in content
-    assert "tr '[:upper:]' '[:lower:]'" in content
-    assert "steps.image-name.outputs.image_name" in content
-
-
-def test_release_workflow_publishes_both_node_packages_to_github_packages() -> None:
-    content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")
-
-    assert "Publish ${{ env.NPM_SDK_PACKAGE }} to GitHub Package Registry" in content
-    assert "Publish ${{ env.NPM_OPENCLAW_PACKAGE }} to GitHub Package Registry" in content
-    assert "pkg.name = `@${process.env.GITHUB_PACKAGES_SCOPE}/${pkg.name}`;" in content
-    assert (
-        'unscoped_sdk_tarball="$(npm pack --pack-destination "$assets_dir" | tail -n 1)"' in content
-    )
-    assert "SDK_TARBALL: ${{ steps.gpr-sdk-publish.outputs.unscoped_sdk_tarball }}" in content
-
-
-def test_release_workflow_publishes_python_distributions_to_github_release() -> None:
-    content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")
-
-    assert "Publish ${{ env.PYPI_PACKAGE }} Python distributions to GitHub Release" in content
-    assert (
-        'gh release upload "$TAG" release-assets/*.whl release-assets/*.tar.gz --clobber' in content
-    )
-    assert "Publish Node package tarballs to GitHub Release" in content
-    assert 'gh release upload "$TAG" release-assets/*.tgz --clobber' in content
-
-
-def test_create_release_runs_after_successful_build_even_if_other_publishes_fail() -> None:
-    content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")
-
-    assert (
-        "needs: [detect-version, build, publish-pypi, publish-npm, publish-github-packages, publish-docker]"
-        in content
-    )
-    assert "always()" in content
-    assert "needs.build.result == 'success'" in content
-
-
-def test_macos_native_wrapper_dependency_install_retries_pypi_downloads() -> None:
-    content = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
-
-    assert "python -m pip install --retries 10 --timeout 60 pytest" in content
-
-
-def test_ci_commitlint_skips_default_github_merge_commits() -> None:
-    content = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
-
-    assert "github.event_name != 'push'" in content
-    assert "!startsWith(github.event.head_commit.message, 'Merge pull request ')" in content
+"""Workflow regression tests for release publishing behavior."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def test_docker_workflow_normalizes_repository_name_for_signing() -> None:
+    content = (ROOT / ".github" / "workflows" / "docker.yml").read_text(encoding="utf-8")
+
+    assert "id: image-name" in content
+    assert "tr '[:upper:]' '[:lower:]'" in content
+    assert "steps.image-name.outputs.image_name" in content
+
+
+def test_release_workflow_publishes_both_node_packages_to_github_packages() -> None:
+    content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")
+
+    assert "Publish ${{ env.NPM_SDK_PACKAGE }} to GitHub Package Registry" in content
+    assert "Publish ${{ env.NPM_OPENCLAW_PACKAGE }} to GitHub Package Registry" in content
+    assert "pkg.name = `@${process.env.GITHUB_PACKAGES_SCOPE}/${pkg.name}`;" in content
+    assert (
+        'unscoped_sdk_tarball="$(npm pack --pack-destination "$assets_dir" | tail -n 1)"' in content
+    )
+    assert "SDK_TARBALL: ${{ steps.gpr-sdk-publish.outputs.unscoped_sdk_tarball }}" in content
+
+
+def test_release_workflow_publishes_python_distributions_to_github_release() -> None:
+    content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")
+
+    assert "Publish ${{ env.PYPI_PACKAGE }} Python distributions to GitHub Release" in content
+    assert (
+        'gh release upload "$TAG" release-assets/*.whl release-assets/*.tar.gz --clobber' in content
+    )
+    assert "Publish Node package tarballs to GitHub Release" in content
+    assert 'gh release upload "$TAG" release-assets/*.tgz --clobber' in content
+
+
+def test_create_release_runs_after_successful_build_even_if_other_publishes_fail() -> None:
+    content = (ROOT / ".github" / "workflows" / "release.yml").read_text(encoding="utf-8")
+
+    assert (
+        "needs: [detect-version, build, publish-pypi, publish-npm, publish-github-packages, publish-docker]"
+        in content
+    )
+    assert "always()" in content
+    assert "needs.build.result == 'success'" in content
+
+
+def test_macos_native_wrapper_dependency_install_retries_pypi_downloads() -> None:
+    content = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+
+    assert "python -m pip install --retries 10 --timeout 60 pytest" in content
+
+
+def test_ci_commitlint_skips_default_github_merge_commits() -> None:
+    content = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+
+    assert "github.event_name != 'push'" in content
+    assert "!startsWith(github.event.head_commit.message, 'Merge pull request ')" in content
diff --git a/tests/test_reporting.py b/tests/test_reporting.py
index 8a9f150c2202a8191b747def9f2eac42117c3654..407bfd67c1ce5c9bb559f3a47a0d84a8503d9f8f 100644
--- a/tests/test_reporting.py
+++ b/tests/test_reporting.py
@@ -1,305 +1,305 @@
-from __future__ import annotations
-
-import builtins
-import sys
-from dataclasses import dataclass
-from datetime import datetime, timedelta
-from types import SimpleNamespace
-
-import pytest
-
-import headroom.reporting as reporting
-from headroom.reporting import generator
-
-
-@dataclass
-class FakeMetrics:
-    request_id: str
-    model: str
-    mode: str
-    timestamp: datetime
-    tokens_input_before: int
-    tokens_input_after: int
-    cache_alignment_score: float
-    waste_signals: dict[str, int]
-
-
-class FakeStorage:
-    def __init__(self, stats: dict, items: list[FakeMetrics]) -> None:
-        self._stats = stats
-        self._items = items
-        self.closed = False
-
-    def get_summary_stats(self, start_time, end_time):
-        return dict(self._stats)
-
-    def iter_all(self):
-        return iter(self._items)
-
-    def close(self) -> None:
-        self.closed = True
-
-
-def test_reporting_public_export() -> None:
-    assert reporting.generate_report is generator.generate_report
-    assert reporting.__all__ == ["generate_report"]
-
-
-def test_get_jinja2_template_success_with_stub(monkeypatch) -> None:
-    class FakeTemplate:
-        def __init__(self, template_str: str) -> None:
-            self.template_str = template_str
-
-        def render(self, **kwargs) -> str:
-            return f"{self.template_str}:{kwargs['name']}"
-
-    monkeypatch.setitem(sys.modules, "jinja2", SimpleNamespace(Template=FakeTemplate))
-    template = generator._get_jinja2_template("hello")
-    assert template.render(name="world") == "hello:world"
-
-
-def test_get_jinja2_template_raises_helpful_error(monkeypatch) -> None:
-    real_import = builtins.__import__
-
-    def fake_import(name, globals=None, locals=None, fromlist=(), level=0):
-        if name == "jinja2":
-            raise ImportError("missing")
-        return real_import(name, globals, locals, fromlist, level)
-
-    monkeypatch.setattr(builtins, "__import__", fake_import)
-    with pytest.raises(ImportError, match="jinja2 is required for report generation"):
-        generator._get_jinja2_template("ignored")
-
-
-def test_build_waste_histogram_empty_and_filtered_data() -> None:
-    now = datetime(2026, 4, 23, 12, 0, 0)
-    metrics = [
-        FakeMetrics(
-            request_id="before",
-            model="gpt-4o",
-            mode="audit",
-            timestamp=now - timedelta(days=2),
-            tokens_input_before=100,
-            tokens_input_after=90,
-            cache_alignment_score=10,
-            waste_signals={"json_bloat": 5},
-        ),
-        FakeMetrics(
-            request_id="inside",
-            model="gpt-4o",
-            mode="optimize",
-            timestamp=now,
-            tokens_input_before=200,
-            tokens_input_after=100,
-            cache_alignment_score=70,
-            waste_signals={"json_bloat": 30, "html_noise": 10, "dynamic_date": 5},
-        ),
-        FakeMetrics(
-            request_id="flat",
-            model="gpt-4o",
-            mode="audit",
-            timestamp=now,
-            tokens_input_before=50,
-            tokens_input_after=50,
-            cache_alignment_score=50,
-            waste_signals={"whitespace": 4},
-        ),
-        FakeMetrics(
-            request_id="after",
-            model="gpt-4o",
-            mode="audit",
-            timestamp=now + timedelta(days=2),
-            tokens_input_before=100,
-            tokens_input_after=20,
-            cache_alignment_score=20,
-            waste_signals={"base64": 50},
-        ),
-    ]
-    histogram = generator._build_waste_histogram(
-        FakeStorage({}, metrics),
-        start_time=now - timedelta(hours=1),
-        end_time=now + timedelta(hours=1),
-    )
-
-    assert histogram[0] == {"label": "History Bloat", "tokens": 55, "percentage": 100.0}
-    assert histogram[1] == pytest.approx(
-        {"label": "Tool JSON Bloat", "tokens": 30, "percentage": 54.54545454545454}
-    )
-    assert any(item["label"] == "HTML Noise" and item["tokens"] == 10 for item in histogram)
-    assert any(item["label"] == "Dynamic Dates" and item["tokens"] == 5 for item in histogram)
-    assert any(item["label"] == "Base64 Blobs" and item["tokens"] == 0 for item in histogram)
-
-    empty = generator._build_waste_histogram(FakeStorage({}, []), None, None)
-    assert all(item["tokens"] == 0 and item["percentage"] == 0 for item in empty)
-
-
-def test_get_top_waste_requests_sorts_filters_and_limits() -> None:
-    now = datetime(2026, 4, 23, 12, 0, 0)
-    metrics = [
-        FakeMetrics("one", "gpt-4o", "audit", now, 400, 100, 80, {}),
-        FakeMetrics("two", "gpt-4o-mini", "optimize", now, 350, 330, 70, {}),
-        FakeMetrics("three", "claude", "audit", now - timedelta(days=3), 1000, 10, 50, {}),
-        FakeMetrics("four", "claude", "audit", now + timedelta(days=3), 1000, 200, 40, {}),
-    ]
-    top_requests = generator._get_top_waste_requests(
-        FakeStorage({}, metrics),
-        start_time=now - timedelta(hours=1),
-        end_time=now + timedelta(hours=1),
-        limit=1,
-    )
-    assert top_requests == [
-        {
-            "request_id": "one",
-            "model": "gpt-4o",
-            "mode": "audit",
-            "tokens_before": 400,
-            "tokens_saved": 300,
-            "cache_alignment": 80,
-        }
-    ]
-
-
-def test_generate_recommendations_for_heavy_waste_and_for_getting_started() -> None:
-    stats = {
-        "avg_cache_alignment": 40,
-        "audit_count": 7,
-        "optimize_count": 3,
-        "total_tokens_saved": 120000,
-        "estimated_savings": "$1.23",
-    }
-    histogram = [
-        {"label": "Tool JSON Bloat", "tokens": 15000, "percentage": 100},
-        {"label": "History Bloat", "tokens": 60000, "percentage": 50},
-    ]
-    recommendations = generator._generate_recommendations(stats, histogram, top_requests=[{}])
-    titles = [item["title"] for item in recommendations]
-    assert titles == [
-        "Improve Cache Alignment",
-        "Enable Tool Output Compression",
-        "Review Rolling Window Settings",
-        "Switch to Optimize Mode",
-        "Continue Monitoring",
-    ]
-    assert "15,000" in recommendations[1]["description"]
-    assert "60,000" in recommendations[2]["description"]
-
-    starter = generator._generate_recommendations(
-        {
-            "avg_cache_alignment": 90,
-            "audit_count": 1,
-            "optimize_count": 1,
-            "total_tokens_saved": 0,
-            "estimated_savings": "$0.00",
-        },
-        [{"label": "Tool JSON Bloat", "tokens": 1, "percentage": 100}],
-        top_requests=[],
-    )
-    assert starter == [
-        {
-            "title": "Get Started",
-            "description": "No optimizations applied yet. Try setting headroom_mode='optimize' "
-            "on your next request to start seeing token savings.",
-        }
-    ]
-
-
-@pytest.mark.parametrize(
-    ("start_time", "end_time", "expected_period"),
-    [
-        (
-            datetime(2026, 4, 20, 8, 0, 0),
-            datetime(2026, 4, 23, 18, 0, 0),
-            "2026-04-20 to 2026-04-23",
-        ),
-        (datetime(2026, 4, 20, 8, 0, 0), None, "Since 2026-04-20"),
-        (None, datetime(2026, 4, 23, 18, 0, 0), "Until 2026-04-23"),
-        (None, None, "All time"),
-    ],
-)
-def test_generate_report_writes_output_and_closes_storage(
-    monkeypatch, tmp_path, start_time, end_time, expected_period
-) -> None:
-    storage = FakeStorage(
-        {
-            "total_requests": 3,
-            "total_tokens_saved": 50,
-            "avg_tokens_saved": 16.6,
-            "total_tokens_before": 100,
-            "total_tokens_after": 0,
-            "avg_cache_alignment": 82,
-            "audit_count": 1,
-            "optimize_count": 2,
-        },
-        [],
-    )
-    render_calls: list[dict] = []
-
-    class FakeTemplate:
-        def render(self, **kwargs) -> str:
-            render_calls.append(kwargs)
-            return "<html>report</html>"
-
-    monkeypatch.setattr(generator, "create_storage", lambda store_url: storage)
-    monkeypatch.setattr(
-        generator, "_build_waste_histogram", lambda *args: [{"label": "x", "tokens": 1}]
-    )
-    monkeypatch.setattr(
-        generator, "_get_top_waste_requests", lambda *args, **kwargs: [{"request_id": "abc"}]
-    )
-    monkeypatch.setattr(
-        generator, "_generate_recommendations", lambda *args: [{"title": "Keep going"}]
-    )
-    monkeypatch.setattr(generator, "_get_jinja2_template", lambda template_str: FakeTemplate())
-    monkeypatch.setattr(
-        generator,
-        "estimate_cost",
-        lambda tokens, output_tokens, model: {100: 2.0, 0: None}[tokens],
-    )
-    monkeypatch.setattr(generator, "format_cost", lambda cost: f"${cost:.2f}")
-
-    output_path = tmp_path / "report.html"
-    result = generator.generate_report(
-        "sqlite:///demo.db",
-        output_path=str(output_path),
-        start_time=start_time,
-        end_time=end_time,
-    )
-
-    assert result == str(output_path)
-    assert output_path.read_text() == "<html>report</html>"
-    assert render_calls[0]["period"] == expected_period
-    assert render_calls[0]["stats"]["tpm_multiplier"] == 100.0
-    assert render_calls[0]["stats"]["estimated_savings"] == "$2.00"
-    assert storage.closed is True
-
-
-def test_generate_report_closes_storage_when_render_fails(monkeypatch, tmp_path) -> None:
-    storage = FakeStorage(
-        {
-            "total_requests": 0,
-            "total_tokens_saved": 0,
-            "avg_tokens_saved": 0,
-            "total_tokens_before": 0,
-            "total_tokens_after": 0,
-            "avg_cache_alignment": 0,
-            "audit_count": 0,
-            "optimize_count": 0,
-        },
-        [],
-    )
-
-    class FakeTemplate:
-        def render(self, **kwargs) -> str:
-            raise RuntimeError("boom")
-
-    monkeypatch.setattr(generator, "create_storage", lambda store_url: storage)
-    monkeypatch.setattr(generator, "_build_waste_histogram", lambda *args: [])
-    monkeypatch.setattr(generator, "_get_top_waste_requests", lambda *args, **kwargs: [])
-    monkeypatch.setattr(generator, "_generate_recommendations", lambda *args: [])
-    monkeypatch.setattr(generator, "_get_jinja2_template", lambda template_str: FakeTemplate())
-    monkeypatch.setattr(generator, "estimate_cost", lambda *args: 0.0)
-    monkeypatch.setattr(generator, "format_cost", lambda cost: "$0.00")
-
-    with pytest.raises(RuntimeError, match="boom"):
-        generator.generate_report("sqlite:///demo.db", output_path=str(tmp_path / "report.html"))
-    assert storage.closed is True
+from __future__ import annotations
+
+import builtins
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from types import SimpleNamespace
+
+import pytest
+
+import headroom.reporting as reporting
+from headroom.reporting import generator
+
+
+@dataclass
+class FakeMetrics:
+    request_id: str
+    model: str
+    mode: str
+    timestamp: datetime
+    tokens_input_before: int
+    tokens_input_after: int
+    cache_alignment_score: float
+    waste_signals: dict[str, int]
+
+
+class FakeStorage:
+    def __init__(self, stats: dict, items: list[FakeMetrics]) -> None:
+        self._stats = stats
+        self._items = items
+        self.closed = False
+
+    def get_summary_stats(self, start_time, end_time):
+        return dict(self._stats)
+
+    def iter_all(self):
+        return iter(self._items)
+
+    def close(self) -> None:
+        self.closed = True
+
+
+def test_reporting_public_export() -> None:
+    assert reporting.generate_report is generator.generate_report
+    assert reporting.__all__ == ["generate_report"]
+
+
+def test_get_jinja2_template_success_with_stub(monkeypatch) -> None:
+    class FakeTemplate:
+        def __init__(self, template_str: str) -> None:
+            self.template_str = template_str
+
+        def render(self, **kwargs) -> str:
+            return f"{self.template_str}:{kwargs['name']}"
+
+    monkeypatch.setitem(sys.modules, "jinja2", SimpleNamespace(Template=FakeTemplate))
+    template = generator._get_jinja2_template("hello")
+    assert template.render(name="world") == "hello:world"
+
+
+def test_get_jinja2_template_raises_helpful_error(monkeypatch) -> None:
+    real_import = builtins.__import__
+
+    def fake_import(name, globals=None, locals=None, fromlist=(), level=0):
+        if name == "jinja2":
+            raise ImportError("missing")
+        return real_import(name, globals, locals, fromlist, level)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+    with pytest.raises(ImportError, match="jinja2 is required for report generation"):
+        generator._get_jinja2_template("ignored")
+
+
+def test_build_waste_histogram_empty_and_filtered_data() -> None:
+    now = datetime(2026, 4, 23, 12, 0, 0)
+    metrics = [
+        FakeMetrics(
+            request_id="before",
+            model="gpt-4o",
+            mode="audit",
+            timestamp=now - timedelta(days=2),
+            tokens_input_before=100,
+            tokens_input_after=90,
+            cache_alignment_score=10,
+            waste_signals={"json_bloat": 5},
+        ),
+        FakeMetrics(
+            request_id="inside",
+            model="gpt-4o",
+            mode="optimize",
+            timestamp=now,
+            tokens_input_before=200,
+            tokens_input_after=100,
+            cache_alignment_score=70,
+            waste_signals={"json_bloat": 30, "html_noise": 10, "dynamic_date": 5},
+        ),
+        FakeMetrics(
+            request_id="flat",
+            model="gpt-4o",
+            mode="audit",
+            timestamp=now,
+            tokens_input_before=50,
+            tokens_input_after=50,
+            cache_alignment_score=50,
+            waste_signals={"whitespace": 4},
+        ),
+        FakeMetrics(
+            request_id="after",
+            model="gpt-4o",
+            mode="audit",
+            timestamp=now + timedelta(days=2),
+            tokens_input_before=100,
+            tokens_input_after=20,
+            cache_alignment_score=20,
+            waste_signals={"base64": 50},
+        ),
+    ]
+    histogram = generator._build_waste_histogram(
+        FakeStorage({}, metrics),
+        start_time=now - timedelta(hours=1),
+        end_time=now + timedelta(hours=1),
+    )
+
+    assert histogram[0] == {"label": "History Bloat", "tokens": 55, "percentage": 100.0}
+    assert histogram[1] == pytest.approx(
+        {"label": "Tool JSON Bloat", "tokens": 30, "percentage": 54.54545454545454}
+    )
+    assert any(item["label"] == "HTML Noise" and item["tokens"] == 10 for item in histogram)
+    assert any(item["label"] == "Dynamic Dates" and item["tokens"] == 5 for item in histogram)
+    assert any(item["label"] == "Base64 Blobs" and item["tokens"] == 0 for item in histogram)
+
+    empty = generator._build_waste_histogram(FakeStorage({}, []), None, None)
+    assert all(item["tokens"] == 0 and item["percentage"] == 0 for item in empty)
+
+
+def test_get_top_waste_requests_sorts_filters_and_limits() -> None:
+    now = datetime(2026, 4, 23, 12, 0, 0)
+    metrics = [
+        FakeMetrics("one", "gpt-4o", "audit", now, 400, 100, 80, {}),
+        FakeMetrics("two", "gpt-4o-mini", "optimize", now, 350, 330, 70, {}),
+        FakeMetrics("three", "claude", "audit", now - timedelta(days=3), 1000, 10, 50, {}),
+        FakeMetrics("four", "claude", "audit", now + timedelta(days=3), 1000, 200, 40, {}),
+    ]
+    top_requests = generator._get_top_waste_requests(
+        FakeStorage({}, metrics),
+        start_time=now - timedelta(hours=1),
+        end_time=now + timedelta(hours=1),
+        limit=1,
+    )
+    assert top_requests == [
+        {
+            "request_id": "one",
+            "model": "gpt-4o",
+            "mode": "audit",
+            "tokens_before": 400,
+            "tokens_saved": 300,
+            "cache_alignment": 80,
+        }
+    ]
+
+
+def test_generate_recommendations_for_heavy_waste_and_for_getting_started() -> None:
+    stats = {
+        "avg_cache_alignment": 40,
+        "audit_count": 7,
+        "optimize_count": 3,
+        "total_tokens_saved": 120000,
+        "estimated_savings": "$1.23",
+    }
+    histogram = [
+        {"label": "Tool JSON Bloat", "tokens": 15000, "percentage": 100},
+        {"label": "History Bloat", "tokens": 60000, "percentage": 50},
+    ]
+    recommendations = generator._generate_recommendations(stats, histogram, top_requests=[{}])
+    titles = [item["title"] for item in recommendations]
+    assert titles == [
+        "Improve Cache Alignment",
+        "Enable Tool Output Compression",
+        "Review Rolling Window Settings",
+        "Switch to Optimize Mode",
+        "Continue Monitoring",
+    ]
+    assert "15,000" in recommendations[1]["description"]
+    assert "60,000" in recommendations[2]["description"]
+
+    starter = generator._generate_recommendations(
+        {
+            "avg_cache_alignment": 90,
+            "audit_count": 1,
+            "optimize_count": 1,
+            "total_tokens_saved": 0,
+            "estimated_savings": "$0.00",
+        },
+        [{"label": "Tool JSON Bloat", "tokens": 1, "percentage": 100}],
+        top_requests=[],
+    )
+    assert starter == [
+        {
+            "title": "Get Started",
+            "description": "No optimizations applied yet. Try setting headroom_mode='optimize' "
+            "on your next request to start seeing token savings.",
+        }
+    ]
+
+
+@pytest.mark.parametrize(
+    ("start_time", "end_time", "expected_period"),
+    [
+        (
+            datetime(2026, 4, 20, 8, 0, 0),
+            datetime(2026, 4, 23, 18, 0, 0),
+            "2026-04-20 to 2026-04-23",
+        ),
+        (datetime(2026, 4, 20, 8, 0, 0), None, "Since 2026-04-20"),
+        (None, datetime(2026, 4, 23, 18, 0, 0), "Until 2026-04-23"),
+        (None, None, "All time"),
+    ],
+)
+def test_generate_report_writes_output_and_closes_storage(
+    monkeypatch, tmp_path, start_time, end_time, expected_period
+) -> None:
+    storage = FakeStorage(
+        {
+            "total_requests": 3,
+            "total_tokens_saved": 50,
+            "avg_tokens_saved": 16.6,
+            "total_tokens_before": 100,
+            "total_tokens_after": 0,
+            "avg_cache_alignment": 82,
+            "audit_count": 1,
+            "optimize_count": 2,
+        },
+        [],
+    )
+    render_calls: list[dict] = []
+
+    class FakeTemplate:
+        def render(self, **kwargs) -> str:
+            render_calls.append(kwargs)
+            return "<html>report</html>"
+
+    monkeypatch.setattr(generator, "create_storage", lambda store_url: storage)
+    monkeypatch.setattr(
+        generator, "_build_waste_histogram", lambda *args: [{"label": "x", "tokens": 1}]
+    )
+    monkeypatch.setattr(
+        generator, "_get_top_waste_requests", lambda *args, **kwargs: [{"request_id": "abc"}]
+    )
+    monkeypatch.setattr(
+        generator, "_generate_recommendations", lambda *args: [{"title": "Keep going"}]
+    )
+    monkeypatch.setattr(generator, "_get_jinja2_template", lambda template_str: FakeTemplate())
+    monkeypatch.setattr(
+        generator,
+        "estimate_cost",
+        lambda tokens, output_tokens, model: {100: 2.0, 0: None}[tokens],
+    )
+    monkeypatch.setattr(generator, "format_cost", lambda cost: f"${cost:.2f}")
+
+    output_path = tmp_path / "report.html"
+    result = generator.generate_report(
+        "sqlite:///demo.db",
+        output_path=str(output_path),
+        start_time=start_time,
+        end_time=end_time,
+    )
+
+    assert result == str(output_path)
+    assert output_path.read_text() == "<html>report</html>"
+    assert render_calls[0]["period"] == expected_period
+    assert render_calls[0]["stats"]["tpm_multiplier"] == 100.0
+    assert render_calls[0]["stats"]["estimated_savings"] == "$2.00"
+    assert storage.closed is True
+
+
+def test_generate_report_closes_storage_when_render_fails(monkeypatch, tmp_path) -> None:
+    storage = FakeStorage(
+        {
+            "total_requests": 0,
+            "total_tokens_saved": 0,
+            "avg_tokens_saved": 0,
+            "total_tokens_before": 0,
+            "total_tokens_after": 0,
+            "avg_cache_alignment": 0,
+            "audit_count": 0,
+            "optimize_count": 0,
+        },
+        [],
+    )
+
+    class FakeTemplate:
+        def render(self, **kwargs) -> str:
+            raise RuntimeError("boom")
+
+    monkeypatch.setattr(generator, "create_storage", lambda store_url: storage)
+    monkeypatch.setattr(generator, "_build_waste_histogram", lambda *args: [])
+    monkeypatch.setattr(generator, "_get_top_waste_requests", lambda *args, **kwargs: [])
+    monkeypatch.setattr(generator, "_generate_recommendations", lambda *args: [])
+    monkeypatch.setattr(generator, "_get_jinja2_template", lambda template_str: FakeTemplate())
+    monkeypatch.setattr(generator, "estimate_cost", lambda *args: 0.0)
+    monkeypatch.setattr(generator, "format_cost", lambda cost: "$0.00")
+
+    with pytest.raises(RuntimeError, match="boom"):
+        generator.generate_report("sqlite:///demo.db", output_path=str(tmp_path / "report.html"))
+    assert storage.closed is True
diff --git a/tests/test_subscription_base.py b/tests/test_subscription_base.py
index ae73952af4621904ce95de6a5955bbeba8e59510..6f233a6e697be1e3d41235eb26a4e5a86ac8bc9c 100644
--- a/tests/test_subscription_base.py
+++ b/tests/test_subscription_base.py
@@ -1,140 +1,140 @@
-from __future__ import annotations
-
-import pytest
-
-import headroom.subscription.base as base_module
-from headroom.subscription.base import (
-    QuotaTracker,
-    QuotaTrackerRegistry,
-    get_quota_registry,
-    reset_quota_registry,
-)
-
-
-class DummyTracker(QuotaTracker):
-    def __init__(
-        self,
-        key: str,
-        *,
-        label: str = "Dummy",
-        available: bool = True,
-        stats: dict | None = None,
-        stop_error: Exception | None = None,
-    ) -> None:
-        self._key = key
-        self._label = label
-        self._available = available
-        self._stats = stats
-        self._stop_error = stop_error
-        self.started = 0
-        self.stopped = 0
-
-    @property
-    def key(self) -> str:
-        return self._key
-
-    @property
-    def label(self) -> str:
-        return self._label
-
-    def is_available(self) -> bool:
-        return self._available
-
-    async def start(self) -> None:
-        self.started += 1
-
-    async def stop(self) -> None:
-        self.stopped += 1
-        if self._stop_error:
-            raise self._stop_error
-
-    def get_stats(self) -> dict | None:
-        return self._stats
-
-
-class PassiveTracker(QuotaTracker):
-    @property
-    def key(self) -> str:
-        return "passive"
-
-    @property
-    def label(self) -> str:
-        return "Passive"
-
-    def get_stats(self) -> dict | None:
-        return {"passive": True}
-
-
-def test_register_get_trackers_and_duplicate_keys() -> None:
-    registry = QuotaTrackerRegistry()
-    tracker = DummyTracker("alpha", stats={"ok": True})
-    registry.register(tracker)
-
-    assert registry.get("alpha") is tracker
-    assert registry.get("missing") is None
-    assert registry.trackers == [tracker]
-    assert registry.get_stats("alpha") == {"ok": True}
-    assert registry.get_stats("missing") is None
-
-    snapshot = registry.trackers
-    snapshot.clear()
-    assert registry.trackers == [tracker]
-
-    with pytest.raises(ValueError, match="already registered"):
-        registry.register(DummyTracker("alpha"))
-
-
-@pytest.mark.asyncio
-async def test_start_all_stop_all_and_stats_filtering() -> None:
-    registry = QuotaTrackerRegistry()
-    enabled = DummyTracker("enabled", label="Enabled", stats={"value": 1})
-    disabled = DummyTracker("disabled", label="Disabled", available=False, stats={"skip": True})
-    empty = DummyTracker("empty", label="Empty", stats=None)
-    broken = DummyTracker(
-        "broken", label="Broken", stats={"value": 2}, stop_error=RuntimeError("boom")
-    )
-
-    for tracker in (enabled, disabled, empty, broken):
-        registry.register(tracker)
-
-    await registry.start_all()
-    assert enabled.started == 1
-    assert disabled.started == 0
-    assert empty.started == 1
-    assert broken.started == 1
-
-    assert registry.get_all_stats() == {
-        "enabled": {"value": 1},
-        "broken": {"value": 2},
-    }
-
-    await registry.stop_all()
-    assert enabled.stopped == 1
-    assert disabled.stopped == 1
-    assert empty.stopped == 1
-    assert broken.stopped == 1
-
-
-def test_quota_registry_singleton_reset() -> None:
-    reset_quota_registry()
-    base_module._registry = None
-    first = get_quota_registry()
-    second = get_quota_registry()
-    assert first is second
-
-    first.register(DummyTracker("singleton"))
-    assert get_quota_registry().get("singleton") is not None
-
-    reset_quota_registry()
-    refreshed = get_quota_registry()
-    assert refreshed is not first
-    assert refreshed.trackers == []
-
-
-@pytest.mark.asyncio
-async def test_quota_tracker_default_methods() -> None:
-    tracker = PassiveTracker()
-    assert tracker.is_available() is True
-    await tracker.start()
-    await tracker.stop()
-    assert tracker.get_stats() == {"passive": True}
+from __future__ import annotations
+
+import pytest
+
+import headroom.subscription.base as base_module
+from headroom.subscription.base import (
+    QuotaTracker,
+    QuotaTrackerRegistry,
+    get_quota_registry,
+    reset_quota_registry,
+)
+
+
+class DummyTracker(QuotaTracker):
+    def __init__(
+        self,
+        key: str,
+        *,
+        label: str = "Dummy",
+        available: bool = True,
+        stats: dict | None = None,
+        stop_error: Exception | None = None,
+    ) -> None:
+        self._key = key
+        self._label = label
+        self._available = available
+        self._stats = stats
+        self._stop_error = stop_error
+        self.started = 0
+        self.stopped = 0
+
+    @property
+    def key(self) -> str:
+        return self._key
+
+    @property
+    def label(self) -> str:
+        return self._label
+
+    def is_available(self) -> bool:
+        return self._available
+
+    async def start(self) -> None:
+        self.started += 1
+
+    async def stop(self) -> None:
+        self.stopped += 1
+        if self._stop_error:
+            raise self._stop_error
+
+    def get_stats(self) -> dict | None:
+        return self._stats
+
+
+class PassiveTracker(QuotaTracker):
+    @property
+    def key(self) -> str:
+        return "passive"
+
+    @property
+    def label(self) -> str:
+        return "Passive"
+
+    def get_stats(self) -> dict | None:
+        return {"passive": True}
+
+
+def test_register_get_trackers_and_duplicate_keys() -> None:
+    registry = QuotaTrackerRegistry()
+    tracker = DummyTracker("alpha", stats={"ok": True})
+    registry.register(tracker)
+
+    assert registry.get("alpha") is tracker
+    assert registry.get("missing") is None
+    assert registry.trackers == [tracker]
+    assert registry.get_stats("alpha") == {"ok": True}
+    assert registry.get_stats("missing") is None
+
+    snapshot = registry.trackers
+    snapshot.clear()
+    assert registry.trackers == [tracker]
+
+    with pytest.raises(ValueError, match="already registered"):
+        registry.register(DummyTracker("alpha"))
+
+
+@pytest.mark.asyncio
+async def test_start_all_stop_all_and_stats_filtering() -> None:
+    registry = QuotaTrackerRegistry()
+    enabled = DummyTracker("enabled", label="Enabled", stats={"value": 1})
+    disabled = DummyTracker("disabled", label="Disabled", available=False, stats={"skip": True})
+    empty = DummyTracker("empty", label="Empty", stats=None)
+    broken = DummyTracker(
+        "broken", label="Broken", stats={"value": 2}, stop_error=RuntimeError("boom")
+    )
+
+    for tracker in (enabled, disabled, empty, broken):
+        registry.register(tracker)
+
+    await registry.start_all()
+    assert enabled.started == 1
+    assert disabled.started == 0
+    assert empty.started == 1
+    assert broken.started == 1
+
+    assert registry.get_all_stats() == {
+        "enabled": {"value": 1},
+        "broken": {"value": 2},
+    }
+
+    await registry.stop_all()
+    assert enabled.stopped == 1
+    assert disabled.stopped == 1
+    assert empty.stopped == 1
+    assert broken.stopped == 1
+
+
+def test_quota_registry_singleton_reset() -> None:
+    reset_quota_registry()
+    base_module._registry = None
+    first = get_quota_registry()
+    second = get_quota_registry()
+    assert first is second
+
+    first.register(DummyTracker("singleton"))
+    assert get_quota_registry().get("singleton") is not None
+
+    reset_quota_registry()
+    refreshed = get_quota_registry()
+    assert refreshed is not first
+    assert refreshed.trackers == []
+
+
+@pytest.mark.asyncio
+async def test_quota_tracker_default_methods() -> None:
+    tracker = PassiveTracker()
+    assert tracker.is_available() is True
+    await tracker.start()
+    await tracker.stop()
+    assert tracker.get_stats() == {"passive": True}
diff --git a/tests/test_subscription_client.py b/tests/test_subscription_client.py
index f8056d719fc6839d9d0fe06f63fdcaa04893a0c7..65d9a87565bf194b9fdddda0a389fcc01eacef4a 100644
--- a/tests/test_subscription_client.py
+++ b/tests/test_subscription_client.py
@@ -1,179 +1,179 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-import httpx
-import pytest
-
-from headroom.subscription.client import (
-    _BETA_HEADER,
-    _USAGE_URL,
-    SubscriptionClient,
-    _credentials_path,
-    _load_credentials_file,
-    read_cached_oauth_token,
-)
-
-
-class DummyResponse:
-    def __init__(self, status_code: int, data: dict | None = None) -> None:
-        self.status_code = status_code
-        self._data = data or {}
-
-    def json(self) -> dict:
-        return self._data
-
-
-class AsyncClientStub:
-    def __init__(
-        self,
-        *,
-        response=None,
-        error: Exception | None = None,
-        record: dict | None = None,
-        timeout=None,
-    ):
-        self._response = response
-        self._error = error
-        self._record = record if record is not None else {}
-        self._record["timeout"] = timeout
-
-    async def __aenter__(self):
-        return self
-
-    async def __aexit__(self, exc_type, exc, tb):
-        return False
-
-    async def get(self, url: str, headers: dict[str, str]):
-        self._record["url"] = url
-        self._record["headers"] = headers
-        if self._error:
-            raise self._error
-        return self._response
-
-
-def test_credentials_path_uses_env_override(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-) -> None:
-    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))
-    assert _credentials_path() == tmp_path / ".credentials.json"
-
-
-def test_load_credentials_file_handles_missing_invalid_and_valid(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-) -> None:
-    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))
-    assert _load_credentials_file() is None
-
-    creds_path = tmp_path / ".credentials.json"
-    creds_path.write_text("{invalid", encoding="utf-8")
-    assert _load_credentials_file() is None
-
-    payload = {"claudeAiOauth": {"accessToken": "token-from-file"}}
-    creds_path.write_text(json.dumps(payload), encoding="utf-8")
-    assert _load_credentials_file() == payload
-
-
-def test_read_cached_oauth_token_prefers_env_and_checks_expiry(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.setenv("CLAUDE_CODE_OAUTH_TOKEN", " env-token ")
-    monkeypatch.setattr("headroom.subscription.client._load_credentials_file", lambda: None)
-    assert read_cached_oauth_token() == "env-token"
-
-    monkeypatch.delenv("CLAUDE_CODE_OAUTH_TOKEN", raising=False)
-    monkeypatch.setattr(
-        "headroom.subscription.client._load_credentials_file",
-        lambda: {"claudeAiOauth": {"accessToken": "cached-token"}},
-    )
-    assert read_cached_oauth_token() == "cached-token"
-
-    monkeypatch.setattr(
-        "headroom.subscription.client._load_credentials_file",
-        lambda: {
-            "claudeAiOauth": {
-                "accessToken": "expired-token",
-                "expiresAt": 59_000,
-            }
-        },
-    )
-    monkeypatch.setattr("time.time", lambda: 60)
-    assert read_cached_oauth_token() is None
-
-    monkeypatch.setattr(
-        "headroom.subscription.client._load_credentials_file",
-        lambda: {"claudeAiOauth": {"accessToken": ""}},
-    )
-    assert read_cached_oauth_token() is None
-
-    monkeypatch.setattr(
-        "headroom.subscription.client._load_credentials_file",
-        lambda: None,
-    )
-    assert read_cached_oauth_token() is None
-
-
-@pytest.mark.asyncio
-async def test_subscription_client_fetch_handles_success_and_status_codes(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    record: dict = {}
-    monkeypatch.setattr(
-        "headroom.subscription.client.httpx.AsyncClient",
-        lambda timeout: AsyncClientStub(
-            response=DummyResponse(200, {"five_hour": {"total": 1}}),
-            record=record,
-            timeout=timeout,
-        ),
-    )
-    monkeypatch.setattr(
-        "headroom.subscription.client.SubscriptionSnapshot.from_api_response",
-        lambda data, token="": {"data": data, "token": token},
-    )
-
-    client = SubscriptionClient(timeout=3.5)
-    result = await client.fetch("  explicit-token  ")
-    assert result == {"data": {"five_hour": {"total": 1}}, "token": "explicit-token"}
-    assert record["timeout"] == 3.5
-    assert record["url"] == _USAGE_URL
-    assert record["headers"] == {
-        "Authorization": "Bearer explicit-token",
-        "anthropic-beta": _BETA_HEADER,
-        "Content-Type": "application/json",
-    }
-
-    for status_code in (401, 404, 500):
-        monkeypatch.setattr(
-            "headroom.subscription.client.httpx.AsyncClient",
-            lambda timeout, status_code=status_code: AsyncClientStub(
-                response=DummyResponse(status_code), timeout=timeout
-            ),
-        )
-        assert await client.fetch("explicit-token") is None
-
-
-@pytest.mark.asyncio
-async def test_subscription_client_fetch_uses_cached_token_and_handles_exceptions(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    client = SubscriptionClient()
-
-    monkeypatch.setattr("headroom.subscription.client.read_cached_oauth_token", lambda: None)
-    assert await client.fetch() is None
-
-    monkeypatch.setattr(
-        "headroom.subscription.client.read_cached_oauth_token",
-        lambda: "cached-token",
-    )
-    monkeypatch.setattr(
-        "headroom.subscription.client.httpx.AsyncClient",
-        lambda timeout: AsyncClientStub(error=httpx.TimeoutException("slow"), timeout=timeout),
-    )
-    assert await client.fetch() is None
-
-    monkeypatch.setattr(
-        "headroom.subscription.client.httpx.AsyncClient",
-        lambda timeout: AsyncClientStub(error=RuntimeError("boom"), timeout=timeout),
-    )
-    assert await client.fetch() is None
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import httpx
+import pytest
+
+from headroom.subscription.client import (
+    _BETA_HEADER,
+    _USAGE_URL,
+    SubscriptionClient,
+    _credentials_path,
+    _load_credentials_file,
+    read_cached_oauth_token,
+)
+
+
+class DummyResponse:
+    def __init__(self, status_code: int, data: dict | None = None) -> None:
+        self.status_code = status_code
+        self._data = data or {}
+
+    def json(self) -> dict:
+        return self._data
+
+
+class AsyncClientStub:
+    def __init__(
+        self,
+        *,
+        response=None,
+        error: Exception | None = None,
+        record: dict | None = None,
+        timeout=None,
+    ):
+        self._response = response
+        self._error = error
+        self._record = record if record is not None else {}
+        self._record["timeout"] = timeout
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return False
+
+    async def get(self, url: str, headers: dict[str, str]):
+        self._record["url"] = url
+        self._record["headers"] = headers
+        if self._error:
+            raise self._error
+        return self._response
+
+
+def test_credentials_path_uses_env_override(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))
+    assert _credentials_path() == tmp_path / ".credentials.json"
+
+
+def test_load_credentials_file_handles_missing_invalid_and_valid(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))
+    assert _load_credentials_file() is None
+
+    creds_path = tmp_path / ".credentials.json"
+    creds_path.write_text("{invalid", encoding="utf-8")
+    assert _load_credentials_file() is None
+
+    payload = {"claudeAiOauth": {"accessToken": "token-from-file"}}
+    creds_path.write_text(json.dumps(payload), encoding="utf-8")
+    assert _load_credentials_file() == payload
+
+
+def test_read_cached_oauth_token_prefers_env_and_checks_expiry(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_CODE_OAUTH_TOKEN", " env-token ")
+    monkeypatch.setattr("headroom.subscription.client._load_credentials_file", lambda: None)
+    assert read_cached_oauth_token() == "env-token"
+
+    monkeypatch.delenv("CLAUDE_CODE_OAUTH_TOKEN", raising=False)
+    monkeypatch.setattr(
+        "headroom.subscription.client._load_credentials_file",
+        lambda: {"claudeAiOauth": {"accessToken": "cached-token"}},
+    )
+    assert read_cached_oauth_token() == "cached-token"
+
+    monkeypatch.setattr(
+        "headroom.subscription.client._load_credentials_file",
+        lambda: {
+            "claudeAiOauth": {
+                "accessToken": "expired-token",
+                "expiresAt": 59_000,
+            }
+        },
+    )
+    monkeypatch.setattr("time.time", lambda: 60)
+    assert read_cached_oauth_token() is None
+
+    monkeypatch.setattr(
+        "headroom.subscription.client._load_credentials_file",
+        lambda: {"claudeAiOauth": {"accessToken": ""}},
+    )
+    assert read_cached_oauth_token() is None
+
+    monkeypatch.setattr(
+        "headroom.subscription.client._load_credentials_file",
+        lambda: None,
+    )
+    assert read_cached_oauth_token() is None
+
+
+@pytest.mark.asyncio
+async def test_subscription_client_fetch_handles_success_and_status_codes(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    record: dict = {}
+    monkeypatch.setattr(
+        "headroom.subscription.client.httpx.AsyncClient",
+        lambda timeout: AsyncClientStub(
+            response=DummyResponse(200, {"five_hour": {"total": 1}}),
+            record=record,
+            timeout=timeout,
+        ),
+    )
+    monkeypatch.setattr(
+        "headroom.subscription.client.SubscriptionSnapshot.from_api_response",
+        lambda data, token="": {"data": data, "token": token},
+    )
+
+    client = SubscriptionClient(timeout=3.5)
+    result = await client.fetch("  explicit-token  ")
+    assert result == {"data": {"five_hour": {"total": 1}}, "token": "explicit-token"}
+    assert record["timeout"] == 3.5
+    assert record["url"] == _USAGE_URL
+    assert record["headers"] == {
+        "Authorization": "Bearer explicit-token",
+        "anthropic-beta": _BETA_HEADER,
+        "Content-Type": "application/json",
+    }
+
+    for status_code in (401, 404, 500):
+        monkeypatch.setattr(
+            "headroom.subscription.client.httpx.AsyncClient",
+            lambda timeout, status_code=status_code: AsyncClientStub(
+                response=DummyResponse(status_code), timeout=timeout
+            ),
+        )
+        assert await client.fetch("explicit-token") is None
+
+
+@pytest.mark.asyncio
+async def test_subscription_client_fetch_uses_cached_token_and_handles_exceptions(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = SubscriptionClient()
+
+    monkeypatch.setattr("headroom.subscription.client.read_cached_oauth_token", lambda: None)
+    assert await client.fetch() is None
+
+    monkeypatch.setattr(
+        "headroom.subscription.client.read_cached_oauth_token",
+        lambda: "cached-token",
+    )
+    monkeypatch.setattr(
+        "headroom.subscription.client.httpx.AsyncClient",
+        lambda timeout: AsyncClientStub(error=httpx.TimeoutException("slow"), timeout=timeout),
+    )
+    assert await client.fetch() is None
+
+    monkeypatch.setattr(
+        "headroom.subscription.client.httpx.AsyncClient",
+        lambda timeout: AsyncClientStub(error=RuntimeError("boom"), timeout=timeout),
+    )
+    assert await client.fetch() is None
diff --git a/tests/test_subscription_tracker.py b/tests/test_subscription_tracker.py
index 6b274a6f9b65a0270245c65aa699db47f04ecc5c..d246f438bcb843ad7472b38bc5c032f7a4d8cba9 100644
--- a/tests/test_subscription_tracker.py
+++ b/tests/test_subscription_tracker.py
@@ -1,201 +1,201 @@
-from __future__ import annotations
-
-import sys
-from datetime import timedelta
-from pathlib import Path
-from types import SimpleNamespace
-
-import pytest
-
-import headroom.subscription.tracker as tracker_module
-from headroom.subscription.models import (
-    HeadroomContribution,
-    RateLimitWindow,
-    SubscriptionSnapshot,
-    WindowDiscrepancy,
-    WindowTokens,
-    _utc_now,
-)
-from headroom.subscription.tracker import SubscriptionTracker
-
-
-def _make_snapshot(
-    *, token_prefix: str = "token123", reset_offset_hours: int = 5
-) -> SubscriptionSnapshot:
-    return SubscriptionSnapshot(
-        five_hour=RateLimitWindow(
-            used=10,
-            limit=100,
-            utilization_pct=10.0,
-            resets_at=_utc_now() + timedelta(hours=reset_offset_hours),
-        ),
-        seven_day=RateLimitWindow(used=20, limit=200, utilization_pct=10.0),
-        token_prefix=token_prefix,
-    )
-
-
-def test_tracker_notify_active_update_and_basic_state(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)
-    tracker = SubscriptionTracker(enabled=False)
-
-    assert tracker.is_available() is False
-    assert tracker.latest_snapshot is None
-    assert tracker.is_active() is False
-    assert isinstance(tracker.get_stats(), dict)
-
-    tracker.notify_active("")
-    tracker.notify_active("Basic token")
-    tracker.notify_active("Bearer sk-ant-api-key")
-    assert tracker._current_token is None
-
-    tracker.notify_active("Bearer oauth-token-123")
-    assert tracker._current_token == "oauth-token-123"
-    assert tracker._full_tokens["oauth-to"] == 1
-    assert tracker.is_active() is True
-
-    tracker.update_contribution(
-        tokens_submitted=10,
-        tokens_saved_compression=5,
-        tokens_saved_rtk=-1,
-        tokens_saved_cache_reads=3,
-        compression_savings_usd=1.25,
-        cache_savings_usd=-2.0,
-    )
-    contribution = tracker._state.contribution
-    assert contribution.tokens_submitted == 10
-    assert contribution.tokens_saved_compression == 5
-    assert contribution.tokens_saved_rtk == 0
-    assert contribution.tokens_saved_cache_reads == 3
-    assert contribution.compression_savings_usd == 1.25
-    assert contribution.cache_savings_usd == 0.0
-
-
-@pytest.mark.asyncio
-async def test_tracker_start_stop_and_rollover_reset(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-) -> None:
-    monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)
-    tracker = SubscriptionTracker(persist_path=tmp_path / "state.json")
-
-    async def fake_poll_loop() -> None:
-        assert tracker._stop_event is not None
-        await tracker._stop_event.wait()
-
-    tracker._poll_loop = fake_poll_loop  # type: ignore[method-assign]
-    await tracker.start()
-    first_task = tracker._poll_task
-    assert first_task is not None
-
-    await tracker.start()
-    assert tracker._poll_task is first_task
-
-    await tracker.stop()
-    assert tracker._stop_event is not None and tracker._stop_event.is_set()
-    assert tracker._persist_path.exists()
-
-    tracker._state.history = [
-        _make_snapshot(reset_offset_hours=5),
-        _make_snapshot(reset_offset_hours=6),
-    ]
-    tracker._state.contribution = HeadroomContribution(tokens_submitted=99)
-    tracker._maybe_reset_contribution(tracker._state.history[-1])
-    assert tracker._state.contribution.tokens_submitted == 0
-
-
-@pytest.mark.asyncio
-async def test_maybe_poll_handles_inactive_and_none_snapshot(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)
-    tracker = SubscriptionTracker()
-
-    monkeypatch.setattr("headroom.subscription.client.read_cached_oauth_token", lambda: None)
-    await tracker._maybe_poll()
-    assert tracker._state.poll_count == 0
-
-    monkeypatch.setattr(
-        "headroom.subscription.client.read_cached_oauth_token", lambda: "cached-token"
-    )
-
-    async def fetch_none(token: str | None):
-        return None
-
-    tracker._client = SimpleNamespace(fetch=fetch_none)
-    await tracker._maybe_poll()
-    assert tracker._state.last_error == "fetch returned None"
-    assert tracker._state.poll_errors == 1
-
-
-@pytest.mark.asyncio
-async def test_maybe_poll_success_updates_state_and_metrics(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)
-    tracker = SubscriptionTracker()
-    tracker.notify_active("Bearer live-oauth-token")
-
-    snapshot = _make_snapshot()
-    discrepancies = [WindowDiscrepancy(kind="cache_miss", description="miss", severity="warning")]
-    metrics_calls: list[dict] = []
-
-    async def fetch_snapshot(token: str | None):
-        assert token == "live-oauth-token"
-        return snapshot
-
-    tracker._client = SimpleNamespace(fetch=fetch_snapshot)
-    monkeypatch.setattr(
-        tracker_module, "_compute_window_tokens_for_snapshot", lambda snap: WindowTokens(input=7)
-    )
-    monkeypatch.setattr(tracker_module, "_detect_discrepancies", lambda snap, tokens: discrepancies)
-    monkeypatch.setattr(
-        tracker, "_persist_state", lambda: metrics_calls.append({"persisted": True})
-    )
-    monkeypatch.setitem(
-        sys.modules,
-        "headroom.observability.metrics",
-        SimpleNamespace(
-            get_otel_metrics=lambda: SimpleNamespace(
-                record_subscription_window=lambda state: metrics_calls.append(state)
-            )
-        ),
-    )
-
-    await tracker._maybe_poll()
-    assert tracker.latest_snapshot is snapshot
-    assert tracker._state.window_tokens.input == 7
-    assert tracker._state.discrepancies[-1].kind == "cache_miss"
-    assert tracker._state.last_error is None
-    assert tracker._state.poll_count == 1
-    assert metrics_calls[0] == {"persisted": True}
-    assert isinstance(metrics_calls[1], dict)
-
-
-def test_persist_and_load_state_round_trip(tmp_path: Path) -> None:
-    persist_path = tmp_path / "tracker-state.json"
-    tracker = SubscriptionTracker(persist_path=persist_path)
-    tracker.update_contribution(
-        tokens_submitted=11,
-        tokens_saved_compression=2,
-        tokens_saved_rtk=3,
-        tokens_saved_cache_reads=4,
-        compression_savings_usd=1.5,
-        cache_savings_usd=2.5,
-    )
-    tracker._state.poll_count = 7
-    tracker._persist_state()
-
-    loader = SubscriptionTracker(persist_path=persist_path)
-    assert loader._state.contribution.tokens_submitted == 11
-    assert loader._state.contribution.tokens_saved_compression == 2
-    assert loader._state.contribution.tokens_saved_rtk == 3
-    assert loader._state.contribution.tokens_saved_cache_reads == 4
-    assert loader._state.contribution.compression_savings_usd == 1.5
-    assert loader._state.contribution.cache_savings_usd == 2.5
-    assert loader._state.poll_count == 7
-
-    persist_path.write_text("{invalid", encoding="utf-8")
-    broken = SubscriptionTracker(persist_path=persist_path)
-    assert broken._state.poll_count == 0
-
-    missing = SubscriptionTracker(persist_path=tmp_path / "missing.json")
-    assert missing._state.poll_count == 0
+from __future__ import annotations
+
+import sys
+from datetime import timedelta
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+import headroom.subscription.tracker as tracker_module
+from headroom.subscription.models import (
+    HeadroomContribution,
+    RateLimitWindow,
+    SubscriptionSnapshot,
+    WindowDiscrepancy,
+    WindowTokens,
+    _utc_now,
+)
+from headroom.subscription.tracker import SubscriptionTracker
+
+
+def _make_snapshot(
+    *, token_prefix: str = "token123", reset_offset_hours: int = 5
+) -> SubscriptionSnapshot:
+    return SubscriptionSnapshot(
+        five_hour=RateLimitWindow(
+            used=10,
+            limit=100,
+            utilization_pct=10.0,
+            resets_at=_utc_now() + timedelta(hours=reset_offset_hours),
+        ),
+        seven_day=RateLimitWindow(used=20, limit=200, utilization_pct=10.0),
+        token_prefix=token_prefix,
+    )
+
+
+def test_tracker_notify_active_update_and_basic_state(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)
+    tracker = SubscriptionTracker(enabled=False)
+
+    assert tracker.is_available() is False
+    assert tracker.latest_snapshot is None
+    assert tracker.is_active() is False
+    assert isinstance(tracker.get_stats(), dict)
+
+    tracker.notify_active("")
+    tracker.notify_active("Basic token")
+    tracker.notify_active("Bearer sk-ant-api-key")
+    assert tracker._current_token is None
+
+    tracker.notify_active("Bearer oauth-token-123")
+    assert tracker._current_token == "oauth-token-123"
+    assert tracker._full_tokens["oauth-to"] == 1
+    assert tracker.is_active() is True
+
+    tracker.update_contribution(
+        tokens_submitted=10,
+        tokens_saved_compression=5,
+        tokens_saved_rtk=-1,
+        tokens_saved_cache_reads=3,
+        compression_savings_usd=1.25,
+        cache_savings_usd=-2.0,
+    )
+    contribution = tracker._state.contribution
+    assert contribution.tokens_submitted == 10
+    assert contribution.tokens_saved_compression == 5
+    assert contribution.tokens_saved_rtk == 0
+    assert contribution.tokens_saved_cache_reads == 3
+    assert contribution.compression_savings_usd == 1.25
+    assert contribution.cache_savings_usd == 0.0
+
+
+@pytest.mark.asyncio
+async def test_tracker_start_stop_and_rollover_reset(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)
+    tracker = SubscriptionTracker(persist_path=tmp_path / "state.json")
+
+    async def fake_poll_loop() -> None:
+        assert tracker._stop_event is not None
+        await tracker._stop_event.wait()
+
+    tracker._poll_loop = fake_poll_loop  # type: ignore[method-assign]
+    await tracker.start()
+    first_task = tracker._poll_task
+    assert first_task is not None
+
+    await tracker.start()
+    assert tracker._poll_task is first_task
+
+    await tracker.stop()
+    assert tracker._stop_event is not None and tracker._stop_event.is_set()
+    assert tracker._persist_path.exists()
+
+    tracker._state.history = [
+        _make_snapshot(reset_offset_hours=5),
+        _make_snapshot(reset_offset_hours=6),
+    ]
+    tracker._state.contribution = HeadroomContribution(tokens_submitted=99)
+    tracker._maybe_reset_contribution(tracker._state.history[-1])
+    assert tracker._state.contribution.tokens_submitted == 0
+
+
+@pytest.mark.asyncio
+async def test_maybe_poll_handles_inactive_and_none_snapshot(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)
+    tracker = SubscriptionTracker()
+
+    monkeypatch.setattr("headroom.subscription.client.read_cached_oauth_token", lambda: None)
+    await tracker._maybe_poll()
+    assert tracker._state.poll_count == 0
+
+    monkeypatch.setattr(
+        "headroom.subscription.client.read_cached_oauth_token", lambda: "cached-token"
+    )
+
+    async def fetch_none(token: str | None):
+        return None
+
+    tracker._client = SimpleNamespace(fetch=fetch_none)
+    await tracker._maybe_poll()
+    assert tracker._state.last_error == "fetch returned None"
+    assert tracker._state.poll_errors == 1
+
+
+@pytest.mark.asyncio
+async def test_maybe_poll_success_updates_state_and_metrics(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)
+    tracker = SubscriptionTracker()
+    tracker.notify_active("Bearer live-oauth-token")
+
+    snapshot = _make_snapshot()
+    discrepancies = [WindowDiscrepancy(kind="cache_miss", description="miss", severity="warning")]
+    metrics_calls: list[dict] = []
+
+    async def fetch_snapshot(token: str | None):
+        assert token == "live-oauth-token"
+        return snapshot
+
+    tracker._client = SimpleNamespace(fetch=fetch_snapshot)
+    monkeypatch.setattr(
+        tracker_module, "_compute_window_tokens_for_snapshot", lambda snap: WindowTokens(input=7)
+    )
+    monkeypatch.setattr(tracker_module, "_detect_discrepancies", lambda snap, tokens: discrepancies)
+    monkeypatch.setattr(
+        tracker, "_persist_state", lambda: metrics_calls.append({"persisted": True})
+    )
+    monkeypatch.setitem(
+        sys.modules,
+        "headroom.observability.metrics",
+        SimpleNamespace(
+            get_otel_metrics=lambda: SimpleNamespace(
+                record_subscription_window=lambda state: metrics_calls.append(state)
+            )
+        ),
+    )
+
+    await tracker._maybe_poll()
+    assert tracker.latest_snapshot is snapshot
+    assert tracker._state.window_tokens.input == 7
+    assert tracker._state.discrepancies[-1].kind == "cache_miss"
+    assert tracker._state.last_error is None
+    assert tracker._state.poll_count == 1
+    assert metrics_calls[0] == {"persisted": True}
+    assert isinstance(metrics_calls[1], dict)
+
+
+def test_persist_and_load_state_round_trip(tmp_path: Path) -> None:
+    persist_path = tmp_path / "tracker-state.json"
+    tracker = SubscriptionTracker(persist_path=persist_path)
+    tracker.update_contribution(
+        tokens_submitted=11,
+        tokens_saved_compression=2,
+        tokens_saved_rtk=3,
+        tokens_saved_cache_reads=4,
+        compression_savings_usd=1.5,
+        cache_savings_usd=2.5,
+    )
+    tracker._state.poll_count = 7
+    tracker._persist_state()
+
+    loader = SubscriptionTracker(persist_path=persist_path)
+    assert loader._state.contribution.tokens_submitted == 11
+    assert loader._state.contribution.tokens_saved_compression == 2
+    assert loader._state.contribution.tokens_saved_rtk == 3
+    assert loader._state.contribution.tokens_saved_cache_reads == 4
+    assert loader._state.contribution.compression_savings_usd == 1.5
+    assert loader._state.contribution.cache_savings_usd == 2.5
+    assert loader._state.poll_count == 7
+
+    persist_path.write_text("{invalid", encoding="utf-8")
+    broken = SubscriptionTracker(persist_path=persist_path)
+    assert broken._state.poll_count == 0
+
+    missing = SubscriptionTracker(persist_path=tmp_path / "missing.json")
+    assert missing._state.poll_count == 0
diff --git a/tests/test_tokenizer.py b/tests/test_tokenizer.py
index 030aeb56fd9a82bd3f1f282a6a73c9eb5f44cbb3..f95295ae19f7c2dbd5f7cd4c306590fab8cc4dca 100644
--- a/tests/test_tokenizer.py
+++ b/tests/test_tokenizer.py
@@ -1,50 +1,50 @@
-from __future__ import annotations
-
-from typing import Any
-
-from headroom.tokenizer import Tokenizer, count_tokens_messages, count_tokens_text
-
-
-class FakeTokenCounter:
-    def __init__(self) -> None:
-        self.calls: list[tuple[str, Any]] = []
-
-    def count_text(self, text: str) -> int:
-        self.calls.append(("text", text))
-        return len(text.split())
-
-    def count_message(self, message: dict[str, Any]) -> int:
-        self.calls.append(("message", message))
-        return len(str(message.get("content", "")).split())
-
-    def count_messages(self, messages: list[dict[str, Any]]) -> int:
-        self.calls.append(("messages", messages))
-        return sum(len(str(msg.get("content", "")).split()) for msg in messages)
-
-
-def test_tokenizer_delegates_to_counter() -> None:
-    counter = FakeTokenCounter()
-    tokenizer = Tokenizer(counter, model="gpt-4o")
-
-    assert tokenizer.model == "gpt-4o"
-    assert tokenizer.available is True
-    assert tokenizer.count_text("hello world") == 2
-    assert tokenizer.count_message({"role": "user", "content": "three word text"}) == 3
-    assert tokenizer.count_messages([{"content": "one two"}, {"content": "three"}]) == 3
-    assert counter.calls == [
-        ("text", "hello world"),
-        ("message", {"role": "user", "content": "three word text"}),
-        ("messages", [{"content": "one two"}, {"content": "three"}]),
-    ]
-
-
-def test_tokenizer_convenience_functions() -> None:
-    counter = FakeTokenCounter()
-    messages = [{"content": "one"}, {"content": "two three"}]
-
-    assert count_tokens_text("alpha beta gamma", counter) == 3
-    assert count_tokens_messages(messages, counter) == 3
-    assert counter.calls == [
-        ("text", "alpha beta gamma"),
-        ("messages", messages),
-    ]
+from __future__ import annotations
+
+from typing import Any
+
+from headroom.tokenizer import Tokenizer, count_tokens_messages, count_tokens_text
+
+
+class FakeTokenCounter:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, Any]] = []
+
+    def count_text(self, text: str) -> int:
+        self.calls.append(("text", text))
+        return len(text.split())
+
+    def count_message(self, message: dict[str, Any]) -> int:
+        self.calls.append(("message", message))
+        return len(str(message.get("content", "")).split())
+
+    def count_messages(self, messages: list[dict[str, Any]]) -> int:
+        self.calls.append(("messages", messages))
+        return sum(len(str(msg.get("content", "")).split()) for msg in messages)
+
+
+def test_tokenizer_delegates_to_counter() -> None:
+    counter = FakeTokenCounter()
+    tokenizer = Tokenizer(counter, model="gpt-4o")
+
+    assert tokenizer.model == "gpt-4o"
+    assert tokenizer.available is True
+    assert tokenizer.count_text("hello world") == 2
+    assert tokenizer.count_message({"role": "user", "content": "three word text"}) == 3
+    assert tokenizer.count_messages([{"content": "one two"}, {"content": "three"}]) == 3
+    assert counter.calls == [
+        ("text", "hello world"),
+        ("message", {"role": "user", "content": "three word text"}),
+        ("messages", [{"content": "one two"}, {"content": "three"}]),
+    ]
+
+
+def test_tokenizer_convenience_functions() -> None:
+    counter = FakeTokenCounter()
+    messages = [{"content": "one"}, {"content": "two three"}]
+
+    assert count_tokens_text("alpha beta gamma", counter) == 3
+    assert count_tokens_messages(messages, counter) == 3
+    assert counter.calls == [
+        ("text", "alpha beta gamma"),
+        ("messages", messages),
+    ]
diff --git a/tests/test_transforms_content_detection.py b/tests/test_transforms_content_detection.py
index 1ca9de7ea1fd33d3483b0fc304ffe0f2a5d44d5d..9bf7a6353f930475ef536a63bece86e93c54bc5b 100644
--- a/tests/test_transforms_content_detection.py
+++ b/tests/test_transforms_content_detection.py
@@ -1,202 +1,202 @@
-from __future__ import annotations
-
-from headroom.transforms.content_detector import (
-    ContentType,
-    _try_detect_code,
-    _try_detect_diff,
-    _try_detect_html,
-    _try_detect_json,
-    _try_detect_log,
-    _try_detect_search,
-    detect_content_type,
-    is_json_array_of_dicts,
-)
-from headroom.transforms.error_detection import (
-    ERROR_INDICATOR_KEYWORDS,
-    ERROR_KEYWORDS,
-    ERROR_PATTERN,
-    IMPORTANCE_KEYWORDS,
-    IMPORTANCE_PATTERN,
-    PRIORITY_PATTERNS_DIFF,
-    PRIORITY_PATTERNS_SEARCH,
-    PRIORITY_PATTERNS_TEXT,
-    SECURITY_KEYWORDS,
-    SECURITY_PATTERN,
-    WARNING_PATTERN,
-    content_has_error_indicators,
-)
-
-
-def test_detect_content_type_handles_empty_and_plain_text() -> None:
-    empty = detect_content_type("   ")
-    assert empty.content_type is ContentType.PLAIN_TEXT
-    assert empty.confidence == 0.0
-
-    plain = detect_content_type("just a normal paragraph with no strong patterns")
-    assert plain.content_type is ContentType.PLAIN_TEXT
-    assert plain.confidence == 0.5
-
-
-def test_json_detection_distinguishes_dict_arrays_and_other_lists() -> None:
-    dict_result = _try_detect_json('[{"id": 1}, {"id": 2}]')
-    assert dict_result is not None
-    assert dict_result.content_type is ContentType.JSON_ARRAY
-    assert dict_result.confidence == 1.0
-    assert dict_result.metadata == {"item_count": 2, "is_dict_array": True}
-
-    scalar_result = _try_detect_json("[1, 2, 3]")
-    assert scalar_result is not None
-    assert scalar_result.confidence == 0.8
-    assert scalar_result.metadata == {"item_count": 3, "is_dict_array": False}
-
-    empty_result = _try_detect_json("[]")
-    assert empty_result is not None
-    assert empty_result.metadata == {"item_count": 0, "is_dict_array": False}
-
-    assert _try_detect_json('{"id": 1}') is None
-    assert _try_detect_json("[not valid json") is None
-    assert is_json_array_of_dicts('[{"id": 1}]') is True
-    assert is_json_array_of_dicts('["value"]') is False
-
-
-def test_diff_detection_tracks_headers_and_changes() -> None:
-    diff = "\n".join(
-        [
-            "diff --git a/app.py b/app.py",
-            "--- a/app.py",
-            "@@ -1,2 +1,2 @@",
-            "-old line",
-            "+new line",
-        ]
-    )
-    result = _try_detect_diff(diff)
-    assert result is not None
-    assert result.content_type is ContentType.GIT_DIFF
-    assert result.metadata["header_matches"] == 3
-    assert result.metadata["change_lines"] == 2
-    assert result.confidence == 1.0
-    assert detect_content_type(diff).content_type is ContentType.GIT_DIFF
-
-    assert _try_detect_diff("+not enough by itself") is None
-
-
-def test_html_detection_requires_real_structure() -> None:
-    html = """
-    <!DOCTYPE html>
-    <html>
-      <head><meta charset="utf-8"></head>
-      <body><main><section><div>Hello</div><nav>Links</nav></section></main></body>
-    </html>
-    """
-    result = _try_detect_html(html)
-    assert result is not None
-    assert result.content_type is ContentType.HTML
-    assert result.metadata["has_doctype"] is True
-    assert result.metadata["has_html_tag"] is True
-    assert result.metadata["structural_tags"] >= 3
-    assert detect_content_type(html).content_type is ContentType.HTML
-
-    assert _try_detect_html("<div>only one tag</div>") is None
-    assert _try_detect_html("<html><title>too sparse</title></html>") is None
-
-
-def test_search_detection_uses_match_ratio() -> None:
-    search_output = "\n".join(
-        [
-            "src/app.py:10:def main():",
-            "src/app.py:20:print('hello')",
-            "README.md:5:usage docs",
-            "plain text footer",
-        ]
-    )
-    result = _try_detect_search(search_output)
-    assert result is not None
-    assert result.content_type is ContentType.SEARCH_RESULTS
-    assert result.metadata == {"matching_lines": 3, "total_lines": 4}
-    assert result.confidence == 0.85
-    assert detect_content_type(search_output).content_type is ContentType.SEARCH_RESULTS
-
-    assert _try_detect_search("one:1:match\nplain\nplain\nplain") is None
-    assert _try_detect_search("\n\n") is None
-
-
-def test_log_detection_prefers_build_output_patterns() -> None:
-    log_output = "\n".join(
-        [
-            "2025-01-01 Starting run",
-            "ERROR failed to compile",
-            "WARNING retrying build",
-            "PASSED unit test",
-            "Traceback (most recent call last)",
-            "plain footer",
-        ]
-    )
-    result = _try_detect_log(log_output)
-    assert result is not None
-    assert result.content_type is ContentType.BUILD_OUTPUT
-    assert result.metadata == {"pattern_matches": 5, "error_matches": 2, "total_lines": 6}
-    assert result.confidence == 0.8166666666666667
-    assert detect_content_type(log_output).content_type is ContentType.BUILD_OUTPUT
-
-    assert _try_detect_log("plain\ntext\nonly") is None
-    assert _try_detect_log("\n\n") is None
-    assert _try_detect_log("\n".join(["ERROR one", *["plain"] * 15])) is None
-
-
-def test_code_detection_identifies_language_and_thresholds() -> None:
-    python_code = "\n".join(
-        [
-            "import os",
-            "from pathlib import Path",
-            "",
-            "@cached",
-            "class App:",
-            "    pass",
-            "def main():",
-            '    """Run."""',
-        ]
-    )
-    result = _try_detect_code(python_code)
-    assert result is not None
-    assert result.content_type is ContentType.SOURCE_CODE
-    assert result.metadata == {"language": "python", "pattern_matches": 6}
-    assert result.confidence == 0.8628571428571429
-    assert detect_content_type(python_code).content_type is ContentType.SOURCE_CODE
-
-    assert _try_detect_code("function maybe() {}\nplain text") is None
-    assert _try_detect_code("import os\ndef main():") is None
-    assert _try_detect_code("\n\n") is None
-
-
-def test_detect_content_type_respects_priority_order() -> None:
-    diff_like_search = "\n".join(
-        [
-            "diff --git a/src/app.py b/src/app.py",
-            "@@ -1,1 +1,1 @@",
-            "+src/app.py:10:def still_diff_first()",
-        ]
-    )
-    assert detect_content_type(diff_like_search).content_type is ContentType.GIT_DIFF
-
-
-def test_error_detection_keywords_patterns_and_indicator_helper() -> None:
-    assert {"error", "failed", "critical"} <= ERROR_KEYWORDS
-    assert {"warning", "todo", "fix"} <= IMPORTANCE_KEYWORDS
-    assert {"security", "password", "token"} <= SECURITY_KEYWORDS
-    assert ERROR_INDICATOR_KEYWORDS[0] == "error"
-
-    assert ERROR_PATTERN.search("Fatal error occurred")
-    assert WARNING_PATTERN.search("warning: be careful")
-    assert IMPORTANCE_PATTERN.search("TODO fix this hack")
-    assert SECURITY_PATTERN.search("rotate the auth token")
-
-    assert PRIORITY_PATTERNS_SEARCH[:3] == [ERROR_PATTERN, WARNING_PATTERN, IMPORTANCE_PATTERN]
-    assert PRIORITY_PATTERNS_DIFF == [ERROR_PATTERN, IMPORTANCE_PATTERN, SECURITY_PATTERN]
-    assert PRIORITY_PATTERNS_TEXT[0] is ERROR_PATTERN
-    assert PRIORITY_PATTERNS_TEXT[1] is IMPORTANCE_PATTERN
-    assert PRIORITY_PATTERNS_TEXT[2].match("## Header")
-    assert PRIORITY_PATTERNS_TEXT[3].match("**Bold")
-    assert PRIORITY_PATTERNS_TEXT[4].match("> quote")
-
-    assert content_has_error_indicators("TRACEBACK: Fatal crash in worker") is True
-    assert content_has_error_indicators("Everything completed successfully") is False
+from __future__ import annotations
+
+from headroom.transforms.content_detector import (
+    ContentType,
+    _try_detect_code,
+    _try_detect_diff,
+    _try_detect_html,
+    _try_detect_json,
+    _try_detect_log,
+    _try_detect_search,
+    detect_content_type,
+    is_json_array_of_dicts,
+)
+from headroom.transforms.error_detection import (
+    ERROR_INDICATOR_KEYWORDS,
+    ERROR_KEYWORDS,
+    ERROR_PATTERN,
+    IMPORTANCE_KEYWORDS,
+    IMPORTANCE_PATTERN,
+    PRIORITY_PATTERNS_DIFF,
+    PRIORITY_PATTERNS_SEARCH,
+    PRIORITY_PATTERNS_TEXT,
+    SECURITY_KEYWORDS,
+    SECURITY_PATTERN,
+    WARNING_PATTERN,
+    content_has_error_indicators,
+)
+
+
+def test_detect_content_type_handles_empty_and_plain_text() -> None:
+    empty = detect_content_type("   ")
+    assert empty.content_type is ContentType.PLAIN_TEXT
+    assert empty.confidence == 0.0
+
+    plain = detect_content_type("just a normal paragraph with no strong patterns")
+    assert plain.content_type is ContentType.PLAIN_TEXT
+    assert plain.confidence == 0.5
+
+
+def test_json_detection_distinguishes_dict_arrays_and_other_lists() -> None:
+    dict_result = _try_detect_json('[{"id": 1}, {"id": 2}]')
+    assert dict_result is not None
+    assert dict_result.content_type is ContentType.JSON_ARRAY
+    assert dict_result.confidence == 1.0
+    assert dict_result.metadata == {"item_count": 2, "is_dict_array": True}
+
+    scalar_result = _try_detect_json("[1, 2, 3]")
+    assert scalar_result is not None
+    assert scalar_result.confidence == 0.8
+    assert scalar_result.metadata == {"item_count": 3, "is_dict_array": False}
+
+    empty_result = _try_detect_json("[]")
+    assert empty_result is not None
+    assert empty_result.metadata == {"item_count": 0, "is_dict_array": False}
+
+    assert _try_detect_json('{"id": 1}') is None
+    assert _try_detect_json("[not valid json") is None
+    assert is_json_array_of_dicts('[{"id": 1}]') is True
+    assert is_json_array_of_dicts('["value"]') is False
+
+
+def test_diff_detection_tracks_headers_and_changes() -> None:
+    diff = "\n".join(
+        [
+            "diff --git a/app.py b/app.py",
+            "--- a/app.py",
+            "@@ -1,2 +1,2 @@",
+            "-old line",
+            "+new line",
+        ]
+    )
+    result = _try_detect_diff(diff)
+    assert result is not None
+    assert result.content_type is ContentType.GIT_DIFF
+    assert result.metadata["header_matches"] == 3
+    assert result.metadata["change_lines"] == 2
+    assert result.confidence == 1.0
+    assert detect_content_type(diff).content_type is ContentType.GIT_DIFF
+
+    assert _try_detect_diff("+not enough by itself") is None
+
+
+def test_html_detection_requires_real_structure() -> None:
+    html = """
+    <!DOCTYPE html>
+    <html>
+      <head><meta charset="utf-8"></head>
+      <body><main><section><div>Hello</div><nav>Links</nav></section></main></body>
+    </html>
+    """
+    result = _try_detect_html(html)
+    assert result is not None
+    assert result.content_type is ContentType.HTML
+    assert result.metadata["has_doctype"] is True
+    assert result.metadata["has_html_tag"] is True
+    assert result.metadata["structural_tags"] >= 3
+    assert detect_content_type(html).content_type is ContentType.HTML
+
+    assert _try_detect_html("<div>only one tag</div>") is None
+    assert _try_detect_html("<html><title>too sparse</title></html>") is None
+
+
+def test_search_detection_uses_match_ratio() -> None:
+    search_output = "\n".join(
+        [
+            "src/app.py:10:def main():",
+            "src/app.py:20:print('hello')",
+            "README.md:5:usage docs",
+            "plain text footer",
+        ]
+    )
+    result = _try_detect_search(search_output)
+    assert result is not None
+    assert result.content_type is ContentType.SEARCH_RESULTS
+    assert result.metadata == {"matching_lines": 3, "total_lines": 4}
+    assert result.confidence == 0.85
+    assert detect_content_type(search_output).content_type is ContentType.SEARCH_RESULTS
+
+    assert _try_detect_search("one:1:match\nplain\nplain\nplain") is None
+    assert _try_detect_search("\n\n") is None
+
+
+def test_log_detection_prefers_build_output_patterns() -> None:
+    log_output = "\n".join(
+        [
+            "2025-01-01 Starting run",
+            "ERROR failed to compile",
+            "WARNING retrying build",
+            "PASSED unit test",
+            "Traceback (most recent call last)",
+            "plain footer",
+        ]
+    )
+    result = _try_detect_log(log_output)
+    assert result is not None
+    assert result.content_type is ContentType.BUILD_OUTPUT
+    assert result.metadata == {"pattern_matches": 5, "error_matches": 2, "total_lines": 6}
+    assert result.confidence == 0.8166666666666667
+    assert detect_content_type(log_output).content_type is ContentType.BUILD_OUTPUT
+
+    assert _try_detect_log("plain\ntext\nonly") is None
+    assert _try_detect_log("\n\n") is None
+    assert _try_detect_log("\n".join(["ERROR one", *["plain"] * 15])) is None
+
+
+def test_code_detection_identifies_language_and_thresholds() -> None:
+    python_code = "\n".join(
+        [
+            "import os",
+            "from pathlib import Path",
+            "",
+            "@cached",
+            "class App:",
+            "    pass",
+            "def main():",
+            '    """Run."""',
+        ]
+    )
+    result = _try_detect_code(python_code)
+    assert result is not None
+    assert result.content_type is ContentType.SOURCE_CODE
+    assert result.metadata == {"language": "python", "pattern_matches": 6}
+    assert result.confidence == 0.8628571428571429
+    assert detect_content_type(python_code).content_type is ContentType.SOURCE_CODE
+
+    assert _try_detect_code("function maybe() {}\nplain text") is None
+    assert _try_detect_code("import os\ndef main():") is None
+    assert _try_detect_code("\n\n") is None
+
+
+def test_detect_content_type_respects_priority_order() -> None:
+    diff_like_search = "\n".join(
+        [
+            "diff --git a/src/app.py b/src/app.py",
+            "@@ -1,1 +1,1 @@",
+            "+src/app.py:10:def still_diff_first()",
+        ]
+    )
+    assert detect_content_type(diff_like_search).content_type is ContentType.GIT_DIFF
+
+
+def test_error_detection_keywords_patterns_and_indicator_helper() -> None:
+    assert {"error", "failed", "critical"} <= ERROR_KEYWORDS
+    assert {"warning", "todo", "fix"} <= IMPORTANCE_KEYWORDS
+    assert {"security", "password", "token"} <= SECURITY_KEYWORDS
+    assert ERROR_INDICATOR_KEYWORDS[0] == "error"
+
+    assert ERROR_PATTERN.search("Fatal error occurred")
+    assert WARNING_PATTERN.search("warning: be careful")
+    assert IMPORTANCE_PATTERN.search("TODO fix this hack")
+    assert SECURITY_PATTERN.search("rotate the auth token")
+
+    assert PRIORITY_PATTERNS_SEARCH[:3] == [ERROR_PATTERN, WARNING_PATTERN, IMPORTANCE_PATTERN]
+    assert PRIORITY_PATTERNS_DIFF == [ERROR_PATTERN, IMPORTANCE_PATTERN, SECURITY_PATTERN]
+    assert PRIORITY_PATTERNS_TEXT[0] is ERROR_PATTERN
+    assert PRIORITY_PATTERNS_TEXT[1] is IMPORTANCE_PATTERN
+    assert PRIORITY_PATTERNS_TEXT[2].match("## Header")
+    assert PRIORITY_PATTERNS_TEXT[3].match("**Bold")
+    assert PRIORITY_PATTERNS_TEXT[4].match("> quote")
+
+    assert content_has_error_indicators("TRACEBACK: Fatal crash in worker") is True
+    assert content_has_error_indicators("Everything completed successfully") is False
diff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.py
index 7969bb15255d4f9c061ca64748e36cf9d32290c5..dfbd60ebee995d6ed5e3c2204f474a85dc5ea632 100644
--- a/tests/test_transforms_content_router.py
+++ b/tests/test_transforms_content_router.py
@@ -1,294 +1,294 @@
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-import pytest
-
-import headroom.transforms.content_router as content_router_module
-from headroom.transforms.content_detector import ContentType, DetectionResult
-from headroom.transforms.content_router import (
-    CompressionCache,
-    CompressionStrategy,
-    ContentRouter,
-    ContentRouterConfig,
-    RouterCompressionResult,
-    RoutingDecision,
-    _create_content_signature,
-    _detect_content,
-    _extract_json_block,
-    is_mixed_content,
-    split_into_sections,
-)
-
-
-def test_compression_cache_handles_hits_skips_evictions_and_clear(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    times = iter([100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 112.0, 112.0])
-    monkeypatch.setattr(content_router_module.time, "time", lambda: next(times))
-    monkeypatch.setattr(content_router_module.time, "perf_counter_ns", lambda: 50)
-
-    cache = CompressionCache(ttl_seconds=10)
-    cache.put(1, "compressed", 0.4, "text")
-    cache.mark_skip(2)
-
-    assert cache.get(1) == ("compressed", 0.4, "text")
-    assert cache.is_skipped(2) is True
-    assert cache.size == 1
-    assert cache.skip_size == 1
-
-    cache.move_to_skip(1)
-    assert cache.get(1) is None
-    assert cache.is_skipped(1) is True
-
-    # Expire both skip entries
-    assert cache.is_skipped(2) is False
-    assert cache.is_skipped(1) is False
-
-    assert cache.stats["cache_hits"] == 1
-    assert cache.stats["cache_skip_hits"] == 2
-    assert cache.stats["cache_misses"] == 1
-    assert cache.stats["cache_evictions"] >= 2
-
-    cache.clear()
-    assert cache.size == 0
-    assert cache.skip_size == 0
-
-
-def test_router_result_helpers_and_summary() -> None:
-    pure = RouterCompressionResult(
-        compressed="small",
-        original="very large",
-        strategy_used=CompressionStrategy.TEXT,
-        routing_log=[
-            RoutingDecision(
-                content_type=ContentType.PLAIN_TEXT,
-                strategy=CompressionStrategy.TEXT,
-                original_tokens=10,
-                compressed_tokens=4,
-            )
-        ],
-    )
-    assert pure.total_original_tokens == 10
-    assert pure.total_compressed_tokens == 4
-    assert pure.compression_ratio == 0.4
-    assert pure.tokens_saved == 6
-    assert pure.savings_percentage == 60.0
-    assert pure.summary() == "Pure text: 10→4 tokens (60% saved)"
-
-    mixed = RouterCompressionResult(
-        compressed="joined",
-        original="original",
-        strategy_used=CompressionStrategy.MIXED,
-        sections_processed=2,
-        routing_log=[
-            RoutingDecision(
-                content_type=ContentType.PLAIN_TEXT,
-                strategy=CompressionStrategy.TEXT,
-                original_tokens=0,
-                compressed_tokens=0,
-            ),
-            RoutingDecision(
-                content_type=ContentType.SEARCH_RESULTS,
-                strategy=CompressionStrategy.SEARCH,
-                original_tokens=8,
-                compressed_tokens=2,
-            ),
-        ],
-    )
-    assert mixed.routing_log[0].compression_ratio == 1.0
-    assert mixed.summary().startswith("Mixed content: 2 sections, routed to ")
-
-
-def test_content_signature_and_detection_helpers(monkeypatch: pytest.MonkeyPatch) -> None:
-    signature = _create_content_signature("search", "file.py:10:match", language="python")
-    assert signature is not None
-    assert len(signature.structure_hash) == 24
-
-    fake_detector = SimpleNamespace(
-        detect=lambda content: SimpleNamespace(
-            content_type=SimpleNamespace(value="code"),
-            confidence=0.91,
-            language="python",
-            raw_label="python",
-        )
-    )
-    monkeypatch.setattr(content_router_module, "_get_magika_detector", lambda: fake_detector)
-    magika_result = _detect_content("def main(): pass")
-    assert magika_result == DetectionResult(
-        content_type=ContentType.SOURCE_CODE,
-        confidence=0.91,
-        metadata={"language": "python", "raw_label": "python"},
-    )
-
-    fallback = DetectionResult(ContentType.PLAIN_TEXT, 0.6, {"kind": "fallback"})
-    monkeypatch.setattr(content_router_module, "_get_magika_detector", lambda: None)
-    monkeypatch.setattr(content_router_module, "detect_content_type", lambda content: fallback)
-    assert _detect_content("plain") is fallback
-
-
-def test_mixed_content_section_splitting_and_json_extraction() -> None:
-    content = "\n".join(
-        [
-            "Intro paragraph with Several words included for prose detection.",
-            "Another line with enough words to read as normal prose today.",
-            "Third line adds more prose so the detector sees real text content.",
-            "Fourth sentence keeps the count moving higher for prose patterns.",
-            "Fifth sentence does the same for mixed content identification.",
-            "Sixth sentence seals the prose threshold for the helper.",
-            "```python",
-            "def main():",
-            "    return 1",
-            "```",
-            '[{"id": 1}]',
-            "src/app.py:10:def main():",
-            "src/app.py:11:return 1",
-        ]
-    )
-    assert is_mixed_content(content) is True
-
-    sections = split_into_sections(content)
-    assert [section.content_type for section in sections] == [
-        ContentType.PLAIN_TEXT,
-        ContentType.SOURCE_CODE,
-        ContentType.JSON_ARRAY,
-        ContentType.SEARCH_RESULTS,
-    ]
-    assert sections[1].language == "python"
-    assert sections[1].is_code_fence is True
-    assert sections[2].content == '[{"id": 1}]'
-    assert sections[3].end_line == 12
-
-    json_block, end_idx = _extract_json_block(["[", '{"id": 1}', "]"], 0)
-    assert json_block == '[\n{"id": 1}\n]'
-    assert end_idx == 2
-    assert _extract_json_block(["{", '"a": 1'], 0) == (None, 0)
-
-
-def test_content_router_strategy_and_compress_paths(monkeypatch: pytest.MonkeyPatch) -> None:
-    router = ContentRouter(ContentRouterConfig(prefer_code_aware_for_code=False))
-
-    monkeypatch.setattr(content_router_module, "is_mixed_content", lambda content: False)
-    monkeypatch.setattr(
-        content_router_module,
-        "_detect_content",
-        lambda content: DetectionResult(ContentType.SOURCE_CODE, 1.0, {}),
-    )
-    assert router._determine_strategy("code") is CompressionStrategy.KOMPRESS
-    assert (
-        router._strategy_from_detection(DetectionResult(ContentType.SEARCH_RESULTS, 1.0, {}))
-        is CompressionStrategy.SEARCH
-    )
-    assert router._strategy_from_detection_type(ContentType.GIT_DIFF) is CompressionStrategy.DIFF
-    assert (
-        router._content_type_from_strategy(CompressionStrategy.PASSTHROUGH)
-        is ContentType.PLAIN_TEXT
-    )
-
-    mixed_result = RouterCompressionResult(
-        compressed="mixed",
-        original="mixed",
-        strategy_used=CompressionStrategy.MIXED,
-    )
-    pure_result = RouterCompressionResult(
-        compressed="pure",
-        original="pure",
-        strategy_used=CompressionStrategy.TEXT,
-    )
-    monkeypatch.setattr(router, "_compress_mixed", lambda *args, **kwargs: mixed_result)
-    monkeypatch.setattr(router, "_compress_pure", lambda *args, **kwargs: pure_result)
-
-    monkeypatch.setattr(router, "_determine_strategy", lambda content: CompressionStrategy.MIXED)
-    assert router.compress("mixed") is mixed_result
-
-    monkeypatch.setattr(router, "_determine_strategy", lambda content: CompressionStrategy.TEXT)
-    assert router.compress("pure") is pure_result
-    assert router.compress("   ").strategy_used is CompressionStrategy.PASSTHROUGH
-
-
-def test_content_router_mixed_pure_apply_and_toin(monkeypatch: pytest.MonkeyPatch) -> None:
-    router = ContentRouter()
-    mixed_content = "\n".join(["before", "```python", "print('x')", "```", "after"])
-    monkeypatch.setattr(
-        content_router_module,
-        "split_into_sections",
-        lambda content: [
-            SimpleNamespace(
-                content="print('x')",
-                content_type=ContentType.SOURCE_CODE,
-                language="python",
-                is_code_fence=True,
-            ),
-            SimpleNamespace(
-                content="after text",
-                content_type=ContentType.PLAIN_TEXT,
-                language=None,
-                is_code_fence=False,
-            ),
-        ],
-    )
-    monkeypatch.setattr(
-        router,
-        "_apply_strategy_to_content",
-        lambda content, strategy, context, language=None, question=None, bias=1.0: (
-            f"{strategy.value}:{content}",
-            len(content.split()) - 1,
-        ),
-    )
-    result = router._compress_mixed(mixed_content, "ctx")
-    assert result.strategy_used is CompressionStrategy.MIXED
-    assert result.sections_processed == 2
-    assert "```python\ncode_aware:print('x')\n```" in result.compressed
-
-    monkeypatch.setattr(
-        router,
-        "_apply_strategy_to_content",
-        lambda content, strategy, context, language=None, question=None, bias=1.0: (
-            "shrunk",
-            1,
-        ),
-    )
-    pure = router._compress_pure("some plain text", CompressionStrategy.TEXT, "ctx")
-    assert pure.routing_log[0].content_type is ContentType.PLAIN_TEXT
-    assert pure.total_original_tokens == 3
-    assert pure.total_compressed_tokens == 1
-
-    calls: list[dict] = []
-    router._toin = SimpleNamespace(record_compression=lambda **kwargs: calls.append(kwargs))
-    monkeypatch.setattr(content_router_module, "_create_content_signature", lambda **kwargs: "sig")
-    router._record_to_toin(
-        CompressionStrategy.TEXT,
-        "original content",
-        "small",
-        original_tokens=10,
-        compressed_tokens=4,
-        language="python",
-        context="question",
-    )
-    assert calls[0]["tool_signature"] == "sig"
-    assert calls[0]["strategy"] == "text"
-    assert calls[0]["query_context"] == "question"
-
-    router._record_to_toin(
-        CompressionStrategy.SMART_CRUSHER,
-        "x",
-        "x",
-        original_tokens=10,
-        compressed_tokens=4,
-    )
-    router._record_to_toin(
-        CompressionStrategy.TEXT,
-        "x",
-        "x",
-        original_tokens=2,
-        compressed_tokens=2,
-    )
-    monkeypatch.setattr(content_router_module, "_create_content_signature", lambda **kwargs: None)
-    router._record_to_toin(
-        CompressionStrategy.TEXT,
-        "x",
-        "y",
-        original_tokens=5,
-        compressed_tokens=1,
-    )
-    assert len(calls) == 1
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+import headroom.transforms.content_router as content_router_module
+from headroom.transforms.content_detector import ContentType, DetectionResult
+from headroom.transforms.content_router import (
+    CompressionCache,
+    CompressionStrategy,
+    ContentRouter,
+    ContentRouterConfig,
+    RouterCompressionResult,
+    RoutingDecision,
+    _create_content_signature,
+    _detect_content,
+    _extract_json_block,
+    is_mixed_content,
+    split_into_sections,
+)
+
+
+def test_compression_cache_handles_hits_skips_evictions_and_clear(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    times = iter([100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 112.0, 112.0])
+    monkeypatch.setattr(content_router_module.time, "time", lambda: next(times))
+    monkeypatch.setattr(content_router_module.time, "perf_counter_ns", lambda: 50)
+
+    cache = CompressionCache(ttl_seconds=10)
+    cache.put(1, "compressed", 0.4, "text")
+    cache.mark_skip(2)
+
+    assert cache.get(1) == ("compressed", 0.4, "text")
+    assert cache.is_skipped(2) is True
+    assert cache.size == 1
+    assert cache.skip_size == 1
+
+    cache.move_to_skip(1)
+    assert cache.get(1) is None
+    assert cache.is_skipped(1) is True
+
+    # Expire both skip entries
+    assert cache.is_skipped(2) is False
+    assert cache.is_skipped(1) is False
+
+    assert cache.stats["cache_hits"] == 1
+    assert cache.stats["cache_skip_hits"] == 2
+    assert cache.stats["cache_misses"] == 1
+    assert cache.stats["cache_evictions"] >= 2
+
+    cache.clear()
+    assert cache.size == 0
+    assert cache.skip_size == 0
+
+
+def test_router_result_helpers_and_summary() -> None:
+    pure = RouterCompressionResult(
+        compressed="small",
+        original="very large",
+        strategy_used=CompressionStrategy.TEXT,
+        routing_log=[
+            RoutingDecision(
+                content_type=ContentType.PLAIN_TEXT,
+                strategy=CompressionStrategy.TEXT,
+                original_tokens=10,
+                compressed_tokens=4,
+            )
+        ],
+    )
+    assert pure.total_original_tokens == 10
+    assert pure.total_compressed_tokens == 4
+    assert pure.compression_ratio == 0.4
+    assert pure.tokens_saved == 6
+    assert pure.savings_percentage == 60.0
+    assert pure.summary() == "Pure text: 10→4 tokens (60% saved)"
+
+    mixed = RouterCompressionResult(
+        compressed="joined",
+        original="original",
+        strategy_used=CompressionStrategy.MIXED,
+        sections_processed=2,
+        routing_log=[
+            RoutingDecision(
+                content_type=ContentType.PLAIN_TEXT,
+                strategy=CompressionStrategy.TEXT,
+                original_tokens=0,
+                compressed_tokens=0,
+            ),
+            RoutingDecision(
+                content_type=ContentType.SEARCH_RESULTS,
+                strategy=CompressionStrategy.SEARCH,
+                original_tokens=8,
+                compressed_tokens=2,
+            ),
+        ],
+    )
+    assert mixed.routing_log[0].compression_ratio == 1.0
+    assert mixed.summary().startswith("Mixed content: 2 sections, routed to ")
+
+
+def test_content_signature_and_detection_helpers(monkeypatch: pytest.MonkeyPatch) -> None:
+    signature = _create_content_signature("search", "file.py:10:match", language="python")
+    assert signature is not None
+    assert len(signature.structure_hash) == 24
+
+    fake_detector = SimpleNamespace(
+        detect=lambda content: SimpleNamespace(
+            content_type=SimpleNamespace(value="code"),
+            confidence=0.91,
+            language="python",
+            raw_label="python",
+        )
+    )
+    monkeypatch.setattr(content_router_module, "_get_magika_detector", lambda: fake_detector)
+    magika_result = _detect_content("def main(): pass")
+    assert magika_result == DetectionResult(
+        content_type=ContentType.SOURCE_CODE,
+        confidence=0.91,
+        metadata={"language": "python", "raw_label": "python"},
+    )
+
+    fallback = DetectionResult(ContentType.PLAIN_TEXT, 0.6, {"kind": "fallback"})
+    monkeypatch.setattr(content_router_module, "_get_magika_detector", lambda: None)
+    monkeypatch.setattr(content_router_module, "detect_content_type", lambda content: fallback)
+    assert _detect_content("plain") is fallback
+
+
+def test_mixed_content_section_splitting_and_json_extraction() -> None:
+    content = "\n".join(
+        [
+            "Intro paragraph with Several words included for prose detection.",
+            "Another line with enough words to read as normal prose today.",
+            "Third line adds more prose so the detector sees real text content.",
+            "Fourth sentence keeps the count moving higher for prose patterns.",
+            "Fifth sentence does the same for mixed content identification.",
+            "Sixth sentence seals the prose threshold for the helper.",
+            "```python",
+            "def main():",
+            "    return 1",
+            "```",
+            '[{"id": 1}]',
+            "src/app.py:10:def main():",
+            "src/app.py:11:return 1",
+        ]
+    )
+    assert is_mixed_content(content) is True
+
+    sections = split_into_sections(content)
+    assert [section.content_type for section in sections] == [
+        ContentType.PLAIN_TEXT,
+        ContentType.SOURCE_CODE,
+        ContentType.JSON_ARRAY,
+        ContentType.SEARCH_RESULTS,
+    ]
+    assert sections[1].language == "python"
+    assert sections[1].is_code_fence is True
+    assert sections[2].content == '[{"id": 1}]'
+    assert sections[3].end_line == 12
+
+    json_block, end_idx = _extract_json_block(["[", '{"id": 1}', "]"], 0)
+    assert json_block == '[\n{"id": 1}\n]'
+    assert end_idx == 2
+    assert _extract_json_block(["{", '"a": 1'], 0) == (None, 0)
+
+
+def test_content_router_strategy_and_compress_paths(monkeypatch: pytest.MonkeyPatch) -> None:
+    router = ContentRouter(ContentRouterConfig(prefer_code_aware_for_code=False))
+
+    monkeypatch.setattr(content_router_module, "is_mixed_content", lambda content: False)
+    monkeypatch.setattr(
+        content_router_module,
+        "_detect_content",
+        lambda content: DetectionResult(ContentType.SOURCE_CODE, 1.0, {}),
+    )
+    assert router._determine_strategy("code") is CompressionStrategy.KOMPRESS
+    assert (
+        router._strategy_from_detection(DetectionResult(ContentType.SEARCH_RESULTS, 1.0, {}))
+        is CompressionStrategy.SEARCH
+    )
+    assert router._strategy_from_detection_type(ContentType.GIT_DIFF) is CompressionStrategy.DIFF
+    assert (
+        router._content_type_from_strategy(CompressionStrategy.PASSTHROUGH)
+        is ContentType.PLAIN_TEXT
+    )
+
+    mixed_result = RouterCompressionResult(
+        compressed="mixed",
+        original="mixed",
+        strategy_used=CompressionStrategy.MIXED,
+    )
+    pure_result = RouterCompressionResult(
+        compressed="pure",
+        original="pure",
+        strategy_used=CompressionStrategy.TEXT,
+    )
+    monkeypatch.setattr(router, "_compress_mixed", lambda *args, **kwargs: mixed_result)
+    monkeypatch.setattr(router, "_compress_pure", lambda *args, **kwargs: pure_result)
+
+    monkeypatch.setattr(router, "_determine_strategy", lambda content: CompressionStrategy.MIXED)
+    assert router.compress("mixed") is mixed_result
+
+    monkeypatch.setattr(router, "_determine_strategy", lambda content: CompressionStrategy.TEXT)
+    assert router.compress("pure") is pure_result
+    assert router.compress("   ").strategy_used is CompressionStrategy.PASSTHROUGH
+
+
+def test_content_router_mixed_pure_apply_and_toin(monkeypatch: pytest.MonkeyPatch) -> None:
+    router = ContentRouter()
+    mixed_content = "\n".join(["before", "```python", "print('x')", "```", "after"])
+    monkeypatch.setattr(
+        content_router_module,
+        "split_into_sections",
+        lambda content: [
+            SimpleNamespace(
+                content="print('x')",
+                content_type=ContentType.SOURCE_CODE,
+                language="python",
+                is_code_fence=True,
+            ),
+            SimpleNamespace(
+                content="after text",
+                content_type=ContentType.PLAIN_TEXT,
+                language=None,
+                is_code_fence=False,
+            ),
+        ],
+    )
+    monkeypatch.setattr(
+        router,
+        "_apply_strategy_to_content",
+        lambda content, strategy, context, language=None, question=None, bias=1.0: (
+            f"{strategy.value}:{content}",
+            len(content.split()) - 1,
+        ),
+    )
+    result = router._compress_mixed(mixed_content, "ctx")
+    assert result.strategy_used is CompressionStrategy.MIXED
+    assert result.sections_processed == 2
+    assert "```python\ncode_aware:print('x')\n```" in result.compressed
+
+    monkeypatch.setattr(
+        router,
+        "_apply_strategy_to_content",
+        lambda content, strategy, context, language=None, question=None, bias=1.0: (
+            "shrunk",
+            1,
+        ),
+    )
+    pure = router._compress_pure("some plain text", CompressionStrategy.TEXT, "ctx")
+    assert pure.routing_log[0].content_type is ContentType.PLAIN_TEXT
+    assert pure.total_original_tokens == 3
+    assert pure.total_compressed_tokens == 1
+
+    calls: list[dict] = []
+    router._toin = SimpleNamespace(record_compression=lambda **kwargs: calls.append(kwargs))
+    monkeypatch.setattr(content_router_module, "_create_content_signature", lambda **kwargs: "sig")
+    router._record_to_toin(
+        CompressionStrategy.TEXT,
+        "original content",
+        "small",
+        original_tokens=10,
+        compressed_tokens=4,
+        language="python",
+        context="question",
+    )
+    assert calls[0]["tool_signature"] == "sig"
+    assert calls[0]["strategy"] == "text"
+    assert calls[0]["query_context"] == "question"
+
+    router._record_to_toin(
+        CompressionStrategy.SMART_CRUSHER,
+        "x",
+        "x",
+        original_tokens=10,
+        compressed_tokens=4,
+    )
+    router._record_to_toin(
+        CompressionStrategy.TEXT,
+        "x",
+        "x",
+        original_tokens=2,
+        compressed_tokens=2,
+    )
+    monkeypatch.setattr(content_router_module, "_create_content_signature", lambda **kwargs: None)
+    router._record_to_toin(
+        CompressionStrategy.TEXT,
+        "x",
+        "y",
+        original_tokens=5,
+        compressed_tokens=1,
+    )
+    assert len(calls) == 1
diff --git a/tests/test_transforms_log_compressor.py b/tests/test_transforms_log_compressor.py
index b273bb8465151f4dbed7e14d953081037e02fd74..b31649a0a3c477d74c34a072d364c8ca8cae14f4 100644
--- a/tests/test_transforms_log_compressor.py
+++ b/tests/test_transforms_log_compressor.py
@@ -1,183 +1,183 @@
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-import pytest
-
-from headroom.transforms.log_compressor import (
-    LogCompressionResult,
-    LogCompressor,
-    LogCompressorConfig,
-    LogFormat,
-    LogLevel,
-    LogLine,
-)
-
-
-def test_detect_parse_and_score_log_lines() -> None:
-    compressor = LogCompressor(LogCompressorConfig(stack_trace_max_lines=2))
-    pytest_lines = [
-        "============================= test session starts =============================",
-        "collected 2 items",
-        "ERROR critical failure",
-        "Traceback (most recent call last)",
-        '  File "app.py", line 10',
-        "",
-        "2 failed, 1 warning",
-    ]
-    assert compressor._detect_format(pytest_lines) is LogFormat.PYTEST
-    assert compressor._detect_format(["npm ERR! missing script"]) is LogFormat.NPM
-    assert compressor._detect_format(["Compiling app", "warning: check this"]) is LogFormat.CARGO
-    assert (
-        compressor._detect_format(["PASS src/app.test.js", "Test Suites: 1 failed"])
-        is LogFormat.JEST
-    )
-    assert compressor._detect_format(["make: *** fail", "gcc -o app app.c"]) is LogFormat.MAKE
-    assert compressor._detect_format(["unclassified line"]) is LogFormat.GENERIC
-
-    parsed = compressor._parse_lines(pytest_lines)
-    assert parsed[0].is_summary is True
-    assert parsed[2].level is LogLevel.ERROR
-    assert parsed[3].is_stack_trace is True
-    assert parsed[4].is_stack_trace is True
-    assert parsed[6].is_summary is True
-    assert compressor._score_line(LogLine(1, "warn", level=LogLevel.WARN)) == 0.5
-    assert (
-        compressor._score_line(
-            LogLine(2, "error summary", level=LogLevel.ERROR, is_stack_trace=True, is_summary=True)
-        )
-        == 1.0
-    )
-
-
-def test_select_dedupe_add_context_and_format_output(monkeypatch: pytest.MonkeyPatch) -> None:
-    compressor = LogCompressor(
-        LogCompressorConfig(
-            max_errors=2,
-            max_warnings=1,
-            error_context_lines=1,
-            max_stack_traces=1,
-            stack_trace_max_lines=2,
-        )
-    )
-    monkeypatch.setitem(
-        __import__("sys").modules,
-        "headroom.transforms.adaptive_sizer",
-        SimpleNamespace(compute_optimal_k=lambda items, **kwargs: 6),
-    )
-    log_lines = [
-        LogLine(0, "info line", level=LogLevel.INFO, score=0.1),
-        LogLine(1, "ERROR first", level=LogLevel.ERROR, score=1.0),
-        LogLine(2, "context after first", level=LogLevel.UNKNOWN, score=0.1),
-        LogLine(3, "WARNING /tmp/a/123 issue", level=LogLevel.WARN, score=0.5),
-        LogLine(4, "WARNING /tmp/b/999 issue", level=LogLevel.WARN, score=0.5),
-        LogLine(5, "FAIL final", level=LogLevel.FAIL, score=1.0),
-        LogLine(6, "Traceback (most recent call last)", is_stack_trace=True, score=0.4),
-        LogLine(7, '  File "app.py", line 2', is_stack_trace=True, score=0.4),
-        LogLine(8, "1 failed, 1 warning", is_summary=True, score=0.5),
-    ]
-    selected = compressor._select_lines(log_lines)
-    assert [line.line_number for line in selected] == [1, 3, 4, 5, 6, 8]
-
-    assert compressor._select_with_first_last(log_lines[:2], max_count=5) == log_lines[:2]
-    many_errors = [
-        LogLine(10, "first", level=LogLevel.ERROR, score=0.1),
-        LogLine(11, "mid", level=LogLevel.ERROR, score=0.9),
-        LogLine(12, "last", level=LogLevel.ERROR, score=0.2),
-    ]
-    trimmed = compressor._select_with_first_last(many_errors, max_count=2)
-    assert trimmed == [many_errors[0], many_errors[2]]
-    deduped = compressor._dedupe_similar(log_lines[3:5])
-    assert len(deduped) == 1
-
-    output, stats = compressor._format_output(selected, log_lines)
-    assert stats == {
-        "errors": 1,
-        "fails": 1,
-        "warnings": 2,
-        "info": 1,
-        "total": 9,
-        "selected": 6,
-    }
-    assert output.endswith("[3 lines omitted: 1 ERROR, 1 FAIL, 2 WARN, 1 INFO]")
-
-
-def test_log_compressor_compress_and_ccr_paths(monkeypatch: pytest.MonkeyPatch) -> None:
-    compressor = LogCompressor(LogCompressorConfig(enable_ccr=True, min_lines_for_ccr=3))
-    short = compressor.compress("a\nb")
-    assert short.format_detected is LogFormat.GENERIC
-    assert short.compression_ratio == 1.0
-
-    monkeypatch.setattr(compressor, "_detect_format", lambda lines: LogFormat.NPM)
-    parsed = [LogLine(0, "npm ERR! boom", level=LogLevel.ERROR, score=1.0)]
-    monkeypatch.setattr(compressor, "_parse_lines", lambda lines: parsed)
-    monkeypatch.setattr(compressor, "_select_lines", lambda log_lines, bias=1.0: parsed)
-    monkeypatch.setattr(
-        compressor,
-        "_format_output",
-        lambda selected, all_lines: (
-            "tiny",
-            {"errors": 1, "fails": 0, "warnings": 0, "info": 0, "total": 3, "selected": 1},
-        ),
-    )
-    monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: "deadbeef")
-    result = compressor.compress(
-        "x\ny\nz\nvery verbose fourth line to improve compression ratio math"
-    )
-    assert result.format_detected is LogFormat.NPM
-    assert result.cache_key == "deadbeef"
-    assert result.stats["errors"] == 1
-    assert result.compressed.endswith("[4 lines compressed to 1. Retrieve more: hash=deadbeef]")
-
-    monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: None)
-    no_cache = compressor.compress(
-        "x\ny\nz\nvery verbose fourth line to improve compression ratio math"
-    )
-    assert no_cache.cache_key is None
-    assert no_cache.compressed == "tiny"
-
-    monkeypatch.setattr(
-        compressor,
-        "_format_output",
-        lambda selected, all_lines: (
-            "this output is intentionally much longer than the original content",
-            {"errors": 1, "fails": 0, "warnings": 0, "info": 0, "total": 4, "selected": 1},
-        ),
-    )
-    high_ratio = compressor.compress("x\ny\nz\nw")
-    assert high_ratio.cache_key is None
-
-
-def test_store_in_ccr_and_result_properties(monkeypatch: pytest.MonkeyPatch) -> None:
-    compressor = LogCompressor()
-    monkeypatch.setitem(
-        __import__("sys").modules,
-        "headroom.cache.compression_store",
-        SimpleNamespace(
-            get_compression_store=lambda: SimpleNamespace(
-                store=lambda original, compressed, original_item_count=0: "stored-log"
-            )
-        ),
-    )
-    assert compressor._store_in_ccr("orig", "comp", 10) == "stored-log"
-
-    def broken_store():
-        raise RuntimeError("boom")
-
-    monkeypatch.setitem(
-        __import__("sys").modules,
-        "headroom.cache.compression_store",
-        SimpleNamespace(get_compression_store=broken_store),
-    )
-    assert compressor._store_in_ccr("orig", "comp", 10) is None
-
-    result = LogCompressionResult(
-        compressed="small",
-        original="this is a substantially longer log body",
-        original_line_count=20,
-        compressed_line_count=5,
-        format_detected=LogFormat.GENERIC,
-        compression_ratio=0.25,
-    )
-    assert result.tokens_saved_estimate > 0
-    assert result.lines_omitted == 15
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from headroom.transforms.log_compressor import (
+    LogCompressionResult,
+    LogCompressor,
+    LogCompressorConfig,
+    LogFormat,
+    LogLevel,
+    LogLine,
+)
+
+
+def test_detect_parse_and_score_log_lines() -> None:
+    compressor = LogCompressor(LogCompressorConfig(stack_trace_max_lines=2))
+    pytest_lines = [
+        "============================= test session starts =============================",
+        "collected 2 items",
+        "ERROR critical failure",
+        "Traceback (most recent call last)",
+        '  File "app.py", line 10',
+        "",
+        "2 failed, 1 warning",
+    ]
+    assert compressor._detect_format(pytest_lines) is LogFormat.PYTEST
+    assert compressor._detect_format(["npm ERR! missing script"]) is LogFormat.NPM
+    assert compressor._detect_format(["Compiling app", "warning: check this"]) is LogFormat.CARGO
+    assert (
+        compressor._detect_format(["PASS src/app.test.js", "Test Suites: 1 failed"])
+        is LogFormat.JEST
+    )
+    assert compressor._detect_format(["make: *** fail", "gcc -o app app.c"]) is LogFormat.MAKE
+    assert compressor._detect_format(["unclassified line"]) is LogFormat.GENERIC
+
+    parsed = compressor._parse_lines(pytest_lines)
+    assert parsed[0].is_summary is True
+    assert parsed[2].level is LogLevel.ERROR
+    assert parsed[3].is_stack_trace is True
+    assert parsed[4].is_stack_trace is True
+    assert parsed[6].is_summary is True
+    assert compressor._score_line(LogLine(1, "warn", level=LogLevel.WARN)) == 0.5
+    assert (
+        compressor._score_line(
+            LogLine(2, "error summary", level=LogLevel.ERROR, is_stack_trace=True, is_summary=True)
+        )
+        == 1.0
+    )
+
+
+def test_select_dedupe_add_context_and_format_output(monkeypatch: pytest.MonkeyPatch) -> None:
+    compressor = LogCompressor(
+        LogCompressorConfig(
+            max_errors=2,
+            max_warnings=1,
+            error_context_lines=1,
+            max_stack_traces=1,
+            stack_trace_max_lines=2,
+        )
+    )
+    monkeypatch.setitem(
+        __import__("sys").modules,
+        "headroom.transforms.adaptive_sizer",
+        SimpleNamespace(compute_optimal_k=lambda items, **kwargs: 6),
+    )
+    log_lines = [
+        LogLine(0, "info line", level=LogLevel.INFO, score=0.1),
+        LogLine(1, "ERROR first", level=LogLevel.ERROR, score=1.0),
+        LogLine(2, "context after first", level=LogLevel.UNKNOWN, score=0.1),
+        LogLine(3, "WARNING /tmp/a/123 issue", level=LogLevel.WARN, score=0.5),
+        LogLine(4, "WARNING /tmp/b/999 issue", level=LogLevel.WARN, score=0.5),
+        LogLine(5, "FAIL final", level=LogLevel.FAIL, score=1.0),
+        LogLine(6, "Traceback (most recent call last)", is_stack_trace=True, score=0.4),
+        LogLine(7, '  File "app.py", line 2', is_stack_trace=True, score=0.4),
+        LogLine(8, "1 failed, 1 warning", is_summary=True, score=0.5),
+    ]
+    selected = compressor._select_lines(log_lines)
+    assert [line.line_number for line in selected] == [1, 3, 4, 5, 6, 8]
+
+    assert compressor._select_with_first_last(log_lines[:2], max_count=5) == log_lines[:2]
+    many_errors = [
+        LogLine(10, "first", level=LogLevel.ERROR, score=0.1),
+        LogLine(11, "mid", level=LogLevel.ERROR, score=0.9),
+        LogLine(12, "last", level=LogLevel.ERROR, score=0.2),
+    ]
+    trimmed = compressor._select_with_first_last(many_errors, max_count=2)
+    assert trimmed == [many_errors[0], many_errors[2]]
+    deduped = compressor._dedupe_similar(log_lines[3:5])
+    assert len(deduped) == 1
+
+    output, stats = compressor._format_output(selected, log_lines)
+    assert stats == {
+        "errors": 1,
+        "fails": 1,
+        "warnings": 2,
+        "info": 1,
+        "total": 9,
+        "selected": 6,
+    }
+    assert output.endswith("[3 lines omitted: 1 ERROR, 1 FAIL, 2 WARN, 1 INFO]")
+
+
+def test_log_compressor_compress_and_ccr_paths(monkeypatch: pytest.MonkeyPatch) -> None:
+    compressor = LogCompressor(LogCompressorConfig(enable_ccr=True, min_lines_for_ccr=3))
+    short = compressor.compress("a\nb")
+    assert short.format_detected is LogFormat.GENERIC
+    assert short.compression_ratio == 1.0
+
+    monkeypatch.setattr(compressor, "_detect_format", lambda lines: LogFormat.NPM)
+    parsed = [LogLine(0, "npm ERR! boom", level=LogLevel.ERROR, score=1.0)]
+    monkeypatch.setattr(compressor, "_parse_lines", lambda lines: parsed)
+    monkeypatch.setattr(compressor, "_select_lines", lambda log_lines, bias=1.0: parsed)
+    monkeypatch.setattr(
+        compressor,
+        "_format_output",
+        lambda selected, all_lines: (
+            "tiny",
+            {"errors": 1, "fails": 0, "warnings": 0, "info": 0, "total": 3, "selected": 1},
+        ),
+    )
+    monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: "deadbeef")
+    result = compressor.compress(
+        "x\ny\nz\nvery verbose fourth line to improve compression ratio math"
+    )
+    assert result.format_detected is LogFormat.NPM
+    assert result.cache_key == "deadbeef"
+    assert result.stats["errors"] == 1
+    assert result.compressed.endswith("[4 lines compressed to 1. Retrieve more: hash=deadbeef]")
+
+    monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: None)
+    no_cache = compressor.compress(
+        "x\ny\nz\nvery verbose fourth line to improve compression ratio math"
+    )
+    assert no_cache.cache_key is None
+    assert no_cache.compressed == "tiny"
+
+    monkeypatch.setattr(
+        compressor,
+        "_format_output",
+        lambda selected, all_lines: (
+            "this output is intentionally much longer than the original content",
+            {"errors": 1, "fails": 0, "warnings": 0, "info": 0, "total": 4, "selected": 1},
+        ),
+    )
+    high_ratio = compressor.compress("x\ny\nz\nw")
+    assert high_ratio.cache_key is None
+
+
+def test_store_in_ccr_and_result_properties(monkeypatch: pytest.MonkeyPatch) -> None:
+    compressor = LogCompressor()
+    monkeypatch.setitem(
+        __import__("sys").modules,
+        "headroom.cache.compression_store",
+        SimpleNamespace(
+            get_compression_store=lambda: SimpleNamespace(
+                store=lambda original, compressed, original_item_count=0: "stored-log"
+            )
+        ),
+    )
+    assert compressor._store_in_ccr("orig", "comp", 10) == "stored-log"
+
+    def broken_store():
+        raise RuntimeError("boom")
+
+    monkeypatch.setitem(
+        __import__("sys").modules,
+        "headroom.cache.compression_store",
+        SimpleNamespace(get_compression_store=broken_store),
+    )
+    assert compressor._store_in_ccr("orig", "comp", 10) is None
+
+    result = LogCompressionResult(
+        compressed="small",
+        original="this is a substantially longer log body",
+        original_line_count=20,
+        compressed_line_count=5,
+        format_detected=LogFormat.GENERIC,
+        compression_ratio=0.25,
+    )
+    assert result.tokens_saved_estimate > 0
+    assert result.lines_omitted == 15
diff --git a/tests/test_transforms_package.py b/tests/test_transforms_package.py
index 95b604a8bc1ba289f91159feb6879ba78a14f589..97eb1b6ca76ac91c83de89f858e61d828a6e8185 100644
--- a/tests/test_transforms_package.py
+++ b/tests/test_transforms_package.py
@@ -1,26 +1,26 @@
-from __future__ import annotations
-
-import pytest
-
-import headroom.transforms as transforms
-
-
-def test_transforms_getattr_and_dir(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setattr(transforms, "_HTML_EXTRACTOR_AVAILABLE", True)
-    monkeypatch.setattr(
-        transforms,
-        "_LAZY_EXPORTS",
-        {"FakeExport": ("fake.module", "VALUE")},
-    )
-    monkeypatch.setattr(transforms, "import_module", lambda name: type("M", (), {"VALUE": 123})())
-
-    assert transforms.__getattr__("_HTML_EXTRACTOR_AVAILABLE") is True
-    assert transforms.__getattr__("FakeExport") == 123
-    assert transforms.FakeExport == 123
-    assert "FakeExport" in transforms.__dir__()
-
-    with pytest.raises(AttributeError, match="__path__"):
-        transforms.__getattr__("__path__")
-
-    with pytest.raises(AttributeError, match="MissingExport"):
-        transforms.__getattr__("MissingExport")
+from __future__ import annotations
+
+import pytest
+
+import headroom.transforms as transforms
+
+
+def test_transforms_getattr_and_dir(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(transforms, "_HTML_EXTRACTOR_AVAILABLE", True)
+    monkeypatch.setattr(
+        transforms,
+        "_LAZY_EXPORTS",
+        {"FakeExport": ("fake.module", "VALUE")},
+    )
+    monkeypatch.setattr(transforms, "import_module", lambda name: type("M", (), {"VALUE": 123})())
+
+    assert transforms.__getattr__("_HTML_EXTRACTOR_AVAILABLE") is True
+    assert transforms.__getattr__("FakeExport") == 123
+    assert transforms.FakeExport == 123
+    assert "FakeExport" in transforms.__dir__()
+
+    with pytest.raises(AttributeError, match="__path__"):
+        transforms.__getattr__("__path__")
+
+    with pytest.raises(AttributeError, match="MissingExport"):
+        transforms.__getattr__("MissingExport")
diff --git a/tests/test_transforms_search_compressor.py b/tests/test_transforms_search_compressor.py
index a2473347ef6b32d88679558f18cf7462de36331c..76d90b0b2cec1bba8c53b655e776961cb1bc00fe 100644
--- a/tests/test_transforms_search_compressor.py
+++ b/tests/test_transforms_search_compressor.py
@@ -1,143 +1,143 @@
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-import pytest
-
-from headroom.transforms.search_compressor import (
-    FileMatches,
-    SearchCompressionResult,
-    SearchCompressor,
-    SearchCompressorConfig,
-    SearchMatch,
-)
-
-
-def test_parse_score_select_and_format_search_results(monkeypatch: pytest.MonkeyPatch) -> None:
-    compressor = SearchCompressor(
-        SearchCompressorConfig(
-            max_matches_per_file=3,
-            max_total_matches=4,
-            max_files=2,
-            context_keywords=["auth"],
-        )
-    )
-    content = "\n".join(
-        [
-            "src/auth.py:10:ERROR auth failed",
-            "src/auth.py-11-warning auth retry",
-            "src/auth.py:12:plain auth line",
-            "src/db.py:2:warning token expired",
-            "not a match",
-        ]
-    )
-    parsed = compressor._parse_search_results(content)
-    assert set(parsed) == {"src/auth.py", "src/db.py"}
-    assert parsed["src/auth.py"].first == SearchMatch(
-        file="src/auth.py", line_number=10, content="ERROR auth failed"
-    )
-    assert parsed["src/auth.py"].last.line_number == 12
-
-    compressor._score_matches(parsed, "find auth error")
-    assert parsed["src/auth.py"].matches[0].score == 1.0
-    assert parsed["src/db.py"].matches[0].score > 0
-
-    monkeypatch.setitem(
-        __import__("sys").modules,
-        "headroom.transforms.adaptive_sizer",
-        SimpleNamespace(compute_optimal_k=lambda items, **kwargs: 4),
-    )
-    selected = compressor._select_matches(parsed, bias=1.2)
-    assert list(selected) == ["src/auth.py", "src/db.py"]
-    assert [m.line_number for m in selected["src/auth.py"].matches] == [10, 11, 12]
-
-    formatted, summaries = compressor._format_output(
-        selected,
-        {
-            **parsed,
-            "src/db.py": FileMatches(
-                file="src/db.py",
-                matches=[
-                    SearchMatch(file="src/db.py", line_number=2, content="warning token expired"),
-                    SearchMatch(file="src/db.py", line_number=3, content="another line"),
-                ],
-            ),
-        },
-    )
-    assert "src/auth.py:10:ERROR auth failed" in formatted
-    assert summaries["src/db.py"] == "[... and 1 more matches in src/db.py]"
-
-
-def test_search_compressor_compress_paths_and_ccr(monkeypatch: pytest.MonkeyPatch) -> None:
-    compressor = SearchCompressor(
-        SearchCompressorConfig(enable_ccr=True, min_matches_for_ccr=2, context_keywords=["auth"])
-    )
-    no_match = compressor.compress("plain text only")
-    assert no_match.original_match_count == 0
-    assert no_match.compressed == "plain text only"
-
-    parsed = {
-        "src/auth.py": FileMatches(
-            file="src/auth.py",
-            matches=[
-                SearchMatch(file="src/auth.py", line_number=1, content="auth error"),
-                SearchMatch(file="src/auth.py", line_number=2, content="auth ok"),
-            ],
-        )
-    }
-    monkeypatch.setattr(compressor, "_parse_search_results", lambda content: parsed)
-    monkeypatch.setattr(compressor, "_score_matches", lambda file_matches, context: None)
-    monkeypatch.setattr(compressor, "_select_matches", lambda file_matches, bias=1.0: parsed)
-    monkeypatch.setattr(
-        compressor,
-        "_format_output",
-        lambda selected, original: ("short", {"src/auth.py": "summary"}),
-    )
-    monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: "abc123")
-
-    result = compressor.compress("raw search", context="auth", bias=0.8)
-    assert result.original_match_count == 2
-    assert result.compressed_match_count == 2
-    assert result.cache_key == "abc123"
-    assert result.summaries == {"src/auth.py": "summary"}
-    assert result.compressed.endswith("[2 matches compressed to 2. Retrieve more: hash=abc123]")
-
-    monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: None)
-    no_cache = compressor.compress("raw search", context="auth")
-    assert no_cache.cache_key is None
-    assert no_cache.compressed == "short"
-
-
-def test_store_in_ccr_and_result_properties(monkeypatch: pytest.MonkeyPatch) -> None:
-    compressor = SearchCompressor()
-    monkeypatch.setitem(
-        __import__("sys").modules,
-        "headroom.cache.compression_store",
-        SimpleNamespace(
-            get_compression_store=lambda: SimpleNamespace(
-                store=lambda original, compressed, original_item_count=0: "stored-key"
-            )
-        ),
-    )
-    assert compressor._store_in_ccr("orig", "comp", 5) == "stored-key"
-
-    def broken_store():
-        raise RuntimeError("boom")
-
-    monkeypatch.setitem(
-        __import__("sys").modules,
-        "headroom.cache.compression_store",
-        SimpleNamespace(get_compression_store=broken_store),
-    )
-    assert compressor._store_in_ccr("orig", "comp", 5) is None
-
-    result = SearchCompressionResult(
-        compressed="tiny",
-        original="this is a much longer original string",
-        original_match_count=10,
-        compressed_match_count=4,
-        files_affected=2,
-        compression_ratio=0.3,
-    )
-    assert result.tokens_saved_estimate > 0
-    assert result.matches_omitted == 6
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from headroom.transforms.search_compressor import (
+    FileMatches,
+    SearchCompressionResult,
+    SearchCompressor,
+    SearchCompressorConfig,
+    SearchMatch,
+)
+
+
+def test_parse_score_select_and_format_search_results(monkeypatch: pytest.MonkeyPatch) -> None:
+    compressor = SearchCompressor(
+        SearchCompressorConfig(
+            max_matches_per_file=3,
+            max_total_matches=4,
+            max_files=2,
+            context_keywords=["auth"],
+        )
+    )
+    content = "\n".join(
+        [
+            "src/auth.py:10:ERROR auth failed",
+            "src/auth.py-11-warning auth retry",
+            "src/auth.py:12:plain auth line",
+            "src/db.py:2:warning token expired",
+            "not a match",
+        ]
+    )
+    parsed = compressor._parse_search_results(content)
+    assert set(parsed) == {"src/auth.py", "src/db.py"}
+    assert parsed["src/auth.py"].first == SearchMatch(
+        file="src/auth.py", line_number=10, content="ERROR auth failed"
+    )
+    assert parsed["src/auth.py"].last.line_number == 12
+
+    compressor._score_matches(parsed, "find auth error")
+    assert parsed["src/auth.py"].matches[0].score == 1.0
+    assert parsed["src/db.py"].matches[0].score > 0
+
+    monkeypatch.setitem(
+        __import__("sys").modules,
+        "headroom.transforms.adaptive_sizer",
+        SimpleNamespace(compute_optimal_k=lambda items, **kwargs: 4),
+    )
+    selected = compressor._select_matches(parsed, bias=1.2)
+    assert list(selected) == ["src/auth.py", "src/db.py"]
+    assert [m.line_number for m in selected["src/auth.py"].matches] == [10, 11, 12]
+
+    formatted, summaries = compressor._format_output(
+        selected,
+        {
+            **parsed,
+            "src/db.py": FileMatches(
+                file="src/db.py",
+                matches=[
+                    SearchMatch(file="src/db.py", line_number=2, content="warning token expired"),
+                    SearchMatch(file="src/db.py", line_number=3, content="another line"),
+                ],
+            ),
+        },
+    )
+    assert "src/auth.py:10:ERROR auth failed" in formatted
+    assert summaries["src/db.py"] == "[... and 1 more matches in src/db.py]"
+
+
+def test_search_compressor_compress_paths_and_ccr(monkeypatch: pytest.MonkeyPatch) -> None:
+    compressor = SearchCompressor(
+        SearchCompressorConfig(enable_ccr=True, min_matches_for_ccr=2, context_keywords=["auth"])
+    )
+    no_match = compressor.compress("plain text only")
+    assert no_match.original_match_count == 0
+    assert no_match.compressed == "plain text only"
+
+    parsed = {
+        "src/auth.py": FileMatches(
+            file="src/auth.py",
+            matches=[
+                SearchMatch(file="src/auth.py", line_number=1, content="auth error"),
+                SearchMatch(file="src/auth.py", line_number=2, content="auth ok"),
+            ],
+        )
+    }
+    monkeypatch.setattr(compressor, "_parse_search_results", lambda content: parsed)
+    monkeypatch.setattr(compressor, "_score_matches", lambda file_matches, context: None)
+    monkeypatch.setattr(compressor, "_select_matches", lambda file_matches, bias=1.0: parsed)
+    monkeypatch.setattr(
+        compressor,
+        "_format_output",
+        lambda selected, original: ("short", {"src/auth.py": "summary"}),
+    )
+    monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: "abc123")
+
+    result = compressor.compress("raw search", context="auth", bias=0.8)
+    assert result.original_match_count == 2
+    assert result.compressed_match_count == 2
+    assert result.cache_key == "abc123"
+    assert result.summaries == {"src/auth.py": "summary"}
+    assert result.compressed.endswith("[2 matches compressed to 2. Retrieve more: hash=abc123]")
+
+    monkeypatch.setattr(compressor, "_store_in_ccr", lambda original, compressed, count: None)
+    no_cache = compressor.compress("raw search", context="auth")
+    assert no_cache.cache_key is None
+    assert no_cache.compressed == "short"
+
+
+def test_store_in_ccr_and_result_properties(monkeypatch: pytest.MonkeyPatch) -> None:
+    compressor = SearchCompressor()
+    monkeypatch.setitem(
+        __import__("sys").modules,
+        "headroom.cache.compression_store",
+        SimpleNamespace(
+            get_compression_store=lambda: SimpleNamespace(
+                store=lambda original, compressed, original_item_count=0: "stored-key"
+            )
+        ),
+    )
+    assert compressor._store_in_ccr("orig", "comp", 5) == "stored-key"
+
+    def broken_store():
+        raise RuntimeError("boom")
+
+    monkeypatch.setitem(
+        __import__("sys").modules,
+        "headroom.cache.compression_store",
+        SimpleNamespace(get_compression_store=broken_store),
+    )
+    assert compressor._store_in_ccr("orig", "comp", 5) is None
+
+    result = SearchCompressionResult(
+        compressed="tiny",
+        original="this is a much longer original string",
+        original_match_count=10,
+        compressed_match_count=4,
+        files_affected=2,
+        compression_ratio=0.3,
+    )
+    assert result.tokens_saved_estimate > 0
+    assert result.matches_omitted == 6
diff --git a/tests/test_utils.py b/tests/test_utils.py
index 5e6b6bbf0cd004fc88979493d3bced35bcc28f0c..7d78bb27daa89d34a235b1fd0f8887f9c3d58403 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -1,122 +1,122 @@
-from __future__ import annotations
-
-from datetime import datetime
-
-from headroom import utils
-
-
-class FakeProvider:
-    def __init__(self, result):
-        self.result = result
-        self.calls: list[tuple[int, int, str, int]] = []
-
-    def estimate_cost(
-        self, input_tokens: int, output_tokens: int, model: str, cached_tokens: int = 0
-    ):
-        self.calls.append((input_tokens, output_tokens, model, cached_tokens))
-        return self.result
-
-
-def test_hash_helpers_and_request_id() -> None:
-    request_id = utils.generate_request_id()
-    assert len(request_id) == 36
-    assert request_id.count("-") == 4
-
-    assert (
-        utils.compute_hash("hello")
-        == "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
-    )
-    assert utils.compute_hash("hi\ud800") == utils.compute_hash(
-        "hi\ud800".encode("utf-8", "surrogatepass")
-    )
-    assert utils.compute_short_hash("hello", length=8) == "2cf24dba"
-    assert utils.fast_hash("hello", length=8) == "5d41402a"
-
-
-def test_extract_user_query_and_message_hashes() -> None:
-    messages = [
-        {"role": "system", "content": "rules"},
-        {"role": "user", "content": "   "},
-        {"role": "assistant", "content": "skip"},
-        {
-            "role": "user",
-            "content": [{"type": "image"}, {"type": "text", "text": "  latest question  "}],
-        },
-    ]
-    assert utils.extract_user_query(messages) == "latest question"
-    assert utils.extract_user_query([{"role": "assistant", "content": "skip"}]) == ""
-
-    hash_one = utils.compute_messages_hash(messages)
-    hash_two = utils.compute_messages_hash(list(messages))
-    assert hash_one == hash_two
-    assert len(hash_one) == 16
-
-    prefix_default = utils.compute_prefix_hash(
-        [
-            {"role": "system", "content": "a"},
-            {"role": "system", "content": "b"},
-            {"role": "user", "content": "c"},
-            {"role": "assistant", "content": "d"},
-        ]
-    )
-    prefix_explicit = utils.compute_prefix_hash(
-        [
-            {"role": "system", "content": "a"},
-            {"role": "system", "content": "b"},
-            {"role": "user", "content": "c"},
-            {"role": "assistant", "content": "d"},
-        ],
-        prefix_count=3,
-    )
-    assert prefix_default == prefix_explicit
-    assert utils.compute_prefix_hash([]) == utils.compute_short_hash("")
-
-
-def test_timestamp_marker_and_json_helpers() -> None:
-    ts = utils.format_timestamp(datetime(2026, 4, 23, 6, 0, 0))
-    assert ts == "2026-04-23T06:00:00Z"
-    assert utils.parse_timestamp(ts) == datetime(2026, 4, 23, 6, 0, 0)
-    assert utils.parse_timestamp("2026-04-23T06:00:00") == datetime(2026, 4, 23, 6, 0, 0)
-
-    marker = utils.create_marker("tool_digest", sha256="abc", count="2")
-    assert marker == '<headroom:tool_digest sha256="abc" count="2">'
-    assert utils.create_tool_digest_marker("abc") == '<headroom:tool_digest sha256="abc">'
-    assert utils.create_dropped_context_marker("budget") == (
-        '<headroom:dropped_context reason="budget">'
-    )
-    assert utils.create_dropped_context_marker("budget", count=4) == (
-        '<headroom:dropped_context reason="budget" count="4">'
-    )
-    assert utils.create_truncated_marker(100, 25) == (
-        '<headroom:truncated original="100" truncated_to="25">'
-    )
-
-    extracted = utils.extract_markers(
-        'x <headroom:tool_digest sha256="abc"> y <headroom:dropped_context reason="budget" count="2">'
-    )
-    assert extracted == [
-        {"type": "tool_digest", "attributes": {"sha256": "abc"}},
-        {"type": "dropped_context", "attributes": {"reason": "budget", "count": "2"}},
-    ]
-
-    assert utils.safe_json_loads('{"ok": true}') == ({"ok": True}, True)
-    assert utils.safe_json_loads("{bad") == (None, False)
-    assert utils.safe_json_dumps({"emoji": "café"}) == '{"emoji":"café"}'
-
-
-def test_cost_formatting_and_deep_copy() -> None:
-    provider = FakeProvider("1.25")
-    assert utils.estimate_cost(100, 50, "gpt-4o", cached_tokens=10, provider=provider) == 1.25
-    assert provider.calls == [(100, 50, "gpt-4o", 10)]
-    assert utils.estimate_cost(1, 1, "gpt-4o", provider=None) is None
-
-    none_provider = FakeProvider(None)
-    assert utils.estimate_cost(1, 1, "gpt-4o", provider=none_provider) is None
-
-    assert utils.format_cost(0.0099) == "$0.0099"
-    assert utils.format_cost(1.234) == "$1.23"
-
-    messages = [{"role": "user", "content": {"nested": ["a"]}}]
-    copied = utils.deep_copy_messages(messages)
-    copied[0]["content"]["nested"].append("b")
-    assert messages == [{"role": "user", "content": {"nested": ["a"]}}]
+from __future__ import annotations
+
+from datetime import datetime
+
+from headroom import utils
+
+
+class FakeProvider:
+    def __init__(self, result):
+        self.result = result
+        self.calls: list[tuple[int, int, str, int]] = []
+
+    def estimate_cost(
+        self, input_tokens: int, output_tokens: int, model: str, cached_tokens: int = 0
+    ):
+        self.calls.append((input_tokens, output_tokens, model, cached_tokens))
+        return self.result
+
+
+def test_hash_helpers_and_request_id() -> None:
+    request_id = utils.generate_request_id()
+    assert len(request_id) == 36
+    assert request_id.count("-") == 4
+
+    assert (
+        utils.compute_hash("hello")
+        == "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+    )
+    assert utils.compute_hash("hi\ud800") == utils.compute_hash(
+        "hi\ud800".encode("utf-8", "surrogatepass")
+    )
+    assert utils.compute_short_hash("hello", length=8) == "2cf24dba"
+    assert utils.fast_hash("hello", length=8) == "5d41402a"
+
+
+def test_extract_user_query_and_message_hashes() -> None:
+    messages = [
+        {"role": "system", "content": "rules"},
+        {"role": "user", "content": "   "},
+        {"role": "assistant", "content": "skip"},
+        {
+            "role": "user",
+            "content": [{"type": "image"}, {"type": "text", "text": "  latest question  "}],
+        },
+    ]
+    assert utils.extract_user_query(messages) == "latest question"
+    assert utils.extract_user_query([{"role": "assistant", "content": "skip"}]) == ""
+
+    hash_one = utils.compute_messages_hash(messages)
+    hash_two = utils.compute_messages_hash(list(messages))
+    assert hash_one == hash_two
+    assert len(hash_one) == 16
+
+    prefix_default = utils.compute_prefix_hash(
+        [
+            {"role": "system", "content": "a"},
+            {"role": "system", "content": "b"},
+            {"role": "user", "content": "c"},
+            {"role": "assistant", "content": "d"},
+        ]
+    )
+    prefix_explicit = utils.compute_prefix_hash(
+        [
+            {"role": "system", "content": "a"},
+            {"role": "system", "content": "b"},
+            {"role": "user", "content": "c"},
+            {"role": "assistant", "content": "d"},
+        ],
+        prefix_count=3,
+    )
+    assert prefix_default == prefix_explicit
+    assert utils.compute_prefix_hash([]) == utils.compute_short_hash("")
+
+
+def test_timestamp_marker_and_json_helpers() -> None:
+    ts = utils.format_timestamp(datetime(2026, 4, 23, 6, 0, 0))
+    assert ts == "2026-04-23T06:00:00Z"
+    assert utils.parse_timestamp(ts) == datetime(2026, 4, 23, 6, 0, 0)
+    assert utils.parse_timestamp("2026-04-23T06:00:00") == datetime(2026, 4, 23, 6, 0, 0)
+
+    marker = utils.create_marker("tool_digest", sha256="abc", count="2")
+    assert marker == '<headroom:tool_digest sha256="abc" count="2">'
+    assert utils.create_tool_digest_marker("abc") == '<headroom:tool_digest sha256="abc">'
+    assert utils.create_dropped_context_marker("budget") == (
+        '<headroom:dropped_context reason="budget">'
+    )
+    assert utils.create_dropped_context_marker("budget", count=4) == (
+        '<headroom:dropped_context reason="budget" count="4">'
+    )
+    assert utils.create_truncated_marker(100, 25) == (
+        '<headroom:truncated original="100" truncated_to="25">'
+    )
+
+    extracted = utils.extract_markers(
+        'x <headroom:tool_digest sha256="abc"> y <headroom:dropped_context reason="budget" count="2">'
+    )
+    assert extracted == [
+        {"type": "tool_digest", "attributes": {"sha256": "abc"}},
+        {"type": "dropped_context", "attributes": {"reason": "budget", "count": "2"}},
+    ]
+
+    assert utils.safe_json_loads('{"ok": true}') == ({"ok": True}, True)
+    assert utils.safe_json_loads("{bad") == (None, False)
+    assert utils.safe_json_dumps({"emoji": "café"}) == '{"emoji":"café"}'
+
+
+def test_cost_formatting_and_deep_copy() -> None:
+    provider = FakeProvider("1.25")
+    assert utils.estimate_cost(100, 50, "gpt-4o", cached_tokens=10, provider=provider) == 1.25
+    assert provider.calls == [(100, 50, "gpt-4o", 10)]
+    assert utils.estimate_cost(1, 1, "gpt-4o", provider=None) is None
+
+    none_provider = FakeProvider(None)
+    assert utils.estimate_cost(1, 1, "gpt-4o", provider=none_provider) is None
+
+    assert utils.format_cost(0.0099) == "$0.0099"
+    assert utils.format_cost(1.234) == "$1.23"
+
+    messages = [{"role": "user", "content": {"nested": ["a"]}}]
+    copied = utils.deep_copy_messages(messages)
+    copied[0]["content"]["nested"].append("b")
+    assert messages == [{"role": "user", "content": {"nested": ["a"]}}]