Windows: _core.detect_content_type hangs on headroom-ai 0.24.0 / Python 3.13, breaking MCP compression

[laiyangli001]

Summary

headroom._core.detect_content_type() hangs on Windows with headroom-ai 0.24.0 and Python 3.13. This makes headroom_compress unusable for any content large enough to enter the real compression path.

This appears related to #713 / #575, but I am filing a new issue because this is still reproducible on the current 0.24.0 Windows wheel and a newer Python 3.13 environment.

Environment

• OS: Windows 10 10.0.19045
• Python: 3.13.13 CPython win_amd64
• headroom-ai: 0.24.0
• Wheel: headroom_ai-0.24.0-cp313-cp313-win_amd64.whl
• Shell: PowerShell

Minimal Reproduction

python -c "from headroom._core import detect_content_type; print(detect_content_type('short headroom mcp smoke test'))"

Actual Result

The process hangs. In my test it did not return within 60 seconds.

This is not caused by large input. The input above is a short plain-text string.

Expected Result

detect_content_type() should return quickly, for example as plain text.

Related Checks

The Rust extension itself imports and other exported functions return immediately:

python -c "from headroom._core import hello; import time; t=time.perf_counter(); print(hello(), round(time.perf_counter()-t,3))"

Output:

headroom-core 0.0

python -c "from headroom._core import is_json_array_of_dicts; import time,json; content=json.dumps([{'a':1}]); t=time.perf_counter(); print(is_json_array_of_dicts(content), round(time.perf_counter()-t,3))"

Output:

True 0.0

The pure Python fallback detector returns immediately:

python -c "from headroom.transforms.content_detector import detect_content_type; import time; content='short headroom mcp smoke test'; t=time.perf_counter(); r=detect_content_type(content); print(r, round(time.perf_counter()-t,3))"

Output:

DetectionResult(content_type=<ContentType.PLAIN_TEXT: 'text'>, confidence=0.5, metadata={}) 0.0

Impact

headroom_compress through MCP only works for very small content because it exits via router:noop.

For larger content:

1. MCP headroom_compress wraps the content as a tool message.
2. headroom.compress.compress() enters ContentRouter.
3. ContentRouter._detect_content() calls headroom._core.detect_content_type().
4. The call hangs.
5. MCP eventually times out after 120 seconds.

headroom perf also showed proxy optimization overhead around 30 seconds per request with 0 tokens saved before I stopped using proxy mode.

Request

Please either:

1. Fix the Windows deadlock/hang in _core.detect_content_type(), or
2. Provide a supported opt-out to force the Python detector, for example an environment variable such as HEADROOM_DETECT_BACKEND=python / regex.

Without such a fallback, Headroom MCP on Windows cannot reliably compress large tool outputs.

[warplayer]

Confirming this reproduces in proxy mode as well, not just MCP — and confirming the Python-detector workaround fixes it.

Environment

• OS: Windows 11
• Python: 3.13.13 (CPython, win_amd64)
• headroom-ai: 0.24.0 (PyPI wheel)
• Invocation: headroom proxy --port 8787

Symptoms: a direct POST /v1/compress with a small payload hangs indefinitely, while x-headroom-bypass: true returns immediately. Switching the Kompress backend between ONNX and PyTorch makes no difference — the request never reaches the model. Through the Anthropic proxy path, requests succeed but compression silently fails open: /stats shows transforms_applied: [], tokens_saved: 0, and overhead.max_ms of 30021 ms — matching the ~30 s per-request overhead described in the original report.

I can also reproduce the minimal case from this issue: the bare _detect_content call hangs past a 20 s faulthandler timeout, pointing at the _rust_detect(content) call site:

Timeout (0:00:20)!
Thread 0x00007844 (most recent call first):
File "...\headroom\transforms\content_router.py", line 126 in _detect_content
File "", line 1 in

py-spy dump taken while the proxy was hung shows all five headroom-compress_* worker threads blocked at the same line:

Thread 12104 (idle): "headroom-compress_0"
_detect_content (headroom\transforms\content_router.py:126)
compress (headroom\transforms\content_router.py:933)
_process_content_blocks (headroom\transforms\content_router.py:2471)
apply (headroom\transforms\content_router.py:2014)
apply (headroom\transforms\pipeline.py:251)
(headroom\proxy\handlers\anthropic.py:1046)
_wrapped (headroom\proxy\server.py:781)

(Threads _1 through _4 are identical.) Once the worker pool is exhausted, all subsequent compression requests queue indefinitely — which is why /v1/compress hangs outright rather than timing out.

Workaround verified: locally patching ContentRouter._detect_content to call headroom.transforms.content_detector.detect_content_type (the pure-Python detector), keeping the existing _regex_detect_content_type refinement for plain-text results, fully restores compression on the same machine. With the patch in place, real proxy traffic shows ~39% token savings (e.g. 33,380 → 15,798 input tokens on one request), compressions_by_strategy: {text: 2}, CCR entries being written, and per-request optimization overhead dropping from the 30 s timeout to ~70–90 ms after warm-up.

Strong +1 for a supported escape hatch like HEADROOM_DETECT_BACKEND=python until the Rust-side hang is fixed — the Python detector clearly still works and the hard dependency currently leaves Windows users with no recourse. Thanks!

[ChanghoSong]

Reproduces on 0.25.0 — Windows 10 + Python 3.13

Confirming this still hangs on the latest release.

Environment

• OS: Windows 10 10.0.19045
• Python: 3.13 (system default)
• headroom-ai: 0.25.0

Evidence from proxy.log

Every single request hits a ~30-second timeout:

2026-06-13 01:59:37 WARNING [hr_1781283547_000002] Optimization failed: TimeoutError
compression_first_stage: 30002.750999992713 ms
total_pre_upstream: 30013.333899900317 ms
opt_ms: 30010 transforms=none

compression_first_stage: 30016 ms
compression_first_stage: 30000 ms
compression_first_stage: 30008 ms

The pattern is consistent — every request burns exactly ~30 seconds before timing out, regardless of content type. This matches the WaitOnAddress deadlock described in #575.

Workaround (passthrough only)

--no-optimize avoids the hang, but disables all compression — no token savings.

--disable-kompress still triggers the deadlock because detect_content_type runs before the ML model check.

---

Update: local patch restores compression

Based on @warplayer's py-spy analysis, I applied the pure-Python detector patch locally:

# In content_router.py _detect_content():
# Replace:
from headroom._core import detect_content_type as _rust_detect
rust_result = _rust_detect(content)

# With:
from headroom.transforms.content_detector import detect_content_type as _py_detect
py_result = _py_detect(content)

Verified results on Windows 10 + Python 3.13 + headroom 0.25.0:

Metric	Before patch	After patch
opt_ms	~30,000ms (TimeoutError)	185ms
Compression	❌ transforms=none	✅ 8.9% (session warmup)
Log errors	Optimization failed: TimeoutError	None

Running headroom proxy (default mode, no flags) now works correctly. Strong +1 for HEADROOM_DETECT_BACKEND=python as an official escape hatch.

[DNYoussef]

Confirming this on a different environment, with some extra characterization that may help.

Env: Windows 10, Python 3.12.5, headroom-ai 0.25.0 (installed isolated via pipx). Reproduces exactly as reported.

Key finding: the hang is unconditional and not data-dependent. headroom._core.detect_content_type deadlocks on its first call for any input -- I tested down to a 1-byte string and the literal "hello"; all hang. It is not about large/JSON payloads (that was just the first input that happened to reach it). Every other _core export returns instantly in the same process (hello(), is_json_array_of_dicts(...), is_html_tag(...)), which rules out a module-load/DLL deadlock and pins it to the magika/onnxruntime session-init path that only detect_content_type triggers.

Note: compress() appears to work on tiny inputs only because it short-circuits before detection; anything that reaches _detect_content hangs forever.

faulthandler stack (8s):

Thread 0x... (most recent call first):
  File ".../headroom/transforms/content_router.py", line 127 in _detect_content
  File ".../headroom/transforms/content_router.py", line 2177 in apply
  File ".../headroom/transforms/pipeline.py", line 323 in apply
  File ".../headroom/compress.py", line 235 in compress

The thread is stuck in the native frame below line 127 (rust_result = _rust_detect(content)), no Python frames underneath.

Mitigations that did NOT help (set before import): OMP_NUM_THREADS=1, ORT_DISABLE_ALL_OPTIMIZATION=1, OMP_WAIT_POLICY=PASSIVE, KMP_DUPLICATE_LIB_OK=TRUE -- all still hang. So the ORT/OpenMP env knobs don't reach the session.

Workaround #1 (pure-Python detector) confirmed working. Bypassing the native call in content_router.py:_detect_content and returning _regex_detect_content_type(content) instead restores compression: a 13.8KB / 150-element JSON array now compresses in 0.13s, ~58% tokens saved (4768 -> 2005), router:smart_crusher. Same result the Rust chain would have produced (JSON_ARRAY), just instant.

Confirming PR #928 looks like the right fix; flagging that as of 0.25.0 it isn't on PyPI yet, so Windows users are currently stuck on the workaround. A released build (or an interim HEADROOM_DETECT_BACKEND=python style escape hatch in the Python layer) would help a lot. Thanks!

[Parideboy]

Verification: this is fixed on main — recommend closing

I traced this against current main. The Windows hang in _core.detect_content_type that broke MCP/proxy compression is addressed by a stack of merged fixes:

Layer	Fix	Where on main
Root cause	Windows 11 24H2+ ships System32\onnxruntime.dll (Windows ML); initializing an ORT 2.x session against it deadlocks at ~0% CPU — matching the WaitOnAddress / 30 s-timeout signature in the comments. headroom/_ort.py now pins ORT_DYLIB_PATH to the pip-installed ONNX Runtime DLL before headroom._core is imported (wired from headroom/__init__.py).	PR #1010 (headroom/_ort.py)
Supported opt-out	The HEADROOM_DETECT_BACKEND=python escape hatch requested across this thread exists, and the detector defaults to the pure-Python regex path on Windows — so the proxy/MCP _detect_content path no longer calls the native detector by default. This is exactly the pure-Python-detector workaround @warplayer, @ChanghoSong and @DNYoussef verified, now shipped as the default.	PR #1063 (content_router._resolve_detect_backend)
Native-panic safety net	A native panic/unknown tag degrades to the pure-Python detector instead of failing the request.	PR #1260 (closes #1123)
Startup safety net	Eager preload is timeout-bounded and off-thread, so a hung model load can't stop the proxy binding its port.	PR #1500 (closes #790)

Regression coverage: tests/test_transforms_content_router.py::test_detect_backend_defaults_to_python_on_windows is tagged with this issue (#845); env-override + panic-fallback tests live in the same file and tests/test_transforms/test_detect_fallback_1123.py.

The reports here were on PyPI wheels 0.24.0–0.25.0, which predate all four PRs — that's why it kept reproducing across versions. On current main, the worker threads no longer block on _rust_detect(content) (the py-spy hot line) because Windows uses the pure-Python detector by default, and the ORT pin removes the underlying deadlock for anyone who explicitly opts into HEADROOM_DETECT_BACKEND=rust.

Note: verified by reading main's source and tests, not by rebuilding the wheel on a Windows 24H2 host — worth a confirmation run from a current-main build (or the next PyPI release) before closing.

#713 is the same root cause; the two can close together.