chore: renormalize line endings to LF

`.gitattributes` declares `*.py text eol=lf` and `*.sh text eol=lf`, but
74 files (73 .py, 1 .sh) are stored in the index with CRLF line endings,
violating that contract. Every macOS/Linux clone reports these files as
"modified" on fresh checkout because git's diff engine sees the stored
bytes don't match the attribute contract, even though the working tree
and index match byte-for-byte.

Running `git add --renormalize .` rewrites each affected blob so the
stored form matches the attribute declaration. No semantic changes —
every affected file's diff is "N insertions, N deletions" with inserts
and deletes being the same lines modulo line endings.

Follow-up commit adds `.git-blame-ignore-revs` so `git blame` / GitHub
blame skip this mechanical commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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

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

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")

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)

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"

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")}

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")

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")

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
+    }

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,
+    }

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)

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)

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()

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",
+]

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()

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

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

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

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

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,
+    }

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()

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()

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()

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"])

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",
+        ]
+    ]

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)

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

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"]

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

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

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

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

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",
+        }
+    ]

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}"
+        )

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

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

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__})"

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()

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"

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"

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"],
+    ]

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

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)

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

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",
+    }

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"