headroomlabs-ai--headroom/CHANGELOG.md

Changelog

All notable changes to Headroom will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Fixed

• The dashboard's per-request metadata (the recent_requests / request_logs tail and the config block with upstream URLs) is gated to loopback callers via _request_is_loopback. When Headroom runs in a bridge-network container (Docker/podman, or Apple Containerization / mocker), a browser on the host reaches the proxy through the container gateway, so request.client.host is the gateway IP rather than 127.0.0.1 — the sensitive block was stripped and the "Recent Requests" table rendered empty even though the operator is local. A peer inside an operator-configured trusted-gateway CIDR (HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS, already used to sanitize X-Forwarded-*) is now treated as loopback-equivalent, while the loopback Host-header gate is retained as the DNS-rebinding defence. Opt-in and empty by default, so there is no behavior change unless the gateway CIDR is allow-listed.
• Non-finite values (NaN, Infinity) in proxy_savings.json or in upstream cost/token metadata no longer crash the proxy or corrupt the savings dashboard. SavingsTracker's numeric coercion caught only TypeError and ValueError, so int(float('inf')) raised an uncaught OverflowError while loading persisted state (SavingsTracker.__init__ failed and the proxy would not start), and float('nan')/float('inf') passed straight through, then serialized to NaN/Infinity literals that the dashboard's JSON.parse rejects. json.loads accepts those literals, so one bad write poisoned every later start. Both coercion helpers now also catch OverflowError and reject non-finite floats, failing open to safe defaults.
• headroom learn now honors CLAUDE_CONFIG_DIR. It resolved the Claude config directory as ~/.claude and wrote global memory to ~/.claude/CLAUDE.md, so users who relocate their Claude config via that env var had learn scan the wrong directory and detect no projects. The scanner and memory writer now read/write the configured directory (#1630).
• --backend bedrock now fails fast with an actionable error when temporary AWS credentials (AWS_SESSION_TOKEN) are used but botocore is not installed (e.g. the slim default Docker image). litellm's session-token auth path imports botocore, so the missing dependency previously surfaced only at request time as a misleading authentication_error: No module named 'botocore'. The proxy now tells the user to install the bedrock extra up front (#1551).
• Content detection no longer crashes the proxy on text containing an orphaned +++ target line with no preceding --- source line (common in set -x xtrace output and partial diffs). The bundled unidiff 0.4.0 parser panics on that input instead of returning an error; the Rust diff detector now contains the panic and treats the fragment as plain text, so the request is compressed and forwarded normally instead of returning HTTP 500 (#1547).
• Proactive expansion blocks injected into user turns are now wrapped in <headroom_proactive_expansion> XML tags, giving downstream consumers (LLMs, loggers, attribution parsers) a machine-readable provenance boundary and preventing misattribution in multi-agent threads.
• cli: the startup banner no longer advertises HEADROOM_COMPRESSION_STABLE_AFTER_TURN and HEADROOM_STALE_READ_COMPRESS_AFTER_TURNS as tuning knobs. Both were read only to render the Performance Tuning banner section and were never wired into the compression path, so setting them changed the banner but had no effect on behavior. The banner now surfaces only the embedding sidecar, which is a real, consumed setting.
• memory/embedder: cap CPU thread oversubscription in the local torch/sentence-transformers embedder. Concurrent encodes previously each fanned out to ~os.cpu_count() BLAS/OpenMP threads, so under load the memory path starved the asyncio event loop and spiked /livez latency to several seconds. CPU encodes now run on a dedicated, size-limited executor whose workers each pin their thread pool, bounding total embedding threads to HEADROOM_EMBED_CONCURRENCY × HEADROOM_EMBED_NUM_THREADS (defaults min(4, cpu) × 1). The ONNX embedder already capped its threads; this brings the torch path to parity (#198).

Changed

• telemetry: anonymous usage telemetry is now opt-in (off by default) instead of opt-out. Nothing is collected or sent unless you set HEADROOM_TELEMETRY=on or pass --telemetry to headroom proxy / headroom install apply. is_telemetry_enabled() is fail-closed — only explicit on-values (on/true/1/yes/enable/enabled) enable it; unset, empty, or unrecognized values stay disabled. The existing --no-telemetry flag and HEADROOM_TELEMETRY=off remain accepted for back-compat, and install manifests now write the HEADROOM_TELEMETRY value explicitly so generated deployments are unambiguous.
• ccr: headroom_stats now labels its formatted proxy output as a rolling/window-scoped session and adds a lifetime savings section from /stats persistent_savings.lifetime when present, while keeping existing summary structure and fallback JSON output behavior.

Features

• proxy: report a new-content-relative input savings rate in /stats: tokens.new_input_tokens (provider-billed non-cache-read input: uncached + cache-write tokens, from response usage) and tokens.new_input_savings_percent (savings as a fraction of new input plus the tokens compression removed before they could be billed). The existing whole-request ratios recount the full transcript on every turn, so a 200-turn session counts its history 200x into the denominator and long-running cached sessions (especially 1M-context models, which never compact) dilute toward ~0% regardless of how well compression performs on content newly entering context. Purely additive; existing fields unchanged. Reports 0 when no cache usage data exists (e.g. providers without cache metrics) rather than dividing savings by themselves.
• transforms: first-class C# support in CodeAwareCompressor via the tree-sitter csharp grammar already shipped in the pinned tree-sitter-language-pack — no new dependencies (#1664). Parity with Java/C++/Rust: signatures preserved verbatim, method/constructor/destructor/operator/local-function bodies compressed; block-scoped and file-scoped namespaces, records, structs, interfaces, and enums handled; C#-distinctive auto-detection. Preprocessor conditionals (#if…#endif) are preserved verbatim as opaque regions (blocks wrapping only using directives stay with the imports), #region markers no longer swallow the following line during class-member extraction, and top-of-file license banners / #region License headers stay on top instead of being relocated below the code. Real-repo runs: 16.1% tokens saved on Newtonsoft.Json (945 files), 37.8% on Polly (797 files), output syntax-valid for 1742/1742 files.
• proxy: add provider-only HTTP proxy routing via --http-proxy and HEADROOM_HTTP_PROXY. Upstream LLM provider calls can now use an HTTP proxy without setting process-wide HTTP_PROXY/HTTPS_PROXY variables that are inherited by tool executions; proxied provider clients use HTTP/1.1 so HTTPS provider APIs can tunnel through CONNECT.
• proxy: add output shaping for OpenAI Responses traffic on /v1/responses HTTP requests and Codex WebSocket response.create frames, with stable output-savings holdout keys and counted WS token strata for the experiment.
• observability: the headroom.compression.pipeline span now also carries the OpenTelemetry GenAI semantic-convention attribute gen_ai.request.model alongside the existing headroom.* attributes, so Headroom's traces group and filter by the standard gen_ai.* schema in any OTel-native backend (Grafana, Datadog, etc.). Purely additive; no existing attribute changed. gen_ai.operation.name, gen_ai.provider.name, and gen_ai.usage.* are deliberately deferred (they need per-caller operation threading, reliable upstream-provider resolution, and response-path usage respectively).
• wrap: headroom wrap claude --1m preserves the 1M context window. Behind a custom ANTHROPIC_BASE_URL (the proxy) Claude Code drops the context-1m beta header and caps the window at 200k for entitled subscription users; the opt-in flag sets ANTHROPIC_MODEL=<opus>[1m] on the launched process so the 1M window activates through Headroom. A model already selected via ANTHROPIC_MODEL is preserved (only the [1m] suffix is appended) (#1158).
• learn: weight loops in headroom learn. A new loop detector (headroom/learn/loops.py) recognizes repeated tool-call patterns — including RTK re-fetch loops, where RTK's output truncation makes the agent re-run larger-limit variants of a successful command — collapses output-limit variants to one signature, measures the wasted tokens, surfaces loops as a highest-priority digest section, and weights loop guardrails above one-off rules by their measured waste. Previously loops had no special weight and a no-failure re-fetch loop was skipped entirely. Adds an RTK-loop eval (benchmarks/rtk_loop_learn_eval.py) that reproduces a loop, runs it through Learn, and asserts the generated guardrail ranks first and prevents re-triggering.
• learn: write per-project learnings to the personal, gitignored CLAUDE.local.md by default instead of the team-shared CLAUDE.md, matching Claude Code's memory convention so machine-specific paths and tool-discovery byproducts no longer pollute the shared file. Adds a --target flag to override the destination (e.g. --target CLAUDE.md to opt back into the shared file, or any custom path), and auto-migrates a stale learned-patterns block out of an existing CLAUDE.md into CLAUDE.local.md with a warning (#1072).
• proxy/transforms: take large cold-start contexts off the synchronous kompress path — the root cause behind the compression_first_stage 30s-timeout + leaked-thread → executor-saturation cascade (#1171). A token size-gate inside the ML boundary routes oversized text away from ModernBERT (HEADROOM_KOMPRESS_MAX_TOKENS); a cooperative chunk-deadline bounds any kompress run that does proceed (HEADROOM_COMPRESSION_DEADLINE_MS); an opt-in off-path mode forwards uncompressed immediately and compresses in a single per-process background drain so the request never blocks on ML (HEADROOM_BACKGROUND_COMPRESSION); and a new native TextCrusher — a fast deterministic extractive prose compressor in headroom._core that reuses the shared BM25 relevance scorer — is the fast alternative to ModernBERT for large plain text (HEADROOM_TEXT_CRUSHER). All default off and fail-open. On a SQuAD answer-retention eval (requires the SQuAD dev set) TextCrusher keeps ~94% of buried answers at 30% size vs ~36% for truncate/random, and runs in one O(n) pass -- sub-second where ModernBERT takes minutes (self-contained speed benchmark in benchmarks/text_crusher_quality_eval.py).
• proxy: measure and surface rolling and current token throughput metrics (active/wall-clock input, compression, effective forward, and streamed generation) in headroom perf CLI and the dashboard (#959).
• vibe: add Mistral Vibe CLI support with headroom wrap vibe.
• proxy: per-project savings breakdown on the dashboard for all wrapped agents — Claude Code, Codex, aider, Copilot, and Cursor (#802). headroom wrap claude/codex tag requests with an X-Headroom-Project header (launch-directory name); wrap aider/copilot/cursor — whose clients cannot send custom headers — use a /p/<name> base-URL prefix the proxy strips. Savings are aggregated per project (persisted, schema v3 with transparent v2 migration), exposed as savings.per_project in /stats and projects in /stats-history, and shown in a Per-Project Savings dashboard table.
• memory: opt-in Apple-GPU (MPS) embedding offload via HEADROOM_EMBEDDER_RUNTIME=pytorch_mps. When set (and Apple MPS is available), the memory embedder runs on the torch sentence-transformers backend on the Apple GPU instead of the default ONNX CPU embedder, freeing the CPU under load. If MPS or the dependencies are unavailable, Headroom logs a warning and uses the existing default embedder selection path (ONNX when available, then the pre-existing local fallback). MPS encode calls are serialized internally (torch-MPS is not thread-safe). Adds the new [pytorch-mps] extra (pip install 'headroom-ai[pytorch-mps]'). Default behavior is unchanged.
• proxy: cross-region Bedrock inference-profile detection — geo-prefixed model IDs (eu./us./apac./global.) are now resolved to their canonical vendor, so Anthropic cross-region profiles (e.g. eu.anthropic.claude-haiku-4-5-20251001-v1:0) receive live-zone compression instead of being silently skipped (#999).
• proxy: Converse-body compression on the native Bedrock route — the live-zone dispatcher now recognizes Bedrock Converse content blocks (typeless {"text": …}, not only Anthropic {"type":"text", …}), so Converse user-message text compresses; run_anthropic_compression no longer bails to passthrough when the body lacks an InvokeModel anthropic_version envelope, and envelope re-emit stays gated on successful parse (#999).
• docker: bundle headroom-proxy binary in published runtime and runtime-slim images — closes #976 (#999).
• transforms: add opt-in audit-safe mode to SmartCrusher — SmartCrusherConfig(audit_safe=True, protected_patterns=[...], fail_closed_on_protected_loss=True). Rows matching a protected pattern are scanned before JSON-array compression and guaranteed to survive the compressed output verbatim afterward (never dropped, never replaced by an opaque <<ccr:...>> marker only). Applies on both the crush_array_json convenience API and the _smart_crush_content path apply() uses for real tool-output compression. If a protected row still can't be preserved after the splice-back pass, the crusher fails closed by returning the original uncompressed content (or ships a best-effort result with a warning when fail_closed_on_protected_loss=False). Default is audit_safe=False — no behavior change for existing callers (#1705).

Bug Fixes

• ccr: don't crash parse_tool_call on a CCR tool call whose arguments aren't an object. For the OpenAI/openai_responses shape the arguments are json.loads-decoded and only JSONDecodeError was caught, so a model that emitted arguments='[]'/'"abc"'/'123' (decoding to a list/str/number) — or a non-dict Anthropic input — reached input_data.get("hash") and raised AttributeError; a null arguments raised an uncaught TypeError from json.loads(None). Both are now handled: the decode also catches TypeError, and a non-dict input_data returns None (not a valid CCR call) instead of crashing CCR response processing.
• proxy/anthropic: give each Anthropic conversation its own session id. SessionTrackerStore.compute_session_id derived its fallback id from model + system text harvested only from role:"system" entries inside messages — but Anthropic carries the system prompt as a top-level body["system"] field, so genuine Anthropic requests (which never carry x-headroom-session-id) collapsed to md5(model:[]) and every conversation on the same model shared one PrefixCacheTracker. That let session-sticky state cross-contaminate: conversation A's sticky headroom_retrieve/memory tools and anthropic-beta headers were injected into conversation B, and frozen-prefix/compression-cache state mixed across conversations. The Anthropic handler now folds the top-level system into the session-id inputs (prepending a synthetic role:"system" message used only to derive the id), giving distinct conversations distinct ids.
• cache/semantic: key entries by the full-context hash, not the trailing query text. SemanticCache.put stored each response under sha256(query)[:16] where query is only the last user message, and the exact-match branch of get returned the slot without checking the stored entry's messages_hash. Two requests that share a trailing message ("continue", "yes", "run the tests") but differ in earlier context therefore collided on one slot — the second overwrote the first, and the first's hash then resolved to the second's cached response (wrong data served). Entries are now keyed by messages_hash when present, and get verifies entry.messages_hash before returning.
• proxy/openai: stop PRE_SEND from reintroducing tools: [] after the direct #728 fix. The OpenAI request handler now mirrors the existing tools or _original_tools is not None body-write guard during PRE_SEND write-back, so providers that reject empty tool arrays no longer see a tools field when the client omitted it, while explicit client tools: [] remains preserved (#1983).
• proxy/openai: keep the exact Responses function name terminal resident during OpenAI tool-search deferral so cache-mode optimization stops forwarding terminal.terminal and triggering the reserved-namespace 400 on Codex Responses (#1946).
• subscription/copilot: show a fully-consumed Copilot quota as 100% used instead of unknown. parse_copilot_quota read remaining = raw.get("remaining") or raw.get("quota_remaining"), so a category reporting remaining: 0 (quota fully spent) had that legitimate 0 treated as falsy and — with no quota_remaining alias in the real payload — collapsed to None. CopilotQuotaCategory.used/used_percent then returned None, so the dashboard rendered the exhausted category as used: - / 0% (green gauge) rather than 300/300 / 100%. Now uses an explicit is None check.
• proxy/gemini: thread the savings-profile kwargs into the native Gemini/Vertex compression paths. handle_gemini_generate_content, handle_google_cloudcode_stream, and handle_gemini_count_tokens called openai_pipeline.apply() without proxy_pipeline_kwargs(self.config), so HEADROOM_SAVINGS_PROFILE and the ProxyConfig knobs (target_ratio/min_tokens_to_compress/protect_recent/max_items_after_crush/...) were silently dropped on the Gemini path — those requests compressed with router defaults instead of the configured profile, diverging from the Claude/Codex/Cursor paths. This is the same fix #1534 made for the OpenAI chat path; it now covers Gemini too.
• wrap: headroom wrap claude no longer installs RTK or lean-ctx by default. Claude context-tool setup is now explicit via --context-tool, --no-context-tool remains accepted, and other wrap commands keep their current defaults (#1915).
• proxy/openai: thread the savings-profile kwargs into the live /v1/chat/completions compression path. The chat handler called openai_pipeline.apply() without proxy_pipeline_kwargs(config), so HEADROOM_SAVINGS_PROFILE=agent-90 (and the individual compress_user_messages/target_ratio/min_tokens_to_compress/... knobs) were silently dropped — OpenAI-compatible clients like OpenCode kept protecting user messages and missed the configured profile. Both the token-mode and non-token chat branches now pass the profile kwargs, matching handlers/anthropic.py and the dedicated OpenAI compress endpoint (#1534).
• proxy: forward Codex Desktop /v1/responses posts byte-faithfully so they stop returning upstream 400 {"detail":"Bad Request"}. handle_openai_responses decoded the inbound body to inspect it but always re-serialized a canonical body on the way out, and it never stripped the inbound content-encoding header — so a content-encoding: zstd Codex Desktop request was forwarded as already-decoded JSON still advertising zstd, and the upstream ChatGPT Codex endpoint rejected it. The handler now keeps the original decoded bytes and forwards them verbatim whenever nothing (compression or memory injection) mutated the request, and drops the stale content-encoding header, mirroring the byte-faithful passthrough the chat and Anthropic paths already use (#1542).
• wrap/codex: headroom unwrap codex now removes the Headroom rtk instruction block from the Codex global AGENTS.md. wrap codex injects it there, but unwrap only restored config.toml and MCP state, so a plain codex launch kept following the "prefix shell commands with rtk" guidance and failed once the managed rtk binary was off PATH. Unwrap now strips the marker-fenced block (preserving the rest of the file), mirroring unwrap copilot (#1421).
• proxy/auth: classify real Anthropic OAuth tokens correctly. classify_auth_mode matched OAuth on the sk-ant-oat- prefix, but real access tokens are sk-ant-oat01-... (a version number, no dash after oat), so every real subscription/OAuth token fell through to the sk- branch and was tagged PAYG — enabling aggressive lossy compression, auto cache_control, and prompt_cache_key injection on subscription-bound requests the classifier is meant to route to the passthrough-prefer path. The prefix is now the dash-less sk-ant-oat (still matches the legacy dashed shape). The existing parity tests only passed because they used a synthetic sk-ant-oat-01- fixture; a regression test now covers the real sk-ant-oat01- format.
• install: stop leaking a file descriptor on every headroom install start. start_detached_agent() opened the agent log file and handed it to subprocess.Popen but never closed the parent's copy, so each call leaked one fd (and pinned the log file open against rotation). The parent now closes its copy in a try/finally once the child has inherited it — the close also runs if Popen raises (#1554).
• memory/sync: stop the Codex AGENTS.md sync adapter from erasing previously-synced memories on every export. sync_export hands each adapter only the delta (memories the agent lacks), but CodexAdapter.write_memories rebuilt its whole managed section from just that delta — so each sync overwrote the section with only the new items, thrashing the file between disjoint subsets and never accumulating. It now merges the delta into the facts already present (deduped), matching the additive contract the ClaudeCode adapter already follows.
• memory/sync: stop the Claude Code sync adapter from clobbering distinct memories that share a first line. write_memories derived each file name from the first line of the content only (headroom_{slug}.md), so two different DB memories whose first lines slugify identically wrote to the same file and the second silently overwrote the first — and because the loser never landed on disk, the next sync re-exported it, ping-ponging the pair forever. When the slug is already taken by a different memory (distinct headroom_id) the file name is now disambiguated with a content-hash suffix; an update to the same memory still rewrites its slug file in place, so existing file names are unchanged.
• transforms/code: stop raising ValueError on common language hints and fence tags. CodeAwareCompressor.compress() built the language with CodeLanguage(language.lower()), which only accepts the exact enum values (python/javascript/typescript/…). A markdown ```js / ```ts / ```py fence tag (or any caller passing an alias) raised ValueError — crashing direct callers, and inside the content router the error was swallowed so those blocks silently skipped code-aware compression. A new coerce_language helper maps the common aliases to their canonical language and returns UNKNOWN (never raises) for unrecognized tags, falling back to content-based detection.
• cli/proxy: honor HEADROOM_MIN_TOKENS=0 / HEADROOM_MAX_ITEMS=0. The Click proxy command built these with _get_env_int_optional(name) or 500/or 50, so an explicit 0 — a legitimate value (min_tokens_to_crush=0 means "crush every item") — was treated as falsy and silently replaced with the default. The headroom proxy argparse path already preserved 0 via _get_env_int, so the two entry points disagreed. The Click path now uses the same None-checking helper.
• proxy: strip the inbound Content-Encoding/Transfer-Encoding request headers on the Anthropic /v1/messages and OpenAI /v1/chat/completions paths before forwarding upstream. read_request_json_with_bytes already decompresses the inbound body (zstd/gzip/deflate/br), so the bytes forwarded upstream are plain JSON — but these two handlers left the original content-encoding header in place, so a client (or an edge proxy like a Cloudflare Worker) that sent a compressed body got its request rejected with upstream HTTP 400 because the provider tried to decompress already-decoded JSON. The /v1/responses handler already carried this fix (#1542); it is now applied to the messages and chat paths too.
• models: fix the model registry's prefix fallback silently returning the wrong context window. ModelRegistry.get accepted any registered name as a str.startswith prefix and returned the first match, so gpt-4-32k-0613 resolved to gpt-4 (8192) instead of gpt-4-32k (32768), and unregistered ids like gpt-4.1/gpt-4.5 inherited gpt-4's 8192-token window — making the proxy think a nearly-empty context was almost full and compress far too aggressively. The fallback now requires the registered name to end at a version boundary in the query (so gpt-4.1 no longer matches gpt-4) and picks the longest qualifying name (so gpt-4-32k-0613 → gpt-4-32k).
• install: stop resolve_targets from rejecting valid --providers all/auto installs under provider scope. The provider-scope "unsupported targets" validation ran before the mode dispatch, so headroom install apply --scope provider --providers all --target cursor raised ClickException even though all/auto ignore the requested target list entirely (user scope silently ignores the same input). The check now runs only on the manual path that actually consults the requested list.
• mcp/opencode: stop the OpenCode MCP registrar from destroying an existing but unparseable opencode.json. _write_entry read the config via a helper that returns {} on JSONDecodeError, then rewrote the whole file with only {"mcp": {...}} — wiping the user's theme/model/provider and any other MCP servers (OpenCode configs are commonly JSONC / hand-edited). The write path now refuses to overwrite a present-but-invalid config and returns a FAILED result; absent/empty files still register fresh and valid files still merge with all other keys preserved. (Same class of fix as the Claude registrar.)
• proxy: include the system prompt, tools, and the response-shaping request fields in the SemanticCache key. _compute_key hashed only {model, messages}, so two non-streaming requests with identical messages but a different top-level system prompt, tool set, sampling config, or output-shaping field collided on one key and the second caller was served the first's cached response — generated under different request semantics, in the default config (cache_enabled defaults on). The key now folds the request fields that shape generation — temperature/top_p/top_k/max_tokens/stop, plus OpenAI tool_choice/response_format/parallel_tool_calls/seed/presence_penalty/frequency_penalty/logit_bias/n/logprobs/top_logprobs/reasoning_effort/verbosity/modalities and Anthropic thinking/tool_choice/output_config — canonicalizing system/tools so a moved cache_control breakpoint does not fragment it, and the handlers snapshot the fields once at the cache read and reuse them at write so a body mutated by the pipeline cannot diverge the key. Non-streaming path only.
• learn (verbosity): --verbosity --apply --all now aggregates the savings baseline across every project instead of overwriting it per project (last-project-wins), which previously left the output shaper with a tiny, unrepresentative baseline. The applied verbosity level comes from the project with the most samples (#1288).
• proxy/anthropic: restore token-mode compression on continued Claude Code turns with a frozen prefix and deferred CCR tool injection. Token mode now runs request-side compression even when the client did not pre-register headroom_retrieve, relying on the existing marker-triggered injection override to keep emitted CCR markers redeemable (#1487).
• proxy: the dedicated OpenAI handlers (/v1/chat/completions, /v1/responses) now honor the x-headroom-base-url request header, matching the generic passthrough route. Previously only the catch-all passthrough honored it, so OpenAI-compatible gateways (LiteLLM, CPA, self-hosted vLLM, Azure OpenAI) routed correctly for passthrough traffic but the dedicated chat/responses handlers ignored the header and fell back to the default OPENAI_API_URL, sending requests (and the user's provider key) to the wrong upstream.
• subscription: stop zeroing the 5-hour headroom contribution counters on every poll. The rollover check compared five_hour.resets_at with a bare !=, but the usage API reports that timestamp with second-level jitter (observed flapping between 01:59:59Z and 02:00:00Z on consecutive polls within the same window), so a spurious "5h window rolled over" reset fired every poll interval (~5 min) and the dashboard's per-window savings stuck near 0%. Only a forward jump larger than _ROLLOVER_MIN_ADVANCE (1 minute) now counts as a real rollover.
• wrap: keep the shared proxy alive when the agent that launched it closes ungracefully on Windows. _start_proxy spawned the proxy without detaching it, so it stayed in the launcher's console and Job object; closing that terminal window (or taskkill/a crash) tree-killed the proxy, bypassing the marker-based reference counting in _make_cleanup and breaking every other headroom wrap instance routed through the same port. The proxy is now created with CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP | CREATE_BREAKAWAY_FROM_JOB (with a graceful fallback when the launcher's Job forbids breakaway); POSIX behavior is unchanged. CREATE_NO_WINDOW (rather than DETACHED_PROCESS) gives the proxy its own hidden console: DETACHED_PROCESS leaves a console-subsystem exe (python.exe) consoleless, so Windows surfaces a visible console window whose close button kills the proxy.
• transforms/content_router: stop replacing role="tool" output with a lossy-unrecoverable summary on the live compression path (refs #1307). ContentRouter.apply() routed OpenAI-style role="tool" string messages — Bash/grep/ls/cat output — through the ML/word-drop summarizers; when the result carried no CCR retrieve marker (CCR off, ratio >= 0.8, or the size-gate fallback) the original was unrecoverable and the agent acted on a fabricated summary. Tool-role string content is now kept verbatim unless the compressed form is CCR-recoverable. Assistant/user text is unaffected, and structurally-lossless passes (SmartCrusher/Log/Search) still apply. The Anthropic tool_result block path is tracked separately.
• rtk: stop rtk hook registration from spuriously timing out during headroom wrap. Output is captured to a temp file instead of pipes, and stdin is closed, so a background process forked by rtk init can no longer hold the pipe open and block subprocess.run past its 10s timeout after the hooks were already registered.
• ccr: stop re-compressing headroom_retrieve output, which created an infinite retrieval loop, and stop emitting retrieval markers when the headroom_retrieve tool is not injected, which silently dropped data (#1077, #1006).
• dashboard: include RTK stats in the Historical tab; /stats-history now attaches live RTK/CLI-filtering stats the same way the Session tab does, so they survive a proxy restart (#1177).
• opencode: write Headroom MCP config as a local stdio server instead of a remote /mcp URL, keep provider-only installs from adding MCP config, and allow install apply --target opencode (#1380).
• proxy: stop discarding a finished compression on very large requests. After the transform pipeline completed, a telemetry-only waste-signal re-parse of the original messages ran on the critical path; on huge Claude Code transcripts (~400k tokens) that parse could exceed the Anthropic compression timeout, so the proxy failed open and forwarded the uncompressed request despite "Pipeline complete" logging real savings (tokens_saved: 0, transforms_applied: [], ~31s latency). Waste-signal detection is now skipped above MAX_WASTE_SIGNAL_DETECTION_TOKENS (100k) so the compression result stays on the critical path (#296).
• codex: retag existing Codex threads when headroom init injects the headroom provider, so Codex Desktop history stays visible. Codex filters its sidebar/search by the active model_provider; the init path set model_provider = "headroom" without retagging, so existing native openai threads disappeared from the menu (data was never deleted, only hidden). _ensure_codex_provider now reconciles thread tags openai→headroom, matching what the install and wrap paths already do; headroom unwrap codex handles the revert direction (#961).
• install: stop duplicating the container ENTRYPOINT in the persistent-docker runtime command. The published image already runs headroom proxy as its ENTRYPOINT, but build_runtime_command re-added headroom proxy after the image name, so the container ran headroom proxy headroom proxy --host 0.0.0.0 … and Click aborted with "Got unexpected extra arguments (headroom proxy)" — the deployment never became ready and rollback left nothing running. The runtime command now appends only the proxy flags (#833).
• proxy: retry upstream 529 overloaded_error like a 429 on both the streaming and non-streaming forwarders, honoring Retry-After. The streaming path previously surfaced a 529 straight to the client with no retry (interactive sessions saw "Overloaded" immediately), and _retry_request retried it only via the generic 5xx path — raising on exhaustion instead of returning the 529 verbatim, and ignoring Retry-After. A shared RETRYABLE_OVERLOAD_STATUSES = {429, 529} keeps the two forwarders in agreement (extends #1221).
• gemini: run compression off the asyncio event loop. The Gemini handlers (generateContent, Cloud Code stream, countTokens) ran the CPU-bound compression pipeline (Magika detection plus ML compression) synchronously on the loop, stalling every concurrent request for the duration of each Gemini request's compression. They now offload it via the shared compression executor, matching the existing OpenAI and Anthropic paths.
• proxy: run image compression off the asyncio event loop. The Anthropic and OpenAI handlers ran the CPU-bound image compressor (ONNX technique routing plus Pillow resize and OCR) synchronously on the loop, stalling every concurrent request for the duration of each image request's compression. They now offload it via the shared compression executor with a timeout and fail open on error, matching the existing text-compression path.
• proxy: queue mid-turn user messages on non-Bedrock streaming path instead of silently dropping them — closes #902.
• proxy: add --protect-tool-results / HEADROOM_PROTECT_TOOL_RESULTS to prevent lossy compression of exact-output tool results (e.g. Bash cat/grep results) — closes #1307.
• cli: add --rpm/--tpm and HEADROOM_RPM/HEADROOM_TPM to the Click proxy command for rate-limit parity with the legacy CLI -- closes #1350 (Problem 1).
• proxy: register ToolResultInterceptorTransform in explicit transforms list when HEADROOM_INTERCEPT_ENABLED is set — closes #829.
• opencode: write Headroom MCP config as a local stdio server instead of a remote /mcp URL, keep provider-only installs from adding MCP config, and allow install apply --target opencode (#1380).
• code: keep Python from __future__ imports before executable code during AST compression and validate compressed Python with compile(..., "exec") so compile-time syntax rules are enforced (#1233).
• proxy: report real input tokens on the streaming message_start event for LiteLLM/Bedrock-backed requests. LiteLLM streaming never surfaces prompt tokens mid-stream, so message_start.usage.input_tokens was always 0; Anthropic clients (e.g. Claude Code) read input-token metrics from that event, underreporting token usage by ~99% in OTel/CloudWatch dashboards. The Bedrock streamer now backfills input_tokens with the count Headroom actually sent upstream when the backend leaves it unset, preserving any non-zero value the backend genuinely reports (#1132).
• proxy: give buffered Anthropic request paths their own longer read timeout, so long /v1/messages turns and Anthropic batch or passthrough reads no longer trip the generic proxy cap while unrelated request timeouts stay unchanged.
• proxy: retry upstream 429 rate limits honoring Retry-After instead of passing them straight to the client. Both the non-streaming (_retry_request) and streaming (_stream_response) forwarders returned an upstream 429 verbatim, so a parallel agent fan-out that exceeded the per-minute limit aborted every run; 429s are now retried with backoff (honoring the upstream Retry-After, capped at retry_max_delay_ms), surfacing only the exhausted 429 to the client (#1221).
• proxy: force Responses API store=true when Headroom injects memory tools so previous_response_id continuations work after memory tool calls from clients that requested store=false (#1103).
• proxy: build SSL contexts for custom CA bundles so enterprise/private PKI roots work with Python/OpenSSL strict verification.
• dashboard: the Proxy $ Saved tile no longer shows a bare $0.00 when cost pricing is unavailable. Pricing depends on litellm, which pyproject gates off on Python 3.14+, so /stats now exposes a top-level litellm_available flag and the tile points you to reinstall on Python 3.13 when it is false (#1296).
• proxy: the output-savings recorder now reloads the learned baseline before estimating and before each flush, so a baseline written by headroom learn --verbosity --apply while the proxy is running takes effect without a restart and the periodic flush no longer overwrites it. Fixes Output Tokens Saved staying at "—" after enabling the shaper (#1296).
• tokenizers: bound token-counting of oversized tool-content blobs instead of running count_text over the whole serialized string. count_messages runs on the proxy request path; serializing is cheap, but count_text over a multi-megabyte tool_result / tool_use string took seconds and could freeze /health and in-flight requests. For payloads over ~50KB serialized, count_text now runs on an even-spread sample of the string and scales by length; it stays model-accurate, bounded for any blob shape, and biased to under-count. Smaller payloads stay exact.
• codex: stop persisting a project-specific --db path in the global headroom_memory MCP config, so headroom wrap codex --memory falls back to the active cwd's .headroom/memory.db at runtime while keeping the current project's local bootstrap work scoped correctly (#1147).
• ccr: stop emitting Anthropic request-side retrieval markers on frozen-prefix turns when headroom_retrieve injection is deferred, so cache-preserving requests forward original content instead of irrecoverable marker-only payloads (#1006).
• proxy: route Codex OAuth image generation and edit requests through the ChatGPT Codex image backend, while preserving OpenAI API-key image passthrough (#1215).
• wrap (codex): keep RTK guidance in the global Codex AGENTS.md instead of modifying the shared project AGENTS.md (#1235).
• subscription: run the transcript token-window scan off the event loop (asyncio.to_thread). The subscription tracker's poll loop scanned every ~/.claude/projects/**/*.jsonl transcript and json.loads'd each line inline on the proxy's single asyncio event loop; on large or long-running sessions this took seconds and froze /health and every in-flight proxied request — a periodic "wedge" recurring on the poll interval. The scan now runs in a worker thread so the loop stays responsive.
• gemini: resolve future Gemini model capabilities through the shared model registry so token counting and context lookup no longer reject new Gemini families.
• proxy: enable SSO credential resolution in the native Bedrock route via the aws-config sso feature flag, making the credential chain match what docs/bedrock.md already documented (#999).
• proxy: route native Bedrock /model/{id}/converse requests to the upstream Converse endpoint instead of the hard-coded /invoke action — the non-streaming handler now resolves the action from the inbound path, matching the streaming handler (#999).
• proxy: preserve byte-faithful /v1/messages forwarding when Anthropic tool arrays are already canonical, and only canonicalize-and-mutate tool lists when sorting changes ordering (#1042).
• ccr: make retrieval store TTL configurable with HEADROOM_CCR_TTL_SECONDS, expose the effective TTL in /v1/retrieve/stats, and distinguish expired retrievals from missing hashes.
• proxy: make force_kompress skip ContentRouter auto-detection during compression and pass savings-profile kwargs through Anthropic batch requests.
• proxy: add native Bedrock /model/{id}/converse-stream route and forward it through the existing streaming EventStream/SSE pipeline.
• proxy/kompress: make pre-upstream backpressure and kompress execution saturation fail-open, so Anthropic requests no longer return 503 during temporary saturation while healthy capacity still compresses and explicit passthrough markers preserve operator visibility (#1025).
• wrap (codex): fix headroom wrap codex producing a config.toml with duplicate top-level model_provider / openai_base_url keys (TOML-spec error) when the user had already configured their own provider. The injector now rewrites pre-existing top-level model_provider and openai_base_url lines in place — the previous value is kept in a # was: … trailing comment — instead of unconditionally prepending a duplicate, so codex can start against the proxy. The pre-wrap snapshot mechanism continues to byte-for-byte restore the original file on headroom unwrap codex.
• install (macOS): fix headroom install restart / install start for launchd persistent-service deployments. stop bootouts the job but start only ran launchctl kickstart, which cannot recover the un-bootstrapped state stop/restart leave behind (launchctl error 113), so the proxy was left stopped. start now tries kickstart (fast path for an already-bootstrapped job) and, on failure, bootstraps the plist fresh — retrying for ~15s to ride out the transient bootstrap EIO (error 5) window while launchd releases the label after a bootout. stop tolerates only the already-absent case (bootout ESRCH / error 3) and still raises on any other bootout failure (#1289).
• wrap: isolate wrapped proxy subprocess stdout/stderr into proxy-stdio.log, so proxy.log remains the canonical rotating runtime log and Windows rollover failures from RotatingFileHandler are no longer blocked by wrapper stdio handles (#1184).
• langchain: fix HeadroomChatModel.ainvoke() crashing with AttributeError: 'AsyncStream' object has no attribute 'model_dump' when the wrapped model has streaming=True. _agenerate() now uses a per-call non-streaming copy of the wrapped model instead of mutating shared state across an await (#1285).
• proxy: a transient rtk/lean-ctx stat-read failure (timeout, non-zero exit, bad JSON) no longer corrupts the dashboard's CLI-filtering session metrics. Failed reads now return "no data" instead of a synthetic zero payload, and the session baseline is only ever pinned from successful installed-tool reads — previously one hiccup re-pinned the baseline to zero and the next successful read inflated session savings by the tool's entire lifetime, at every proxy boot and POST /stats/reset.
• proxy: Concurrent large requests no longer 502 on a transient HTTP/2 stream reset. A single upstream StreamReset poisons the shared h2 connection and raises RemoteProtocolError / LocalProtocolError on every in-flight request; those transport errors weren't in the proxy's retry paths, so they collapsed straight to a 502 with no reconnect. The Anthropic non-streaming and streaming retry paths now treat any httpx.TransportError (including h2 protocol errors) as retryable before the first client byte, so the bad connection is dropped and the request re-sent on a fresh one (#1639).
• install: headroom wrap claude no longer leaves a dead ANTHROPIC_BASE_URL in a project's .claude/settings.local.json after an unclean exit (SIGKILL, OOM, reboot, or terminal/tmux close via SIGHUP, which was not caught). _write_claude_wrap_base_url/_restore_claude_wrap_base_url only removed or restored the entry from the wrap process's own finally block, so a crash skipped it and every later bare claude invocation in that project inherited the stale proxy URL and hung indefinitely retrying a dead port. A wrap session now stamps a sidecar marker (pid, port, prior value); the next wrap, unwrap, or headroom doctor run detects a marker whose pid is dead or reused and restores the recorded prior value automatically. claude() also now catches SIGHUP alongside the existing SIGTERM handler (#1768).
• proxy: Non-finite values (NaN, Infinity) in proxy_savings.json or in upstream cost/token metadata no longer crash the proxy or corrupt the savings dashboard. SavingsTracker's numeric coercion caught only TypeError and ValueError, so int(float('inf')) raised an uncaught OverflowError while loading persisted state (SavingsTracker.__init__ failed and the proxy would not start), and float('nan')/float('inf') passed straight through, then serialized to NaN/Infinity literals that the dashboard's JSON.parse rejects. json.loads accepts those literals, so one bad write poisoned every later start. Both coercion helpers now also catch OverflowError and reject non-finite floats, failing open to safe defaults.
• learn: headroom learn now honors CLAUDE_CONFIG_DIR. It resolved the Claude config directory as ~/.claude and wrote global memory to ~/.claude/CLAUDE.md, so users who relocate their Claude config via that env var had learn scan the wrong directory and detect no projects. The scanner and memory writer now read/write the configured directory (#1630).
• cli: --backend bedrock now fails fast with an actionable error when temporary AWS credentials (AWS_SESSION_TOKEN) are used but botocore is not installed (e.g. the slim default Docker image). litellm's session-token auth path imports botocore, so the missing dependency previously surfaced only at request time as a misleading authentication_error: No module named 'botocore'. The proxy now tells the user to install the bedrock extra up front (#1551).
• compression: Content detection no longer crashes the proxy on text containing an orphaned +++ target line with no preceding --- source line (common in set -x xtrace output and partial diffs). The bundled unidiff 0.4.0 parser panics on that input instead of returning an error; the Rust diff detector now contains the panic and treats the fragment as plain text, so the request is compressed and forwarded normally instead of returning HTTP 500 (#1547).
• proxy: persist lifetime cache-read savings (tokens + USD) in proxy_savings.json (schema v4, additive) so cache-mode savings survive proxy restarts and upgrades. Previously prefix-cache read savings lived only in process memory and every restart reset the dashboard's cache figure to zero; the "Cache Reads (lifetime)" tile now reads the persisted value and the Prefix Cache Impact card renders after a restart with zero traffic, marking session-scoped tiles "no activity since restart".
• compression: Proactive expansion blocks injected into user turns are now wrapped in<headroom_proactive_expansion> XML tags, giving downstream consumers (LLMs, loggers, attribution parsers) a machine-readable provenance boundary and preventing misattribution in multi-agent threads.
• cli: the startup banner no longer advertises HEADROOM_COMPRESSION_STABLE_AFTER_TURN and HEADROOM_STALE_READ_COMPRESS_AFTER_TURNS as tuning knobs. Both were read only to render the Performance Tuning banner section and were never wired into the compression path, so setting them changed the banner but had no effect on behavior. The banner now surfaces only the embedding sidecar, which is a real, consumed setting.
• memory/embedder: cap CPU thread oversubscription in the local torch/sentence-transformers embedder. Concurrent encodes previously each fanned out to ~os.cpu_count() BLAS/OpenMP threads, so under load the memory path starved the asyncio event loop and spiked /livez latency to several seconds. CPU encodes now run on a dedicated, size-limited executor whose workers each pin their thread pool, bounding total embedding threads to HEADROOM_EMBED_CONCURRENCY × HEADROOM_EMBED_NUM_THREADS (defaults min(4, cpu) × 1). The ONNX embedder already capped its threads; this brings the torch path to parity (#198).
• proxy: Buffered passthrough routes (e.g. GET /v1/models) no longer return an opaque HTTP 502 when an OpenAI-compatible upstream closes a pooled keep-alive connection mid-response (httpx.RemoteProtocolError / "incomplete chunked read"). Headroom now retries the request once on a fresh connection — mirroring a direct curl — and only returns a clear upstream_protocol_error 502 if the upstream is genuinely sending an incomplete response (#1112).
• ccr: buffered Anthropic CCR re-streaming now preserves adaptive-thinking response shape, including empty thinking blocks, signature_delta, redacted_thinking.data, verbatim stop_reason values such as refusal, and stop_details.
• cursor: headroom wrap cursor no longer injects the rtk custom-instructions block into .cursorrules when rtk's own native Cursor hook registers successfully. rtk supports a real hook for Cursor via rtk init --agent cursor (the same mechanism headroom already uses for Claude Code), which rewrites shell commands transparently — the injected .cursorrules text duplicated that guidance for no benefit. wrap cursor now tries the native hook first and only falls back to injecting .cursorrules if hook registration fails (#756).
• proxy: The Headroom dashboard no longer tunnels GET /favicon.ico to the wrapped upstream provider. No route matched that path, so it fell through to the proxy's catch-all passthrough route and was forwarded to the configured Anthropic/OpenAI/etc. backend — burning a real upstream request (and possibly failing auth) for a browser's automatic favicon fetch on /dashboard. A dedicated /favicon.ico route now answers with 204 No Content directly, registered ahead of the passthrough catch-all (#1787).
• learn: fix three Windows-specific failures in headroom learn --verbosity and CLI-backed analysis (#1624). verbosity.py read transcripts and profiles with the platform-default text codec instead of UTF-8, so non-ASCII content raised a silently-caught UnicodeDecodeError, producing Sessions: 0, human turns: 0 for every project. _greedy_path_decode listed a directory's children with is_dir() inline in the same expression as iterdir(), so a single PermissionError on an inaccessible sibling (e.g. the AppData\Local\Temporary Internet Files junction present on most Windows profiles) aborted the whole listing and silently mis-decoded any project path that walked through it, causing --project <path> to report "No matching project" or resolve the wrong directory. _call_cli_llm launched CLI backends via Popen/run, which use CreateProcess on Windows and don't apply the shell's PATHEXT extension search, so an npm-installed .cmd shim (e.g. claude, codex) raised FileNotFoundError even though it was on PATH; a shutil.which-based retry now resolves the shim.
• proxy: The Anthropic Messages route (POST /v1/messages) now honors the x-headroom-base-url per-request upstream override. It previously ignored the header and always forwarded to api.anthropic.com, so clients that speak the Anthropic Messages wire format while authenticating against a non-Anthropic gateway (e.g. OpenCode Zen) were rejected upstream with 401 invalid x-api-key. The route now forwards to <x-headroom-base-url>/v1/messages, consistent with the OpenAI-compatible and passthrough routes (#1760).
• proxy: the savings store now fsyncs its parent directory after the atomic rename, so the most recent proxy_savings.json write survives a power-loss or crash. _save_locked fsynced the temp file's contents but never the directory entry the rename created, leaving the rename itself non-durable on POSIX. Best-effort — a no-op on Windows and virtual filesystems where directory fsync is unsupported.

• code: fix two CodeAwareCompressor AST-reassembly bugs: an exported JS/TS function or class (export function foo() {) produced a duplicated export export keyword and invalid syntax, because line-based node slicing (used to preserve indentation) pulled in the preceding export sibling's text on top of the export_statement handler's own prefix reconstruction. Separately, in every supported language, a doc comment immediately above a top-level function, class, or type was detached from its declaration during extraction and re-emitted in a cluster at the end of the compressed output instead of staying attached to what it documents.
• • proxy: Buffered upstream responses containing a server_tool_use (or any other unrecognized Anthropic content block) no longer turn a fully-generated response into an HTTP 502. StreamingMixin._response_to_sse raised ValueError on unknown block types after the entire upstream generation had already been buffered, so a slow-but-successful response failed and the client retried the whole multi-minute request. Unknown blocks are now emitted verbatim in content_block_start (following the existing redacted_thinkingpattern), soserver_tool_use, server_tool_result, mcp_tool_use`, and future block types round-trip (#1806).

0.31.0 (2026-07-09)

Features

• cache: provider-agnostic cache-mode delta + cc-agnostic prefix comparison (#1868) (7c2f0ea)
• ccr: wire retrieve-tool interception into OpenAI Responses handler (#1898) (62cd307)
• compression: add audit-safe mode with protected pattern matching (#1899) (bb112dd)
• content-router: accept any real compression (remove min-savings floor) (#1771) (6c31db9)
• content-router: lossless-first dispatch, cross-turn dedup, and A7 lossy-after-fold (#1818) (60af15f)
• proxy: add provider-only HTTP proxy (#1807) (ebe0a3b)
• proxy: add turn-hook extension point for buffered model turns (#1891) (ec950f7)

Bug Fixes

• build: enable Intel macOS pip installs via ort-load-dynamic (#1538) (32ce99e)
• cache: avoid fallback session collisions (#1827) (0f606b6)
• ccr: make expired retrieve misses terminal (#1781) (9cbdba4)
• ccr: preserve Anthropic re-stream shape (#1854) (f663894)
• ccr: preserve thinking blocks in buffered stream re-synthesis (#1897) (ede085c)
• cli/proxy: preserve explicit HEADROOM_MIN_TOKENS=0 / MAX_ITEMS=0 (#1886) (3a33af1)
• code-compressor: CJK-aware relevance-query symbol matching (#1747) (b38315c)
• codex: discover updated Codex state stores (#1889) (9d42eba)
• codex: OpenCode Zen telemetry attribution (#1648) (f18c6bd)
• content-detector: detect and compress space-separated JSON objects (#1742) (5194bdc)
• content-router: token-measure lossless folds at the acceptance gate (#1772) (c5493ea)
• copilot: normalize subscription routing host (#1836) (afd9cbd)
• copilot: route mixed-model requests per model (#1785) (5af5e22)
• dashboard: deduplicate repeated savings metrics (#1804) (88f935a)
• dashboard: distinguish unavailable RTK from zero stats in Docker (#1900) (87f6e93)
• dashboard: distinguish unavailable RTK from zero stats in Docker (#1901) (361adcd)
• dashboard: price proxy savings without litellm (#1728) (188e382)
• detect and clear stale ANTHROPIC_BASE_URL from crashed wrap sessions (#1768) (#1837) (84509a4)
• docker: persist headroom workspace in compose (#1839) (5e29c06)
• docker: report source build version (#1862) (3807488)
• evals: default unparseable judge scores below pass threshold (#1892) (42ebbc6)
• install: pass sc.exe create as raw command line so binPath= quoting survives (#1654) (#1702) (d6e0710)
• install: persist --no-http2 override through install apply (#1676) (6fb5f3b)
• mcp: isolate ClaudeRegistrar CLI config env (#1888) (1c947b1)
• mcp: surface dead proxy state (#1786) (931eed8)
• memory: resolve Trae cwd metadata from user reminders (#1737) (#1887) (3e85eb1)
• opencode: use local MCP config (#1383) (4bd3ddf)
• proxy/openai: thread savings-profile kwargs into chat completions (#1606) (7ff842d)
• proxy/openai: translate max_tokens -> max_completion_tokens on chat path (#1774) (285808b)
• proxy: bound Codex WS compression fallback latency (#1802) (d24a3f8)
• proxy: bound HF tokenizer load and offload token counting off event loop (#1738) (46d5d68)
• proxy: cancel retry backoff on shutdown (#1834) (da2d8dc)
• proxy: compress Anthropic user text blocks when enabled (#1875) (e36439a)
• proxy: freeze must forward cached (compressed) prefix byte-identical — stop token-mode cache busting (#1850) (248ae0f)
• proxy: fsync savings dir after atomic rename (#1764) (7de2c1e)
• proxy: keep cache_control bounded + stable so the freeze overlay stops busting (#1852) (4820134)
• proxy: persist lifetime cache-read savings across restarts (#1665) (908997e)
• proxy: preserve streaming passthrough beta headers (#1783) (0f553a8)
• proxy: release _active_streams session lock on setup-phase errors (#1864) (2ccd831)
• proxy: retry HTTP/2 stream resets instead of 502ing (#1645) (2ce19c2)
• proxy: retry passthrough on transient upstream connection close (#1513) (5d14080)
• proxy: route Foundry Anthropic messages (#1878) (739f654)
• proxy: serve /favicon.ico locally instead of tunneling upstream (#1787) (#1847) (3076e32)
• proxy: stop rtk stat failures from corrupting session baseline (#1693) (681b9a8)
• proxy: strip 1m model suffix before upstream forwarding (#1840) (e22d745)
• proxy: subtract cache write premiums from net savings (#1800) (53a465b)
• router: honor MCP aliases in excluded tools (#1822) (#1863) (140d6e4)
• rtk: link managed rtk onto PATH instead of mutating the hook (#1698) (140cb05)
• streaming: preserve server_tool_use sse blocks (#1826) (4ac5493)
• toin: publish skip compression recommendations (#1782) (be51008)
• transforms: normalize diff compressor context (#1801) (838c523)
• transforms: pass through ragged tables instead of misaligning columns (#1713) (c7665ca)
• use rtk native Cursor hook instead of injecting .cursorrules (#756) (#1846) (1573f1f)
• wrap: replace stale-proxy detection with Vite-style port fallback (#1406) (b4205c6)

Performance Improvements

• proxy: cap compression workers to CPU count (#1803) (0a3851b)
• savings: batch tracker persistence off the request hot path (#1817) (451b9f0)

Dependencies

• bump the cargo-minor-patch group across 1 directory with 7 updates (#1909) (45601d9)
• bump the npm-minor-patch group across 4 directories with 18 updates (#1907) (8872bbc)

0.29.0 (2026-07-03)

Features

• proxy: add --lossless no-CCR mode with format-native compaction (#1721) (c75ebde)
• stats: surface Codex WS compression counters in /stats summary (#1680) (2fe19c3)
• transforms: adaptive Otsu KEEP/DROP threshold (+ land relevance split on main) (#1726) (eea667a)

Bug Fixes

• bedrock: fail fast when session-token auth lacks botocore (#1553) (54cfa36)
• bedrock: route ARNs via converse, named AWS profiles, and au. re… (#1456) (7d87aa2)
• ccr: honor workspace dir for sqlite store (#1564) (96e1dfe)
• claude: surface Remote Control proxy incompatibility (#1610) (4bf7f92)
• cli: stop advertising unwired compression tuning env vars in banner (#1634) (d5bf98d)
• codex: avoid duplicate headroom provider config (#1431) (ddd4adf)
• compression: reject lossy unmarked tool output in unit router path (#1479) (de24cd5)
• cortex-code: migrate to current Cortex REST API endpoints + add e2e benchmarks (#1474) (f00ace6)
• dashboard: align token savings headline denominator (#1653) (646e705)
• dashboard: derive per-project setup URL from live origin (#1511) (e035aef)
• detection: contain unidiff panic on orphaned +++ target line (#1548) (e386c09)
• evals: CJK-aware F1 tokenization + token estimation (#1527) (99a8540)
• install: close parent log fd in start_detached_agent (#1576) (816cb85)
• install: use Windows-safe PID liveness probe in runtime_status (#1544) (#1560) (6b227b9)
• learn: aggregate verbosity baselines across projects instead of overwriting (#1288) (27a5468)
• mcp: show lifetime totals and label rolling session scope in headroom_stats (#1428) (1c0e152)
• memory: cap local embedder CPU thread oversubscription (#198) (#1559) (b84afbf)
• memory: singleflight LocalBackend init to stop cold-start races (#1691) (bec47a1)
• openclaw: detect uv-installed headroom binary in ~/.local/bin (#1459) (adaeb88)
• opencode: preserve custom OpenAI gateway paths (#1596) (c19347c)
• opencode: route native providers + load transport plugin, fix Serena context (#1573) (ad0034f)
• preserve anthropic passthrough tool order (#1427) (a932247)
• proxy/auth: match real Anthropic OAuth token prefix (sk-ant-oat) (#1672) (8cddf9b)
• proxy: expose persistent savings metrics (#1647) (5fe4e7b)
• proxy: fail open when kompress saturation would exhaust pre-upstream budget (#1430) (15ac650)
• proxy: handle streaming CCR retrieval (#1451) (d337e3b)
• proxy: include system/tools/sampling in cache key (#1473) (312129a)
• proxy: preserve Responses passthrough bytes (#1598) (2a34a82)
• proxy: strip Codex lite header on the HTTP /responses path (#1663) (9fbd47b)
• proxy: wire --compression-max-workers / HEADROOM_COMPRESSION_MAX_WORKERS (#1632) (814ffa3)
• savings: count cache-read tokens in input cost estimate (#1429) (72ade37)
• skip Magika backend on x86 CPUs without AVX2 (#1162) (64783d8)
• transforms/content-router: route grep/log output away from HTML extractor (#1719) (0d18ef2)
• transforms: bound native content detection with a Windows watchdog (#575) (#1563) (95abca3)
• Vertex AI support for Claude Code with ANTHROPIC_VERTEX_BASE_URL (#1393) (cff7247)
• wrap: detach the shared proxy on Windows so it survives an ungraceful agent close (#1464) (6cba441)
• wrap: preserve custom Vertex base URL (#1477) (75427bb)
• wrap: remove rtk instructions from Codex AGENTS.md on unwrap (#1604) (c9d717c)

0.28.0 (2026-06-29)

Features

• add --disable-kompress-fallback to restore legacy PASSTHROUGH fallback (#1185) (f309244)
• add first-class OpenCode support (wrap, learn, mcp install) (#559) (91cd210)
• add HEADROOM_KEEPALIVE_EXPIRY to keep upstream connections warm (#1124) (85786b3)
• azure-foundry: derive upstream URL from ANTHROPIC_FOUNDRY_RESOURCE (#1138) (e5031b0)
• cache: attribute prompt-cache misses to TTL lapse vs prefix change (#1313) (#1343) (4658721)
• code: add Perl support to code-aware compressor (#1125) (f39858c)
• headroom wrap opencode / unwrap opencode CLI (#1105) (b4571cc)
• learn: weight loops in Headroom Learn + RTK-loop eval (#1160) (14e8dc4)
• learn: write per-project learnings to CLAUDE.local.md by default (#1115) (ced75e4)
• proxy: add request timeout config (#738) (c0745d4)
• proxy: pilot hardening — inbound auth, security headers, audit log, air-gap switch (#1537) (546ab55)
• proxy: support glob patterns in exclude_tools (#870) (#1259) (a2159c0)
• read-maturation: activity-based hold-back Read maturation (Mechanism B) (#1068) (723b80c)
• savings: durable savings ledger + headroom savings command (#1127) (978ffa0)
• wrap: add --1m to preserve the 1M context window on wrap claude (#1158) (#1351) (b50d9c1)
• wrap: make tokensave the primary coding-task compressor, Serena the backup (#1230) (dca9853)

Bug Fixes

• agent-evals: Phase 0 — coding-agent accuracy A/B framework (#1037) (84f9871)
• agno: tolerate streaming tool-call SDK objects in parser (#1312) (#1336) (5986c22)
• bedrock: add boto3 1.41 + CRT for aws login credentials (#1486) (4db3bc9)
• bump codebase-memory-mcp to v0.8.1 (#1284) (530318b)
• ccr: make headroom_retrieve a hash-only full-content lookup (#1532) (c2fc4d3)
• ccr: propagate --no-ccr-marker flag to all compressors (#1022) (#1197) (0c9b42a)
• ccr: skip Anthropic marker emission when tool injection is deferred (#1273) (2cae13d)
• ci: extend gitleaks allowlist to cover test fixtures + verified examples (#1539) (d2565a6)
• ci: guarantee model present in test shards to end cache-miss flakiness (#1399) (2e29c72)
• ci: normalize Windows CRLF line endings in PR governance script (#1012) (5194388)
• cli: add explicit UTF-8 encoding to file I/O in wrap commands (#1126) (#1164) (a0cb798)
• cli: fall back gracefully when embedding-server sidecar is absent (#1206) (38f1404)
• cli: harden all CLI surfaces + fix docs accuracy (#1491) (bd76235)
• cli: wire --http2/--no-http2 (HEADROOM_HTTP2) into proxy command (#1373) (e06b616)
• cli: wire --rpm/--tpm and HEADROOM_RPM/HEADROOM_TPM to the Click proxy command (#1375) (8aab8f2)
• code: slice tree-sitter byte offsets as UTF-8 (#1332) (8238402)
• code: validate Python compressed syntax (#1302) (cbd361d)
• code: verify a real parse in tree-sitter availability check (#1231) (#1299) (5e0bb69)
• codex: retag threads on init so Codex Desktop history stays visible (#961) (#1349) (e6bbc40)
• codex: stop pinning Codex memory MCP to one project db (#1269) (ad7993b)
• dashboard: include RTK stats in the historical tab (#1324) (35939c3)
• deps: remediate dependency CVEs and publish SBOM (#1509) (5771a80)
• docker: persist session history across container revisions (#1118) (5912d65)
• gemini: offload compression to the executor (#1382) (615848e)
• gemini: resolve Google model capabilities through ModelRegistry (#1276) (17ecad9)
• install: guard install_agent_ensure against duplicate runtime spawns (#1301) (8da0b4e)
• install: repair macOS launchd restart/start lifecycle (#1290) (da1a397)
• install: stop duplicating ENTRYPOINT in persistent-docker runtime command (#833) (#1348) (feedead)
• io: use UTF-8 with locale fallback and preserve line endings on config/text I/O (#1498) (1baa04e)
• kompress: hard override keeps must-keep tokens regardless of model score (#1400) (42612c8)
• langchain: disable streaming on wrapped model during ainvoke() (#1287) (3590046)
• mcp: register managed installs with a resolvable headroom command (#1386) (22def93)
• mcp: report correct savings_percent in headroom_compress (#1106) (f216e43)
• opencode: write local MCP config (#1381) (6c83790)
• packaging: move hnswlib to optional [vector] extra so [all] needs no C++ toolchain (#1499) (80fa086)
• patch rtk hook script to use absolute path after register_claude_hooks (#571) (b618d2d)
• perf: surface RTK/CLI context-tool savings in perf and the session card (#1433) (9362747)
• proxy: add --protect-tool-results to prevent lossy compression of exact-output Bash results (#1374) (51d4bcf)
• proxy: add an Anthropic buffered read-timeout override (#1331) (3be2526)
• proxy: add versionless Vertex AI routes for Claude Code compatibility (#1321) (bb3e040)
• proxy: bind before eager preload so a hung compressor load can't block startup (#1500) (d5ac07f)
• proxy: build SSL contexts for custom CA bundles (#1134) (561ba17)
• proxy: forward request-id headers on the streaming path (#1100) (#1258) (3d59df7)
• proxy: gate CCR retrieve/compress endpoints to loopback (#1338) (acafb2d)
• proxy: honor force_kompress routing profile (#996) (b4682d6)
• proxy: keep large compression results on the critical path (#296) (#1352) (90734b6)
• proxy: offload /v1/compress to the compression executor to stop blocking the loop (#1501) (27e010e)
• proxy: preserve Responses memory continuations with store=false (#1103) (cdfeeac)
• proxy: queue mid-turn user messages on non-Bedrock streaming path (#1377) (b09f027)
• proxy: register interceptor in explicit transforms list when HEADROOM_INTERCEPT_ENABLED (#1376) (55c700c)
• proxy: report real input tokens on streaming message_start (#1132) (#1305) (70cc96a)
• proxy: retry upstream 429 with Retry-After on both forwarders (#1329) (90bee89)
• proxy: retry upstream 529 overloaded like 429 on both forwarders (#1495) (547b15d)
• proxy: stop re-compressing headroom_retrieve output and emitting unredeemable markers (#1323) (43494ff)
• proxy: strip Codex lite header from OpenAI WebSockets (#1543) (5d3803a)
• read-lifecycle: persist STALE Read originals in the CCR store (#1488) (9157173)
• recover persistent proxy feature checks and reject non-Copilot exchange URL (#1465) (16c638b)
• remove agents.md (#1540) (a7d3360)
• respect COPILOT_PROVIDER_TYPE env var when provider_type is auto (#549) (24cf256)
• restore token-mode compression on frozen prefixes (#1489) (8e0dadf)
• router: degrade to pure-Python detection on native panic (#1123) (#1260) (a00fb67)
• rtk: stop hook registration timing out on a forked daemon (#1314) (9758817)
• smart-crusher: honor enable_ccr_marker on the opaque-blob path (#1130) (27d6f8e)
• subscription: only reset 5h contribution on real rollover, not API jitter (#1255) (8d6c175)
• subscription: run transcript token scan off the event loop (#1263) (f03021f)
• surface output reduction without a restart, and explain $0.00 savings on Python 3.14 (#1296) (c30ec4c)
• tests: reset whole headroom logger subtree so caplog stays deterministic (#1117) (fda4670)
• tls: add HEADROOM_TLS_STRICT=0 toggle for corporate SSL inspection (#1308) (#1341) (52068dd)
• tokenizers: price CJK/Kana/Hangul at ~1 token per char in EstimatingTokenCounter (#1093) (a35fe86)
• transforms: gate tool string output from lossy compression (#1307) (#1387) (c6c921a)
• websocket: harden responses websocket origin handling (#1481) (c632023)
• windows: pin UTF-8 encoding on text-mode subprocess calls (#1311) (d633e81)
• wrap: add Copilot unwrap command (#1251) (b4fde0c)
• wrap: isolate proxy stdio from proxy.log on Windows (#1191) (959ab0d)
• wrap: keep agent savings opt-in (#1294) (b829ceb)
• wrap: show the dashboard URL when the proxy is already running (#1313) (b0146c4)

Performance Improvements

• compression: take large cold-start contexts off the synchronous kompress path (#1171) (#1298) (6c68ff4)

0.27.0 (2026-06-22)

Features

• cli: add headroom doctor setup diagnostics (#926) (e45cf4e)
• cli: add headroom update command and release banner (#1088) (26be2c3)
• compression extraction — Rust knob exposure, CCR hardening, traffic audits (#818) (b7be381)
• measure and surface token throughput (tokens/sec) through the proxy (#983) (0d89c67)
• output-token reduction — verbosity shaper, per-user learning, counterfactual savings (#965) (a99dc61)
• policy: decay P_alive from idle time near cache TTL (#856 P3b) (#1028) (fe4f9ee)
• providers: add Cortex Code (Snowflake CoCo) as a supported agent (#1190) (d9d0bf4)
• proxy: cc-switch reconciler — keep Headroom in the request path alongside cc-switch (#1030) (e8fc8a0)
• proxy: hot-reload live env knobs so a reused proxy picks them up without a restart (#1090) (6904d47)
• proxy: make COMPRESSION_TIMEOUT_SECONDS configurable via env (#946) (#991) (addebdb)
• transforms: tabular + spreadsheet (.xlsx/.xls) compression (#1128) (d789a7c)
• vertex: turnkey Claude Code + Vertex compression (+ fixes from the Vertex review) (#1113) (0e05915)

Bug Fixes

• ccr: accept 12-char SmartCrusher hashes in tool injection (#1095) (#1141) (9f7f3ad)
• ccr: return stored content when headroom_retrieve query matches nothing (#1213) (#1236) (08fb845)
• content-router: honor target_ratio in compression cache + add proxy --target-ratio flag (#1108) (8894ee0)
• dashboard: light-mode backgrounds + aligned savings tables (#1064) (5eae32b)
• deps: make litellm optional on Python 3.14 (#956) (#993) (b2f04e4)
• e2e: align Codex wrap e2e with global-only RTK guidance (#1240) (#1254) (bc12ace)
• init: set ENABLE_TOOL_SEARCH=true so Claude Code keeps deferring tools (#746) (#995) (500ec2b)
• kompress: never block the request path on the cold-cache model download (#1161) (3fc2a78)
• memory: use ONNX embedder for wrap --memory sync (#1092) (#1262) (4f9feda)
• openclaw: wrap plugin export as {register} object for OpenClaw 2026.x compatibility (#1218) (2e6c442)
• providers: update DeepSeek V3 context limit from 128K to 1M (#1038) (#1137) (bcabc5c)
• proxy: allow disabling periodic TOIN stats logging (#1265) (b5f63d8)
• proxy: honor HEADROOM_EXCLUDE_TOOLS for Codex /v1/responses tool outputs (#940) (#1053) (f03e77b)
• proxy: preserve byte-faithful Anthropic tool forwarding (#1222) (1f18d59)
• proxy: route Codex OAuth image requests (#1215) (381d771)
• proxy: scope CORS to loopback + gate operator/content endpoints (#1226) (bd55a42)
• proxy: stamp X-Client: codex on Responses endpoint for unidentified callers (#1036) (b0cd032)
• proxy: treat NODE_EXTRA_CA_CERTS as additive, not replacement (#998) (#1031) (c987283)
• telemetry: switch anonymous telemetry to opt-in (off by default) (#1223) (b998697)
• tokenizers: bound tiktoken vocab load so a stalled download cannot hang requests (#956) (#994) (7e86baf)
• unwrap: remove ANTHROPIC_BASE_URL + ENABLE_TOOL_SEARCH and init hooks on unwrap (#992) (5b84691)
• wrap: keep Codex RTK guidance global (#1240) (7c26a54)
• wrap: percent-encode non-ASCII cwd names in X-Headroom-Project header (#1071) (9f712cc)
• wrap: write env.ANTHROPIC_BASE_URL to settings.json so daemon-spawned conversations inherit proxy (#951) (#1078) (a554c3a)

0.26.0 (2026-06-16)

Features

• add Copilot BYOK provider wrapper utilities and CLI support (#1041) (e67ee2a)
• add dashboard agent usage stats (#814) (6d3f39f)
• Add support for Mistral Vibe CLI (#935) (0932b8b)
• attribute reread waste to over-compression via marker check (#901) (f928576)
• bedrock: cross-region + Converse compression; bundle proxy binary in images (#999) (0dc2e1c)
• dashboard: surface compression-vs-cache net impact in Prefix Cache panel (#913) (2a4d300)
• evals: adversarial-input robustness grid for compressors (#918) (5939004)
• parser: detect re-issued identical tool calls as reread waste (#909) (7d4ae86)
• policy: batch deep edits through one cache-bust (#856 P3a) (#1015) (c2e52fe)
• policy: consume net-cost mutation gate in ContentRouter (#856 P2) (#905) (553ade4)
• proxy: compress AWS Bedrock InvokeModel requests via configurable upstream (#720) (7edb27a)

Bug Fixes

• anthropic: strip styled Claude model ids (#651) (0c5c89d)
• anyllm: forward openai api_base/api_key to the any-llm backend (#942) (#954) (a7ee8a6)
• cache: guard None exemplar embeddings in dynamic detector (#950) (1ec9320)
• cache: name the missing piece in semantic detector guard (#1018) (3b0bcee)
• ci: check out repo in PR Governance label job (#1021) (4558bc2)
• ci: make PR governance advisory (#1047) (74dff94)
• codex: compute waste signals on the OpenAI Responses path (#898) (b9e2761)
• codex: poll /wham/usage for subscription limits (handshake no longer sends x-codex-* headers) (#924) (8c00f71)
• codex: PR health label check state (#986) (99c874d)
• codex: retag thread providers so history menu stays whole across the proxy boundary (#1034) (74ae781)
• codex: write canonical hooks feature flag and migrate deprecated codex_hooks (#743) (dff6a19)
• compression: convert tree-sitter byte offsets to char offsets (#892) (b1f700f)
• compression: correct JSON array item counting and entropy gate (#887) (d6f0f0f)
• compression: keep container bodies compressible in code handler (#890) (16ed73b)
• compression: measure short-value threshold on payload, not token (#889) (65b0e8c)
• compression: use thread-local tree-sitter parsers in code handler (#893) (6cdb846)
• gemini: surface functionResponse payloads to waste-signal detection (#897) (9b0c840)
• learn: decode directory names with spaces in Windows project paths (#997) (#1027) (2d3701b)
• learn: scan subagent and workflow transcripts (#1045) (0ddd4ed)
• openclaw: declare headroom_retrieve tool contract (#947) (7c8c909)
• policy: correct warm-cache penalty in net_mutation_gain to (S + dT) (#903) (0632eba)
• proxy: add native Bedrock converse-stream route (#917) (b08ec15)
• proxy: keep codex image-generation WS turns alive through the relay (#1000) (7dbbb40)
• proxy: make budget enforcement actually work (#885) (a14ab45)
• proxy: read RTK gain stats globally by default (#957) (b70fccb)
• route v1internal code assist requests to cloudcode-pa.googleapis… (#821) (e20f16b)
• serena: stop the Serena dashboard popup and make --no-serena actually disable Serena (#1003) (919379a)
• support Copilot Business subscription auth (#641) (0b4a4bd)
• wire HEADROOM_EXCLUDE_TOOLS / HEADROOM_TOOL_PROFILES into Click proxy entrypoint (#943) (9b7b436)
• wrap: avoid duplicate top-level keys when injecting codex provider (#884) (dd22cfd)

Code Refactoring

• DRY cache logic, add thread safety, fix Bash exclusion (#704) (e36fccd)

0.25.0 (2026-06-12)

Features

• add differential network capture harness (#761) (11ab5f8)
• add light mode for dashboard (#834) (c425893)
• add OAuth2 client-credentials upstream-auth proxy extension (#778) (#784) (eb2e50f)
• add Vertex AI proxy routing (#793) (3c77e52)
• cli: comprehensive help text, validation, and exception handling improvements (#640) (028efab)
• compression safety rails — error-output protection, pipeline circuit breaker, library inflation guard (#851) (c0cadcc)
• dashboard: per-model savings breakdown and expected-vs-actual cost on historical charts (#807) (34dafe6)
• detect re-served tool results as over-compression waste signal (#854) (5f1d88a)
• evals: add zero-cost tool schema compaction integrity eval (#817) (53a08c6)
• gated Markdown-KV compaction formatter (serialization-aware output) (#859) (06b2625)
• kompress: warn on unrecognized HEADROOM_KOMPRESS_BACKEND + document backend selection (#204) (6367d0b)
• memory: add opt-in Apple-GPU (MPS) embedding runtime (#766) (c71592d)
• net-cost cache mutation formula on CompressionPolicy (#856 P1) (#857) (d5f5802)
• plugins: Hermes agent headroom_retrieve plugin (#824) (058bced)
• probe-based retention scoring of recorded compression events (#862) (c2106cb)
• proxy: add CLI opt-outs for CCR injection (compression-only mode) (#823) (693d9d2)
• proxy: attribute savings history rollups per provider (#791) (0b8b8d9)
• proxy: log compressed messages alongside original request (#261) (2269e40)
• proxy: per-project savings breakdown on the dashboard (claude, codex, aider, copilot, cursor) (#803) (914a60a)
• support Python 3.14+ via pyo3 abi3 stable ABI (#516) (19eac8e)
• switch Kompress default to kompress-v2-base with weight-only int8 ONNX (#799) (74392b2)
• transforms: attribute read_lifecycle + smart_crush tags (#249) (8f37426)

Bug Fixes

• anthropic: CCR exception must re-raise, not silently swallow (#838) (8db5efc)
• ccr: key Rust search/diff/log markers with explicit_hash (#852) (bfcb07d)
• ccr: make retrieval TTL configurable (#715) (2533f77)
• ccr: skip CCR when model calls headroom_retrieve alongside user tools (#839) (30078f8)
• ccr: use shared compression store (#875) (249af6c)
• ci: correct comments, timeouts, and pip reliability in native e2e workflows (#878) (b716c8c)
• ci: pin cosign-installer to v3 (v4 does not exist) (#774) (199d693)
• codex: respect CODEX_HOME for wrap config (#731) (96abf38)
• content_router: guard against empty compression output causing Anthropic 400 (#771) (2f9ff07)
• copilot: use responses API for subscription reasoning models (#647) (84ac332)
• correct preserved-entry index mapping in Gemini content round-trip (#836) (0ffe2b6)
• dashboard: stable 'Proxy $ Saved' hero tile under --workers > 1 (#481) (fd73b88)
• don't inject empty tools:[] when client omitted the tools field (#772) (574bbae)
• harden Copilot API auth token handling (#557) (6b0c09f)
• health: readyz verifies upstream connectivity, not just process liveness (#744) (5dfb446)
• init: guard persistent task startup (#616) (9252d85)
• init: normalize Windows hook paths to forward slashes (#788) (6ea6e31)
• init: suppress hook recovery output (#760) (b439599)
• learn: claude-cli streams output with idle timeout (#373) (9bff575)
• make headroom wrap readiness probe timeout configurable for slow ML imports (#581) (163677b)
• parser: detect waste signals in Anthropic tool_result content blocks (#815) (929698a)
• proxy: F4 — trust X-Forwarded-* only behind allow-listed gateway (d10bd5f)
• proxy: lazy-import server to avoid fastapi crash (#442) (93c6937)
• proxy: make CCR multi-worker warning conditional on backend (#770) (d76a729)
• proxy: make Kompress eager preload cache-only so a cold cache can't block startup (#783) (841663d)
• proxy: restore Codex usage headers on WS and streaming SSE transports (#577) (#794) (0ce68de)
• schema compaction must not drop property names that match DROP_KEYS (#785) (ae2122f)
• security: block DNS-rebinding on /debug/* and /stats/reset via Host-header allowlist (#605) (b4b5025)
• ssl: upstream httpx client inherits SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS (#745) (e50fbb3)
• suppress LiteLLM provider banner before import (#874) (f9384ef)
• transforms: use thread-local tree-sitter parsers to prevent pyo3 Unsendable panic (#604) (2ad300a)
• wrap: track shared proxy clients with markers (#877) (05bd56b)

Code Refactoring

• extract litellm model resolution to shared utility (ec7d006)

0.24.0 (2026-06-08)

Features

• perf: add --format {text,json,csv} to headroom perf (#648) (9fe4886)
• proxy: show resolved upstream API targets in startup banner (#586) (8dbe7ad), closes #583
• relevance: weight BM25 score_batch by corpus IDF (#646) (88177bd)
• support CLAUDE_CODE_USE_FOUNDRY and custom upstream gateways (#726) (d90cdce)

Bug Fixes

• ci: restore green lint gate on main (fe50f9d)
• codex: auto-enable fail-open on compression timeout in headroom wrap codex (#531) (5f5f261)
• copilot: restore generic endpoint for non-subscription OAuth (#610) (#612) (18925b8)
• deps: move gunicorn to [proxy-prod] extra, add Windows guard (#537) (fa558c5)
• proxy: fail-open on corrupt golden bytes instead of RuntimeError (#603) (2170a1b)
• proxy: route Claude Code model metadata to Anthropic (#627) (30c1ac8)
• security: patch loopback guard, retry None raise, async subprocess, and cache race (06d7cb9)
• security: patch loopback guard, retry None raise, blocking subprocess, and cache stats race (78f3a4d)
• startup: move HF/httpx log suppression before sentence_transformers init (#622) (176d4c7)
• startup: suppress proxy startup log noise (#619) (4555901)
• wrap: report unbindable proxy ports (#602) (6dfcaa8)

Unreleased

Added

• kompress: warn when HEADROOM_KOMPRESS_BACKEND is set to an unrecognized value instead of silently falling back to auto, and document the backend selection env var (auto / onnx / onnx_cpu / onnx_coreml / pytorch / pytorch_mps plus shorthand aliases) in wiki/configuration.md (issue #202, PR #204).
• proxy: per-provider attribution in the savings history rollups. Each /stats-history bucket (hourly/daily/weekly/monthly) now carries a by_provider map breaking down tokens_saved, compression_savings_usd_delta, total_input_tokens_delta, and total_input_cost_usd_delta per provider, so consumers can show how savings and spend are distributed across providers within a time period. Providers only appear in a bucket where they moved a counter; legacy history checkpoints with no provider collapse into "unknown". Affected files: headroom/proxy/savings_tracker.py, headroom/proxy/prometheus_metrics.py.
• cli: startup banner now includes a Performance Tuning section that surfaces active HEADROOM_COMPRESSION_STABLE_AFTER_TURN, HEADROOM_STALE_READ_COMPRESS_AFTER_TURNS, and embedding-server socket values when set; shows a hint to set them when all defaults are in use.

Changed

• deps: loosen over-pinned constraints and add upper bounds
  • litellm==1.82.3 -> >=1.86.2,<2.0 (exact pin blocked security patches; floor stays above the CVE-2026-42271 fix)
  • transformers>=4.30.0 -> >=4.30.0,<6.0 (add upper bound; library already crossed a major version silently)
  • sentence-transformers>=2.2.0 -> >=2.2.0,<6.0 (same; applied in memory, evals, and dev extras)
  • neo4j>=5.20.0 -> >=5.20.0,<7.0 (client had already crossed the 5.x/6.x boundary)
  • mem0ai>=0.1.100 -> >=1.0.0,<2.0 (floor was pre-1.0; locked package is already 1.0.11)
  • langchain-core>=0.2.0 -> >=1.3.3,<4.0 (floor stays above current high-severity advisory fixes)
  • langchain-openai>=0.1.0 -> >=1.1.14,<2.0 (floor stays above current advisory fixes)
  • qdrant-client>=1.9.0 -> >=1.9.0,<2.0
  • uvicorn>=0.23.0 -> >=0.23.0,<1.0 (applied in proxy and dev extras)
  • Same transformers and litellm bounds applied consistently across ml, voice, and dev extras
• docker: bump neo4j image in docker-compose.yml from 5.15.0 to 5.26 (latest 5.x LTS)
• docker: bump UV_VERSION in Dockerfile from 0.11.16 to 0.11.18

Bug Fixes

• codex: respect CODEX_HOME when headroom wrap codex writes provider, MCP, memory, backup, and global AGENTS.md config, and warn when unwrap codex may be looking at the default Codex home because CODEX_HOME is unset.
• proxy: multi-worker CCR warning is now conditional on backend — when HEADROOM_CCR_BACKEND is unset (default InMemoryBackend, per-process), the startup warning includes CCR retrieval failures and suggests HEADROOM_CCR_BACKEND=sqlite; when a cross-worker backend is already configured, the warning covers only the remaining per-worker stores (compression cache, prefix tracker, TOIN, CostTracker). Updated RUST_DEV.md to accurately document Python CompressionStore as per-process by default.
• deps: move gunicorn to [proxy-prod] extra with sys_platform != 'win32' guard; removed from [proxy] to avoid forcing a Unix-only package on dev, CI, and Windows users (#537)
• startup: suppress proxy startup log noise -- litellm banner, trafilatura parse errors, HuggingFace Hub unauthenticated warnings, tiktoken fallback warning, and httpx INFO lines from sentence_transformers HEAD checks. Affected files: headroom/providers/litellm.py, headroom/transforms/html_extractor.py, headroom/memory/adapters/embedders.py, headroom/providers/anthropic.py, headroom/providers/registry.py, headroom/image/onnx_router.py, headroom/transforms/kompress_compressor.py.

0.23.0 (2026-06-04)

Features

• copilot: GitHub Copilot subscription mode through Headroom (f4dff9b)

Bug Fixes

• ccr: scope proactive expansion by workspace (cross-project leak) (197601b)
• ccr: scope proactive expansion by workspace (cross-project leak) (1bc163f)
• codex: keep init model_provider at config root (#260) (304dcc7)
• codex: keep init model_provider at config root (#260) (849b46d)
• copilot: deterministic subscription token handoff to the proxy (72da461)
• copilot: support subscription auth through Headroom (ff4a0c6)
• correct tiktoken encoding for unknown gpt-4 model snapshots (#552) (0e551de)
• decode/encode owned config, state and template assets as UTF-8 (2f1538a)
• decode/encode owned config, state and template assets as UTF-8 (fixes #533) (92075b9)
• docker: upgrade base images to Python 3.13 / debian13 (e6bf7a0)
• docker: upgrade base images to Python 3.13 / debian13, drop digest pinning (08a2197)
• docs: bump next.js to 16.2.6 for GHSA-h64f-5h5j-jqjh (CVE-2026-44577) (a6a09e6)
• docs: mkdocs configuration to build with correct folder (#543) (5557944)
• docs: update brace-expansion to 5.0.6 to remediate GHSA-jxxr-4gwj-5jf2 (CVE-2026-45149) (6eb6fb5)
• docs: update bun.lock to next 16.2.6 for GHSA-h64f-5h5j-jqjh (CVE-2026-44577) (91e0937)
• ignore brackets inside JSON strings when splitting mixed content (#553) (bdcfc32)
• learn: decode Unix home dirs whose username contains '.', '-' or '_' (211daae)
• learn: decode Unix home dirs whose username contains '.', '-' or '_' (491a8b3)
• learn: finish gemini-flash-latest default model sweep (982d01b)
• learn: finish gemini-flash-latest default model sweep (#532) (d797366)
• memory: READ-ONLY framing + fail-closed unresolved-project fallback (a178249)
• memory: READ-ONLY framing + fail-closed unresolved-project fallback (482f80e)
• update dashboard doc link (#544) (378d77e)
• Update Next.js to 16.2.4 in docs/bun.lock to address GHSA-gx5p-jg67-6x7h (CVE-2026-44580) (0b9f11a)
• Update Next.js to 16.2.6 in docs/package.json and package-lock.json to address GHSA-h64f-5h5j-jqjh (CVE-2026-44577) (db5d15f)
• Upgrade litellm to 1.86.2 to remediate CVE-2026-42271 (07581b9)

Code Refactoring

• cli: factor shared wrap-subcommand scaffolding (8eeb926)
• cli: factor shared wrap-subcommand scaffolding (c74ad11)

0.22.4 (2026-05-26)

Bug Fixes

• cli: G1 remediation — non-string clobber, per-model systemMessage, openhands gate (ea1976e)
• cli: wrap CLI breadth — cline, continue, goose, openhands (8625f80)
• cli: wrap subcommands for cline, continue, goose, openhands (c375fa1)
• observability: G3 remediation — bound cardinality + wire dead metrics (2a717a9)
• observability: RTK metrics + Rust observability (Phase H blocker) (b36ad9f)
• observability: wire Phase G PR-G3 RTK + proxy metrics (H-blocker) (5f264a5)
• release: tag format vX.Y.Z (drop release-please component prefix) (4a39ef5)
• release: tag format vX.Y.Z (drop release-please component prefix) (0f3e3af)
• subscription: address G2 review findings — phantom delta, multi-worker race, silent fallbacks (f68090c)
• subscription: wire tokens_saved_rtk data plane (c7d1247)
• subscription: wire tokens_saved_rtk from RTK stats endpoint (44c605f)
• tests: drive RTK subprocess failure with real exec, not monkeypatched run (9b6d637)
• tests: mock logger.warning directly instead of relying on caplog (c38dac3)
• tests: patch headroom.rtk.get_rtk_path, not the helpers alias (317dffe)
• tests: tomllib fallback to tomli on python 3.10 (74843d1)

Unreleased

Security

• /debug/memory loopback guard. The endpoint was missing the Depends(_require_loopback) guard that all other /debug/* endpoints carry. External callers can no longer reach it.
• retry_max_attempts zero guard. When retry_enabled=True and retry_max_attempts=0 the retry loop exited without setting last_error, causing raise last_error to raise TypeError: exceptions must derive from BaseException. A RuntimeError with an actionable message is now raised instead, and ProxyConfig.__post_init__ rejects retry_max_attempts < 1 at construction time.
• Blocking subprocess on async event loop. _read_rtk_lifetime_stats and _read_lean_ctx_lifetime_stats called subprocess.run directly on the asyncio thread. The initialize_context_tool_session_baseline function is now async and offloads the subprocess via asyncio.to_thread; the stats endpoint uses await asyncio.to_thread(_get_context_tool_stats).
• Hardcoded Neo4j credential in docker-compose.yml. NEO4J_AUTH now defaults to ${NEO4J_AUTH:-neo4j/devpassword} and is documented in .env.example (excluded from .gitignore via !.env.example).
• SemanticCache.get_memory_stats() concurrent iteration. The method iterates self._cache.values() without holding the async lock. A snapshot is now taken via list(self._cache.values()) before iterating to avoid RuntimeError: dictionary changed size during iteration under async load.
• Default Neo4j password in ProxyConfig. memory_neo4j_password default changed from "password" to "". The proxy startup path now emits a logger.warning when memory_backend == "qdrant-neo4j" and the password is empty, prompting operators to set a real credential.

Fixed

• PyPI install clarity and release gating. Documented pipx --python python3.13 for environments where unsupported Python wheel tags cause older-version resolution, made PyPI publish failures block GitHub Releases unless PYPI_SKIP=true, and added an sdist LICENSE invariant.

• headroom learn with claude-cli no longer fails silently on slow networks or large digests. The CLI backend timeout was a hard 120s wall-clock cap with no liveness signal: a successful long analysis and a hung connection looked identical, and exit 0 with "no recommendations" was the only user-visible signal. Two changes: (1) Streaming + idle timeout for claude-cli: the command now uses --output-format stream-json --verbose and a watchdog thread reads events as they arrive. The process is killed only after HEADROOM_LEARN_CLI_IDLE_TIMEOUT_SECS (default 60s) of zero output, or after HEADROOM_LEARN_CLI_TIMEOUT_SECS (default 300s, was 120s) total. Long-but-active analyses run to completion; genuine hangs are caught fast. The final type:"result" event carries the assistant response. Drains stdout/stderr via reader threads so the watchdog works on Windows too. (2) Env-var overrides for all CLI backends: HEADROOM_LEARN_CLI_TIMEOUT_SECS is honored by gemini-cli and codex-cli as the wall-clock timeout; idle override applies only to the streaming claude-cli path.

• Learned: error recovery section in MEMORY.md no longer bloats with stale, one-shot, or contradictory entries. The matchers paired up unrelated tool calls (e.g. state.rs and lib.rs in the same dir becoming File state.rs does not exist. The correct path is lib.rs.), the dedup key was the literal rendered bullet text so near-duplicates each created their own row, the shutdown flush dropped the evidence gate to 1 so every singleton landed at session end, and there was no TTL or re-validation. Fixed at every layer: (1) Emission: Read recoveries require the failed/successful basenames to be identical or close in edit distance; Bash recoveries require a shared binary (allowing python↔python3 and ruff↔.venv/bin/ruff variants) plus low-edit-distance OR a shared substantive non-flag token. Unrelated pairs are rejected at the source. (2) Dedup: error-recovery rows are hashed on recovery intent — Read on (basename(error_path), basename(success_path)), Bash on the primary command stripped of volatile suffixes (| tail -N, 2>&1, etc.). Near-duplicates collapse into one row. (3) Evidence gating: default min_evidence raised from 2 to 5; shutdown-relaxation removed; new --min-evidence flag and HEADROOM_MIN_EVIDENCE envvar so embedded clients can tighten the threshold further. (4) Render-time refinement: drop rows not re-observed in 21 days, re-validate Read success paths against the filesystem, collapse same-error_path-with-multiple-targets into one "use Glob/Grep first" bullet, rank by evidence_count * 0.5 ** (days/5), cap the section at 15. A→B / B→A contradiction pairs are also dropped at flush time. Patterns now stamp first_seen_at / last_seen_at on every save; _bump_persisted_evidence updates them via json_set. Other Learned: … categories (environment, preference, architecture) are untouched.

• headroom unwrap codex now actually undoes headroom wrap codex — previously there was no unwrap codex subcommand at all, so the injected model_provider = "headroom" / [model_providers.headroom] block stayed in ~/.codex/config.toml forever and Codex continued routing through the (potentially stopped) proxy, surfacing as Missing environment variable: OPENAI_API_KEY. wrap codex now snapshots the pre-wrap config.toml to config.toml.headroom-backup before its first injection, and unwrap codex restores that snapshot byte-for-byte (or, if the backup is missing, strips only the Headroom-managed block and leaves surrounding user content intact). Safe no-op when run without a prior wrap. Reported by @raenaryl in Discord.

• Image compressors now release shared router models after use and proxy shutdown — the proxy/image compression path no longer keeps global technique-router and SigLIP model instances pinned in memory after one-off image optimization work. The get_compressor() helper now returns a fresh, caller-owned compressor instead of a process-lifetime singleton.

• headroom learn no longer clobbers prior recommendations on re-run — the marker block in CLAUDE.md / MEMORY.md is now merged with the prior block instead of wholesale-replaced. Sections re-surfaced by the new run win; sections not re-surfaced are carried forward so learnings accumulate across runs instead of disappearing. To fully rebuild the block, delete it manually and re-run. (#231)

• headroom learn no longer emits dangling cross-references when a section is re-surfaced — the analyzer now includes the project's current <!-- headroom:learn --> block (from CLAUDE.md and MEMORY.md) in the LLM digest as a "Prior Learned Patterns" section, and the system prompt instructs the LLM that re-emitting a section replaces the prior one wholesale. Prevents bullets like "X is also large — same rule as Y, Z" from appearing after Y and Z got dropped during per-section replacement. The writer's section-level carry-forward from #231 remains in place as a safety net for sections the LLM omits entirely. New helper extract_marker_block added to headroom.learn.writer.

Added

• turn_id linking agent-loop API calls to a single user prompt — a new compute_turn_id(model, system, messages) helper in headroom/proxy/helpers.py hashes the message prefix up to and including the last user-text message, yielding an id that is stable across every agent-loop iteration of one prompt but rolls over when the user sends a new prompt (or runs /compact, /clear). RequestLog gained a turn_id: str | None field, which is stamped at every log site (anthropic handler bedrock + direct branches, and the streaming handler) and surfaced as turn_id in /transformations/feed. Lets downstream consumers (e.g. the Headroom Desktop Activity tab) aggregate savings per user prompt rather than per API call.
• Live flush of traffic-learned patterns to CLAUDE.md / MEMORY.md — the TrafficLearner now writes to agent-native context files continuously during proxy operation, not just at shutdown. A new dirty-flag debounced _flush_worker (10s window, FLUSH_DEBOUNCE_SECONDS) calls flush_to_file() whenever _accumulate() marks the learner dirty, so patterns surface in CLAUDE.md / MEMORY.md near real-time. Flushes read both persisted rows (via _load_persisted_patterns_from_sqlite) and the in-memory accumulator, bucket patterns by project via the learn plugin registry (plugin.discover_projects() + longest-path anchoring in _project_for_pattern), and route by PatternCategory to the correct file (_patterns_to_recommendations + _CATEGORY_TO_TARGET). Live flushes require evidence_count >= 2; the shutdown flush accepts single-evidence rows.

Fixed

• Traffic-learner evidence count stuck at 1; duplicate DB rows across restarts. _accumulate queued patterns with the default ExtractedPattern.evidence_count = 1 regardless of how many times the pattern was actually seen, so every persisted row landed at 1 and never crossed the live-flush gate (evidence_count >= 2). Worse, once a pattern was in _saved_hashes it was early-returned on every re-sighting, and _saved_hashes reset on process restart — so a second sighting in a later session inserted a duplicate row rather than bumping the existing one. Now: _accumulate writes the real accumulated count at save time, start() hydrates _saved_hashes + a new _persisted_ids map from the DB, and re-sightings bump the persisted row's metadata.evidence_count via an atomic json_set UPDATE (_bump_persisted_evidence). _load_persisted_patterns_from_sqlite now filters via json_extract(metadata, '$.source') instead of a LIKE on the raw JSON string, so rows survive metadata rewrites.

Added

• HEADROOM_QDRANT_* environment variables for memory Qdrant configuration (#31) — Memory(backend="qdrant-neo4j"), Mem0Config, MemoryConfig, and ProxyConfig now resolve their Qdrant connection from HEADROOM_QDRANT_URL, HEADROOM_QDRANT_HOST, HEADROOM_QDRANT_PORT, HEADROOM_QDRANT_API_KEY, HEADROOM_QDRANT_HTTPS, HEADROOM_QDRANT_PREFER_GRPC, and HEADROOM_QDRANT_GRPC_PORT. Explicit constructor arguments still win; unset env keeps the existing localhost:6333 defaults. Adds matching --memory-qdrant-{url,host,port,api-key} CLI flags. Enables hosted Qdrant (Qdrant Cloud) and shared/remote Qdrant stacks without code changes. New helper: headroom/memory/qdrant_env.py.
• Telemetry stack & install-mode identity fields — anonymous beacon now reports headroom_stack (how Headroom is invoked: proxy, wrap_claude, adapter_ts_openai, ...) and install_mode (wrapped / persistent / on_demand), plus requests_by_stack for proxies that serve multiple integrations. Proxy exposes a by_stack bucket alongside by_provider / by_model on /stats, a matching headroom_requests_by_stack Prometheus counter, and an X-Headroom-Stack header honored by the FastAPI middleware. headroom wrap <tool> sets HEADROOM_STACK=wrap_<agent>; the TS SDK and all four adapters (openai, anthropic, gemini, vercel-ai) tag their compress calls. Schema migration: sql/upgrade_telemetry_stack_context.sql.
• Canonical filesystem contract (issue #175) — new HEADROOM_CONFIG_DIR (default ~/.headroom/config, read-mostly) and HEADROOM_WORKSPACE_DIR (default ~/.headroom, read-write state) env vars recognized by the Python proxy/CLI and the npm SDK. Additive; all existing per-resource env vars (HEADROOM_SAVINGS_PATH, HEADROOM_TOIN_PATH, HEADROOM_SUBSCRIPTION_STATE_PATH, HEADROOM_MODEL_LIMITS) continue to work with identical semantics. Docker install scripts and docker-compose.native.yml forward the new vars into containers so savings, logs, and telemetry resolve to the bind-mounted .headroom path. See wiki/filesystem-contract.md.

Changed

• /stats-history now returns compact checkpoint history by default — the JSON response keeps recent checkpoints dense while evenly sampling older checkpoints so long-running installs do not return ever-growing payloads. Add history_mode=full to fetch the full retained checkpoint list, or history_mode=none to skip it entirely while still receiving the derived hourly/daily/weekly/monthly rollups. Responses now include a history_summary block describing stored versus returned points.

Fixed

• Streaming Anthropic requests are now visible to /stats.recent_requests and /transformations/feed — _finalize_stream_response did not call self.logger.log(...), so the entire streaming Anthropic code path (the one Claude Code uses) silently bypassed the request logger. Only the non-streaming Anthropic path and the Bedrock streaming path were logged. As a consequence, --log-messages had no observable effect on the live transformations feed for typical traffic. The streaming finalizer now emits the same RequestLog shape the other paths do, including request_messages when log_full_messages is enabled.

[0.5.22] - 2026-04-11

Added

• Cross-agent memory — Claude saves a fact, Codex reads it back. All agents sharing one proxy share one memory store. Project-scoped DB at .headroom/memory.db, auto user_id from $USER.
• Agent provenance tracking — every memory records which agent saved it (source_agent, source_provider, created_via), with edit history on updates.
• LLM-mediated dedup — on memory_save, enriched response hints similar existing memories to the LLM. Background async dedup auto-removes >92% cosine duplicates. Zero extra LLM calls.
• Memory for OpenAI and Gemini handlers — context injection + tool handling wired into all three provider handlers (Anthropic, OpenAI, Gemini).
• Plugin architecture for headroom learn — each agent (Claude, Codex, Gemini) is a self-contained plugin. External plugins register via headroom.learn_plugin entry points. --agent flag for CLI.
• GeminiScanner for headroom learn — reads ~/.gemini/tmp/*/chats/session-*.json and .jsonl.
• Code graph integration — headroom wrap claude --code-graph auto-indexes the project via codebase-memory-mcp for call-chain traversal, impact analysis, and architectural queries. Opt-in, ~200 token overhead with Claude Code's MCP Tool Search.
• OpenAI embedder auto-detection — memory backend uses OpenAI embeddings when sentence-transformers is unavailable (no torch/2GB dependency needed).
• Live traffic learning flush — headroom wrap <agent> --learn flushes learned patterns to the correct agent-native file (MEMORY.md / AGENTS.md / GEMINI.md) at proxy shutdown.

Changed

• CodeCompressor disabled by default — AST-based code compression produced invalid syntax on 40% of real files. Code now passes through uncompressed. Use --code-graph for code intelligence instead, or re-enable with --code-aware.
• Shared tool name map — consolidated tool normalization across all learn plugins into _shared.py.
• Dynamic CLI agent detection — headroom learn discovers agents via plugin registry, no hardcoded choices.

Fixed

• CodeCompressor statement-based truncation — body truncation now walks AST statements (not lines), never cuts mid-expression. Fixes syntax errors on multi-line dict literals and function calls.
• Docstring FIRST_LINE mode — uses source lines directly instead of reconstructing from byte offsets. Properly handles all quote styles.
• Memory shutdown queue drain — patterns in the save queue were lost on proxy shutdown. Now drained before exit.

Unreleased

Added

• Codex-proxy resilience hardening — reduces event-loop starvation under cold-start reconnect storms
  • Stage-timing instrumentation — per-stage durations for both Codex WS accept and Anthropic /v1/messages pre-upstream phases emitted as a single STAGE_TIMINGS structured log line per request plus Prometheus histograms
  • Per-pipeline shared warmup — Anthropic + OpenAI pipelines eagerly load compressors/parsers once at startup; status merged into WarmupRegistry for /debug/warmup and /readyz
  • WS session registry — first-class tracking of active Codex WS sessions with deterministic relay-task cancellation and termination-cause classification (client_disconnect, upstream_error, client_timeout, etc.)
  • Bounded pre-upstream Anthropic concurrency — --anthropic-pre-upstream-concurrency / HEADROOM_ANTHROPIC_PRE_UPSTREAM_CONCURRENCY caps simultaneous /v1/messages pre-upstream work (body read, deep copy, first compression stage, memory-context lookup, upstream connect) so replay storms cannot starve /livez, /readyz, and new Codex WS opens. Default: auto max(2, min(8, cpu_count)); 0 or negative disables (unbounded)
  • Loopback-only debug endpoints — /debug/tasks, /debug/ws-sessions, /debug/warmup return 404 (not 403) to non-loopback callers so external scanners cannot enumerate them
  • Reconnect-storm repro harness — scripts/repro_codex_replay.py drives concurrent WS + HTTP replay traffic against a local proxy and asserts /livez p99 under threshold; --json output routes JSON to stdout and the human summary to stderr
• Proxy liveness and readiness health checks
  • Adds GET /livez for process liveness and GET /readyz for traffic readiness
  • Keeps GET /health backward compatible while expanding it with readiness details and subsystem checks
  • Eagerly initializes configured memory backends during proxy startup so readiness reflects real serving capability
  • Wires /readyz into the Docker image HEALTHCHECK and the example docker-compose.yml
• Durable proxy savings history
  • Persists proxy compression savings history locally at ~/.headroom/proxy_savings.json
  • Supports HEADROOM_SAVINGS_PATH to override the storage location
  • Adds /stats-history with lifetime totals plus hourly/daily/weekly/monthly rollups
  • Supports JSON and CSV export from /stats-history
  • Extends /stats with a persistent_savings block while keeping savings_history backward compatible
  • Adds a historical mode to /dashboard backed by /stats-history, including export actions
• Proxy telemetry SDK override via HEADROOM_SDK
  • Downstream apps can override the anonymous telemetry sdk field without patching installed files
  • Blank values fall back to the default proxy label
• headroom learn — Offline failure learning for coding agents
  • Analyzes past conversation history (Claude Code, extensible to Cursor/Codex)
  • Success correlation: for each failure, finds what succeeded after and extracts the specific correction
  • 5 analyzers: Environment, Structure, Command Patterns, Retry Prevention, Cross-Session
  • Writes specific learnings to CLAUDE.md (stable project facts) and MEMORY.md (session patterns)
  • Generic architecture: tool-agnostic ToolCall model, pluggable Scanner/Writer adapters
  • Dry-run by default, --apply to write, --all for all projects
  • Example output: "FirstClassEntity.java is not at axion-formats/ — actually at axion-scala-common/"
• Read Lifecycle Management — Event-driven compression of stale/superseded Read outputs
  • Detects when a Read output becomes stale (file was edited after) or superseded (file was re-read)
  • Replaces stale/superseded content with compact CCR markers, stores originals for retrieval
  • 75% of Read output bytes are provably stale or redundant (from real-world analysis of 66K tool calls)
  • Fresh Reads (latest read, no subsequent edit) are never touched — Edit safety preserved
  • Opt-in via ReadLifecycleConfig(enabled=True), disabled by default
  • Handles both OpenAI and Anthropic message formats
• any-llm backend - Route requests through 38+ LLM providers (OpenAI, Mistral, Groq, Ollama, etc.) via any-llm
  • Enable with --backend anyllm --anyllm-provider <provider>
  • Install with: pip install 'headroom-ai[anyllm]'
• Production-ready proxy server with caching, rate limiting, and metrics
• CLI command headroom proxy to start the proxy server
• IntelligentContextManager (semantic-aware context management)
  • Multi-factor importance scoring: recency, semantic similarity, TOIN importance, error indicators, forward references, token density
  • No hardcoded patterns - all importance signals learned from TOIN or computed from metrics
  • TOIN integration for retrieval_rate and field_semantics-based scoring
  • Strategy selection: NONE, COMPRESS_FIRST, DROP_BY_SCORE based on budget overage
  • Atomic tool unit handling (call + response dropped together)
  • Configurable scoring weights via ScoringWeights dataclass
  • IntelligentContextConfig for full configuration control
  • Backwards compatible with RollingWindowConfig
• LLMLingua-2 Integration (opt-in ML-based compression)
  • LLMLinguaCompressor transform using Microsoft's LLMLingua-2 model
  • Content-aware compression rates (code: 0.4, JSON: 0.35, text: 0.3)
  • Memory management utilities: unload_llmlingua_model(), is_llmlingua_model_loaded()
  • Proxy integration via --llmlingua flag
  • Device selection: --llmlingua-device (auto/cuda/cpu/mps)
  • Custom compression rate: --llmlingua-rate
  • Helpful startup hints when llmlingua is available but not enabled
  • Install with: pip install headroom-ai[llmlingua] (the [llmlingua] extra was removed in 0.9.x)
• Code-Aware Compression (AST-based, syntax-preserving)
  • CodeAwareCompressor transform using tree-sitter for AST parsing
  • Supports Python, JavaScript, TypeScript, Go, Rust, Java, C, C++
  • Preserves imports, function signatures, type annotations, error handlers
  • Compresses function bodies while maintaining structural integrity
  • Guarantees syntactically valid output (no broken code)
  • Automatic language detection from code patterns
  • Memory management: is_tree_sitter_available(), unload_tree_sitter()
  • Uses tree-sitter-language-pack for broad language support
  • Install with: pip install headroom-ai[code]
• ContentRouter (intelligent compression orchestrator)
  • Auto-routes content to optimal compressor based on type detection
  • Source hint support for high-confidence routing (file paths, tool names)
  • Handles mixed content (e.g., markdown with code blocks)
  • Strategies: CODE_AWARE, SMART_CRUSHER, SEARCH, LOG, TEXT, LLMLINGUA
  • Configurable strategy preferences and fallbacks
  • Routing decision log for transparency and debugging
• Custom Model Configuration
  • Support for new models: Claude 4.5 (Opus), Claude 4 (Sonnet, Haiku), o3, o3-mini
  • Pattern-based inference for unknown models (opus/sonnet/haiku tiers)
  • Custom model config via HEADROOM_MODEL_LIMITS environment variable
  • Config file support: ~/.headroom/models.json
  • Graceful fallback for unknown models (no crashes)
  • Updated pricing data for all current models

Fixed

• Event.wait task leak in subscription trackers — asyncio.shield pattern prevents cancellation of the outer wait_for from leaking the inner Event.wait task
• Python 3.10 compatibility for memory-context fail-open — catches asyncio.TimeoutError (the 3.10-compatible alias) rather than TimeoutError to preserve behaviour on older runtimes
• uvicorn proxy_headers=False — refuses Forwarded / X-Forwarded-For rewrites so the loopback guard on /debug/* cannot be spoofed by a misconfigured reverse proxy
• First-frame timeout for Codex WS accepts — guards against a client that opens a handshake and never sends the first frame; relays cancel deterministically with client_timeout
• Semaphore leak on unexpected exception in Anthropic pre-upstream path — the finalizer now releases the pre-upstream semaphore on every exit path (early 4xx, cache hit, upstream error, streaming handoff)
• active_relay_tasks gauge double-decrement — deregister_and_count returns (handle, released_task_count) atomically so the handler decrements the Prometheus gauge by the exact number it registered, eliminating drift

Internal

• IPv6-mapped loopback recognition — the loopback guard parses ::ffff:127.0.0.1 and other dual-stack literals through ipaddress.ip_address(...).is_loopback
• Lock-free stage-timing accumulators — record_stage_timings writes to per-path counters that do not contend with /metrics export or record_request
• Narrow contextlib.suppress in relay classification — only CancelledError is suppressed where we reclassify it; other exceptions propagate so termination cause stays truthful
• jitter_delay_ms helper — shared exponential-backoff + 50-150% jitter formula in headroom/proxy/helpers.py; used by three proxy retry sites and mirrored inline in the repro harness

0.2.0 - 2025-01-07

Added

• SmartCrusher: Statistical compression for tool outputs
  • Keeps first/last K items, errors, anomalies, and relevance matches
  • Variance-based change point detection
  • Pattern detection (time series, logs, search results)
• Relevance Scoring Engine: ML-powered item relevance
  • BM25Scorer: Fast keyword matching (zero dependencies)
  • EmbeddingScorer: Semantic similarity with sentence-transformers
  • HybridScorer: Adaptive combination of both methods
• CacheAligner: Prefix stabilization for better cache hits
  • Dynamic date extraction
  • Whitespace normalization
  • Stable prefix hashing
• RollingWindow: Context management within token limits
  • Drops oldest tool units first
  • Never orphans tool results
  • Preserves recent turns
• Multi-Provider Support:
  • Anthropic with official count_tokens API
  • Google with official countTokens API
  • Cohere with official tokenize API
  • Mistral with official tokenizer
  • LiteLLM for unified interface
• Integrations:
  • LangChain callback handler (HeadroomOptimizer)
  • MCP (Model Context Protocol) utilities
• Proxy Server (headroom.proxy):
  • Semantic caching with LRU eviction
  • Token bucket rate limiting
  • Retry with exponential backoff
  • Cost tracking with budget enforcement
  • Prometheus metrics endpoint
  • Request logging (JSONL)
• Pricing Registry: Centralized model pricing with staleness tracking
• Benchmarks: Performance benchmarks for transforms and relevance scoring

Changed

• Improved token counting accuracy across all providers
• Enhanced tool output compression with relevance-aware selection

Fixed

• Mistral tokenizer API compatibility
• Google token counting for multi-turn conversations

0.1.0 - 2025-01-05

Added

• Initial release
• HeadroomClient: OpenAI-compatible client wrapper
• ToolCrusher: Basic tool output compression
• Audit mode for observation without modification
• Optimize mode for applying transforms
• Simulate mode for previewing changes
• SQLite and JSONL storage backends
• HTML report generation
• Streaming support

Safety Guarantees

• Never removes human content
• Never breaks tool ordering
• Parse failures are no-ops
• Preserves recency (last N turns)

---

Migration Guide

From 0.1.x to 0.2.x

The 0.2.0 release is backward compatible. New features are opt-in:

# Old code still works
from headroom import HeadroomClient, OpenAIProvider

# New SmartCrusher (replaces ToolCrusher for better compression)
from headroom import SmartCrusher, SmartCrusherConfig

config = SmartCrusherConfig(
    min_tokens_to_crush=200,
    max_items_after_crush=50,
)
crusher = SmartCrusher(config)

# New relevance scoring
from headroom import create_scorer

scorer = create_scorer("hybrid")  # or "bm25" for zero deps

Using the Proxy

New in 0.2.0 - run Headroom as a proxy server:

# Start the proxy
headroom proxy --port 8787

# Use with Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude