Commit Graph
240 Commits
Author SHA1 Message Date
d379efe90c test: skip tests marked live by default (#4786)
## Description

`pyproject.toml` declares a `live` marker ("opt-in multi-turn tests that
hit real upstream APIs; require provider keys"), and two test files
carry it: `tests/test_thinking_signature_scope_live.py` ("Opt-in:
requires a real key and is gated behind `pytest.mark.live`. Run with
`pytest -m live ...`") and `tests/test_realignment_live_multi_turn.py`
(which describes a "default `pytest -m "not live"` run that never
touches the network"). `addopts` was `-v --tb=short` with no `-m`
filter, so a plain `pytest` run on a machine with `ANTHROPIC_API_KEY` in
the environment, or in the project's `.env` (loaded by
`tests/_dotenv.py`), collected these tests and called the real API.

This PR adds `-m 'not live'` to `addopts`, so the default run deselects
them. `pytest -m live <file>` still selects them (a later `-m` replaces
this one).

Part of #4783

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `pyproject.toml`: `addopts = "-v --tb=short -m 'not live'"`, with a
three-line comment saying why and how to opt in.
- `tests/test_realignment_live_multi_turn.py`: the module-wide `live`
marker is replaced by `@pytest.mark.live` on the eight tests that need a
provider key, so the offline
`test_classify_auth_mode_routes_payg_vs_oauth` keeps running by default.
- `tests/test_live_marker_default_deselect.py`: collection-only test
that the default run deselects live tests, keeps the offline one, and
that `-m live` selects them again (fails against the old `addopts`).

## Testing

- [x] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

This changes pytest configuration only, so no new test is added; the
proof is the collection result below (`--collect-only`, with a dummy
`ANTHROPIC_API_KEY`, nothing contacted).

### Test Output

```text
Before (origin/main pyproject.toml):
pytest tests/test_thinking_signature_scope_live.py tests/test_realignment_live_multi_turn.py --collect-only -q
15 tests collected

After (this branch):
same command                           -> 1 test collected (the offline test_classify_auth_mode_routes_payg_vs_oauth), 14 deselected
same command with -m live              -> 14 tests collected
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12, pytest 9.2.0,
`ANTHROPIC_API_KEY=sk-ant-dummy-collect-only` in the environment.
- Exact command / steps: `python -m pytest
tests/test_thinking_signature_scope_live.py
tests/test_realignment_live_multi_turn.py --collect-only -q`, with the
pyproject from `origin/main` and with this branch's, and once more with
`-m live`.
- Observed result: before, 15 tests collected (they would run and call
the API when a key is present); after, the 14 provider-calling tests are
deselected and the offline one is still collected; with `-m live`, 14
collected.
- Not tested: an actual live run (no provider key was used), and CI (the
CI workflows I read do not export a provider key to pytest, so this PR
is aimed at developer machines).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; test configuration only.
- Minimum rollout channel: n/a
- Stable/default behavior changed: no for the library and proxy. The
default `pytest` run no longer collects tests marked `live`.
- Kill switch / disable path: run `pytest -m live ...` (or pass any `-m`
expression).
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes (the
whole suite was not run; see Testing)
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

- If a CI job runs `pytest -m live` deliberately it keeps working,
because the later `-m` wins. I did not find such a job.

AI assistance: this change and the runs above were done with Claude
(Sonnet 5.5), operated by me (HetCreep).

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

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4786"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-16 19:48:28 -06:00
JD DavisandCopilot e9301f34c1 feat(tray): opt-in system tray icon with savings counter, dashboard and update alert (#4726)
## Description

Adds an **opt-in system tray icon** for Headroom while it runs (Windows
first; macOS/Linux planned). The icon is the Headroom logomark and its
right-click menu shows a compact savings counter (tokens and estimated $
saved), opens the dashboard, alerts when an update is available, and
lets you quit.

Closes #

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- New `headroom/tray/` package: `core.py` (GUI-free stats
polling/formatting), `icon.py` (logomark drawn with Pillow, no binary
assets in the wheel), `app.py` (pystray app), `launcher.py` (spawns the
tray as a child of the proxy).
- `headroom proxy --tray` starts the tray with the proxy; `headroom tray
--port N` attaches to a running proxy.
- Menu: live `▼ tokens · ~$ saved` counter (from `/stats` →
`persistent_savings.lifetime`, polled every 5s), Open Dashboard, "Update
available" (only when newer; reuses `headroom.update_check`, honours
`HEADROOM_UPDATE_CHECK=off`; one-time notification), Quit.
- Icon states: normal, orange dot when an update exists, grey when the
proxy is offline.
- New optional extra `headroom-ai[tray]` (`pystray`, `pillow`).
Unsupported platform / missing extra: `--tray` prints why and the proxy
starts normally.
- Docs: `docs/content/docs/system-tray.mdx` + nav entry; screenshots in
`docs/public/assets/tray/`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
> python -m ruff check headroom\tray headroom\cli tests\test_tray_core.py
All checks passed!
> python -m mypy headroom\tray headroom\cli\tray.py
Success: no issues found in 7 source files
> python -m pytest tests\test_tray_core.py tests\cli tests\test_offline_egress_chokepoint.py tests\test_proxy\test_settings_store.py -q
293 passed, 2 skipped
```

(Scoped runs; I did not run the full suite or `mypy headroom` over the
whole package.)

## Real Behavior Proof

- Environment: Windows 11, Python 3.13.13, 3840x2160 display, `pystray`
+ `pillow` 12.3.0, branch based on `upstream/main` @ 1da8930ab.
- Exact command / steps: run the 4 steps below.
1. `HEADROOM_UPDATE_CHECK=off`, then `python -m headroom.cli proxy
--tray --port 8799`
2. Confirmed `GET /health` → 200 and a `python -m headroom.tray --host
127.0.0.1 --port 8799 --owns-proxy` child process.
3. Opened the taskbar overflow, right-clicked the Headroom icon,
captured the menu (below).
  4. Clicked **Quit Headroom**.
- Observed result: icon appeared with the logomark; menu showed `▼ 256M
tokens · ~$765.96 saved` (my real lifetime savings store), **Open
Dashboard**, **Quit Headroom**. After Quit, `/health` no longer
responded (proxy shut down gracefully).
- Not tested: the real update toast and "Update available" menu item
(covered only by a unit test of `available_update()` and a rendered
icon); clicking Open Dashboard / double-click default action; macOS and
Linux (intentionally unsupported for now); HiDPI/light-theme variations;
`headroom tray` standalone Exit in the UI.

## Runtime Rollout Safety

- Rollout-managed feature(s): None (not rollout-channel gated).
- Minimum rollout channel: N/A
- Stable/default behavior changed: No. Off by default; only active with
`--tray`.
- Kill switch / disable path: omit `--tray` (or pass `--no-tray`).
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: revert this PR; the new extra and command are additive.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes (only
`tests/test_tray_core.py` and `tests/cli` were run)
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

**Tray icon** (left: real icon in the Windows taskbar overflow, zoomed;
then rendered states: live, update available, proxy offline)

![Tray icon
states](https://raw.githubusercontent.com/JerrettDavis/headroom/3e824653772642c95fded190b454fff82f2ce86a/docs/public/assets/tray/tray-icon.png)

**Right-click menu** (real capture)

![Tray right-click
menu](https://raw.githubusercontent.com/JerrettDavis/headroom/3e824653772642c95fded190b454fff82f2ce86a/docs/public/assets/tray/tray-menu.png)

**How to use**

```bash
pip install "headroom-ai[tray]"
headroom proxy --tray        
headroom tray --port 8787    # attach to an already-running proxy
```

Windows hides new tray icons in the `^` overflow next to the clock; drag
the icon onto the taskbar to pin it, then right-click. Full guide:
`docs/content/docs/system-tray.mdx`.

## Feature spec

- **API surface**: `headroom proxy --tray/--no-tray`, `headroom tray
--port N`, extra `headroom-ai[tray]`. No change to existing behavior
when the flag is absent.
- **User stories**: Given the proxy runs with `--tray`, when I
right-click the icon, then I see tokens/$ saved, Open Dashboard and
Quit. Edge: given the proxy is down, the icon turns grey and the tooltip
says offline.
- **Failure modes / recovery**: unsupported platform or missing extra
prints a reason and the proxy starts normally; the tray child exits when
the proxy dies (stdin EOF); a stats fetch failure shows the offline
state and retries every 5s. Quit sends SIGINT for graceful shutdown
without a force-exit deadline.
- **Security**: tray only polls the local proxy `/stats`; no network
calls of its own (update info read from the existing cache; honours
`HEADROOM_UPDATE_CHECK=off`); child is spawned with a fixed argv.

## Dependency justification

- **Why**: `pystray` is the standard cross-platform tray library
(Win/macOS/Linux); `pillow` is required by it for icons and lets us draw
the logomark with no binary assets. No existing dep provides a tray.
- **Maintainers**: pystray (moses-palmer), BSD/LGPL, stable ~0.19.5
releases; Pillow (python-pillow org), very active, frequent security
releases.
- **Install surface**: optional extra only (not default). pystray pulls
`six`, plus pywin32-free ctypes on Windows; Pillow ships prebuilt
wheels. No install-time network access.
- **Why these versions**: `pystray>=0.19.5` is the current release
(required new functionality); `pillow>=12.3.0` matches the repo pin
level already used elsewhere to avoid known CVEs.

## Additional Notes

- The menu screenshot shows my real local savings numbers.
- The Quit item stops the proxy only when the tray was started via
`headroom proxy --tray`; the standalone `headroom tray` shows "Exit" and
only closes the tray.
- Follow-ups: macOS/Linux backends (pystray needs the main thread on
macOS, hence the child-process design).

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-16 19:40:55 -06:00
dependabot[bot]andJerrettDavis e89d2c2ab2 deps: bump ruff from 0.17.3 to 0.17.4 in the pip-minor-patch group (#4804)
Bumps the pip-minor-patch group with 1 update:
[ruff](https://github.com/astral-sh/ruff).

Updates `ruff` from 0.17.3 to 0.17.4
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/ruff/releases">ruff's
releases</a>.</em></p>
<blockquote>
<h2>0.17.4</h2>
<h2>Release Notes</h2>
<p>Released on 2026-11-05.</p>
<h3>Preview features</h3>
<ul>
<li>[<code>flake8-logging-format</code>] Avoid behavior changes and
syntax errors in fixes (<code>G004</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27419">#27419</a>)</li>
<li>[<code>security</code>] Implement
<code>tarfile-ignore-zeros-true</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28680">#28680</a>)</li>
</ul>
<h3>Bug fixes</h3>
<ul>
<li>Accept a bare raise before a semicolon (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29761">#29761</a>)</li>
<li>Allow match identifiers after a semicolon (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29760">#29760</a>)</li>
<li>Fix panic on BOM-prefixed files in diagnostic renderer (<a
href="https://redirect.github.com/astral-sh/ruff/pull/30017">#30017</a>)</li>
<li>[<code>flake8-simplify</code>] Report collapsible <code>elif</code>
clauses after a multi-statement <code>if</code> branch
(<code>SIM102</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29814">#29814</a>)</li>
</ul>
<h3>Rule changes</h3>
<ul>
<li>Show more nonprinting characters in diagnostic fix diffs (<a
href="https://redirect.github.com/astral-sh/ruff/pull/30062">#30062</a>)</li>
</ul>
<h3>Performance</h3>
<ul>
<li>Coalesce source slices when formatting attributes (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29841">#29841</a>)</li>
<li>Collect return statements with a statement-only visitor (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29911">#29911</a>)</li>
<li>[<code>pyflakes</code>] Defer value comparisons for repeated
dictionary keys (<code>F601</code>, <code>F602</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29739">#29739</a>)</li>
<li>Format node fields directly when comment handling is unnecessary (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29853">#29853</a>)</li>
<li>Reduce formatter source-slice overhead (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29855">#29855</a>)</li>
<li>Reuse a callee's qualified name across lint rules (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29916">#29916</a>)</li>
<li>Skip invalid string character checks when the source contains none
(<a
href="https://redirect.github.com/astral-sh/ruff/pull/29883">#29883</a>)</li>
<li>Use a Bloom filter for formatter comment lookups (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29852">#29852</a>)</li>
<li>Use a concrete buffer for ordinary writes (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29819">#29819</a>)</li>
</ul>
<h3>CLI</h3>
<ul>
<li>Give <code>NO_COLOR</code> precedence in Ruff and ty diagnostics (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29898">#29898</a>)</li>
<li>Honor <code>CLICOLOR=0</code> in Ruff and ty diagnostics (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29910">#29910</a>)</li>
</ul>
<h3>Documentation</h3>
<ul>
<li>Correct the documented <code>version</code> and <code>src</code>
defaults for <code>ruff-action</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29880">#29880</a>)</li>
<li>[<code>flake8-bugbear</code>] Make <code>B014</code> example error
out-of-the-box (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29941">#29941</a>)</li>
<li>[<code>flake8-no-pep420</code>] Document preview behavior
(<code>INP001</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29764">#29764</a>)</li>
<li>[<code>isort</code>] Expand <code>I001</code> documentation (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29843">#29843</a>)</li>
</ul>
<h3>Other changes</h3>
<ul>
<li>[syntax-errors] Extend <code>__debug__</code> write check to
attribute targets (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27908">#27908</a>)</li>
</ul>
<h3>Contributors</h3>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md">ruff's
changelog</a>.</em></p>
<blockquote>
<h2>0.17.4</h2>
<p>Released on 2026-11-05.</p>
<h3>Preview features</h3>
<ul>
<li>[<code>flake8-logging-format</code>] Avoid behavior changes and
syntax errors in fixes (<code>G004</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27419">#27419</a>)</li>
<li>[<code>security</code>] Implement
<code>tarfile-ignore-zeros-true</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28680">#28680</a>)</li>
</ul>
<h3>Bug fixes</h3>
<ul>
<li>Accept a bare raise before a semicolon (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29761">#29761</a>)</li>
<li>Allow match identifiers after a semicolon (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29760">#29760</a>)</li>
<li>Fix panic on BOM-prefixed files in diagnostic renderer (<a
href="https://redirect.github.com/astral-sh/ruff/pull/30017">#30017</a>)</li>
<li>[<code>flake8-simplify</code>] Report collapsible <code>elif</code>
clauses after a multi-statement <code>if</code> branch
(<code>SIM102</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29814">#29814</a>)</li>
</ul>
<h3>Rule changes</h3>
<ul>
<li>Show more nonprinting characters in diagnostic fix diffs (<a
href="https://redirect.github.com/astral-sh/ruff/pull/30062">#30062</a>)</li>
</ul>
<h3>Performance</h3>
<ul>
<li>Coalesce source slices when formatting attributes (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29841">#29841</a>)</li>
<li>Collect return statements with a statement-only visitor (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29911">#29911</a>)</li>
<li>[<code>pyflakes</code>] Defer value comparisons for repeated
dictionary keys (<code>F601</code>, <code>F602</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29739">#29739</a>)</li>
<li>Format node fields directly when comment handling is unnecessary (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29853">#29853</a>)</li>
<li>Reduce formatter source-slice overhead (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29855">#29855</a>)</li>
<li>Reuse a callee's qualified name across lint rules (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29916">#29916</a>)</li>
<li>Skip invalid string character checks when the source contains none
(<a
href="https://redirect.github.com/astral-sh/ruff/pull/29883">#29883</a>)</li>
<li>Use a Bloom filter for formatter comment lookups (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29852">#29852</a>)</li>
<li>Use a concrete buffer for ordinary writes (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29819">#29819</a>)</li>
</ul>
<h3>CLI</h3>
<ul>
<li>Give <code>NO_COLOR</code> precedence in Ruff and ty diagnostics (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29898">#29898</a>)</li>
<li>Honor <code>CLICOLOR=0</code> in Ruff and ty diagnostics (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29910">#29910</a>)</li>
</ul>
<h3>Documentation</h3>
<ul>
<li>Correct the documented <code>version</code> and <code>src</code>
defaults for <code>ruff-action</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29880">#29880</a>)</li>
<li>[<code>flake8-bugbear</code>] Make <code>B014</code> example error
out-of-the-box (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29941">#29941</a>)</li>
<li>[<code>flake8-no-pep420</code>] Document preview behavior
(<code>INP001</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29764">#29764</a>)</li>
<li>[<code>isort</code>] Expand <code>I001</code> documentation (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29843">#29843</a>)</li>
</ul>
<h3>Other changes</h3>
<ul>
<li>[syntax-errors] Extend <code>__debug__</code> write check to
attribute targets (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27908">#27908</a>)</li>
</ul>
<h3>Contributors</h3>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/astral-sh/ruff/commit/05cdc36a45a29e078c2af9358969d0f576408bef"><code>05cdc36</code></a>
Bump version to 0.17.4 (<a
href="https://redirect.github.com/astral-sh/ruff/issues/30073">#30073</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/c6b17c2b0bd1a0ffe6cd562c6dfaeece2a65f742"><code>c6b17c2</code></a>
[ty] Freshen method typevars before owner specialization (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29543">#29543</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/4b0b407bfccff1d6aa46e2f26112f334bfab3140"><code>4b0b407</code></a>
[ty] Preserve unions inferred during fixpoint iteration (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29927">#29927</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/1dd3e9ec7eb8da6b39318ef1084bc070a53ae272"><code>1dd3e9e</code></a>
Show more nonprinting characters in diagnostic fix diffs (<a
href="https://redirect.github.com/astral-sh/ruff/issues/30062">#30062</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/32be8e7258782da94b18752249971be4708d485c"><code>32be8e7</code></a>
[ty] Skip fixpoint iteration for simple generic calls (<a
href="https://redirect.github.com/astral-sh/ruff/issues/30054">#30054</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/926ccc883c5cf3d54b1dea610603acd2aae93c19"><code>926ccc8</code></a>
[ty] Handle output errors when generating shell completions (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29997">#29997</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/c86652abceafe81457858c75c9233eadf1d39912"><code>c86652a</code></a>
[ty] Skip active Conda and Pixi environments during discovery if the
environm...</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/c9150f008303c86ad49675f73b75b923f0013bdf"><code>c9150f0</code></a>
Add project walltime benchmarks for Ruff (<a
href="https://redirect.github.com/astral-sh/ruff/issues/30061">#30061</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/64989ec2a42c65dabb471e20976f4f014c966f27"><code>64989ec</code></a>
[ty] Report invalid module globs once per override pattern (<a
href="https://redirect.github.com/astral-sh/ruff/issues/30031">#30031</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/367a5639d2bbd4a641e5fb4a1aaa6a41beab9711"><code>367a563</code></a>
[ty] Fix conditional type and tuple annotations (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29987">#29987</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/astral-sh/ruff/compare/0.17.3...0.17.4">compare
view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=ruff&package-manager=pip&previous-version=0.17.3&new-version=0.17.4)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions


</details>
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4804"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

## Real Behavior Proof

- Setup: pushed commit aligning `.pre-commit-config.yaml` ruff pin to
`v0.17.4` to match the `uv.lock` bump.
- Observed: repo ruff-pin consistency check passes; `uv run ruff check
.` clean on PR head (0 errors, no new lint findings needing source
edits).
- Not tested: pre-commit.ci hook run (covered by CI).

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-14 13:31:22 -06:00
devin-ai-integration[bot]andjd 0368a872cd fix(deps): patch quinn-udp, rustix and opentelemetry-api advisories (#4835)
## Description

The security audit jobs in `security.yml` block merges and run on every
PR whatever paths changed, so newly published advisories turned main and
every open PR red ([failing run on
c21b081](https://github.com/headroomlabs-ai/headroom/actions/runs/43454755457/job/131985838851)).

**Rust (`cargo audit`)**
- **RUSTSEC-2026-0538** (vulnerability, the original blocker):
`quinn-udp` 0.5.14 can spin in its receive loop after a truncated
datagram. Fixed in `>=0.5.16, <0.6.0`.
- **RUSTSEC-2026-0486** (unsound warning, not blocking): in `rustix`
1.1.4 the xattr functions mishandle a zero-length buffer. Fixed in
1.1.6. Bumped so the audit output is clean.

**Python (`pip-audit`)**: this advisory was published after main's last
run, so main would have gone red on it next.
- **CVE-2026-126360**: `opentelemetry-api` 1.45.1 has a ReDoS in
`TraceContextTextMapPropagator.extract()` when given a crafted
`traceparent`. Fixed in 1.45.2. I raised the floor in `pyproject.toml`,
keeping the CVE-comment style of the existing pin, and ran `uv lock
--upgrade-package opentelemetry-api`. That also moves
`opentelemetry-sdk` to 1.45.2 and the `0.66b1` instrumentation/semconv
packages to `0.66b2`.

Nothing was added to `.cargo/audit.toml` or any other ignore list.

Side effect: `rustix` 1.1.6 accepts `windows-sys >=0.52, <0.62`, so
Cargo unified it, and the Windows-only deps of `errno`, `tempfile` and
one other crate, onto the `windows-sys 0.52.0` already in the lock. All
of their version ranges allow 0.52.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `Cargo.lock`: `quinn-udp` 0.5.14 → 0.5.16, `rustix` 1.1.4 → 1.1.6
- `pyproject.toml`: `opentelemetry-api>=1.45.2`
- `uv.lock`: opentelemetry-api/sdk 1.45.1 → 1.45.2, instrumentation,
instrumentation-threading and semantic-conventions 0.66b1 → 0.66b2

## Testing

- [x] Unit tests pass (`pytest`): the opentelemetry-related test files,
50 passed
- [x] Manual testing performed

### Test Output

```text
$ cargo audit   # before (main)
error: 1 vulnerability found!   RUSTSEC-2026-0538 quinn-udp 0.5.14
$ cargo audit   # after
(no findings, exit 0)

$ uv export --frozen --no-dev --no-emit-project --no-hashes --extra all --format requirements-txt > req.txt
$ uvx pip-audit==2.10.1 -r req.txt --no-deps --disable-pip   # before
opentelemetry-api 1.45.1  CVE-2026-126360 1.45.2
$ ... # after
No known vulnerabilities found

$ make ci-precheck   # pre-push hook
cargo fmt / clippy -D warnings / cargo test --workspace: ok
Python parity subset: 180 passed, 5 skipped
✅ ci-precheck PASSED
```

## Real Behavior Proof

- Environment: Ubuntu VM, Python 3.12 uv venv, stable Rust, advisory DBs
as of 2026-11-13
- Exact command / steps: commands as above (they are the same ones the
CI audit jobs run), plus `cargo check --workspace --locked`
- Observed result: both audits are clean; workspace builds and tests
pass
- Not tested: Windows/macOS locally (only `x86_64-unknown-linux-gnu` is
available here). CI's Windows and macOS jobs cover the `windows-sys`
unification.

## Runtime Rollout Safety

- Rollout-managed feature(s): N/A (dependency patch bumps)
- Stable/default behavior changed: No
- Rollback path: revert this PR

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

There is no failing-before test because these are lockfile and
version-floor bumps. The failing audit gates themselves show the problem
and the fix.

Link to Devin session:
https://app.devin.ai/sessions/4f3fe33a42094da5a5ed332a9c076230
Open in Devin Desktop:
https://app.devin.ai/desktop/session/4f3fe33a42094da5a5ed332a9c076230?variant=devin
Requested by: @JerrettDavis
<!-- devin-review-badge-begin -->

---

🟢 Devin Review found nothing to fix · [View
findings](https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4835)

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4835"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a><!-- devin-review-badge-end -->

---------

Co-authored-by: jd <jd@headroomlabs.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-11-13 15:41:29 -06:00
headroom-release[bot]andgithub-actions[bot] b21479e0fa chore: release 0.44.0 (#4665)
🤖 I have created a release *beep* *boop*
---


##
[0.44.0](https://github.com/headroomlabs-ai/headroom/compare/v0.43.1...v0.44.0)
(2026-11-09)


### ⚠ BREAKING CHANGES

* **packaging:** keep PyTorch extras out of all
([#4067](https://github.com/headroomlabs-ai/headroom/issues/4067))

### Features

* **pipeline:** say whose request an OutcomeSnapshot is
([#4698](https://github.com/headroomlabs-ai/headroom/issues/4698))
([a2bcbd1](https://github.com/headroomlabs-ai/headroom/commit/a2bcbd101b1391debfd218ec8c63cb72d2bc240a))
* **providers:** add Hermes agent wrap support
([#934](https://github.com/headroomlabs-ai/headroom/issues/934))
([7877241](https://github.com/headroomlabs-ai/headroom/commit/7877241d84c93b3ec487e07324245838ddae85cc))
* **proxy/model-router:** add shadow mode
(HEADROOM_MODEL_ROUTER_LOG_ONLY)
([#2395](https://github.com/headroomlabs-ai/headroom/issues/2395))
([861ef95](https://github.com/headroomlabs-ai/headroom/commit/861ef95620c801c2560a2eacc5773a26e131dfd0))
* **proxy:** add lossless /v1/compress mode and detect provider by wire
shape ([#4617](https://github.com/headroomlabs-ai/headroom/issues/4617))
([33f067a](https://github.com/headroomlabs-ai/headroom/commit/33f067a243b2e648730c01ae6b9f20cba879f351))
* **proxy:** expose per-request cost_usd in /stats recent_requests
([#1079](https://github.com/headroomlabs-ai/headroom/issues/1079))
([#1565](https://github.com/headroomlabs-ai/headroom/issues/1565))
([84cedbf](https://github.com/headroomlabs-ai/headroom/commit/84cedbf2b4197f09ace9944c50655786dac35b03))
* **proxy:** expose shared Redis store availability in /health and
/metrics
([#4578](https://github.com/headroomlabs-ai/headroom/issues/4578))
([602ca65](https://github.com/headroomlabs-ai/headroom/commit/602ca65126e12d73ef44d4b1b01bbe1fa3b37080))
* **proxy:** give turn hooks one conversation id per client conversation
([#4496](https://github.com/headroomlabs-ai/headroom/issues/4496))
([94a99ed](https://github.com/headroomlabs-ai/headroom/commit/94a99ed20f6fe110e03d2613e9feec42d9547150))
* **proxy:** report DeepSeek as its own provider in dashboard
([#2565](https://github.com/headroomlabs-ai/headroom/issues/2565))
([9ad16a7](https://github.com/headroomlabs-ai/headroom/commit/9ad16a77f8b9a7817331aa5e9a9ee04d1e1fc05e))
* **proxy:** show per-request /stats metadata to token-authenticated
callers
([#4168](https://github.com/headroomlabs-ai/headroom/issues/4168))
([9b2dec5](https://github.com/headroomlabs-ai/headroom/commit/9b2dec56f9882a25fb511dc5f480b047845141f9))
* **proxy:** unified multi-upstream routing for Anthropic Cloud and
local oMLX
([#4597](https://github.com/headroomlabs-ai/headroom/issues/4597))
([f896161](https://github.com/headroomlabs-ai/headroom/commit/f896161340893dd8e96502d4c309980bed52d3d1))
* **savings:** carry cumulative actual output_tokens in history
checkpoints
([#2921](https://github.com/headroomlabs-ai/headroom/issues/2921))
([8388ff5](https://github.com/headroomlabs-ai/headroom/commit/8388ff5efd7caf3a827e66bf69449c4a64df05af))
* **wrap:** add `headroom wrap droid` for Factory Droid
([#4143](https://github.com/headroomlabs-ai/headroom/issues/4143))
([bb8d18a](https://github.com/headroomlabs-ai/headroom/commit/bb8d18a56abb07ca7e811235c86ea6b626eb1f8b))
* **wrap:** make the Serena code-memory MCP opt-in
([#4509](https://github.com/headroomlabs-ai/headroom/issues/4509))
([2649835](https://github.com/headroomlabs-ai/headroom/commit/2649835a51e6d459ac47e8dcb8591e5bf027715b))


### Bug Fixes

* **asgi:** stop buffering when the client disconnects
(GHSA-mc2f-vg4v-2fh4)
([#4701](https://github.com/headroomlabs-ai/headroom/issues/4701))
([c6d7081](https://github.com/headroomlabs-ai/headroom/commit/c6d708144ce27abeb08c4c57374b373eebe1951e))
* **beacon:** enforce the allowlist below the top-level keys
([#4691](https://github.com/headroomlabs-ai/headroom/issues/4691))
([456288d](https://github.com/headroomlabs-ai/headroom/commit/456288da0765985ca31eed58dbdaef44ff9aa43a))
* **binaries:** fail closed on
HEADROOM_BINARIES_ALLOW_UNVERIFIED=0/false
([#3218](https://github.com/headroomlabs-ai/headroom/issues/3218))
([da6d973](https://github.com/headroomlabs-ai/headroom/commit/da6d9736cd82074988c7d0a2360b49d9d8b6c0a0))
* **cache:** record TTL observations with relative filenames
([#4711](https://github.com/headroomlabs-ai/headroom/issues/4711))
([51d9dc5](https://github.com/headroomlabs-ai/headroom/commit/51d9dc59b3dc6b8c386cc2293e78d1334aac0893))
* **cache:** round learned TTL upper bounds up to whole seconds
([#4710](https://github.com/headroomlabs-ai/headroom/issues/4710))
([13347e3](https://github.com/headroomlabs-ai/headroom/commit/13347e339c4cc88dfa0cfa1deceeb0dae56ee2fc))
* **cache:** save prefix-tracker state when the exit signal arrives
([#4715](https://github.com/headroomlabs-ai/headroom/issues/4715))
([3ba4223](https://github.com/headroomlabs-ai/headroom/commit/3ba422361e3bce92afd6bb30e3cd817ec3b9cb46))
* **ccr:** lowercase the hash in the streaming feedback recorders
([#2313](https://github.com/headroomlabs-ai/headroom/issues/2313))
([3912c04](https://github.com/headroomlabs-ai/headroom/commit/3912c0405321c498f854fd0c152ae01abf63bf48))
* **ci:** keep the npm publish token out of install and build steps
([#4690](https://github.com/headroomlabs-ai/headroom/issues/4690))
([8f6366c](https://github.com/headroomlabs-ai/headroom/commit/8f6366cf66d035fc8e9f390be424bc9bdf6c62e4))
* **cli:** resolve active proxy port for read commands
([#3522](https://github.com/headroomlabs-ai/headroom/issues/3522))
([02c4e92](https://github.com/headroomlabs-ai/headroom/commit/02c4e922f748cfac5db59303918bb13906031650))
* **content-router:** trust confident HTML detection over mixed-content
heuristics
([#3627](https://github.com/headroomlabs-ai/headroom/issues/3627))
([f50db67](https://github.com/headroomlabs-ai/headroom/commit/f50db67006e2fe3f43b295542b759d90bb73e5a1))
* **dashboard:** lifetime metrics and refresh
([#2374](https://github.com/headroomlabs-ai/headroom/issues/2374))
([eb9932a](https://github.com/headroomlabs-ai/headroom/commit/eb9932a671c92b19c58949a63ec833869fc1a8e7))
* **doctor:** recognize IPv6 loopback and case-insensitive proxy routing
URLs ([#3255](https://github.com/headroomlabs-ai/headroom/issues/3255))
([2b0315b](https://github.com/headroomlabs-ai/headroom/commit/2b0315b2d4b0d54947050bbdad2de9e89df06378))
* **install:** decode Windows Task Scheduler XML output before parsing
([#3969](https://github.com/headroomlabs-ai/headroom/issues/3969))
([#4064](https://github.com/headroomlabs-ai/headroom/issues/4064))
([b78e07d](https://github.com/headroomlabs-ai/headroom/commit/b78e07da7fadeaafdbba16312140d44f812bc181))
* **install:** make install status agree with doctor when the proxy is
reachable
([#3072](https://github.com/headroomlabs-ai/headroom/issues/3072))
([#3141](https://github.com/headroomlabs-ai/headroom/issues/3141))
([05431b2](https://github.com/headroomlabs-ai/headroom/commit/05431b264f4fc105a302cceed60b5327abc35e10))
* **langchain:** check optional integration availability
([#4042](https://github.com/headroomlabs-ai/headroom/issues/4042))
([cde584d](https://github.com/headroomlabs-ai/headroom/commit/cde584d7fe6930b8ecf612b705e984b2c6a41527))
* **learn:** harden analyzer JSON parsing against malformed LLM output
([#2471](https://github.com/headroomlabs-ai/headroom/issues/2471))
([12864fc](https://github.com/headroomlabs-ai/headroom/commit/12864fc8f01a1ca6c58440eccef0dabdd3e595b8))
* **learn:** support opencode v2 session schema in learn scanner
([#4199](https://github.com/headroomlabs-ai/headroom/issues/4199))
([c05466a](https://github.com/headroomlabs-ai/headroom/commit/c05466a469c848c69a62a5c283c09dcd35d8e9c8))
* **lossless:** fold only pure path listings, never markup
([#4716](https://github.com/headroomlabs-ai/headroom/issues/4716))
([0ccd559](https://github.com/headroomlabs-ai/headroom/commit/0ccd559db052ea2ec8baef122ac769a146a75518))
* **memory:** gracefully degrade on context lookup and initialization
errors
([#3251](https://github.com/headroomlabs-ai/headroom/issues/3251))
([#4049](https://github.com/headroomlabs-ai/headroom/issues/4049))
([00d4f44](https://github.com/headroomlabs-ai/headroom/commit/00d4f441d3f1d48c463fea57e6c574c2f3671302))
* **metrics:** cap savings_by_source rows and fold the rest into other
([#4257](https://github.com/headroomlabs-ai/headroom/issues/4257))
([2038fb2](https://github.com/headroomlabs-ai/headroom/commit/2038fb2a3667d9cba3ff9cb1c4957add06ef5acb))
* **packaging:** keep PyTorch extras out of all
([#4067](https://github.com/headroomlabs-ai/headroom/issues/4067))
([a890521](https://github.com/headroomlabs-ai/headroom/commit/a8905214d949cdc42b1d76fbc83146f51e0c4f19))
* **proxy:** add --no-ccr-response-handling flag to bypass response
buffering
([#3082](https://github.com/headroomlabs-ai/headroom/issues/3082))
([#3100](https://github.com/headroomlabs-ai/headroom/issues/3100))
([ce14271](https://github.com/headroomlabs-ai/headroom/commit/ce14271ba8ca66b653fbbb555d50ca20e7a36d3f))
* **proxy:** bound the Bedrock Prometheus model label
([#4694](https://github.com/headroomlabs-ai/headroom/issues/4694))
([d70a8b7](https://github.com/headroomlabs-ai/headroom/commit/d70a8b76a5bc12b4eae6655e40e60abe19b145d0))
* **proxy:** drop headers named by Connection when forwarding responses
([#4674](https://github.com/headroomlabs-ai/headroom/issues/4674))
([3871b36](https://github.com/headroomlabs-ai/headroom/commit/3871b3664a03c9dc489be13f245462f2a9fc0b67))
* **proxy:** keep cold-turn reasoning drops sticky so the next warm turn
reuses the cached prefix
([#4592](https://github.com/headroomlabs-ai/headroom/issues/4592))
([3544cf5](https://github.com/headroomlabs-ai/headroom/commit/3544cf5b88a0d0e704f3d3c5eb8a89f7c52d8c13))
* **proxy:** keep the Bedrock credentials provider when startup
resolution fails
([#4705](https://github.com/headroomlabs-ai/headroom/issues/4705))
([5438f00](https://github.com/headroomlabs-ai/headroom/commit/5438f0035d2fd0261b50aac0520b30021dc56fe0))
* **proxy:** refresh Bedrock AWS credentials before they expire
([#4696](https://github.com/headroomlabs-ai/headroom/issues/4696))
([adc6724](https://github.com/headroomlabs-ai/headroom/commit/adc67249660b4464e8489e21287d9b95d044b095))
* **proxy:** rename leaked_threads metric to timed_out_workers_total
([#3908](https://github.com/headroomlabs-ai/headroom/issues/3908))
([bd164a2](https://github.com/headroomlabs-ai/headroom/commit/bd164a2c3ba3a2eeb470a0b9503a696dd02b0e9c))
* **proxy:** track response.-prefixed item and content-part events in
Responses SSE state
([#4695](https://github.com/headroomlabs-ai/headroom/issues/4695))
([8f4122f](https://github.com/headroomlabs-ai/headroom/commit/8f4122f4e5ae351703c775e042d2ad705cebc143))
* **router:** compress tool_result blocks in mutable window with
trailing messages
([#4717](https://github.com/headroomlabs-ai/headroom/issues/4717))
([0511bcd](https://github.com/headroomlabs-ai/headroom/commit/0511bcd33186f57d76e508bbec388bb4256cfc68))
* **router:** ignore shell operators inside quoted arguments in read
detection
([#4646](https://github.com/headroomlabs-ai/headroom/issues/4646))
([8cdce17](https://github.com/headroomlabs-ai/headroom/commit/8cdce172ea5b70f9ed5300f089c11f4ca23b8c66))
* **scripts:** skip ci-precheck in the pre-push hook when a push only
deletes refs
([#4702](https://github.com/headroomlabs-ai/headroom/issues/4702))
([cbcf8d8](https://github.com/headroomlabs-ai/headroom/commit/cbcf8d8d9b3c43a93276b46db569fab185ed949d))
* **sdk:** keep Vercel AI SDK tool-result output kinds through
compression
([#4670](https://github.com/headroomlabs-ai/headroom/issues/4670))
([ce42754](https://github.com/headroomlabs-ai/headroom/commit/ce4275491299231bc9d2907833f72f72ea22b8a9))
* **search_compressor:** keep kept rows byte-for-byte and in input order
([#3982](https://github.com/headroomlabs-ai/headroom/issues/3982))
([a538740](https://github.com/headroomlabs-ai/headroom/commit/a538740ee40a80642bb1092d179171828260696c))
* **smart-crusher:** keep mixed-array dict rows and exact drop count
with factor_out_constants
([#4692](https://github.com/headroomlabs-ai/headroom/issues/4692))
([ced2685](https://github.com/headroomlabs-ai/headroom/commit/ced26852c6d103991e05c5eec1f13103e5ce2755))
* **smart-crusher:** keep the row the question names
([#4713](https://github.com/headroomlabs-ai/headroom/issues/4713))
([e6e2ebb](https://github.com/headroomlabs-ai/headroom/commit/e6e2ebb6782119e46400a66cef33bb8eb9295484))
* **storage:** return the latest snapshot from JSONLStorage.get
([#4675](https://github.com/headroomlabs-ai/headroom/issues/4675))
([b25c45b](https://github.com/headroomlabs-ai/headroom/commit/b25c45b08f1cc5ed8fe49671e356711b89800ac1))
* **tabular:** split fixed-width rows on column boundaries, not on
double spaces
([#4541](https://github.com/headroomlabs-ai/headroom/issues/4541))
([b80245e](https://github.com/headroomlabs-ai/headroom/commit/b80245ea73e452f2c14de7a5cd8520f7e7d92c61))
* **tag-protector:** do not treat a slash in an unquoted attribute as
self-closing
([#4681](https://github.com/headroomlabs-ai/headroom/issues/4681))
([d5644cb](https://github.com/headroomlabs-ai/headroom/commit/d5644cbacab79607fe8864d007810aa06c5c68ea))
* **tag-protector:** keep the enclosing tag open after a nested close in
marker mode
([#4682](https://github.com/headroomlabs-ai/headroom/issues/4682))
([385d487](https://github.com/headroomlabs-ai/headroom/commit/385d487f41abd029fb4e2f8346c0cc30dc546bc4))
* **telemetry:** keep install ID stateless
([#3542](https://github.com/headroomlabs-ai/headroom/issues/3542))
([27bba79](https://github.com/headroomlabs-ai/headroom/commit/27bba79ff2d1800e390ed20820adff971e99ce08))
* **tokenizers:** resolve chatgpt-4o-* aliases to o200k_base
([#4672](https://github.com/headroomlabs-ai/headroom/issues/4672))
([9648d2d](https://github.com/headroomlabs-ai/headroom/commit/9648d2d867c99eb7e91f81754c5e2877be56feac))
* **tokenizers:** unwrap BatchEncoding in
HuggingFaceTokenizer.count_messages
([#2447](https://github.com/headroomlabs-ai/headroom/issues/2447))
([9eed58f](https://github.com/headroomlabs-ai/headroom/commit/9eed58f84cacc30116c6b6b29cb99eade57e0edf))
* **vertex:** explain Vertex failures in-band, correct the model/region
matrix
([#2640](https://github.com/headroomlabs-ai/headroom/issues/2640))
([0ddaa56](https://github.com/headroomlabs-ai/headroom/commit/0ddaa56c21cdc01c4774391fdcc69e987ecc4e5c))
* **wrap:** route Claude Code's Bedrock mode through Headroom
([#4316](https://github.com/headroomlabs-ai/headroom/issues/4316))
([aa2093b](https://github.com/headroomlabs-ai/headroom/commit/aa2093b4a08ca1f1bb9c8fb92fe0fc85d9ffe936))


### Dependencies

* bump rusqlite from 0.40.2 to 0.41.1
([#4658](https://github.com/headroomlabs-ai/headroom/issues/4658))
([74b7ac2](https://github.com/headroomlabs-ai/headroom/commit/74b7ac23861944f1411d30c5394043ec0505b334))
* bump the cargo-minor-patch group with 3 updates
([#4657](https://github.com/headroomlabs-ai/headroom/issues/4657))
([c01cf07](https://github.com/headroomlabs-ai/headroom/commit/c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4))
* bump the npm-minor-patch group across 1 directory with 2 updates
([#4650](https://github.com/headroomlabs-ai/headroom/issues/4650))
([def4ef1](https://github.com/headroomlabs-ai/headroom/commit/def4ef10099514d09188326852138a8b20c26237))
* update click requirement from &gt;=8.3.3 to &gt;=8.5.0
([#4655](https://github.com/headroomlabs-ai/headroom/issues/4655))
([ea59ac3](https://github.com/headroomlabs-ai/headroom/commit/ea59ac3eef3a3dc02076e9fe4bb30d572ca9c1a9))
* update sqlite-vec requirement from &gt;=0.1.6 to &gt;=0.1.9
([#4654](https://github.com/headroomlabs-ai/headroom/issues/4654))
([de1a1e0](https://github.com/headroomlabs-ai/headroom/commit/de1a1e0f478d1eb9257dd8dd0d4ac87c9e6fc639))
* update tree-sitter requirement from &lt;0.27,&gt;=0.25.2 to
&gt;=0.26.0,&lt;0.27
([#4656](https://github.com/headroomlabs-ai/headroom/issues/4656))
([910588e](https://github.com/headroomlabs-ai/headroom/commit/910588e6b15ab54c4099d03703e5fa20c8abb757))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: headroom-release[bot] <352661243+headroom-release[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-11-09 19:58:06 -06:00
alan blountandJD Davis 0ddaa56c21 fix(vertex): explain Vertex failures in-band, correct the model/region matrix (#2640)
## Description

Vertex rejects onboarding requests for a handful of recurring reasons —
expired ADC, a partner model never enabled in Model Garden, a model not
served in the requested location, a missing optional SDK — and its own
error text names none of the fixes. Users see a bare `404` or an opaque
`500` through their SDK and cannot tell a proxy bug from a
project-config gap.

This makes the proxy explain those failures where it happens, adds a
`[vertex]` extra so the LiteLLM Vertex backend can actually start, and
corrects an example, a test matrix, and three documentation claims that
could not have worked as written.

Closes #2632

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

**Explain Vertex failures in-band**
(`headroom/providers/vertex/diagnostics.py`, new)

- On `401/403/404/429`, attach an actionable hint three ways: a WARNING
in the proxy log, an `x-headroom-hint` response header, and a note
appended to `error.message`. The last is load-bearing — SDKs raise with
the message string and discard headers.
- Successful responses are never modified; annotation is idempotent;
statuses we cannot explain get no hint rather than a plausible-sounding
wrong one.
- Routes opt in via a one-line `@with_vertex_diagnostics` decorator
reading path params FastAPI already injects (**+8 lines** in
`proxy_routes.py`, no re-indentation).
- Same treatment for backend setup failures, where `--backend vertex`
surfaced LiteLLM's raw `No module named 'vertexai'` as an opaque 500.

**Make `--backend vertex` able to start** (`pyproject.toml`,
`registry.py`, `cli/proxy.py`)

- New `[vertex]` extra carrying `google-cloud-aiplatform>=1.38`.
Deliberately **not** folded into `[proxy]`: measured at ~175 MB
installed, and the native passthrough routes never needed it. Follows
the existing `proxy-prod` split.
- Startup preflight keyed on the **resolved provider**, so every alias
normalized at `registry.py:229` (`vertex`, `vertex_ai`,
`litellm-vertex`, `google-vertex`, `googlevertex`) is covered. Skipped
when a backend class is injected, so existing fake-based tests are
unaffected.
- New `BackendUnavailableError` so the CLI prints the remedy and exits
`2` instead of dumping a traceback through startup internals.

**Correct things that could not have worked**

| | was | is |
|---|---|---|
| SDK client | `http_options={"api_endpoint": ...}` | `{"base_url":
"http://..."}` — `api_endpoint` is not a field on `HttpOptions`;
pydantic rejects it before any request is sent |
| Thinking config | `ThinkingConfig(thinking_budget_tokens=)` |
`thinking_budget=` |
| Request payload | `contents: [{parts: [...]}]` | adds `role: "user"` —
the `global` endpoint enforces it, regional was silently lenient |
| Auth guidance | `gcloud auth print-access-token` |
`application-default` — the plain user token gets `401
ACCESS_TOKEN_TYPE_UNSUPPORTED` |
| Test matrix | model × location cross-product | explicit servable pairs
|

- Test matrix is now four pairs that can actually serve:
`global`/`gemini-flash-latest`, `global`/`claude-sonnet-4-6`,
`europe-west2`/`gemini-3.5-flash`, `us-east5`/`claude-sonnet-4-6`.
Gemini 3.x has no US regional endpoint and `-latest` aliases are
global-only, so a pinned `us-central1` Gemini case can never pass. No
Gemini 2.5 — it retires 2026-10-16.
- `test_thinking_levels` asserted only `status_code < 500` while sending
an ignored `thinkingBudgetTokens` key: it passed on 400s and proved
nothing. Now asserts 200 plus scored usage metadata with the correct
`thinkingBudget` spelling.
- Cases the caller's project genuinely cannot serve now **skip** with an
actionable reason instead of reporting a red proxy.

**Docs** (`proxy.mdx`, `installation.mdx`, `wiki/vertex.md`)

- `proxy.mdx` claimed `publisher=anthropic` passthrough "routes through
the same LiteLLM-Vertex path as `--backend vertex_ai`". It does not —
without the flag it is a direct forward, which is why it works on a bare
`[proxy]` install where the LiteLLM path cannot even import.
- Documented the trap of combining `--backend vertex` with native Vertex
URLs: LiteLLM takes project/region/model from its own config and ignores
the URL.
- `installation.mdx` and `wiki/vertex.md` said the SDK is "not included
in any extra".
- Cleared 15 pre-existing `ruff` findings in the two files this PR
rewrites (4 remain in `plugins/headroom-oauth2`, untouched by this
work).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ mypy headroom
Success: no issues found in 511 source files

$ ruff check .
Found 4 errors.        # all in plugins/headroom-oauth2, pre-existing, untouched by this PR

$ pytest tests/test_proxy_vertex_native_integration.py tests/test_vertex_diagnostics.py -q
44 passed, 1 warning in 69.86s          # 8 live integration + 36 offline diagnostics, 0 skipped

$ pytest tests/ -k "anthropic_messages or handler_anthropic or backend or registry or cli_proxy or vertex or proxy_routes"
853 passed, 49 skipped, 9345 deselected, 2 warnings in 28.41s
```

New tests in `tests/test_vertex_diagnostics.py` (36, no credentials
required): status coverage, per-publisher remedy divergence,
idempotency, `content-length` consistency after body rewrite, non-JSON
and body-less/streaming responses, every backend alias preflighted,
other providers unaffected, injected backend bypasses the preflight.

## Real Behavior Proof

- Environment: macOS 14, Python 3.11.15, live GCP project
(`alanblount-sandbox`) with `aiplatform.googleapis.com` enabled and
Claude enabled in Model Garden; ADC via `gcloud auth application-default
login`
- Exact command / steps: `export GCP_PROJECT_ID=alanblount-sandbox &&
export GCP_ACCESS_TOKEN=$(gcloud auth application-default
print-access-token) && uv run --extra proxy --with google-genai python3
examples/vertex_genai_sdk_demo.py && uv run --extra proxy --with
pytest-asyncio pytest tests/test_proxy_vertex_native_integration.py
tests/test_vertex_diagnostics.py -q && headroom proxy --backend vertex`
(exits 2, then retried with `[proxy,vertex]` extra installed)
- Observed result: demo printed `✓ Standard response received
successfully! > 1, 2, 3, 4, 5` and `✓ Thinking response received
successfully!`; 44 tests passed (8 live integration, 36 diagnostics), 0
skipped; `--backend vertex` exited 2 with the remedy message; same
request with the extra installed returned 200; invalid region produced
`[headroom] hint:` in the response body and `x-headroom-hint` header;
success responses were byte-clean
- Not tested: Windows; `us`/`eu` multi-region endpoints and Claude 4.7+
(project cannot serve them); Provisioned Throughput; Rust proxy path;
`--backend vertex` dropping URL project/model on native Vertex routes
(documented as known gap in Additional Notes)


## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A — proxy and CLI behavior; terminal output is quoted above.

## Additional Notes

- `uv.lock` intentionally not included: the new extra is opt-in and does
not change default resolution.
- Error-body rewriting is confined to already-failing responses and
wrapped so a diagnostic can never turn a clean upstream error into a
proxy 500.
- The preflight raises where the provider is resolved (`registry.py`)
rather than at the CLI, so programmatic embedders get the same
guarantee; the CLI only formats it.
- Three test files fail to collect on this branch
(`test_hermes_passthrough_compression`, `test_observability_metrics`,
`test_observability_tracing`). They predate this work and are unrelated,
so they were excluded rather than fixed — happy to open a separate
issue.
- `[vertex]` was chosen over adding the dependency to `[proxy]` after
measuring the footprint at ~175 MB. If maintainers prefer it in
`[proxy]`, that is a one-line change.
## Runtime Rollout Safety

- Rollout-managed feature(s): none; diagnostics annotate already-failing
Vertex responses and the backend dependency is opt-in through the vertex
extra.
- Minimum rollout channel: normal stable release after Vertex
diagnostics, route, and backend-path tests pass.
- Stable/default behavior changed: successful responses and native
passthrough remain unchanged; supported Vertex failures gain an
actionable header/message, and selecting the LiteLLM Vertex backend
without its SDK now fails once at startup.
- Kill switch / disable path: use native Vertex passthrough without the
LiteLLM backend, or human-revert the diagnostic/preflight change.
- Unsafe override required: none.
- Qualification impact: offline diagnostics, native integration, and
mocked LiteLLM Vertex request-shaping tests must remain green.
- Rollback path: human-revert the PR; no persisted state or migration is
involved.
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/2640"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

### Maintainer current-main requalification

Exact head `5d7071f348d2462f666fd7ac1ceb8ac18050169a`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.

Re-reviewed latest integration head c70c1a497 and current author
responses, including fixed public error hints, log escaping, body/header
consistency, all four backend error sites, and native-route versus
LiteLLM SDK dependency behavior. Clean integration with upstream/main
2d3ee51846. No new PR-specific source
blocker found in reviewed scope; no contributor diagnostic/routing logic
rewritten.

232 Vertex diagnostics/native-route/backend/CLI/release/version/MCP
tests pass with11 skips. Offline lock validation passes (268 packages);
all12 changed Python files pass Ruff check/format, and whitespace
passes. These checks cover synthetic error/transport paths and do not
establish live cloud regional availability or billing behavior. Earlier
author live evidence remains scoped to its stated environment; no fresh
cloud request or native build claimed here. Historical shared
cached-read fixture failure was main-reproduced and is not a
contributor-code blocker. Maintainers handle current exact-head hosted
qualification before approval; nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `486a716adbf642ae5e43276df4c2dc1e63b901d7`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Clean mechanical sync with upstream main
c01cf07d94. Re-reviewed current
author/Devin discussion and public diagnostic/error boundaries,
native-versus-SDK route separation and startup preflight. This sync does
not alter the PR Vertex diagnostics, backend or route-registry
modules.158 focused diagnostics/native-route/backend/streaming/CLI tests
pass,11live-environment skips,1deprecation warning. Offline uv lock
--check passes;all12 changed Python files pass Ruff lint/format and
main-relative whitespace passes. Fixed hints remain separate from raw
provider error text; multi-worker preflight and non-Google partner
guidance retain resolved regressions. No contributor diagnostic/routing
correctness logic rewritten. Tests use existing current-main DLL and
synthetic errors/transports; no fresh native build, live regional
availability/provider inference or billing qualification claimed. Formal
approval awaits exact-head hosted qualification; maintainers handle CI.
Nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `0b75c609f24562c8b6ed2aaeaf58239984b4810c`, upstream main
`ce4275491299231bc9d2907833f72f72ea22b8a9`.

Requalified after human merges #4667,#4669,#4670 against upstream main
ce42754912. Earlier approval and
publication guards stopped stale candidates before either was posted.
Current clean merge retains Vertex diagnostics/native-versus-SDK routing
and main enable_kompress checks, lossless cold-prefix disable, and
Python token-window boundary behavior.190 combined
Vertex/backend/CLI/Kompress-disable/must-keep tests
pass,11live-environment skips,1warning. Offline lock validation,12-file
Ruff lint/format and main-relative whitespace pass. No contributor
diagnostic/routing logic rewritten. Native Rust/Cargo sources are
identical to c01 across these merges; existing matching-core DLL
supports tests, not a fresh native build. No new live Vertex
regional/provider/billing qualification claimed. All prior-main hosted
results are superseded for readiness; approval awaits exact checks on
this published merge head. Maintainers handle CI; no agent merge.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `1fe62702ce614315679d68d9d126e31c57208c67`, upstream main
`00d4f441d3f1d48c463fea57e6c574c2f3671302`.

Requalified after human merges #4667,#4669,#4670 against upstream main
ce42754912. Earlier approval and
publication guards stopped stale candidates before either was posted.
Current clean merge retains Vertex diagnostics/native-versus-SDK routing
and main enable_kompress checks, lossless cold-prefix disable, and
Python token-window boundary behavior.190 combined
Vertex/backend/CLI/Kompress-disable/must-keep tests
pass,11live-environment skips,1warning. Offline lock validation,12-file
Ruff lint/format and main-relative whitespace pass. No contributor
diagnostic/routing logic rewritten. Native Rust/Cargo sources are
identical to c01 across these merges; existing matching-core DLL
supports tests, not a fresh native build. No new live Vertex
regional/provider/billing qualification claimed. All prior-main hosted
results are superseded for readiness; approval awaits exact checks on
this published merge head. Maintainers handle CI; no agent merge.

Final current-main requalification:
07d5add5ba, including human merges #4671
action pinning and #4648 multimodal memory preservation. Clean
mechanical merge; Vertex/backend/CLI inputs retain the preceding
190-test qualification. Fresh workflow/release suite: 62 passed. Fresh
memory wrapper suite: 9 passed. New wrapper retains list payload parts
and extracts textual search inputs; no contributor Vertex logic
rewritten. Existing native input provenance remains unchanged. Hosted
qualification must run on this final head before approval.

Newer human merge #4646 advanced authoritative main to
8cdce172ea before publication. Cleanly
integrated quote-aware read detection; reviewed new masking/segmentation
overlap. Fresh read-command/content-router suite: 188 passed, 1 optional
SOCKS warning. Vertex code remains unchanged by this merge.

Final additional human merge #4067 packaging changes advanced main to
a8905214d: cleanly integrated explicit torch-extras split, retaining
Vertex optional dependencies. Fresh ONNX/optional-dependency contracts:
12 passed. Offline lock check and whitespace pass. No live clean-install
or Torch backend claim. Earlier publication candidates were stopped
before push by fresh-main guard.

Latest human merge #4042 advances authoritative main to
cde584d7fe. Clean merge preserves optional
LangChain availability handling and CI dependency setup. Fresh
binding/compatibility/startup-log/xAI regression suite: 29 passed. New
main integration re-reviewed; no contributor Vertex behavior rewritten.

Subsequent #4049 main merge 00d4f441d adds graceful context lookup/init
failure handling. Cleanly integrated with Vertex handler diagnostics
intact. Fresh Anthropic pre-upstream/memory native ops/OpenAI Codex
routing/WebSocket lifecycle suite: 192 passed, 1 deprecation warning.
Reviewed exception handling and transport overlap; no live provider
qualification claim.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `6c63811d6de7491ebce9a16f89e197f5f5dd86dd`, upstream main
`2b0315b2d4b0d54947050bbdad2de9e89df06378`.

Requalified against authoritative
main2b0315b2d4b0d54947050bbdad2de9e89df06378 after further human merges.
All10 integration patches exactly match00d4f441-to-current-main changes
after diff-location normalization; contributor Vertex
diagnostics/routing policy unchanged.539combined
Vertex/backend/CLI/Kompress-disable/must-keep/binary/doctor/Windows-supervisor/provider/search/text
tests pass;13platform/live-environment skips,2warnings. Nine changed
Python files pass Ruff lint/format; offline lock and whitespace pass.
Existing pr3982 native DLL verified against every tracked native
build-input hash and artifact checksum; no fresh native build claimed.
Current author/Devin discussion checked; prior fixes remain intact. No
live Vertex regional/provider/billing,IPv6 listener or unsupported cloud
qualification claimed. No new finding in reviewed scope. Exact-head
hosted checks must qualify this published head before formal approval;
maintainers handle them. Nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-06 12:27:47 -06:00
lorenzozaneandJerrettDavis a8905214d9 fix(packaging)!: keep PyTorch extras out of all (#4067)
<!-- maintainer-current-main -->
## Maintainer latest-main checkpoint
Published `fb146c0663b30488da0a49cfb33624ee82862074` contains current
upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 22
dependency/Gemini tests and lock check passed. Earlier live behavior
proofs below retain their commit/platform scope; contributor runtime
logic is unchanged.

The common shard-2 failure was independently confirmed on main's hosted
job 127069149772 and locally (four failures, six passes): the Gemini
memory fixture mocked an unused body reader and provided no request
stream. The maintainer test-only follow-up now constructs a real
FastAPI/ASGI Request carrying JSON bytes and exercises the actual body
reader. All six test-function ASTs/assertions are unchanged, and all 10
parameterized Gemini cases pass. Touched-file Ruff/format and whitespace
checks pass. This fixes the inherited fixture instead of asking
contributors to run CI or weakening the memory/content assertions. Fresh
exact-head hosted qualification is requested. Nothing merged.
<!-- /maintainer-current-main -->

## Description



On Linux, installing `headroom-ai[all]` resolved PyTorch and NVIDIA CUDA
packages even for users who only needed the CLI/proxy profile. The
locked dependency graph included those packages through `ml`, `memory`,
`evals`, and `voice`.



This keeps those PyTorch-backed extras available for explicit
installation while removing them from `[all]`. Image support and the
other CLI/proxy dependencies remain included; dependency metadata cannot
detect installed GPU hardware.



Closes #3339



## Type of Change



- [ ] Bug fix (non-breaking change that fixes an issue)

- [ ] New feature (non-breaking change that adds functionality)

- [x] Breaking change (fix or feature that would cause existing
functionality to change)

- [ ] Documentation update

- [ ] Performance improvement

- [ ] Code refactoring (no functional changes)



## Changes Made



- Remove `ml`, `memory`, `evals`, and `voice` from the `[all]` extra
while keeping each separately installable.

- Retain `image` and the other default CLI/proxy capabilities.

- Update README and installation docs to describe the opt-in extras and
CUDA package implications.

- Add a dependency contract assertion for the `[all]` extra.



## Testing



- [ ] Unit tests pass (`pytest`)

- [ ] Linting passes (`ruff check .`)

- [ ] Type checking passes (`mypy headroom`)

- [ ] New tests added for new functionality

- [x] Manual testing performed



### Test Output



```text

Focused dependency contract tests: 3 passed, 5 deselected.

Python 3.13 locked `uv export` exited 0; the fixed export omits torch, CUDA, NVIDIA, sentence-transformers, and datasets. The baseline export contained them.

`uv lock --check`, scoped Ruff check/format, and `git diff --check` exited 0.

The broader dependency test module had 3 passed and 5 import failures because `opentelemetry` is absent from the local environment.

```



## Real Behavior Proof



- Environment: Linux, Python 3.13, locked uv dependency resolution.

- Exact command / steps: `UV_PYTHON_DOWNLOADS=never uv export --python
3.13 --extra all --no-dev --locked --no-hashes --no-emit-project`.

- Observed result: exit 0; the resolved export no longer contains torch,
CUDA, NVIDIA, sentence-transformers, or datasets, all of which were
present in the baseline export.

- Not tested: a full environment install and GPU runtime behavior.



## Runtime Rollout Safety



- Rollout-managed feature(s): None.

- Minimum rollout channel: Stable package release.

- Stable/default behavior changed: Yes; `[all]` no longer installs the
four PyTorch-backed extras.

- Kill switch / disable path: Not applicable; install the desired extras
explicitly.

- Unsafe override required: No.

- Qualification impact: Users of those capabilities must add the
corresponding extras.

- Rollback path: Restore the extras to `[all]` and regenerate `uv.lock`.



## Review Readiness



- [x] I have performed a self-review

- [x] This PR is ready for human review



## Checklist



- [x] My code follows the project's style guidelines

- [x] I have performed a self-review of my code

- [ ] I have commented my code, particularly in hard-to-understand areas

- [x] I have made corresponding changes to the documentation

- [ ] My changes generate no new warnings

- [x] I have added tests that prove my fix is effective or that my
feature works

- [ ] New and existing unit tests pass locally with my changes

- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)



## Screenshots (if applicable)



Not applicable to this dependency-resolution change.



## Additional Notes



The `[all]` install profile intentionally no longer includes
PyTorch-backed optional capabilities; each remains available through its
named extra. The focused regression and locked resolver proof passed,
but the full dependency test module and a full install were not verified
locally.





## Maintainer integration qualification

Published head `3229690b613810d496f015cedd086ca1d7421843` includes
current upstream main `31dcaf41`. The merge preserves main's `lean`
dependency profile and deprecated `sandbox` alias alongside the
contributor's opt-in `[all]` policy. No optional-feature runtime logic
was changed.



- Reconciled the existing macOS dependency test with the declared
policy, retaining the transitive exclusion check and independently
verifying explicit `ml`/`voice` opt-ins on Intel macOS and Linux. All 12
tests across `tests/test_onnx_dependency_contract.py` and
`tests/test_optional_dependencies.py` pass on Windows/Python 3.12.13.

- Evaluation workflow installs now explicitly request `evals`, and the
model-allowed weekly job also requests `ml`, preserving its previous
intended dependencies. The evaluation guide and AI install index
identify those opt-ins. These address the existing Devin workflow/docs
findings.

- `uv lock --check`, touched Python Ruff/format and whitespace checks
pass. All 253 locked package versions are unchanged; only the root
`[all]` dependency metadata/flattened list changes.

- Real resolver commands from this checkout: `uv export --extra all
--no-dev --locked --no-hashes --no-emit-project` and `uv export --extra
all --extra ml --extra voice --extra evals --no-dev --locked --no-hashes
--no-emit-project`. Evaluating their actual requirement markers for
Python 3.12/3.13/3.14 on Linux x86_64, Windows AMD64, macOS arm64 and
macOS x86_64 shows `[all]` excludes torch, sentence-transformers,
datasets and CUDA/NVIDIA packages in all 12 environments. Explicit
opt-ins retain datasets and torch where supported; Intel macOS still
excludes torch.

- Not tested: a fresh full environment install, GPU runtime, live paid
evaluations or a fresh native build. Hosted CI must qualify the
published final head separately.



### Maintainer current-main requalification

Exact head `f1ed1e0019037e7b53ff9ef548843449c3c7a16f`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Current-main integration against upstream
c01cf07d94. The sole conflict was the
inherited Gemini fixture: adopted main's streamed-body helper after
verifying all six test-function ASTs unchanged. No contributor
dependency policy rewritten. The declared breaking change keeps
Torch-backed ml/memory/evals/voice opt-in while preserving the default
CLI/proxy bundle, image capability and main's lean profile. Evaluation
workflows and guides explicitly request removed extras; current
author/Devin discussion considered.

Fresh verification: 25 dependency/Gemini tests pass; offline uv lock
check resolves 253 packages; changed Python lint/format and
main-relative whitespace pass. Actual locked exports evaluated over 12
OS/Python marker environments (Linux/Windows/macOS, Python 3.10–3.13):
all excludes Torch/NVIDIA dependencies, explicit
all+ml+memory+evals+voice retains Torch. This is resolver/export proof,
not a fresh full installation or GPU runtime claim. No new source
blocker found; formal approval awaits exact-head hosted checks. Nothing
merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-06 09:23:03 -06:00
dependabot[bot]andJerrettDavis de1a1e0f47 deps: update sqlite-vec requirement from >=0.1.6 to >=0.1.9 (#4654)
Updates the requirements on [sqlite-vec](https://TODO.com) to permit the
latest version.


Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)


</details>
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4654"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

### Maintainer current-main requalification

Exact head `45ff018fcda1368f0e1b3d8cf84f97203dd993d8`, upstream main
`f50db67006e2fe3f43b295542b759d90bb73e5a1`.

Maintainer remediation under the user's explicit directive to maintain
Dependabot updates and qualify them for approval. This records an
authorized routine-maintenance exception rather than inventing a newly
required vector feature or claiming the old range excluded0.1.9.
sqlite-vec remains in the existing optional memory extras; the base
install gains no new dependency, service or network behavior. Native
extension/wheel compatibility is the relevant install surface.

Synchronized current main and repaired the selected sqlite-vec lock
entry plus all three declared floor records to0.1.9, retaining unrelated
lock metadata. Offline lock consistency and whitespace checks pass.
Installed the actual0.1.9 Python3.12 native wheel in an isolated overlay
and verified its module path/version. All45
vector-index/local-search/core-search/relation-key tests pass,
exercising real extension loading, indexing/querying, filters,
updates/deletes and persistence.

The initial Windows suite exposed pre-existing fixture teardown errors:
indexes cached connections but fixtures unlinked the open databases. A
clean-main control reproduced that error. Fixed the test-only lifecycle
to await close before unlink, and strengthened the persistence test to
close the first index before reopening the database. Production
vector/runtime logic and assertions are unchanged. Re-execution passes
all45 with no cleanup errors. Existing Headroom native core supports
startup; this does not claim a rebuilt sqlite-vec wheel or fresh
Headroom Rust extension build. Hosted checks cover remaining platforms;
maintainers handle final approval. No requests for changes to the bot
and nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `6d6cd26dff5f6f954fc737a5ac89ba9a960d2448`, upstream main
`def4ef10099514d09188326852138a8b20c26237`.

Maintainer remediation under the user's explicit directive to maintain
Dependabot updates and qualify them for approval. This records an
authorized routine-maintenance exception rather than inventing a newly
required vector feature or claiming the old range excluded0.1.9.
sqlite-vec remains in the existing optional memory extras; the base
install gains no new dependency, service or network behavior. Native
extension/wheel compatibility is the relevant install surface.

Synchronized current main and repaired the selected sqlite-vec lock
entry plus all three declared floor records to0.1.9, retaining unrelated
lock metadata. Offline lock consistency and whitespace checks pass.
Installed the actual0.1.9 Python3.12 native wheel in an isolated overlay
and verified its module path/version. All45
vector-index/local-search/core-search/relation-key tests pass,
exercising real extension loading, indexing/querying, filters,
updates/deletes and persistence.

The initial Windows suite exposed pre-existing fixture teardown errors:
indexes cached connections but fixtures unlinked the open databases. A
clean-main control reproduced that error. Fixed the test-only lifecycle
to await close before unlink, and strengthened the persistence test to
close the first index before reopening the database. Production
vector/runtime logic and assertions are unchanged. Re-execution passes
all45 with no cleanup errors. Existing Headroom native core supports
startup; this does not claim a rebuilt sqlite-vec wheel or fresh
Headroom Rust extension build. Hosted checks cover remaining platforms;
maintainers handle final approval. No requests for changes to the bot
and nothing merged.


Post-merge requalification: main
def4ef1009 adds only the already approved
docs/package.json and npm lock update. The new integration changes no
Python/runtime/test or dependency inputs for this PR; prior
exact-version local results remain scoped to byte-identical inputs.
Offline lock consistency and whitespace pass again. New-head hosted
qualification remains pending; no redundant runtime run is claimed.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `ba7370bf466fd27ca8c124d4626465cc6ead9daf`, upstream main
`ea59ac3eef3a3dc02076e9fe4bb30d572ca9c1a9`.

Final landing preparation after merged Click#4655: clean integration
with current upstream/main ea59ac3eef,
including the proven macOS native setup fix. Reviewed the remaining
three-file delta: sqlite-vec floor/lock0.1.9 and test-only connection
lifecycle cleanup. Actual isolated sqlite-vec0.1.9 plus Click8.5.0 run
together:79
vector/local/core/relation/scoped-clear/metadata-sync/connection-cleanup/temporal-filter/CLI-help
tests pass. Offline frozen lock consistency and whitespace pass. No
production vector logic changed. Maintainers handle fresh exact-head
hosted qualification and merge only after green; no bot changes request.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 22:22:33 -06:00
dependabot[bot]andJerrettDavis ea59ac3eef deps: update click requirement from >=8.3.3 to >=8.5.0 (#4655)
Updates the requirements on [click](https://github.com/pallets/click) to
permit the latest version.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/pallets/click/releases">click's
releases</a>.</em></p>
<blockquote>
<h2>8.5.0</h2>
<p>This is the Click 8.5.0 feature release. A feature release may
include new features, remove previously deprecated code, add new
deprecation, or introduce potentially breaking changes.</p>
<p>We encourage everyone to upgrade. You can read more about our <a
href="https://palletsprojects.com/versions">Version Support Policy</a>
on our website.</p>
<p>PyPI: <a
href="https://pypi.org/project/click/8.5.0/">https://pypi.org/project/click/8.5.0/</a>
Changes: <a
href="https://click.palletsprojects.com/page/changes/#version-8-5-0">https://click.palletsprojects.com/page/changes/#version-8-5-0</a>
Milestone <a
href="https://github.com/pallets/click/milestone/33">https://github.com/pallets/click/milestone/33</a></p>
<ul>
<li>Add built-in shell completion support for PowerShell (Windows
PowerShell
5.1+ and pwsh 7+) alongside the existing <code>bash</code>,
<code>zsh</code>, and <code>fish</code>
completers. Use <code>_FOO_BAR_COMPLETE=powershell_source foo-bar</code>
to generate
the completion script. <a
href="https://redirect.github.com/pallets/click/issues/2672">#2672</a>
<a
href="https://redirect.github.com/pallets/click/issues/3637">#3637</a></li>
<li>Supported versions of Windows enable ANSI terminal styles by
default.
Colorama is no longer a dependency and is not used. <a
href="https://redirect.github.com/pallets/click/issues/2986">#2986</a>
<a
href="https://redirect.github.com/pallets/click/issues/3505">#3505</a></li>
<li>{class}<code>Argument</code> accepts a <code>help</code> parameter,
and help output includes
a <code>Positional arguments</code> section when argument help is
available. <a
href="https://redirect.github.com/pallets/click/issues/2983">#2983</a>
<a
href="https://redirect.github.com/pallets/click/issues/3473">#3473</a></li>
<li><code>confirm()</code> and <code>prompt()</code> strip ANSI color
and style codes from the
prompt when the output stream does not support them, matching
<code>echo()</code>.
This stripping was lost in <code>8.4.0</code> when <a
href="https://redirect.github.com/pallets/click/issues/2969">#2969</a>
began writing the
prompt with <code>input()</code> directly. <a
href="https://redirect.github.com/pallets/click/issues/3572">#3572</a>
<a
href="https://redirect.github.com/pallets/click/issues/3653">#3653</a></li>
<li>{class}<code>Path</code> with <code>allow_dash=True</code> no longer
triggers a <code>BytesWarning</code>,
an error under <code>python -bb</code>, when checking a value against
the <code>-</code>
convention. <a
href="https://redirect.github.com/pallets/click/issues/2877">#2877</a>
<a
href="https://redirect.github.com/pallets/click/issues/3642">#3642</a></li>
<li>Add {func}<code>custom_version_option</code>, a
<code>--version</code> option whose output is
produced by a callback, covering cases {func}<code>version_option</code>
intentionally
does not. The feature set of {func}<code>version_option</code> is now
frozen; see
[discussion <a
href="https://redirect.github.com/pallets/click/issues/3527">#3527</a>](<a
href="https://github.com/pallets/click/discussions/3527">https://github.com/pallets/click/discussions/3527</a>).
<a
href="https://redirect.github.com/pallets/click/issues/3581">#3581</a></li>
<li><code>style()</code> and <code>secho()</code> no longer silently
drop the 256-color index <code>0</code>
(black) passed as <code>fg</code> or <code>bg</code>, and now validate
color arguments. Invalid
colors raise a <code>ValueError</code> instead of a
<code>TypeError</code>. <a
href="https://redirect.github.com/pallets/click/issues/3677">#3677</a></li>
<li>The automatic help option stores its value under the reserved name
<code>_click_default_help</code> instead of <code>help</code>, so a
parameter named <code>help</code> no
longer breaks parsing. The new name is visible in
{meth}<code>Command.to_info_dict</code> output. Parameters that
overwrite each other's
value trigger a warning: an argument sharing its name with another
parameter, or any parameter claiming the reserved name. Options may
still
share a name to compete for the same value (feature switches).
<a
href="https://redirect.github.com/pallets/click/issues/2819">#2819</a>
<a
href="https://redirect.github.com/pallets/click/issues/3678">#3678</a></li>
<li><code>unstyle</code> and the ANSI handling behind help-text wrapping
now strip the full
CSI escape-sequence grammar. <a
href="https://redirect.github.com/pallets/click/issues/3681">#3681</a></li>
<li>Streamline <code>Option</code> flag handling: the flag-kind, type,
lazy-default and
validation steps in <code>Option.__init__</code> move into focused
helpers, and
<code>flag_value</code> and <code>default</code> keep their unset
sentinel at construction
(resolved lazily on read) so <code>is UNSET</code> reliably tells a
user-supplied value
from an auto-derived one. Runtime behavior is unchanged, but
{meth}<code>Parameter.to_info_dict</code> now resolves
<code>default=True</code> on a feature
switch to its <code>flag_value</code>, matching what the function
receives at call</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/pallets/click/blob/main/CHANGES.md">click's
changelog</a>.</em></p>
<blockquote>
<h2>Version 8.5.0</h2>
<p>Released 2026-08-24</p>
<ul>
<li>Add built-in shell completion support for PowerShell (Windows
PowerShell
5.1+ and pwsh 7+) alongside the existing <code>bash</code>,
<code>zsh</code>, and <code>fish</code>
completers. Use <code>_FOO_BAR_COMPLETE=powershell_source foo-bar</code>
to generate
the completion script. {issue}<code>2672</code>
{pr}<code>3637</code></li>
<li>Supported versions of Windows enable ANSI terminal styles by
default.
Colorama is no longer a dependency and is not used.
{issue}<code>2986</code> {pr}<code>3505</code></li>
<li>{class}<code>Argument</code> accepts a <code>help</code> parameter,
and help output includes
a <code>Positional arguments</code> section when argument help is
available. {issue}<code>2983</code> {pr}<code>3473</code></li>
<li><code>confirm()</code> and <code>prompt()</code> strip ANSI color
and style codes from the
prompt when the output stream does not support them, matching
<code>echo()</code>.
This stripping was lost in <code>8.4.0</code> when {pr}<code>2969</code>
began writing the
prompt with <code>input()</code> directly. {issue}<code>3572</code>
{pr}<code>3653</code></li>
<li>Fix test failures when using pytest &gt;= 9.1.
{pr}<code>3656</code></li>
<li>{class}<code>Path</code> with <code>allow_dash=True</code> no longer
triggers a <code>BytesWarning</code>,
an error under <code>python -bb</code>, when checking a value against
the <code>-</code>
convention. {issue}<code>2877</code> {pr}<code>3642</code></li>
<li>Add {func}<code>custom_version_option</code>, a
<code>--version</code> option whose output is
produced by a callback, covering cases {func}<code>version_option</code>
intentionally
does not. The feature set of {func}<code>version_option</code> is now
frozen; see
[discussion <a
href="https://redirect.github.com/pallets/click/issues/3527">#3527</a>](<a
href="https://github.com/pallets/click/discussions/3527">https://github.com/pallets/click/discussions/3527</a>).
{pr}<code>3581</code></li>
<li><code>style()</code> and <code>secho()</code> no longer silently
drop the 256-color index <code>0</code>
(black) passed as <code>fg</code> or <code>bg</code>, and now validate
color arguments. Invalid
colors raise a <code>ValueError</code> instead of a
<code>TypeError</code>. {pr}<code>3677</code></li>
<li>The automatic help option stores its value under the reserved name
<code>_click_default_help</code> instead of <code>help</code>, so a
parameter named <code>help</code> no
longer breaks parsing. The new name is visible in
{meth}<code>Command.to_info_dict</code> output. Parameters that
overwrite each other's
value trigger a warning: an argument sharing its name with another
parameter, or any parameter claiming the reserved name. Options may
still
share a name to compete for the same value (feature switches).
{issue}<code>2819</code> {pr}<code>3678</code></li>
<li><code>unstyle</code> and the ANSI handling behind help-text wrapping
now strip the full
CSI escape-sequence grammar. {pr}<code>3681</code></li>
<li>Streamline <code>Option</code> flag handling: the flag-kind, type,
lazy-default and
validation steps in <code>Option.__init__</code> move into focused
helpers, and
<code>flag_value</code> and <code>default</code> keep their unset
sentinel at construction
(resolved lazily on read) so <code>is UNSET</code> reliably tells a
user-supplied value
from an auto-derived one. Runtime behavior is unchanged, but
{meth}<code>Parameter.to_info_dict</code> now resolves
<code>default=True</code> on a feature
switch to its <code>flag_value</code>, matching what the function
receives at call
time. {pr}<code>3641</code></li>
<li>{func}<code>get_binary_stream</code> and
{func}<code>get_text_stream</code> are deprecated and
will be removed in Click 9.0. {issue}<code>3481</code>
{pr}<code>3695</code></li>
<li>The following <code>click.utils</code> names were never
intentionally public and are
now private (<code>_</code>-prefixed). The old names remain available
with a
<code>DeprecationWarning</code> until Click 9.0: <code>LazyFile</code>,
<code>KeepOpenFile</code>,</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/pallets/click/commit/8b19813f2bfca99f1018a587a8cf54fc959f2e5d"><code>8b19813</code></a>
Release version 8.5.0</li>
<li><a
href="https://github.com/pallets/click/commit/2c8cd3ac958a7eb316d67f2d316c27086c4c0369"><code>2c8cd3a</code></a>
Add FAQ entry about <code>UnicodeEncodeError</code> on Windows (<a
href="https://redirect.github.com/pallets/click/issues/3778">#3778</a>)</li>
<li><a
href="https://github.com/pallets/click/commit/131c86aadddfa5cb6dca8339c9d6294c4eacb8ac"><code>131c86a</code></a>
Add FAQ entry about <code>UnicodeEncodeError</code> on Windows</li>
<li><a
href="https://github.com/pallets/click/commit/e1fd5946ab26aaf372009eaff1acf947140b40fb"><code>e1fd594</code></a>
Add support of <code>pathlib.Path</code> to <code>edit</code> (<a
href="https://redirect.github.com/pallets/click/issues/3781">#3781</a>)</li>
<li><a
href="https://github.com/pallets/click/commit/a1d87858abd77fa8e3ffc204670ccd75b96c4781"><code>a1d8785</code></a>
Add support of <code>pathlib.Path</code> to <code>edit</code></li>
<li><a
href="https://github.com/pallets/click/commit/2103e157683c5e4cadc8ee1838df526a54bde9a4"><code>2103e15</code></a>
Forward all user's parameters set in <code>PAGER</code> and improve flag
detection (<a
href="https://redirect.github.com/pallets/click/issues/3777">#3777</a>)</li>
<li><a
href="https://github.com/pallets/click/commit/a6256bfb5971d5e58585fe7b6c656134e1ade5a4"><code>a6256bf</code></a>
Forwards all user's parameters set in <code>PAGER</code></li>
<li><a
href="https://github.com/pallets/click/commit/61b69e967e525bd502f5bf42def4d551e761fe0e"><code>61b69e9</code></a>
Resolve the pager command once, in <code>_pager_contextmanager</code>
(<a
href="https://redirect.github.com/pallets/click/issues/3776">#3776</a>)</li>
<li><a
href="https://github.com/pallets/click/commit/9835b0f7612d1b1ea180a975fd6d24cf16791ba8"><code>9835b0f</code></a>
Resolve the pager command once, in
<code>_pager_contextmanager</code></li>
<li><a
href="https://github.com/pallets/click/commit/f36d58bbd7f188178de2d4fe1d0292c510375ca7"><code>f36d58b</code></a>
Refactor pager stream handling (<a
href="https://redirect.github.com/pallets/click/issues/3767">#3767</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/pallets/click/compare/8.3.3...8.5.0">compare
view</a></li>
</ul>
</details>
<br />


Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)


</details>

### Maintainer current-main requalification

Exact head `44cdfa89659155ae558110ce77abdbb0ebb59725`, upstream main
`f50db67006e2fe3f43b295542b759d90bb73e5a1`.

Maintainer remediation under the user's explicit directive to maintain
Dependabot updates and qualify them for approval. This is an authorized
routine-maintenance exception, not a claim that the previous Click floor
excluded8.5.0 or lacked the earlier click.edit security fix. Click is
the existing base CLI dependency; no new service, executable hook or
outbound network behavior is added.

Synchronized current main and repaired the frozen lock to Click8.5.0 and
the declared>=8.5.0 floor, preserving unrelated package metadata.
Offline lock consistency and whitespace checks pass. Installed the
actual8.5.0 pure-Python wheel in an isolated Python3.12 overlay and
verified module path/version. Port parsing/discovery, main help/version,
console entrypoint, proxy preflight, environment options and Claude
base-URL wrapper selection:249pass,6skip,one environment-only failure.
The failed installed-distribution metadata assertion independently fails
identically on clean current main: the shared installed console
entrypoint is stale (headroom.cli:main versus headroom.cli.main:main).
It is not attributed to Click or hidden as a passing test.

Existing native core supports startup; no fresh native build or macOS
runtime claim. All CLI runtime/code remains unchanged. Maintainers
handle exact-head hosted checks and final approval; no changes requested
from the bot and nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `510908d54ca652769ab981098518485af62174f0`, upstream main
`def4ef10099514d09188326852138a8b20c26237`.

Maintainer remediation under the user's explicit directive to maintain
Dependabot updates and qualify them for approval. This is an authorized
routine-maintenance exception, not a claim that the previous Click floor
excluded8.5.0 or lacked the earlier click.edit security fix. Click is
the existing base CLI dependency; no new service, executable hook or
outbound network behavior is added.

Synchronized current main and repaired the frozen lock to Click8.5.0 and
the declared>=8.5.0 floor, preserving unrelated package metadata.
Offline lock consistency and whitespace checks pass. Installed the
actual8.5.0 pure-Python wheel in an isolated Python3.12 overlay and
verified module path/version. Port parsing/discovery, main help/version,
console entrypoint, proxy preflight, environment options and Claude
base-URL wrapper selection:249pass,6skip,one environment-only failure.
The failed installed-distribution metadata assertion independently fails
identically on clean current main: the shared installed console
entrypoint is stale (headroom.cli:main versus headroom.cli.main:main).
It is not attributed to Click or hidden as a passing test.

Existing native core supports startup; no fresh native build or macOS
runtime claim. All CLI runtime/code remains unchanged. Maintainers
handle exact-head hosted checks and final approval; no changes requested
from the bot and nothing merged.


Post-merge requalification: main
def4ef1009 adds only the already approved
docs/package.json and npm lock update. The new integration changes no
Python/runtime/test or dependency inputs for this PR; prior
exact-version local results remain scoped to byte-identical inputs.
Offline lock consistency and whitespace pass again. New-head hosted
qualification remains pending; no redundant runtime run is claimed.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `a551180102dfa3d1c5f98941040cb081f30a88fe`, upstream main
`7877241d84c93b3ec487e07324245838ddae85cc`.

Maintainer remediation under the user's explicit directive to maintain
Dependabot updates and qualify them for approval. This is an authorized
routine-maintenance exception, not a claim that the previous Click floor
excluded8.5.0 or lacked the earlier click.edit security fix. Click is
the existing base CLI dependency; no new service, executable hook or
outbound network behavior is added.

Synchronized current main and repaired the frozen lock to Click8.5.0 and
the declared>=8.5.0 floor, preserving unrelated package metadata.
Offline lock consistency and whitespace checks pass. Installed the
actual8.5.0 pure-Python wheel in an isolated Python3.12 overlay and
verified module path/version. Port parsing/discovery, main help/version,
console entrypoint, proxy preflight, environment options and Claude
base-URL wrapper selection:249pass,6skip,one environment-only failure.
The failed installed-distribution metadata assertion independently fails
identically on clean current main: the shared installed console
entrypoint is stale (headroom.cli:main versus headroom.cli.main:main).
It is not attributed to Click or hidden as a passing test.

Existing native core supports startup; no fresh native build or macOS
runtime claim. All CLI runtime/code remains unchanged. Maintainers
handle exact-head hosted checks and final approval; no changes requested
from the bot and nothing merged.


Post-merge requalification: main
def4ef1009 adds only the already approved
docs/package.json and npm lock update. The new integration changes no
Python/runtime/test or dependency inputs for this PR; prior
exact-version local results remain scoped to byte-identical inputs.
Offline lock consistency and whitespace pass again. New-head hosted
qualification remains pending; no redundant runtime run is claimed.


Landing qualification on
main7877241d84c93b3ec487e07324245838ddae85cc:296 latest
CLI/Hermes/port-discovery tests pass,6optional skips. The previously
baseline-reproduced stale installed console-script metadata assertion is
excluded from this focused local rerun (1deselected), not weakened in
committed tests. Added maintainer CI prerequisite fix: test-macos
explicitly installs pinnedRust1.95.0 with rustfmt/clippy, verifies
cargo/rustc, then performs editable pip install. This addresses the two
observed implicit rustup bootstrap failures before test execution.
Independent review confirmed action pin/components/order and no deletion
workaround; Actionlint and all58 release-workflow tests pass. No runtime
code or dependency behavior changed. User explicitly authorized landing
Dependabot PRs once green; merge remains gated by successful exact-head
checks and current-main integration.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 22:02:00 -06:00
dependabot[bot]andJerrettDavis 910588e6b1 deps: update tree-sitter requirement from <0.27,>=0.25.2 to >=0.26.0,<0.27 (#4656)
Updates the requirements on
[tree-sitter](https://github.com/tree-sitter/py-tree-sitter) to permit
the latest version.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/tree-sitter/py-tree-sitter/releases">tree-sitter's
releases</a>.</em></p>
<blockquote>
<h2>v0.26.0</h2>
<p><em>Breaking changes are marked with <strong>!</strong>.</em></p>
<h3>Additions:</h3>
<ul>
<li><code>Point.edit()</code></li>
<li><code>Point.__repr__()</code></li>
<li><code>QueryCursor.set_containing_byte_range()</code></li>
<li><code>QueryCursor.set_containing_point_range()</code></li>
<li><code>Range.edit()</code></li>
<li><code>tree_sitter.__version__</code></li>
</ul>
<h3>Removals:</h3>
<ul>
<li><code>Language.version</code>: use <code>Language.abi_version</code>
<strong>!</strong></li>
<li><code>Language.query(source)</code>: use <code>Query(language,
source)</code> <strong>!</strong></li>
<li><code>Parser.timeout_micros</code>: use the
<code>progress_callback</code> in <code>parse()</code>
<strong>!</strong></li>
<li><code>QueryCursor.timeout_micros</code>: use the
<code>progress_callback</code> in <code>matches()</code> or
<code>captures()</code> <strong>!</strong></li>
</ul>
<h3>Changes:</h3>
<ul>
<li><code>Point</code> is a tuple subclass rather than a namedtuple
object</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/a9e753ef67875c55267ebe02e786eac193a53bc1"><code>a9e753e</code></a>
ci(pypi): skip riscv64 tests properly</li>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/eeababc529a44d2d3ef09486f2f71711ca50de25"><code>eeababc</code></a>
chore: release 0.26.0</li>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/dac834eca3523201a6890d647e0ee3fae6cec892"><code>dac834e</code></a>
fix(node): fix reference leak</li>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/bdddb6180da9a6100bd670416963d6d47e96c70d"><code>bdddb61</code></a>
build: bump tree-sitter-rust from 0.24.1 to 0.24.2</li>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/baa5fd8e277e10d68632bc4ed832e317f8070553"><code>baa5fd8</code></a>
ci: bump the actions group across 1 directory with 2 updates</li>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/c680e3b51353d8e22b41414a74b538672ea7f59b"><code>c680e3b</code></a>
build: bump tree_sitter/core from <code>cd5b087</code> to
<code>7f53486</code></li>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/2d3fb3a2a7a23995791f2f7b621e933cf300ec7d"><code>2d3fb3a</code></a>
ci: bump actions/upload-pages-artifact from 4 to 5 in the actions
group</li>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/bae0829cea6b44f072c00e1385f459b16a281ed9"><code>bae0829</code></a>
build: bump tree-sitter-rust from 0.24.0 to 0.24.1</li>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/d99f79601f25c74edd10823cb3fceb95d65ae3f3"><code>d99f796</code></a>
build: bump tree_sitter/core from <code>6f2e8a6</code> to
<code>cd5b087</code></li>
<li><a
href="https://github.com/tree-sitter/py-tree-sitter/commit/a9282df03584eb98e8d67df3b151cf8df0b38f14"><code>a9282df</code></a>
build: bump tree_sitter/core from <code>cd4b6e2</code> to
<code>6f2e8a6</code></li>
<li>Additional commits viewable in <a
href="https://github.com/tree-sitter/py-tree-sitter/compare/v0.25.2...v0.26.0">compare
view</a></li>
</ul>
</details>
<br />


Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)


</details>

### Maintainer current-main requalification

Exact head `b2f53b2e6f451a291263dcb669ae899c0bbd3ea9`, upstream main
`f50db67006e2fe3f43b295542b759d90bb73e5a1`.

Maintainer remediation under the user's explicit instruction to maintain
Dependabot updates directly and qualify them for approval. This records
a routine-maintenance exception to the ordinary dependency-policy
justification requirement; it does not invent a newly required parser
feature or claim the old supported floor was insecure.

Synchronized current main and regenerated the selected tree-sitter lock
entry and code-extra floor together. Kept unrelated lock package
markers/versions intact. Offline lock consistency and frozen code-extra
export pass; the lock now selects tree-sitter0.26.0 rather than the
stale0.25.2. The dependency remains optional in the code extra with the
existing <0.27 bound; the base install gains no new dependency, service
or network behavior.

Installed the actual0.26.0 Python3.12 native wheel in an isolated
overlay and verified the imported module path/version. All162
code-compressor, parser thread-safety, language-alias, Bash,
syntax-breaker and CJK tests pass using existing language-pack0.13.0.
The later main merges do not change that parser implementation;
qualification is carried forward against the unchanged source, with no
redundant run claimed. These are real parser executions, not mocks
substituted for the tree-sitter binding. Headroom startup uses the
existing native core; this does not claim a fresh Headroom Rust build or
cross-platform wheel build.

Changed manifest/lock whitespace checks pass. Maintainers handle
exact-head hosted checks; formal approval follows current-main ancestry
and successful CI. No requests for changes to the bot and nothing
merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 21:00:54 -06:00
headroom-release[bot]andgithub-actions[bot] 2d3ee51846 chore: release 0.43.1 (#4661)
🤖 I have created a release *beep* *boop*
---


##
[0.43.1](https://github.com/headroomlabs-ai/headroom/compare/v0.43.0...v0.43.1)
(2026-11-05)


### Bug Fixes

* **ccr:** keep the in-memory order queue from evicting re-stored
entries
([#4545](https://github.com/headroomlabs-ai/headroom/issues/4545))
([c6f5bf9](https://github.com/headroomlabs-ai/headroom/commit/c6f5bf9549e9b357e9c2369d4e04bc437f5e180d))
* **memory:** read the relation key the memory_save schema advertises
([#4647](https://github.com/headroomlabs-ai/headroom/issues/4647))
([7592e68](https://github.com/headroomlabs-ai/headroom/commit/7592e681459f14a2041eb5f524a658cb6ad1dd92))
* **memory:** replace the HNSW vector when a memory is re-indexed
([#4649](https://github.com/headroomlabs-ai/headroom/issues/4649))
([ee638f9](https://github.com/headroomlabs-ai/headroom/commit/ee638f9532b3788bacd13ed8d26dd0faf0740baf))
* **openclaw:** accept 12-character hashes in headroom_retrieve
([#4640](https://github.com/headroomlabs-ai/headroom/issues/4640))
([8d3e9e5](https://github.com/headroomlabs-ai/headroom/commit/8d3e9e5ca7cd645eb73084b848edbea5fc796e1a))
* **ort:** avoid implicit runtime discovery from the workspace
([#4570](https://github.com/headroomlabs-ai/headroom/issues/4570))
([69fbd23](https://github.com/headroomlabs-ai/headroom/commit/69fbd2390d9c8b0fa1f59fb8314bc9b8f01b1a55))
* **proxy:** bound the model-keyed tokenizer, beacon and litellm caches
([#4497](https://github.com/headroomlabs-ai/headroom/issues/4497))
([e51b806](https://github.com/headroomlabs-ai/headroom/commit/e51b8065a4a2aa3a3c7f266c1cb8d8bde6b568d0))
* **proxy:** use HTTP/1.1 client for ChatGPT streaming and model
metadata
([#4006](https://github.com/headroomlabs-ai/headroom/issues/4006))
([e1becdf](https://github.com/headroomlabs-ai/headroom/commit/e1becdf7329bf4ca03874b9f512ac19837ca29c2))
* **release:** normalize damaged release PR envelopes before detection
([#4664](https://github.com/headroomlabs-ai/headroom/issues/4664))
([917edc6](https://github.com/headroomlabs-ai/headroom/commit/917edc62230c3c4a8a415e2053da68dab1f003dd))
* **router:** keep tagged blocks out of the lossy size-gate fallback
([#4543](https://github.com/headroomlabs-ai/headroom/issues/4543))
([f333edf](https://github.com/headroomlabs-ai/headroom/commit/f333edf20f0d7acf5ea67e040c1f58539a0edd4d))
* **router:** log the ONNX fallbacks at info instead of warning
([#4535](https://github.com/headroomlabs-ai/headroom/issues/4535))
([db30d82](https://github.com/headroomlabs-ai/headroom/commit/db30d82dfffdb3bbe4d60a0e0bfe88640e58470f))


### Dependencies

* bump the npm-minor-patch group across 3 directories with 6 updates
([#4662](https://github.com/headroomlabs-ai/headroom/issues/4662))
([8f104f8](https://github.com/headroomlabs-ai/headroom/commit/8f104f8e298c85ff0005f2fd4848eea95f32b7c7))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: headroom-release[bot] <352661243+headroom-release[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-11-05 13:33:39 -06:00
81fa4bdda6 chore: release 0.43.0 (#4643)
🤖 I have created a release *beep* *boop*
---


##
[0.43.0](https://github.com/headroomlabs-ai/headroom/compare/v0.42.0...v0.43.0)
(2026-11-05)


### ⚠ BREAKING CHANGES

* **mcp:** port MCP servers to SDK 2.x
([#4603](https://github.com/headroomlabs-ai/headroom/issues/4603))

### Features

* **ccr:** answer headroom_retrieve on streaming chat completions
([#4631](https://github.com/headroomlabs-ai/headroom/issues/4631))
([31dcaf4](https://github.com/headroomlabs-ai/headroom/commit/31dcaf41f7fafaebec0838a05ff328da456faef0))
* **mcp:** port MCP servers to SDK 2.x
([#4603](https://github.com/headroomlabs-ai/headroom/issues/4603))
([ee2252a](https://github.com/headroomlabs-ai/headroom/commit/ee2252a3155c87e948c8893b79af5824eb30e64c))
* **plugins:** headroom skill for Claude Code, Codex, Copilot and
skills.sh
([#4533](https://github.com/headroomlabs-ai/headroom/issues/4533))
([66e1467](https://github.com/headroomlabs-ai/headroom/commit/66e14676827366c2bf8d15e252f8766cb27b1a98))
* **savings:** show the proxy's model-routing savings in headroom
savings
([#4304](https://github.com/headroomlabs-ai/headroom/issues/4304))
([aaab338](https://github.com/headroomlabs-ai/headroom/commit/aaab338b64cb55929de904411db65db126e22ec0))


### Bug Fixes

* [BUG] A timeout in one image compression call resets the shared worker
pool and affects concurrent requests
([#4528](https://github.com/headroomlabs-ai/headroom/issues/4528))
([e9bcfe7](https://github.com/headroomlabs-ai/headroom/commit/e9bcfe73fadf69f0b27b7bc338ea7d2380931054))
* [BUG] DirectMem0Adapter.search_memories calls removed mem0 search API
([#4518](https://github.com/headroomlabs-ai/headroom/issues/4518))
([d9cee45](https://github.com/headroomlabs-ai/headroom/commit/d9cee452681c79d6f13919e9e651e88a774c0874))
* [BUG] Saved request metrics lose their cache optimization fields
([#4584](https://github.com/headroomlabs-ai/headroom/issues/4584))
([b4c9bdf](https://github.com/headroomlabs-ai/headroom/commit/b4c9bdf100d97fb038beba95de6d4ad6a8786090))
* [BUG] Volatile SQLite metrics stores lose their schema before the
first save
([#4633](https://github.com/headroomlabs-ai/headroom/issues/4633))
([d8ff0fe](https://github.com/headroomlabs-ai/headroom/commit/d8ff0fe9d2cb2477f6662a90f8fcd7e030a52666))
* Add info about apply to README.md
([#1592](https://github.com/headroomlabs-ai/headroom/issues/1592))
([4d34680](https://github.com/headroomlabs-ai/headroom/commit/4d34680c34ad379d693820869e77d4a2a6be2cdf))
* **backends/litellm:** keep cache_control on text blocks for Bedrock
prompt caching
([#4565](https://github.com/headroomlabs-ai/headroom/issues/4565))
([23a5bb1](https://github.com/headroomlabs-ai/headroom/commit/23a5bb1c81dc943398f9271f068a02487207f2e7))
* **backends:** forward the standard service_tier param (litellm +
anyllm)
([#2468](https://github.com/headroomlabs-ai/headroom/issues/2468))
([62cc38a](https://github.com/headroomlabs-ai/headroom/commit/62cc38a6b09dbcf723681a0ff56acd02131ad1f1))
* **cache:** build semantic entry before evicting so a failed embedding
keeps live entries
([#4581](https://github.com/headroomlabs-ai/headroom/issues/4581))
([0d4c450](https://github.com/headroomlabs-ai/headroom/commit/0d4c450d774691568b850f0d22ce17e087405281))
* **cache:** count a tool_result with no text as replayable in the
frozen prefix
([#4523](https://github.com/headroomlabs-ai/headroom/issues/4523))
([fba09f6](https://github.com/headroomlabs-ai/headroom/commit/fba09f674c8a9c91b39a563a70ab7727b44d1dbc))
* **cache:** fail closed on SQLite corruption instead of deleting the
store online
([#4361](https://github.com/headroomlabs-ai/headroom/issues/4361))
([9801833](https://github.com/headroomlabs-ai/headroom/commit/98018333f997783487af15efe4d9e631ecd85939))
* **cache:** invalidate configured registry instances on replacement
([#4363](https://github.com/headroomlabs-ai/headroom/issues/4363))
([1bcdca2](https://github.com/headroomlabs-ai/headroom/commit/1bcdca2d9dd279f49aa4276d523d93c2cfeb5a51))
* **cache:** namespace SemanticCacheLayer by provider, model and
metadata
([#4473](https://github.com/headroomlabs-ai/headroom/issues/4473))
([99cdaaf](https://github.com/headroomlabs-ai/headroom/commit/99cdaaf1c7de2bd81a8e64f198462fd1ceec3a17))
* **cache:** preserve OpenAI tool block metadata on cached replay
([#4334](https://github.com/headroomlabs-ai/headroom/issues/4334))
([f1035ac](https://github.com/headroomlabs-ai/headroom/commit/f1035ac73788a577fb5495a59eed0fc925d42782))
* **cache:** scope router results to request compression policy
([#4590](https://github.com/headroomlabs-ai/headroom/issues/4590))
([5d40fe7](https://github.com/headroomlabs-ai/headroom/commit/5d40fe76471b12ffe2a5c81309d9df617ca60b41))
* **ccr:** buffer a stream only for a marker new this turn
([#4607](https://github.com/headroomlabs-ai/headroom/issues/4607))
([946a70c](https://github.com/headroomlabs-ai/headroom/commit/946a70cfcbdc522f940b01f0aeb2b7a214f54cb5))
* **ccr:** keep proactive expansion out of the cached prefix
([#4300](https://github.com/headroomlabs-ai/headroom/issues/4300))
([b1f340e](https://github.com/headroomlabs-ai/headroom/commit/b1f340e0b35d4659d7ebc993d9dcc08057da93e9))
* **cli:** document that code-aware compression is enabled by default
([#4616](https://github.com/headroomlabs-ai/headroom/issues/4616))
([affd17c](https://github.com/headroomlabs-ai/headroom/commit/affd17c5fde174ad78287eef1696251e18363722))
* **client:** close upstream responses when wrapped streams are closed
([#4482](https://github.com/headroomlabs-ai/headroom/issues/4482))
([3d8dcf4](https://github.com/headroomlabs-ai/headroom/commit/3d8dcf476c148f633e66eb98c478095adfd9354b))
* **client:** honor configured cache optimizer enablement
([#4501](https://github.com/headroomlabs-ai/headroom/issues/4501))
([d4c0810](https://github.com/headroomlabs-ai/headroom/commit/d4c0810ea3ebdd7e49e5d29f4e0dfd2da1511b02))
* **client:** preserve Anthropic create stream flags
([#4500](https://github.com/headroomlabs-ai/headroom/issues/4500))
([3910caa](https://github.com/headroomlabs-ai/headroom/commit/3910caabd68311ae99d5659aa2d470eb2c15ea0e))
* **codex:** accept multi-line inline tables in Codex config.toml
([#4436](https://github.com/headroomlabs-ai/headroom/issues/4436))
([4a851ed](https://github.com/headroomlabs-ai/headroom/commit/4a851ed25469a51de00ccd00d14d0a6ab62a0866))
* **compaction:** reject negative dictionary indices and non-array
legends in expand_compacted
([#4470](https://github.com/headroomlabs-ai/headroom/issues/4470))
([3c1fcbd](https://github.com/headroomlabs-ai/headroom/commit/3c1fcbdfde31069795b03faf9f43fdd73e6941d9))
* **core:** case-insensitive Bearer scheme, clamp SQLite CCR TTLs,
redact the Redis URL in logs
([#4561](https://github.com/headroomlabs-ai/headroom/issues/4561))
([9e8cc64](https://github.com/headroomlabs-ai/headroom/commit/9e8cc64b48ebd4e2fb31332f261464d3bd0550b7))
* **dedup:** bound line-number digit run and never fold into a longer
pointer
([#4488](https://github.com/headroomlabs-ai/headroom/issues/4488))
([21e8867](https://github.com/headroomlabs-ai/headroom/commit/21e8867504df57c8f99aa30bd889e7eed01cd49e))
* **deps:** clear the glob and minimatch npm audit findings
([#4599](https://github.com/headroomlabs-ai/headroom/issues/4599))
([2e49e53](https://github.com/headroomlabs-ai/headroom/commit/2e49e5304b245fdaca0d2640bb1a59cb1ffa63fc))
* **diff:** keep combined-diff changes made against a later parent
([#4318](https://github.com/headroomlabs-ai/headroom/issues/4318))
([4b788fd](https://github.com/headroomlabs-ai/headroom/commit/4b788fd04d407cea0113c74f979f7cc3072a0132))
* **docker:** install the redis extra in every image
([#4514](https://github.com/headroomlabs-ai/headroom/issues/4514))
([8d5dde7](https://github.com/headroomlabs-ai/headroom/commit/8d5dde77656c9bb3daa354a14ffa6904cb8311aa))
* **docker:** pass RUNTIME_HOME=/root for root bake targets
([#4445](https://github.com/headroomlabs-ai/headroom/issues/4445))
([670767e](https://github.com/headroomlabs-ai/headroom/commit/670767eeb49f224a7a0bcbcc31b3584a35110b7d))
* **doctor:** detect root openai_base_url Codex routing and
agent-configured proxy ports
([#4490](https://github.com/headroomlabs-ai/headroom/issues/4490))
([222f2d1](https://github.com/headroomlabs-ai/headroom/commit/222f2d1df3c6296462bc38c871cd29c221af55bc))
* **evals:** reject changed numeric probe values
([#4502](https://github.com/headroomlabs-ai/headroom/issues/4502))
([1fe8549](https://github.com/headroomlabs-ai/headroom/commit/1fe8549f9ca77a2bc1280e4319980e0b9b31f5b9))
* **install:** stabilize Windows task lifecycle and eliminate console
window popup
([#4627](https://github.com/headroomlabs-ai/headroom/issues/4627))
([6b903cb](https://github.com/headroomlabs-ai/headroom/commit/6b903cbc81c13f417485f059aa6ef7aca6b0c4ec))
* **install:** tolerate absent Windows tasks in stop_supervisor
([#4465](https://github.com/headroomlabs-ai/headroom/issues/4465))
([#4468](https://github.com/headroomlabs-ai/headroom/issues/4468))
([50af2ff](https://github.com/headroomlabs-ai/headroom/commit/50af2ff7a81efb89d6752374a811be4fa2eec6f6))
* **kompress:** keep words past the tokenizer's truncation point
([#4328](https://github.com/headroomlabs-ai/headroom/issues/4328))
([bb13384](https://github.com/headroomlabs-ai/headroom/commit/bb13384829069e7e0559fccf77620891e0c90be0))
* **kompress:** read the pinned snapshot from Python's one HF cache in
the native proxy
([#4438](https://github.com/headroomlabs-ai/headroom/issues/4438))
([eef44f6](https://github.com/headroomlabs-ai/headroom/commit/eef44f60cc56118a0de98455012cc18ff3eaafbd))
* **langgraph:** replace the compressed ToolMessage in graph state
([#4620](https://github.com/headroomlabs-ai/headroom/issues/4620))
([70a8f09](https://github.com/headroomlabs-ai/headroom/commit/70a8f0979e585aa4e9b6f663fa7528340fb4efd6))
* **mcp:** confine headroom_read to the workspace (GHSA-8g49-pg6g-xgrf)
([#4525](https://github.com/headroomlabs-ai/headroom/issues/4525))
([8ab2e91](https://github.com/headroomlabs-ai/headroom/commit/8ab2e914687266f5b602f6d3a78f13026fd5ef88))
* **memory:** bound verb-pattern word runs to stop quadratic
backtracking in bridge import
([#4370](https://github.com/headroomlabs-ai/headroom/issues/4370))
([#4376](https://github.com/headroomlabs-ai/headroom/issues/4376))
([d232d09](https://github.com/headroomlabs-ai/headroom/commit/d232d097cf33d92f3a5112c14a306ba4a80330ee))
* **memory:** fail close unresolved project operations
([#2637](https://github.com/headroomlabs-ai/headroom/issues/2637))
([957ab18](https://github.com/headroomlabs-ai/headroom/commit/957ab1830d73a39ba7662ee9b01dd22c7abd403e))
* **memory:** keep learned evidence until persistence succeeds
([#4229](https://github.com/headroomlabs-ai/headroom/issues/4229))
([662a7f6](https://github.com/headroomlabs-ai/headroom/commit/662a7f6fd836ca87db5f2093c6487b500e8da2eb))
* **memory:** preserve parent scopes when clearing memories
([#4305](https://github.com/headroomlabs-ai/headroom/issues/4305))
([a8375a1](https://github.com/headroomlabs-ai/headroom/commit/a8375a1d26c5fc6dd619bfa7a50a15bbba18acf3))
* **mixed-content:** do not carve ISO-timestamped log rows as search
results
([#4463](https://github.com/headroomlabs-ai/headroom/issues/4463))
([abbade9](https://github.com/headroomlabs-ai/headroom/commit/abbade9b4c761a82f711d0687703d0409fbe6edc))
* **offline:** guard the learn and memory-eval LLM calls under
HEADROOM_OFFLINE
([#4344](https://github.com/headroomlabs-ai/headroom/issues/4344))
([dd361bb](https://github.com/headroomlabs-ai/headroom/commit/dd361bb7a3a1d3f2e3c7572bf544ea4ea895b0a5))
* **openclaw/release:** ship responsive npm integrations
([#1458](https://github.com/headroomlabs-ai/headroom/issues/1458))
([33f2044](https://github.com/headroomlabs-ai/headroom/commit/33f204406cc670588b9a873678b74b4af6ca3620))
* **openclaw:** record turn advancements as one marker file per key
([#4212](https://github.com/headroomlabs-ai/headroom/issues/4212))
([24acbe8](https://github.com/headroomlabs-ai/headroom/commit/24acbe8f32b6d49e3f61097398330e7529729d3e))
* **opencode:** only route POST requests to LLM endpoint paths
([#4464](https://github.com/headroomlabs-ai/headroom/issues/4464))
([336d462](https://github.com/headroomlabs-ai/headroom/commit/336d46225370c946ad8420ecb3f6bac81193e2f7))
* **opencode:** route Copilot Claude models through the proxy
([#4594](https://github.com/headroomlabs-ai/headroom/issues/4594))
([3d9a6f2](https://github.com/headroomlabs-ai/headroom/commit/3d9a6f2cf7fefa2cd0d347521e0050d604a50d22))
* **output-savings:** rewrite a pre-rule ledger once instead of warning
on every /stats poll
([#4196](https://github.com/headroomlabs-ai/headroom/issues/4196))
([96e81ac](https://github.com/headroomlabs-ai/headroom/commit/96e81ac6703dcfcf4535f989319d677775e2384d))
* **packaging:** rename the sandbox extra to lean and correct
SECURITY.md claims
([#3727](https://github.com/headroomlabs-ai/headroom/issues/3727))
([09b7e8c](https://github.com/headroomlabs-ai/headroom/commit/09b7e8c1e41779b4c22f1a4ec941b59a61e621f1))
* **packaging:** use direct CLI module entry point
([#2665](https://github.com/headroomlabs-ai/headroom/issues/2665))
([2892214](https://github.com/headroomlabs-ai/headroom/commit/28922148816b2b6ebf192abfcd6e65db8bb71511))
* **pipeline:** store the pipeline input in CCR behind offload markers
([#4576](https://github.com/headroomlabs-ai/headroom/issues/4576))
([4d7765c](https://github.com/headroomlabs-ai/headroom/commit/4d7765c84b06d1a8630faa32a897a39a40261cd1))
* **pricing:** add Claude Haiku 5.5 rates, 1M context and its 100K
long-prompt card
([#4037](https://github.com/headroomlabs-ai/headroom/issues/4037))
([703755e](https://github.com/headroomlabs-ai/headroom/commit/703755e873d3af74b89d25792c7c9869322b0467))
* **privacy:** turn off Mem0's PostHog telemetry by default
([#4619](https://github.com/headroomlabs-ai/headroom/issues/4619))
([fe69f38](https://github.com/headroomlabs-ai/headroom/commit/fe69f381168035ea6527bb7b908d11eeeb01838f))
* **providers:** isolate resolved Anthropic context limits
([#4593](https://github.com/headroomlabs-ai/headroom/issues/4593))
([51258ef](https://github.com/headroomlabs-ai/headroom/commit/51258ef14a987b2c3137027e0c90f586eb290462))
* **proxy/memory:** harden _extract_tool_calls against malformed choices
and blocks
([#2483](https://github.com/headroomlabs-ai/headroom/issues/2483))
([effa5a5](https://github.com/headroomlabs-ai/headroom/commit/effa5a5886be7e3c5bc553b86da5b506046d461f))
* **proxy:** allow loopback-published container hosts to access
/debug/memory
([#4259](https://github.com/headroomlabs-ai/headroom/issues/4259))
([e546e71](https://github.com/headroomlabs-ai/headroom/commit/e546e71aeb32c355584d37abb61e8d587efce0c3))
* **proxy:** answer /api/hello probes behind the token gate, log
rejection context
([#4150](https://github.com/headroomlabs-ai/headroom/issues/4150))
([673831a](https://github.com/headroomlabs-ai/headroom/commit/673831a456ef0f551de8dc3b2cbb0deae3861c65))
* **proxy:** cap cache_control breakpoints on OpenAI chat path
([#4471](https://github.com/headroomlabs-ai/headroom/issues/4471))
([#4491](https://github.com/headroomlabs-ai/headroom/issues/4491))
([55602fc](https://github.com/headroomlabs-ai/headroom/commit/55602fc1e207e7101917e45bf6dba30ce544558c))
* **proxy:** do not book Gemini countTokens as a request outcome
([#4412](https://github.com/headroomlabs-ai/headroom/issues/4412))
([4d2dd62](https://github.com/headroomlabs-ai/headroom/commit/4d2dd62b7c61724497b4bde33ef8685717f6a682))
* **proxy:** don't fail startup when libc_ver() can't read the
interpreter
([#4519](https://github.com/headroomlabs-ai/headroom/issues/4519))
([28172a9](https://github.com/headroomlabs-ai/headroom/commit/28172a921f4e3945aa43061a9e5cdd0ffd066c0e))
* **proxy:** forward Copilot accounting headers on streaming path
([#4431](https://github.com/headroomlabs-ai/headroom/issues/4431))
([66023a0](https://github.com/headroomlabs-ai/headroom/commit/66023a0187b3260747ece4e99e6932098805442a))
* **proxy:** handle ClientDisconnect in anthropic_messages
([#3532](https://github.com/headroomlabs-ai/headroom/issues/3532))
([251d149](https://github.com/headroomlabs-ai/headroom/commit/251d149a13ae482c1a0843d899b0321e175ac66d))
* **proxy:** honor x-headroom-base-url on provider passthrough routes
([#4596](https://github.com/headroomlabs-ai/headroom/issues/4596))
([5c8772b](https://github.com/headroomlabs-ai/headroom/commit/5c8772b7210caeb291a202a58d4b5e88d51ff35b))
* **proxy:** install SOCKS support for websocket proxies
([#3357](https://github.com/headroomlabs-ai/headroom/issues/3357))
([79181ca](https://github.com/headroomlabs-ai/headroom/commit/79181ca0fe35798b25104ff93b2c3a6c38baa72c))
* **proxy:** keep Gemini memory context on entries with non-text parts
([#4506](https://github.com/headroomlabs-ai/headroom/issues/4506))
([35a2b76](https://github.com/headroomlabs-ai/headroom/commit/35a2b763f09bb147888aeeec69f72d1ed3ae872b))
* **proxy:** keep health probes and the Codex attestation out of the
proxy log
([#4611](https://github.com/headroomlabs-ai/headroom/issues/4611))
([78736a1](https://github.com/headroomlabs-ai/headroom/commit/78736a16bc46ee0bd86b7aae8ef04f7f9cfa9d6d))
* **proxy:** keep read maturation out of the provider-confirmed prefix
([#4522](https://github.com/headroomlabs-ai/headroom/issues/4522))
([526e06b](https://github.com/headroomlabs-ai/headroom/commit/526e06b7e0120820e5b1be44b4ded70698bb86c8))
* **proxy:** keep tool deferral on Copilot
Business/Enterprise/Individual hosts
([#4608](https://github.com/headroomlabs-ai/headroom/issues/4608))
([be456d4](https://github.com/headroomlabs-ai/headroom/commit/be456d4e3f46c7f4dae725c2dd150324000c724f))
* **proxy:** log unknown model ids as one bounded token; skip
unparseable PERF lines
([#4374](https://github.com/headroomlabs-ai/headroom/issues/4374))
([c014bd6](https://github.com/headroomlabs-ai/headroom/commit/c014bd6311742e35c86ef64adfbec88ab264ef28))
* **proxy:** preserve response cache keys across in-place hooks
([#4457](https://github.com/headroomlabs-ai/headroom/issues/4457))
([03590cd](https://github.com/headroomlabs-ai/headroom/commit/03590cd61e17ad1ef313e38a35932f729ff0c871))
* **proxy:** recognise every local spelling of the proxy in the
cc-switch loop guard
([#4405](https://github.com/headroomlabs-ai/headroom/issues/4405))
([d9958bf](https://github.com/headroomlabs-ai/headroom/commit/d9958bfdff047ff2a7ef26f9e29fc7263f790346))
* **proxy:** reconcile Chat content-block cache markers after prefix
replay
([#4333](https://github.com/headroomlabs-ai/headroom/issues/4333))
([35ca9b8](https://github.com/headroomlabs-ai/headroom/commit/35ca9b835616f7923eab23e99e9561a8da452f9f))
* **proxy:** route /v1/models to the x-headroom-base-url upstream
([#4308](https://github.com/headroomlabs-ai/headroom/issues/4308))
([6ef52c2](https://github.com/headroomlabs-ai/headroom/commit/6ef52c2047688e41c7903a0331149a915f20d6b3))
* **proxy:** skip memory-context search in cache mode on OpenAI routes
([#4632](https://github.com/headroomlabs-ai/headroom/issues/4632))
([365f6fe](https://github.com/headroomlabs-ai/headroom/commit/365f6fe5233c4e102584ee4c3e7a140aeccb6a75))
* **proxy:** skip memory-context search on OpenAI paths in cache mode
([#4634](https://github.com/headroomlabs-ai/headroom/issues/4634))
([3654037](https://github.com/headroomlabs-ai/headroom/commit/36540379e0dee0c071e3a3ff00bea9b16eb3902a))
* **proxy:** skip the memory-context search in cache mode
([#4606](https://github.com/headroomlabs-ai/headroom/issues/4606))
([053925b](https://github.com/headroomlabs-ai/headroom/commit/053925b03c6cae028731634f0ad3557518f931d5))
* **proxy:** strip only one leading space from SSE field values
([#4306](https://github.com/headroomlabs-ai/headroom/issues/4306))
([9226eaf](https://github.com/headroomlabs-ai/headroom/commit/9226eaf3852f6d7462ebb95e6d09af3b33eb53c3))
* **proxy:** strip upstream transport framing headers from Gemini
response replays
([#4605](https://github.com/headroomlabs-ai/headroom/issues/4605))
([dfcac78](https://github.com/headroomlabs-ai/headroom/commit/dfcac78119b7038b2e20ad38cead2f4e7fe60c43))
* **read-lifecycle:** keep Reads fresh after a failed Edit or Write
([#4461](https://github.com/headroomlabs-ai/headroom/issues/4461))
([4c3799f](https://github.com/headroomlabs-ai/headroom/commit/4c3799fd81567cd516cdc5c1463f23cea99d6594))
* **relevance:** cap embedding batch size so ORT's arena stays small
([#4507](https://github.com/headroomlabs-ai/headroom/issues/4507))
([a2d4fe7](https://github.com/headroomlabs-ai/headroom/commit/a2d4fe72381e186651466ee94e92ce9d8d1396cc))
* **relevance:** hand the embedding arena back after each run on macOS
([#4567](https://github.com/headroomlabs-ai/headroom/issues/4567))
([2363f83](https://github.com/headroomlabs-ai/headroom/commit/2363f833092052227a9b98a9e21a0b1a69647eab))
* **relevance:** load the Rust default embedder from Python's pinned
snapshot
([#4190](https://github.com/headroomlabs-ai/headroom/issues/4190))
([9bb4b13](https://github.com/headroomlabs-ai/headroom/commit/9bb4b130ff87a2914a8f74dbcc6b49b49c3c87a8))
* **router:** keep small shell results verbatim
([#3590](https://github.com/headroomlabs-ai/headroom/issues/3590))
([#4426](https://github.com/headroomlabs-ai/headroom/issues/4426))
([4ee6164](https://github.com/headroomlabs-ai/headroom/commit/4ee616453fcebed5ab7ce847e1da1016c827a4ed))
* **router:** preserve read protection for quiet sed options
([#4521](https://github.com/headroomlabs-ai/headroom/issues/4521))
([312ffec](https://github.com/headroomlabs-ai/headroom/commit/312ffec8ead5c8c93b8f4c794ca7f588a7b84bd2))
* **router:** validate lossless provider output on the excluded-tool
path ([#4486](https://github.com/headroomlabs-ai/headroom/issues/4486))
([9f068a6](https://github.com/headroomlabs-ai/headroom/commit/9f068a6c135730c1bd4f1d800083f9318a3067a4))
* **scripts:** resolve hooks dir via git so install-git-hooks works in
linked worktrees
([#4176](https://github.com/headroomlabs-ai/headroom/issues/4176))
([0f4275f](https://github.com/headroomlabs-ai/headroom/commit/0f4275f8b331f3db14c41d958c85180a3c70a318))
* **sdk:** carry Vercel AI SDK reasoning parts and provider options
through compression
([#4564](https://github.com/headroomlabs-ai/headroom/issues/4564))
([a26faae](https://github.com/headroomlabs-ai/headroom/commit/a26faaeee34ecfde57608aea4a1ec7ea2b33272f))
* **sdk:** send Anthropic messages to /v1/compress natively so thinking
blocks survive
([#4489](https://github.com/headroomlabs-ai/headroom/issues/4489))
([cd5e2b9](https://github.com/headroomlabs-ai/headroom/commit/cd5e2b9e73eb8bd783ab872bdda71263b941e2d3))
* **security:** lstat before narrowing sqlite files
([#4527](https://github.com/headroomlabs-ai/headroom/issues/4527))
([2cf64ef](https://github.com/headroomlabs-ai/headroom/commit/2cf64ef0cc918c7cdb3de98d56f48fdc9c4c2b4b))
* **smart-crusher:** preserve unchanged JSON bytes
([#4044](https://github.com/headroomlabs-ai/headroom/issues/4044))
([93279f3](https://github.com/headroomlabs-ai/headroom/commit/93279f3208b1afffdbba87c2fdecbeea246d5234))
* **tabular:** keep empty records and separator-like Markdown body rows
([#4582](https://github.com/headroomlabs-ai/headroom/issues/4582))
([5cebb90](https://github.com/headroomlabs-ai/headroom/commit/5cebb90db1f179b00eafdf79568efbc98c8ef366))
* **tabular:** keep interior blank CSV rows instead of dropping them
([#4563](https://github.com/headroomlabs-ai/headroom/issues/4563))
([8c360ca](https://github.com/headroomlabs-ai/headroom/commit/8c360ca69fd3fc9cd6bc1e4b02109c1e5595385c))
* **thinking:** isolate compaction memo by compressor instance
([#4569](https://github.com/headroomlabs-ai/headroom/issues/4569))
([5dcb1e4](https://github.com/headroomlabs-ai/headroom/commit/5dcb1e4adec4f6e82d943488d8aecb8967753e4e))
* **thinking:** leave a thinking block with a null or non-string value
unchanged
([#4562](https://github.com/headroomlabs-ai/headroom/issues/4562))
([cc1eb54](https://github.com/headroomlabs-ai/headroom/commit/cc1eb5402aade58204b96b6b4b4d280cdd5456d2))
* **toin:** preserve stores that exceed the byte limit
([#4589](https://github.com/headroomlabs-ai/headroom/issues/4589))
([f9cae66](https://github.com/headroomlabs-ai/headroom/commit/f9cae66b6b19d6e6acfa4bf6da031642c256404a))
* **toin:** retain pending changes after filesystem save failures
([#4568](https://github.com/headroomlabs-ai/headroom/issues/4568))
([8b15a15](https://github.com/headroomlabs-ai/headroom/commit/8b15a15799898d8c0a396ca0d39f951be4e0cfcf))
* **toin:** skip a malformed pattern instead of aborting the store load
([#4484](https://github.com/headroomlabs-ai/headroom/issues/4484))
([8b628d9](https://github.com/headroomlabs-ai/headroom/commit/8b628d968574053b26849b21e5cea2e2593691c5))
* **tokenizers:** coerce structured text values in message token
counters
([#4472](https://github.com/headroomlabs-ai/headroom/issues/4472))
([6cc27a4](https://github.com/headroomlabs-ai/headroom/commit/6cc27a453d9cf69c76dc8134eb6739891471716e))
* **tokenizers:** don't cache token-count inputs larger than max_chars
([#4469](https://github.com/headroomlabs-ai/headroom/issues/4469))
([aebb729](https://github.com/headroomlabs-ai/headroom/commit/aebb729ef3f03bee8852d067c365f075957638f9))
* **tokenizers:** price Anthropic document blocks by page count, not as
([fc1ba89](https://github.com/headroomlabs-ai/headroom/commit/fc1ba891bff2d1e0cb53c4ffd4037f5066988c8e))
* **tokenizers:** price Anthropic document blocks by page count, not as
base64 text
([#4441](https://github.com/headroomlabs-ai/headroom/issues/4441))
([fc1ba89](https://github.com/headroomlabs-ai/headroom/commit/fc1ba891bff2d1e0cb53c4ffd4037f5066988c8e))
* **tokenizers:** resolve tiktoken encoding for gateway-prefixed model
ids ([#4637](https://github.com/headroomlabs-ai/headroom/issues/4637))
([e9331b6](https://github.com/headroomlabs-ai/headroom/commit/e9331b6b963b5b6554f45943abed2366aaa25ea6))
* **transforms:** enforce role, mutable, and cache zone guards in batch
compression
([#4480](https://github.com/headroomlabs-ai/headroom/issues/4480))
([#4494](https://github.com/headroomlabs-ai/headroom/issues/4494))
([40cd7e7](https://github.com/headroomlabs-ai/headroom/commit/40cd7e7503c66a903ac88e6a090aa0bdac7b315d))
* **transforms:** honour Subscription toin_read_only when the router
calls SmartCrusher
([#4493](https://github.com/headroomlabs-ai/headroom/issues/4493))
([7c11d46](https://github.com/headroomlabs-ai/headroom/commit/7c11d462e6d8265a2cfdb8a1cf62026fb4d1f401))
* **transforms:** preserve YAML block scalar data during comment elision
([#4498](https://github.com/headroomlabs-ai/headroom/issues/4498))
([534cec0](https://github.com/headroomlabs-ai/headroom/commit/534cec0e14db48e787ada13535e0763fc7c52e8e))
* **transforms:** recognise code fences whose info string is not a bare
word ([#4291](https://github.com/headroomlabs-ai/headroom/issues/4291))
([a8df6f9](https://github.com/headroomlabs-ai/headroom/commit/a8df6f919f1c4730971fc2481fd18853ddcfe6b9))
* **transforms:** stop an embedded markdown table from dropping the rest
of a tool result
([#4216](https://github.com/headroomlabs-ai/headroom/issues/4216))
([b66c9c7](https://github.com/headroomlabs-ai/headroom/commit/b66c9c7db6fb7314c366fd2c28866d0ab688f211))
* **transforms:** tolerate malformed assistant tool calls in
ContentRouter.apply
([#4459](https://github.com/headroomlabs-ai/headroom/issues/4459))
([cddd2fd](https://github.com/headroomlabs-ai/headroom/commit/cddd2fd60ed711d7fc1df75b1d5e1cac947ae6c8))
* **update-check:** skip releases with no files and do not fall back to
an uninstallable version
([#4560](https://github.com/headroomlabs-ai/headroom/issues/4560))
([c1dae5a](https://github.com/headroomlabs-ai/headroom/commit/c1dae5adae2b93871314143bba4cb03b7b971e05))
* use all user text blocks for relevance scoring
([#4628](https://github.com/headroomlabs-ai/headroom/issues/4628))
([12dca26](https://github.com/headroomlabs-ai/headroom/commit/12dca26aa11d99b3af6c6d68cdf96ff90ef415aa))
* **wrap:** overwrite drifted selfheal hook command instead of skipping
it ([#2723](https://github.com/headroomlabs-ai/headroom/issues/2723))
([2643f34](https://github.com/headroomlabs-ai/headroom/commit/2643f34a542d944ba3ad4a0a574b5e9e9d9bd474))
* **wrap:** route OMP OpenAI providers through Headroom
([#2755](https://github.com/headroomlabs-ai/headroom/issues/2755))
([fae1e84](https://github.com/headroomlabs-ai/headroom/commit/fae1e849cb59c85cfbd46e76a05e6c299e446b02))


### Dependencies

* Bump @anthropic-ai/sdk from 0.133.0 to 1.3.0 in /sdk/typescript
([#4554](https://github.com/headroomlabs-ai/headroom/issues/4554))
([74277d4](https://github.com/headroomlabs-ai/headroom/commit/74277d47ecfbca349ddb99f81094c4dd30539d43))
* Bump lru from 0.18.5 to 0.19.0
([#4382](https://github.com/headroomlabs-ai/headroom/issues/4382))
([038af59](https://github.com/headroomlabs-ai/headroom/commit/038af599e1a3c5e7e6b3047781aaf9ba2bbbf8bd))
* bump ruff from 0.17.0 to 0.17.2 in the pip-minor-patch group across 1
directory
([#4380](https://github.com/headroomlabs-ai/headroom/issues/4380))
([64f43bd](https://github.com/headroomlabs-ai/headroom/commit/64f43bdf8f2080d5d7c1874fe1572acbb05872b6))
* bump ruff from 0.17.2 to 0.17.3 in the pip-minor-patch group
([#4652](https://github.com/headroomlabs-ai/headroom/issues/4652))
([cb9602a](https://github.com/headroomlabs-ai/headroom/commit/cb9602aef0e4914f723a33ef6bad3a7c06eb485a))
* Bump the cargo-minor-patch group across 1 directory with 12 updates
([#4553](https://github.com/headroomlabs-ai/headroom/issues/4553))
([b9049d7](https://github.com/headroomlabs-ai/headroom/commit/b9049d703af340ff90ed867f86e5fafa10c155c9))
* Bump the npm-minor-patch group across 1 directory with 6 updates
([#4621](https://github.com/headroomlabs-ai/headroom/issues/4621))
([5e4827d](https://github.com/headroomlabs-ai/headroom/commit/5e4827de12c9fdf33d7d36b1939eee73a18fe6c5))
* Bump the npm-minor-patch group across 2 directories with 14 updates
([#4455](https://github.com/headroomlabs-ai/headroom/issues/4455))
([f10725e](https://github.com/headroomlabs-ai/headroom/commit/f10725e6b9940d8bc2fcde950c86f8ac97543cb6))
* Bump the npm-minor-patch group across 3 directories with 9 updates
([#4495](https://github.com/headroomlabs-ai/headroom/issues/4495))
([f367728](https://github.com/headroomlabs-ai/headroom/commit/f36772805178e3fed1a95313e8211c57a291b953))
* Bump tsup from 8.5.1 to 9.0.0 in /plugins/openclaw
([#4384](https://github.com/headroomlabs-ai/headroom/issues/4384))
([9d87151](https://github.com/headroomlabs-ai/headroom/commit/9d871516101ff5428b592acb213aeacd30afc328))
* Bump tsup from 8.5.1 to 9.0.0 in /plugins/opencode
([#4385](https://github.com/headroomlabs-ai/headroom/issues/4385))
([99e223c](https://github.com/headroomlabs-ai/headroom/commit/99e223c0e2c2ea6eb88ce28b160ae179897a9c67))
* Bump tsup from 8.5.1 to 9.0.0 in /sdk/typescript
([#4386](https://github.com/headroomlabs-ai/headroom/issues/4386))
([e666fd8](https://github.com/headroomlabs-ai/headroom/commit/e666fd8e35dbe7c0433739297873b6a0a51c26cf))
* qualify latest Anthropic SDK 1.4.0 in docs
([#4556](https://github.com/headroomlabs-ai/headroom/issues/4556))
([65bcc4c](https://github.com/headroomlabs-ai/headroom/commit/65bcc4c313aadfb609973563573b8bb3f308d81f))
* qualify latest compatible docs and E2E tools
([#4580](https://github.com/headroomlabs-ai/headroom/issues/4580))
([e42f74e](https://github.com/headroomlabs-ai/headroom/commit/e42f74ebc9a784014ad9799b75f862efe4bf69e3))
* require Python 3.11; clear Dependabot alerts in the 3.10 lock fork
([#4517](https://github.com/headroomlabs-ai/headroom/issues/4517))
([3c6f82b](https://github.com/headroomlabs-ai/headroom/commit/3c6f82b06091206379106f8fe1a54f2400ed7a93))
* update tomlkit requirement from &lt;1.0,&gt;=0.15.0 to
&gt;=0.15.2,&lt;1.0
([#4653](https://github.com/headroomlabs-ai/headroom/issues/4653))
([00d5a5c](https://github.com/headroomlabs-ai/headroom/commit/00d5a5ca619f6e23da54d8b7e3fa4cc7af444035))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

### Maintainer current-main requalification

Exact head `0dea0c5acf5a9b00efff4eb4aa5cb4bf44d5d4fe`, upstream main
`ecbaf86d78cf52d185fbffa306157b9a4cc1b906`.

Re-reviewed generated release metadata against current main
ecbaf86d78. The bot-generated release
commit had restored Ruff 0.17.2 while current main, uv.lock and
pre-commit use 0.17.3. Both verify-ruff-version and offline lock checks
reproduced this mechanical mismatch; restored only the current-main
development-tool pin. No release version, contributor runtime logic or
dependency lock versions changed.

All 88 focused release workflow/version/MCP descriptor/Gemini tests
pass. verify-versions reports tracked release metadata aligned at
0.43.0. After the pin correction, verify-ruff-version, uv lock --check
--offline and whitespace checks pass. Generated CHANGELOG was reviewed
without manual edits. Earlier Devin version-metadata finding is
addressed. Formal approval awaits exact-head hosted qualification;
maintainers handle CI. Nothing merged or published as a release.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


Current release-bot head 2a1ebf746b has
the identical tree to the locally verified Ruff correction (including
preserved manifest line endings). Exact-head hosted qualification is in
progress; no release published or PR merged.

---------

Co-authored-by: headroom-release[bot] <352661243+headroom-release[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 10:35:15 -06:00
dependabot[bot]andJerrettDavis cb9602aef0 deps: bump ruff from 0.17.2 to 0.17.3 in the pip-minor-patch group (#4652)
Bumps the pip-minor-patch group with 1 update:
[ruff](https://github.com/astral-sh/ruff).

Updates `ruff` from 0.17.2 to 0.17.3
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/ruff/releases">ruff's
releases</a>.</em></p>
<blockquote>
<h2>0.17.3</h2>
<h2>Release Notes</h2>
<p>Released on 2026-10-26.</p>
<h3>Preview features</h3>
<ul>
<li>[<code>suspicious</code>] Add <code>shared-clock-mock</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29074">#29074</a>)</li>
</ul>
<h3>Bug fixes</h3>
<ul>
<li>[<code>pyupgrade</code>] Avoid incorrect conversions to f-strings
(<code>UP032</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/25485">#25485</a>)</li>
</ul>
<h3>Performance</h3>
<ul>
<li>Buffer stdout in <code>ruff format</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29631">#29631</a>)</li>
<li>Specialize ASCII identifier lexing (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29503">#29503</a>)</li>
<li>Speed up identifier and keyword lexing (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29463">#29463</a>)</li>
</ul>
<h3>Documentation</h3>
<ul>
<li>[<code>flake8-bandit</code>] Describe what the rule actually checks
for <code>httpx</code> (<code>S113</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27936">#27936</a>)</li>
</ul>
<h3>Contributors</h3>
<ul>
<li><a
href="https://github.com/itsvedantkumar"><code>@​itsvedantkumar</code></a></li>
<li><a
href="https://github.com/charliermarsh"><code>@​charliermarsh</code></a></li>
<li><a
href="https://github.com/anishgirianish"><code>@​anishgirianish</code></a></li>
</ul>
<h2>Install ruff 0.17.3</h2>
<h3>Install prebuilt binaries via shell script</h3>
<pre lang="sh"><code>curl --proto '=https' --tlsv1.2 -LsSf
https://releases.astral.sh/github/ruff/releases/download/0.17.3/ruff-installer.sh
| sh
</code></pre>
<h3>Install prebuilt binaries via powershell script</h3>
<pre lang="sh"><code>powershell -ExecutionPolicy Bypass -c &quot;irm
https://releases.astral.sh/github/ruff/releases/download/0.17.3/ruff-installer.ps1
| iex&quot;
</code></pre>
<h2>Download ruff 0.17.3</h2>
<table>
<thead>
<tr>
<th>File</th>
<th>Platform</th>
<th>Checksum</th>
</tr>
</thead>
<tbody>
<tr>
<td><a
href="https://releases.astral.sh/github/ruff/releases/download/0.17.3/ruff-aarch64-apple-darwin.tar.gz">ruff-aarch64-apple-darwin.tar.gz</a></td>
<td>Apple Silicon macOS</td>
<td><a
href="https://releases.astral.sh/github/ruff/releases/download/0.17.3/ruff-aarch64-apple-darwin.tar.gz.sha256">checksum</a></td>
</tr>
<tr>
<td><a
href="https://releases.astral.sh/github/ruff/releases/download/0.17.3/ruff-x86_64-apple-darwin.tar.gz">ruff-x86_64-apple-darwin.tar.gz</a></td>
<td>Intel macOS</td>
<td><a
href="https://releases.astral.sh/github/ruff/releases/download/0.17.3/ruff-x86_64-apple-darwin.tar.gz.sha256">checksum</a></td>
</tr>
<tr>
<td><a
href="https://releases.astral.sh/github/ruff/releases/download/0.17.3/ruff-aarch64-pc-windows-msvc.zip">ruff-aarch64-pc-windows-msvc.zip</a></td>
<td>ARM64 Windows</td>
<td><a
href="https://releases.astral.sh/github/ruff/releases/download/0.17.3/ruff-aarch64-pc-windows-msvc.zip.sha256">checksum</a></td>
</tr>
</tbody>
</table>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md">ruff's
changelog</a>.</em></p>
<blockquote>
<h2>0.17.3</h2>
<p>Released on 2026-10-26.</p>
<h3>Preview features</h3>
<ul>
<li>[<code>suspicious</code>] Add <code>shared-clock-mock</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29074">#29074</a>)</li>
</ul>
<h3>Bug fixes</h3>
<ul>
<li>[<code>pyupgrade</code>] Avoid incorrect conversions to f-strings
(<code>UP032</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/25485">#25485</a>)</li>
</ul>
<h3>Performance</h3>
<ul>
<li>Buffer stdout in <code>ruff format</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29631">#29631</a>)</li>
<li>Specialize ASCII identifier lexing (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29503">#29503</a>)</li>
<li>Speed up identifier and keyword lexing (<a
href="https://redirect.github.com/astral-sh/ruff/pull/29463">#29463</a>)</li>
</ul>
<h3>Documentation</h3>
<ul>
<li>[<code>flake8-bandit</code>] Describe what the rule actually checks
for <code>httpx</code> (<code>S113</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27936">#27936</a>)</li>
</ul>
<h3>Contributors</h3>
<ul>
<li><a
href="https://github.com/itsvedantkumar"><code>@​itsvedantkumar</code></a></li>
<li><a
href="https://github.com/charliermarsh"><code>@​charliermarsh</code></a></li>
<li><a
href="https://github.com/anishgirianish"><code>@​anishgirianish</code></a></li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/astral-sh/ruff/commit/ba65abf8ba7bfbcc059f7fb9712be5ba9cab6abc"><code>ba65abf</code></a>
Bump version to 0.17.3 (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29745">#29745</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/fb2f9218793e3b0e979175d43d88dcac791e92d6"><code>fb2f921</code></a>
[ty] Fix narrowing of strings and integers compared with enum members
(<a
href="https://redirect.github.com/astral-sh/ruff/issues/29743">#29743</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/d1812878d5f81af6f5810d193ebc44413d1b21cc"><code>d181287</code></a>
[ty] Index nominal union alternatives (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29196">#29196</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/07872adbafa7c00f42f1174d8aa3c3e324033009"><code>07872ad</code></a>
[ty] Preserve string literals in comparisons with
<code>LiteralString</code> (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29741">#29741</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/95888b2edfaa34d0159732856b1466cf53b33e64"><code>95888b2</code></a>
[ty] Preserve narrowing after guarded match subject captures (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29558">#29558</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/3c8166b683805aa89557b0739f5b9918ad58ea6d"><code>3c8166b</code></a>
[ty] Fix hang when negating recursive unions of instance types (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29652">#29652</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/3fd20e08598ac345b8afd524d3f7086456e4e758"><code>3fd20e0</code></a>
[ty] Preserve generic callback specializations during return refinement
(<a
href="https://redirect.github.com/astral-sh/ruff/issues/29667">#29667</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/2f0a29ece1f1a539c65c0671c04c76bb886219fe"><code>2f0a29e</code></a>
[ty] Record predicate truthiness alongside expression inference (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29706">#29706</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/60f104a1a2ec4e980198ff54c38ba6fe7045b29f"><code>60f104a</code></a>
[ty] Honor <a
href="https://github.com/override"><code>@​override</code></a> on
overload implementations in stubs (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29470">#29470</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/207ec3affeb118fce03a65f9333959157e228312"><code>207ec3a</code></a>
[ty] Add diagnostic baseline support (<a
href="https://redirect.github.com/astral-sh/ruff/issues/27636">#27636</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/astral-sh/ruff/compare/0.17.2...0.17.3">compare
view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=ruff&package-manager=pip&previous-version=0.17.2&new-version=0.17.3)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions


</details>
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4652"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

### Dependency justification and maintainer qualification

Ruff remains the existing Astral-maintained developer tool from the
official astral-sh/ruff project. The official release notes and upstream
correction were reviewed. PyPI metadata reports no runtime Python
dependencies and Python >=3.7; platform wheels contain the existing
native Rust executable, so this is still a native developer-tool
download rather than a new production runtime dependency. Source builds
require the upstream Rust/build toolchain and may fetch build
dependencies; wheel retrieval/pre-commit bootstrap uses configured
registries as before. Neither the demonstrated lint/autofix execution
nor formatting requires a provider/network connection after
installation. PyPI reports no listed vulnerabilities for this release at
review time, not a comprehensive security audit. The package/project
identity is unchanged and upstream maintenance continues.

The selected patch fixes a demonstrated unsafe UP032 autofix: for a
format-string lookup of dictionary string key "+1", Ruff 0.17.2 rewrites
it as integer key 1 and changes the executed output from expected to
wrong. Ruff 0.17.3 preserves the string key and prints expected. The
exact external tool and Python execution reproducer is included below;
this is not a claim that this particular expression exists in Headroom.
It justifies avoiding a known incorrect conversion in the project
lint/autofix tool. All three Ruff execution paths now align at 0.17.3
(dev pin, scoped generated lock, pre-commit revision). The version
verifier and uv 0.13.6 lock --check pass; full repository lint passes
and all 1,893 files are already formatted under the new tool. Shared
Gemini request-fixture tests pass (10 cases); their test-only repair
addresses independently verified main failures. No contributor
production logic was changed.

### Real behavior proof

Windows, Python 3.12, actual Ruff 0.17.2 and 0.17.3 executables obtained
through uvx, real temporary files and post-autofix Python execution.
Save the program below and run `python ruff_runtime.py`; replace its
owned scratch root and Python executable paths for another environment.
Both invocations select UP032 explicitly and use --isolated so the
comparison is independent of global configuration. Full-repository
lint/format checks separately use the project configuration. This does
not qualify every Ruff rule, every platform, or every autofix input.

<details><summary>Reproduction program</summary>

```python
import json
from pathlib import Path
import subprocess
import tempfile

owned=Path('G:/git/headroom/.codex').resolve()
source='d = {"+1": "expected", 1: "wrong"}\nresult = "{0[+1]}".format(d)\nprint(result)\n'
observed=[]
with tempfile.TemporaryDirectory(prefix='pr4652-ruff-runtime-',dir=owned) as directory:
    root=Path(directory).resolve();assert root.is_relative_to(owned)
    for version in ('0.17.2','0.17.3'):
        path=root/f'sample_{version.replace(".","_")}.py'
        path.write_text(source,encoding='utf-8',newline='\n')
        fix=subprocess.run(['uvx','--from','ruff=='+version,'ruff','check','--isolated','--select','UP032','--fix',str(path)],capture_output=True,text=True,encoding='utf-8',creationflags=subprocess.CREATE_NO_WINDOW)
        assert fix.returncode==0,(version,fix.stdout,fix.stderr)
        run=subprocess.run(['G:/git/headroom/.venv/Scripts/python.exe',str(path)],capture_output=True,text=True,encoding='utf-8',creationflags=subprocess.CREATE_NO_WINDOW)
        assert run.returncode==0,run.stderr
        observed.append({'ruff':version,'fixed_source':path.read_text(encoding='utf-8'),'output':run.stdout.strip()})
    assert observed[1]['output']=='expected'
    print(json.dumps({'input':source,'observed':observed},indent=2))

```
</details>

<details><summary>Observed executable output</summary>

```json
{
  "input": "d = {\"+1\": \"expected\", 1: \"wrong\"}\nresult = \"{0[+1]}\".format(d)\nprint(result)\n",
  "observed": [
    {
      "ruff": "0.17.2",
      "fixed_source": "d = {\"+1\": \"expected\", 1: \"wrong\"}\nresult = f\"{d[1]}\"\nprint(result)\n",
      "output": "wrong"
    },
    {
      "ruff": "0.17.3",
      "fixed_source": "d = {\"+1\": \"expected\", 1: \"wrong\"}\nresult = f\"{d['+1']}\"\nprint(result)\n",
      "output": "expected"
    }
  ]
}

```
</details>

Exact-head hosted CI is pending; current upstream main
e4a60ed72f is included. Nothing merged.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 07:30:11 -06:00
dependabot[bot]andJerrettDavis 00d5a5ca61 deps: update tomlkit requirement from <1.0,>=0.15.0 to >=0.15.2,<1.0 (#4653)
Updates the requirements on
[tomlkit](https://github.com/python-poetry/tomlkit) to permit the latest
version.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/python-poetry/tomlkit/releases">tomlkit's
releases</a>.</em></p>
<blockquote>
<h2>0.15.2</h2>
<h2>What's Changed</h2>
<ul>
<li>Fix inline table separator after append by <a
href="https://github.com/cyliu0"><code>@​cyliu0</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/477">python-poetry/tomlkit#477</a></li>
<li>chore(deps): bump idna from 3.7 to 3.15 in /docs by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/481">python-poetry/tomlkit#481</a></li>
<li>chore(deps-dev): bump idna from 3.7 to 3.15 by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/480">python-poetry/tomlkit#480</a></li>
<li>chore(deps): bump urllib3 from 2.5.0 to 2.7.0 in /docs by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/475">python-poetry/tomlkit#475</a></li>
<li>[pre-commit.ci] pre-commit autoupdate by <a
href="https://github.com/pre-commit-ci"><code>@​pre-commit-ci</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/478">python-poetry/tomlkit#478</a></li>
<li>[pre-commit.ci] pre-commit autoupdate by <a
href="https://github.com/pre-commit-ci"><code>@​pre-commit-ci</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/484">python-poetry/tomlkit#484</a></li>
<li>Fix duplicated comma when removing a middle inline table element by
<a
href="https://github.com/sarathfrancis90"><code>@​sarathfrancis90</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/486">python-poetry/tomlkit#486</a></li>
<li>Add native <strong>contains</strong> to Container, Table and
InlineTable by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/487">python-poetry/tomlkit#487</a></li>
<li>Make Source index-based instead of materializing a char list by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/489">python-poetry/tomlkit#489</a></li>
<li>reject surrogate code points in \U unicode escapes by <a
href="https://github.com/netliomax25-code"><code>@​netliomax25-code</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/493">python-poetry/tomlkit#493</a></li>
<li>[pre-commit.ci] pre-commit autoupdate by <a
href="https://github.com/pre-commit-ci"><code>@​pre-commit-ci</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/496">python-poetry/tomlkit#496</a></li>
<li>Scan character runs in bulk while parsing by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/490">python-poetry/tomlkit#490</a></li>
<li>Fix doubled comma when inserting into a comma-first array by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/499">python-poetry/tomlkit#499</a></li>
<li>reject tab characters in bare keys by <a
href="https://github.com/netliomax25-code"><code>@​netliomax25-code</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/497">python-poetry/tomlkit#497</a></li>
<li>reject non-hex digits in \u and \U escapes by <a
href="https://github.com/netliomax25-code"><code>@​netliomax25-code</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/501">python-poetry/tomlkit#501</a></li>
<li>Bulk-scan single-line string bodies by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/491">python-poetry/tomlkit#491</a></li>
<li>Remove the internal TOMLChar wrapper by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/492">python-poetry/tomlkit#492</a></li>
<li>Fix corrupt output when adding to a dotted key inside an inline
table by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/500">python-poetry/tomlkit#500</a></li>
<li>Compare StringType members by identity instead of building a set by
<a href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/502">python-poetry/tomlkit#502</a></li>
<li>Merge super tables in place instead of deep-copying on every merge
by <a href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/503">python-poetry/tomlkit#503</a></li>
<li>Move a value replacing a table out of the table region by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/506">python-poetry/tomlkit#506</a></li>
<li>Restore dumps() delegating to as_string for non-Mapping wrappers by
<a href="https://github.com/binggao1230"><code>@​binggao1230</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/508">python-poetry/tomlkit#508</a></li>
<li>Limit parser nesting depth instead of crashing with RecursionError
by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/510">python-poetry/tomlkit#510</a></li>
<li>Prefix every line of a multiline comment with # by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/511">python-poetry/tomlkit#511</a></li>
<li>Add a native OutOfOrderTableProxy.<strong>contains</strong> by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/515">python-poetry/tomlkit#515</a></li>
<li>Place inline-table separator after the value, not a trailing comment
(fix <a
href="https://redirect.github.com/python-poetry/tomlkit/issues/512">#512</a>)
by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/514">python-poetry/tomlkit#514</a></li>
<li>reject a table redefined after its parent table header by <a
href="https://github.com/netliomax25-code"><code>@​netliomax25-code</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/516">python-poetry/tomlkit#516</a></li>
<li>Don't build a discarded error when an array closes right after a
value by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/517">python-poetry/tomlkit#517</a></li>
<li>Validate out-of-order tables incrementally while parsing by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/509">python-poetry/tomlkit#509</a></li>
<li>Return a single key from key() for a single-element list (fixes <a
href="https://redirect.github.com/python-poetry/tomlkit/issues/430">#430</a>)
by <a
href="https://github.com/tienvantranspk-tech"><code>@​tienvantranspk-tech</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/520">python-poetry/tomlkit#520</a></li>
<li>[pre-commit.ci] pre-commit autoupdate by <a
href="https://github.com/pre-commit-ci"><code>@​pre-commit-ci</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/522">python-poetry/tomlkit#522</a></li>
<li>Speed up unwrap() by resolving keys from the key map instead of
items() by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/521">python-poetry/tomlkit#521</a></li>
<li>Merge AoT fragments when building an out-of-order table proxy by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/507">python-poetry/tomlkit#507</a></li>
<li>Bulk-scan multiline string bodies by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/518">python-poetry/tomlkit#518</a></li>
<li>reject array-of-tables header missing its second closing bracket by
<a
href="https://github.com/netliomax25-code"><code>@​netliomax25-code</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/519">python-poetry/tomlkit#519</a></li>
<li>[pre-commit.ci] pre-commit autoupdate by <a
href="https://github.com/pre-commit-ci"><code>@​pre-commit-ci</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/541">python-poetry/tomlkit#541</a></li>
<li>Fix ParseError when a sub-table extends an array of tables out of
order by <a
href="https://github.com/sarathfrancis90"><code>@​sarathfrancis90</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/498">python-poetry/tomlkit#498</a></li>
<li>Render inline tables in O(n) instead of O(n²) by <a
href="https://github.com/tfoutrein"><code>@​tfoutrein</code></a> in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/525">python-poetry/tomlkit#525</a></li>
<li>Fix duplicated prefix and captured sibling when replacing a dotted
key with a table by <a
href="https://github.com/Labib-Bin-Salam"><code>@​Labib-Bin-Salam</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/526">python-poetry/tomlkit#526</a></li>
<li>Reject tables inserted into inline tables by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/532">python-poetry/tomlkit#532</a></li>
<li>raise on malformed array element instead of dropping it by <a
href="https://github.com/netliomax25-code"><code>@​netliomax25-code</code></a>
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/527">python-poetry/tomlkit#527</a></li>
<li>fix: reject out-of-order concrete+super table redefinitions at parse
time by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/530">python-poetry/tomlkit#530</a></li>
<li>fix: keep newline after dotted inline table by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/533">python-poetry/tomlkit#533</a></li>
<li>[pre-commit.ci] pre-commit autoupdate by <a
href="https://github.com/pre-commit-ci"><code>@​pre-commit-ci</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/548">python-poetry/tomlkit#548</a></li>
<li>chore(deps): bump soupsieve from 2.5 to 2.8.4 in /docs by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/560">python-poetry/tomlkit#560</a></li>
<li>chore(deps-dev): bump soupsieve from 2.4.1 to 2.8.4 by <a
href="https://github.com/dependabot"><code>@​dependabot</code></a>[bot]
in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/559">python-poetry/tomlkit#559</a></li>
<li>Preserve whitespace when replacing super tables by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/534">python-poetry/tomlkit#534</a></li>
<li>Preserve table display names on self assignment by <a
href="https://github.com/binggao1230"><code>@​binggao1230</code></a> in
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/537">python-poetry/tomlkit#537</a></li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/python-poetry/tomlkit/blob/master/CHANGELOG.md">tomlkit's
changelog</a>.</em></p>
<blockquote>
<h2>[0.15.2] - 2026-10-16</h2>
<h3>Changed</h3>
<ul>
<li>Write the ESC control character as <code>\^[</code> instead of
<code>\e</code>, which is only valid in TOML 1.1, so the output stays
readable by TOML 1.0 parsers such as <code>tomllib</code>. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/641">#641</a>)</li>
<li><code>key_value()</code> now raises <code>UnexpectedCharError</code>
on anything other than whitespace or a comment after the pair, instead
of silently discarding it (e.g. <code>key_value(&quot;a = 1 b =
2&quot;)</code>), matching <code>parse()</code>. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/594">#594</a>)</li>
<li><code>integer()</code> given a string now validates it against the
TOML integer grammar and keeps the original text, so grouping
underscores (e.g. <code>integer(&quot;1_000&quot;)</code>) survive
<code>dumps()</code>; strings that are not valid TOML integers (e.g.
<code>&quot;010&quot;</code>) now raise <code>ValueError</code>. (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/336">#336</a>)</li>
<li>Add a <code>fold</code> argument to <code>DateTime</code> and
<code>Time</code>, mirroring the stdlib, and carry <code>fold</code>
through <code>item()</code>, arithmetic (including datetime subtraction)
and <code>unwrap()</code>, so a folded local time no longer converts an
hour off. (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/619">#619</a>,
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/623">#623</a>,
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/626">#626</a>)</li>
<li>Declare the project metadata in the PEP 621 <code>[project]</code>
table; building from source now requires
<code>poetry-core&gt;=2.2.0</code>. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/607">#607</a>,
<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/609">#609</a>)</li>
</ul>
<h3>Fixed</h3>
<ul>
<li>Fix invalid output after deleting the last key under a dotted key
inside an inline table; the emptied table now renders as <code>b =
{}</code>. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/664">#664</a>)</li>
<li>Fix valid TOML being rejected when an out-of-order table reopens an
implicit super-table with a dotted key: <code>[a.b.c]</code> then
<code>[a]</code> with <code>b.z = 1</code> extends the implicit
<code>a.b</code> super-table rather than redefining it (stdlib
<code>tomllib</code> accepts it), so it now parses and round-trips
instead of raising <code>Redefinition of an existing table</code>. The
concrete-table case (<code>[a.b]</code> then <code>[a]</code> <code>b.z
= 1</code>) stays rejected. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/565">#565</a>)</li>
<li>Fix uppercase <code>E</code> exponent after a leading-zero mantissa
(e.g. <code>0E2</code>) being rejected as an invalid number while
<code>0e2</code> parsed fine. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/586">#586</a>)</li>
<li>Fix non-lowercase special floats (e.g. <code>Inf</code>,
<code>NaN</code>, <code>-INF</code>) being accepted; TOML only allows
lowercase <code>inf</code> and <code>nan</code>, so they now raise
<code>ParseError</code>. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/628">#628</a>)</li>
<li>Fix parse errors reporting the wrong line and column in documents
with CRLF or mixed line endings. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/642">#642</a>)</li>
<li>Fix <code>item()</code> reordering the keys of an inline table
(dict-valued keys were forced last) under the default
<code>sort_keys=False</code>. (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/546">#546</a>)</li>
<li>Fix <code>unwrap()</code> moving a key to the end after its value
was replaced (e.g. <code>doc[&quot;b&quot;] = 9</code>), while
<code>dumps()</code> and <code>keys()</code> kept the original order.
(<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/591">#591</a>)</li>
<li>Fix appending a key to a parsed inline table that uses <code>&quot;,
&quot;</code> separators emitting a bare <code>&quot;,&quot;</code> for
the new entry, leaving the table inconsistently spaced (e.g. <code>{x =
1, y = 2,z = 3}</code>). (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/595">#595</a>)</li>
<li>Fix an emptied array of tables being dropped from the output: it now
renders as <code>key = []</code>, placed and keyed relative to the
nearest table header so it parses back into the same table. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/567">#567</a>)</li>
<li>Fix a single-line array whose last element is a trailing comment
(e.g. from <code>add_line(value, comment=...)</code>) rendering its
closing <code>]</code> on the comment line, producing unparseable
output. (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/580">#580</a>)</li>
<li>Fix <code>del array[start:stop:step]</code> with a negative or
omitted bound removing the wrong elements from the rendered output. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/599">#599</a>)</li>
<li>Fix array slice assignment mutating the array before raising
<code>ValueError(&quot;slice assignment is not supported&quot;)</code>.
(<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/600">#600</a>)</li>
<li>Fix <code>String.__add__</code> splicing the appended text into a
basic string without escaping it, so appending a quote or backslash
produced invalid TOML. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/612">#612</a>)</li>
<li>Fix a bare carriage return in a multiline string producing invalid
TOML: it is now escaped as <code>\r</code> in a multiline basic string
and rejected with <code>InvalidStringError</code> in a multiline literal
string; CRLF line endings are left intact. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/539">#539</a>)</li>
<li>Fix a tz-aware <code>datetime.time</code> rendering with a UTC
offset (e.g. <code>07:32:00+02:00</code>), which TOML local times do not
allow; it now renders as a local time. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/613">#613</a>)</li>
<li>Fix arithmetic on a signed float producing <code>+-0.0</code> (e.g.
<code>-1.5</code> times <code>0</code>), which does not parse. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/629">#629</a>)</li>
<li>Fix two <code>Bool</code> items never comparing equal to each other;
they now compare by value. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/660">#660</a>)</li>
</ul>
<h2>[0.15.1] - 2026-07-17</h2>
<h3>Changed</h3>
<ul>
<li>Speed up membership tests (<code>key in ...</code>) on
<code>Container</code>, <code>Table</code> and <code>InlineTable</code>
with native <code>__contains__</code> implementations, avoiding the
inherited <code>MutableMapping</code> round-trip through
<code>__getitem__</code> (which resolves the value and builds an
exception on every absent key). (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/483">#483</a>)</li>
<li>Speed up parsing by making <code>Source</code> index-based: it now
tracks an integer position over the input string instead of
materializing a list of <code>(index, char)</code> tuples up front, so
construction is O(1) and state save/restore no longer copies an
iterator. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/489">#489</a>)</li>
<li>Speed up parsing by scanning character runs in bulk:
<code>Source.advance_while</code>/<code>advance_until</code> consume a
whole run of whitespace, bare-key or number characters in a single pass
over the input string instead of one <code>inc()</code> call per
character. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/490">#490</a>)</li>
<li>Speed up parsing of single-line strings by bulk-appending the run of
ordinary characters up to the next delimiter, backslash or control
character in one pass, instead of one character at a time. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/491">#491</a>)</li>
<li>Speed up parsing by removing the internal <code>TOMLChar</code>
wrapper: the parser now reads plain <code>str</code> characters from
<code>Source</code> and detects end-of-input positionally, avoiding a
per-character object construction and method dispatch. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/492">#492</a>)</li>
<li>Speed up parsing by comparing <code>StringType</code> members by
identity (<code>is</code>) instead of building a set on every
<code>is_basic</code>/<code>is_literal</code>/<code>is_singleline</code>/<code>is_multiline</code>
call, avoiding millions of enum hashes while parsing. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/502">#502</a>)</li>
<li>Speed up merging super tables by merging in place instead of
deep-copying the growing target on every merge, turning the parse of
documents with many subtables under a shared super table (e.g.
consecutive <code>[a.b.c]</code> / <code>[a.b.d]</code> headers) from
O(n²) into O(n). (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/503">#503</a>)</li>
<li>Speed up membership tests (<code>key in ...</code>) on out-of-order
tables with a native <code>OutOfOrderTableProxy.__contains__</code>,
completing <a
href="https://redirect.github.com/python-poetry/tomlkit/issues/483">#483</a>
for the last mapping type that still inherited the slow
<code>MutableMapping</code> mixin (which resolves the value and builds
an exception on every absent key). (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/515">#515</a>)</li>
<li>Speed up parsing documents with many dotted keys or table headers
sharing a prefix by validating out-of-order tables incrementally: each
new fragment is merged into a cached validation container once, instead
of re-merging (and deep-copying) every earlier fragment on each append,
turning a super-cubic worst case into linear time (80 shared-prefix
dotted keys: ~8 s → ~10 ms). (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/479">#479</a>)</li>
<li>Speed up parsing of arrays that close right after a value (e.g. the
<code>files = [...]</code> blocks that dominate lock files): the parser
no longer attempts to read a value while sitting on the closing
<code>]</code>, which previously built an
<code>UnexpectedCharError</code> just to discard it — and constructing
that exception eagerly computes a line/column by scanning the whole
document, making it O(document size) per such array. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/517">#517</a>)</li>
<li>Speed up parsing of multiline strings by bulk-appending the run of
ordinary characters — across raw line feeds and tabs — up to the next
delimiter, backslash, carriage return or control character, instead of
one character at a time. This extends to
<code>&quot;&quot;&quot;</code>/<code>'''</code> bodies the single-line
fast path added in <a
href="https://redirect.github.com/python-poetry/tomlkit/pull/491">#491</a>;
a <code>\r</code> still stops the scan so <code>\r\n</code> stays
validated and byte-for-byte preserved. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/518">#518</a>)</li>
<li>Speed up <code>unwrap()</code> (converting a parsed document to a
plain <code>dict</code>) by resolving each key directly from the
container's key map instead of iterating the inherited
<code>MutableMapping</code> view, which rebuilt a <code>SingleKey</code>
from the bare string for every key just to re-look-up the value.
Out-of-order tables still resolve through their proxy, so their
validation is unchanged. (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/521">#521</a>)</li>
<li>Speed up rendering (<code>as_string()</code> / <code>dumps()</code>)
of inline tables with many keys by precomputing the last-key and
last-deleted-element indices in a single pass, instead of rescanning the
remaining body on every separator comma — turning an O(n²) render into
O(n). (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/525">#525</a>)</li>
<li>Raise on malformed array element instead of dropping it, (<a
href="https://redirect.github.com/python-poetry/tomlkit/pull/527">#527</a>)</li>
</ul>
<h3>Fixed</h3>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/a0b15ebb09167ede584fc36ad5362fc3039b0530"><code>a0b15eb</code></a>
chore: release 0.15.2 (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/668">#668</a>)</li>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/18e7f98252f18db5c973435453cd25e1c7bd4c61"><code>18e7f98</code></a>
Compare Bool items by value (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/660">#660</a>)</li>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/19edc23b0244e1546abbf3b7890c3d8a0deeaf81"><code>19edc23</code></a>
[pre-commit.ci] pre-commit autoupdate (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/654">#654</a>)</li>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/6b5f079099d4bd77b442f4fae96a10790ba3d55c"><code>6b5f079</code></a>
Render an emptied array of tables as an empty array (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/567">#567</a>)</li>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/229ee8660872df482a56c93c83b14ac98fedf864"><code>229ee86</code></a>
fix: don't reject an out-of-order super-table extended by a dotted key
(<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/565">#565</a>)</li>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/096148f8947adbfbae7b36bce356a3da7fc1dbf1"><code>096148f</code></a>
escape or reject a bare carriage return in multiline strings (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/539">#539</a>)</li>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/5fe4329fee7943d2376104e5977f3e3baa6d6abd"><code>5fe4329</code></a>
test: add coverage for tomlkit._types wrapper operators (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/570">#570</a>)</li>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/2279e18aacb8504a3d153ea623ad6f3edcf15cfe"><code>2279e18</code></a>
Enable intersphinx so stdlib references resolve (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/624">#624</a>)</li>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/a963fe16d67afaa5293a2c21cfaf9bba666d5647"><code>a963fe1</code></a>
Preserve inline table key order in item() (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/546">#546</a>)
(<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/552">#552</a>)</li>
<li><a
href="https://github.com/python-poetry/tomlkit/commit/446d6fab132ef38a2ec052a5b2124e04b427dea6"><code>446d6fa</code></a>
Reject non-lowercase special float literals (<a
href="https://redirect.github.com/python-poetry/tomlkit/issues/628">#628</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/python-poetry/tomlkit/compare/0.15.0...0.15.2">compare
view</a></li>
</ul>
</details>
<br />


Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)


</details>
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4653"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

### Dependency justification and maintainer qualification

tomlkit remains the existing python-poetry parser used for
loss-minimizing configuration recovery. This official project release
supplies the inline-table serialization fixes reproduced below; the
minimum is needed to exclude known-broken versions for these supported
recovery inputs. The official PyPI metadata identifies the same
python-poetry/tomlkit repository, Python >=3.9, no runtime dependencies,
and a universal py3-none-any wheel. No new native compiler/runtime or
network dependency is added by that wheel. Source installations use the
upstream poetry-core>=2.2.0 build backend and may fetch build
dependencies from the configured index; the offline recovery path itself
makes no provider/network call. PyPI lists no reported vulnerabilities
for this release at review time; this is metadata evidence, not a
comprehensive security audit. Upstream release history and release notes
show continuing maintenance; no change of dependency project is
proposed.

The new minimum fixes demonstrated Headroom config corruption: public
recover_codex_home() with tomlkit 0.15.0 produces invalid TOML when
merging dotted keys in inline tables and when removing a managed
Headroom provider from the middle of an inline table. With 0.15.2 both
cases serialize valid TOML and preserve intended values; a third
comment-preservation control passes on both versions. Production
recovery source is identical to current upstream main; the comparison
changes only the installed tomlkit version. All 53 focused
recovery/config/Gemini tests pass, with two platform skips. The scoped
generated lock updates only the tomlkit package and its root
requirement; uv 0.13.6 lock --check passes and frozen export selects
tomlkit==0.15.2. The additional shared Gemini streamed-request fixture
repair is test-only and addresses independently verified main failures.
No contributor production logic was changed.

### Real behavior proof

Windows, Python 3.12, isolated checkout at
`65bfda5fc658a399b23ededcb7c02502ebb56fa7`, real temporary source/target
Codex homes, no mocks or live Codex account. Install tomlkit 0.15.2 into
a separate directory (`uv pip install --target
ABSOLUTE_DEPENDENCY_DIRECTORY tomlkit==0.15.2`), save the program below,
then run `python recovery_runtime.py ABSOLUTE_CHECKOUT_PATH
ABSOLUTE_DEPENDENCY_DIRECTORY`. Replace its owned scratch-root path with
an existing local scratch directory if needed. The baseline run uses the
same recovery source with tomlkit 0.15.0 and omits the third argument.
Every passing case checks backup creation and unchanged source config.
This qualifies real filesystem recovery/serialization; live Codex,
provider authentication, macOS/Linux recovery permissions, and every
TOML form are not claimed.

<details><summary>Reproduction program</summary>

```python
import importlib.metadata
import json
import os
from pathlib import Path
import sys
import tempfile
import tomllib

sys.stdout.reconfigure(encoding='utf-8')
sys.path.insert(0,sys.argv[1])
if len(sys.argv)>2:
    sys.path.insert(0,sys.argv[2])
import tomlkit
from headroom.providers.codex.recovery import recover_codex_home

owned=Path('G:/git/headroom/.codex').resolve()
cases=[
    ('inline_merge','profiles = {work.model = "old"}\n','profiles = {work.extra = "kept", work.model = "new"}\n'),
    ('remove_managed_middle','model_provider = "headroom"\nmodel_providers = {company = {base_url = "https://company.test/v1"}, headroom = {base_url = "http://127.0.0.1:8787/v1"}, other = {base_url = "https://other.test/v1"}}\n','preferences = {color = "green"}\n'),
    ('preserve_comments','# user-owned config\nmodel = "old" # model choice\n[profiles.work]\nmodel = "work-old"\n','model = "new"\n[profiles.work]\nmodel = "work-new"\nextra = "retained"\n'),
]
results=[]
with tempfile.TemporaryDirectory(prefix='pr4653-runtime-',dir=owned) as directory:
    root=Path(directory).resolve();assert root.is_relative_to(owned)
    for name,target_text,source_text in cases:
        source=root/name/'source';target=root/name/'target'
        source.mkdir(parents=True);target.mkdir()
        (source/'config.toml').write_text(source_text,encoding='utf-8',newline='\n')
        (target/'config.toml').write_text(target_text,encoding='utf-8',newline='\n')
        os.utime(target/'config.toml',(1700000000,1700000000))
        os.utime(source/'config.toml',(1700000010,1700000010))
        try:
            report=recover_codex_home(source=source,target=target)
            output=(target/'config.toml').read_text(encoding='utf-8')
            parsed=tomllib.loads(output)
            assert (source/'config.toml').read_text(encoding='utf-8')==source_text
            assert report.backup_dir.is_dir()
            if name=='inline_merge':assert parsed['profiles']['work']=={'model':'new','extra':'kept'}
            if name=='remove_managed_middle':
                assert 'headroom' not in parsed['model_providers']
                assert parsed['model_providers']['company']['base_url']=='https://company.test/v1'
                assert parsed['model_providers']['other']['base_url']=='https://other.test/v1'
            if name=='preserve_comments':
                assert '# user-owned config' in output and '# model choice' in output
                assert parsed['model']=='new' and parsed['profiles']['work']=={'model':'work-new','extra':'retained'}
            results.append({'case':name,'ok':True,'serialized':output,'backup_created':True,'source_unchanged':True})
        except Exception as exc:
            results.append({'case':name,'ok':False,'error':str(exc),'error_type':type(exc).__name__})
    print(json.dumps({'tomlkit':tomlkit.__version__,'source':sys.argv[1],'results':results},indent=2))

```
</details>

<details><summary>Observed tomlkit 0.15.2</summary>

```json
{
  "tomlkit": "0.15.2",
  "source": "G:/git/headroom-review4653",
  "results": [
    {
      "case": "inline_merge",
      "ok": true,
      "serialized": "profiles = {work.model = \"new\", work.extra = \"kept\"}\n",
      "backup_created": true,
      "source_unchanged": true
    },
    {
      "case": "remove_managed_middle",
      "ok": true,
      "serialized": "model_providers = {company = {base_url = \"https://company.test/v1\"},  other = {base_url = \"https://other.test/v1\"}}\npreferences = {color = \"green\"}\n",
      "backup_created": true,
      "source_unchanged": true
    },
    {
      "case": "preserve_comments",
      "ok": true,
      "serialized": "# user-owned config\nmodel = \"new\" # model choice\n[profiles.work]\nmodel = \"work-new\"\nextra = \"retained\"\n",
      "backup_created": true,
      "source_unchanged": true
    }
  ]
}

```
</details>

<details><summary>Observed tomlkit 0.15.0 control</summary>

```json
{
  "tomlkit": "0.15.0",
  "source": "G:/git/headroom-review4653",
  "results": [
    {
      "case": "inline_merge",
      "ok": false,
      "error": "Unclosed inline table (at line 1, column 31)",
      "error_type": "TOMLDecodeError"
    },
    {
      "case": "remove_managed_middle",
      "ok": false,
      "error": "Invalid initial character for a key part (at line 1, column 70)",
      "error_type": "TOMLDecodeError"
    },
    {
      "case": "preserve_comments",
      "ok": true,
      "serialized": "# user-owned config\nmodel = \"new\" # model choice\n[profiles.work]\nmodel = \"work-new\"\nextra = \"retained\"\n",
      "backup_created": true,
      "source_unchanged": true
    }
  ]
}

```
</details>

Exact-head hosted CI is pending; current upstream main
e4a60ed72f is included. Nothing merged.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 07:29:02 -06:00
ee2252a315 feat(mcp)!: port MCP servers to SDK 2.x (#4603)
## Description

Supersedes #2658 (`tejas/mcp-2x-port`, a draft with conflicts against
`main` since 2026-10-20). This is that PR's net diff rebased onto `main`
as one commit (originally `fc1ba891`, now `7e0094d6`; see below),
crediting Tejas Chopra and Jerrett Davis as co-authors, with three
changes needed on current `main`. Both MCP servers
(`headroom/ccr/mcp_server.py`, `headroom/memory/mcp_server.py`) move
from SDK 1's decorator API to SDK 2's constructor callbacks, as #2658
did. The `<2.0.0` cap from #2642 is then lifted.

Why now: current Claude Code tries the modern `server/discover`
handshake first. On SDK 1, `headroom mcp serve` rejects it and logs
`Failed to validate request: 31 validation errors for ClientRequest` on
stderr in every session. Claude Code then falls back to legacy
`initialize`, so the tools still work. On SDK 2 the modern handshake
succeeds and nothing is logged.

Changes relative to #2658:

1. **The floor is `mcp>=2.2.0,<3.0.0`, not `>=2.0.0`.** The GitHub
advisories mark `mcp` `>=2.0.0, <2.2.0` as affected by CVE-2026-59951
(the reason for #4239's `>=1.30.0` floor), CVE-2026-116684,
CVE-2026-116685 and CVE-2026-116686. #2658's lock resolved 2.1.1. The
contract test keeps `main`'s CVE guard for the 2.x line and rejects 3.x
(see #2977).
2. **`tests/test_ccr_mcp_http.py` is ported.** #1773 added it after
#2658 branched, and it fails on SDK 2: `streamable_http_client` now
takes an `httpx2.AsyncClient`, yields `(read, write)` without the
session-id getter, and its types are snake_case (`protocol_version`).
`headroom/ccr/mcp_http.py` itself needs no change.
3. **The lock is regenerated** with uv 0.9.30 (`uv lock
--upgrade-package mcp`, still `revision = 3`).

**Rebased onto main (`7e0094d6`), 2026-11-03.** The branch is now two
linear commits, with no merge commits:

- `ce4d6442` feat(mcp)!: port MCP servers to SDK 2.x (was `39c574c2`)
- `274f0672` fix(mcp): attribute SDK 2 clients by client_info, not
clientInfo (was `c7900848`)

The previous head was the merge `4c1b774f` (main `5c785e69` into the
branch), which carried the resolution against #4525
(GHSA-8g49-pg6g-xgrf, confining `headroom_read` to the workspace). The
rebase replays the port directly on top of #4525 instead. What it
changed:

- `headroom/ccr/mcp_server.py` conflicted with #4525 in two places: the
imports (#4525's `errno` next to the port's `contextvars`) and the tool
list, where #4525's workspace-scoped `headroom_read` schema met the
port's move from the `@list_tools` decorator to `_on_list_tools`. The
resolved file keeps both: SDK 2 callbacks and #4525's confinement and
`HEADROOM_MCP_READ_ROOTS` description. It is byte-identical to the file
in the previous merge head `4c1b774f`.
- `uv.lock` conflicted in one hunk with #4614's `mem0ai` bump: kept this
PR's `mcp>=2.2.0,<3.0.0` for the `mcp` and `proxy` extras and #4614's
`mem0ai>=2.0.18,<3.0`. `uv lock --check` resolves 253 packages.
- Every other file this PR touches is unchanged from `4c1b774f`. The
only difference in `pyproject.toml` and `uv.lock` against the previous
head is #4614's own diff, line for line.

The Strands blocker from the July review no longer applies:
`strands-agents` 1.63.0 declares `mcp<2.4,>=1.23.0`, and the lock
resolves `mcp` 2.3.0 with it.

Dependency justification (CONTRIBUTING, new dep or version bump):

| Package | Change | Source |
|---|---|---|
| `mcp` | 1.30.0 → 2.3.0 | modelcontextprotocol/python-sdk |
| `mcp-types` | new, 2.3.0 | same SDK; `mcp` 2.3.0 pins it `==2.3.0` |
| `httpx2`, `httpcore2` | new, 2.16.0 | pydantic/httpx2 (Tom Christie);
SDK 2's HTTP client |
| `httpx2-jsfetch` | new, 1.0 | only on `sys_platform == 'emscripten'`;
not installed elsewhere |
| `strands-agents` | 1.62.0 → 1.63.0 | first release that accepts `mcp`
2.2+ |
| `httpx-sse` | removed | SDK 1 only |
| `idna` | 3.15 → 3.20 | required by `httpx2` |

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/ccr/mcp_server.py`, `headroom/memory/mcp_server.py`:
register handlers as `on_list_tools` / `on_call_tool` constructor
callbacks, return `ListToolsResult` / `CallToolResult`, and read the
request context from the callback argument. These are #2658's changes,
including Jerrett's memory-backend cleanup hook.
- `pyproject.toml`: `mcp>=2.2.0,<3.0.0` in the `proxy` and `mcp` extras.
- `uv.lock`: relocked as described above.
- `tests/test_mcp_dependency_contract.py`: both extras must admit 2.2.0
and reject 1.30.0, 2.1.1 and 3.0.0.
- `tests/test_mcp_sdk2_contract.py`, `tests/_mcp_stub.py`,
`tests/test_mcp_stub.py`, `tests/test_memory/test_mcp_server.py`: from
#2658.
- `tests/test_ccr_mcp_http.py`: ported to the SDK 2 client. It reads the
session id from the `mcp-session-id` response header.
- `headroom/ccr/mcp_server.py` `_current_client`: read `client_info`
(SDK 2) instead of `clientInfo` (SDK 1), so `headroom_compress` savings
events name the client again. `tests/test_mcp_sdk2_contract.py` now
builds the SDK's own `InitializeRequestParams`; its old stand-in used
`clientInfo` and stayed green while every client was recorded as
`unknown`. Before and after, with an SDK 2.3 client named
`attribution-probe` over stdio: the ledger recorded `unknown` on both
`server/discover` and `initialize`, and now records `attribution-probe`
on both (found by Devin's review).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

After the rebase, on `274f0672`:

```text
# Python 3.11.17, mcp 2.3.0, strands-agents 1.63.0
$ pytest -q tests/test_mcp_dependency_contract.py tests/test_mcp_sdk2_contract.py tests/test_mcp_stub.py \
    tests/test_ccr_mcp_http.py tests/test_memory/test_mcp_server.py \
    <every test module that references mcp_server, GHSA or HEADROOM_MCP_READ_ROOTS, incl. tests/test_ccr_mcp_server.py>
840 passed, 2 skipped
$ uv lock --check
Resolved 253 packages
$ ruff check && ruff format --check on every changed .py file (ruff 0.17.2); git diff --check origin/main
clean
```

The wider 40-file mcp/strands run below was not repeated after the
rebase.

Before the rebase:

```text
# Python 3.11.17, uv sync --frozen --extra mcp --extra strands --extra proxy --extra otel (mcp 2.3.0, strands-agents 1.63.0)
$ pytest -q <every test module that references mcp, strands or the MCP servers: 40 files>
1163 passed, 31 skipped
$ pytest -q tests/test_ccr_mcp_http.py tests/test_mcp_dependency_contract.py tests/test_mcp_sdk2_contract.py
9 passed
$ pytest -q tests/integrations/test_strands tests/test_strands_tokenizer.py
80 passed, 25 skipped
$ uv run --with uv==0.9.30 python -m uv lock --check
Resolved 253 packages
$ ruff check && ruff format --check on every changed .py file (ruff 0.16.8); git diff --check origin/main
clean
# [all] export against the union of the extras it includes: no package missing
```

## Real Behavior Proof

- Environment: macOS 27 (arm64), Python 3.11.17; `main` `fc1ba891` (SDK
1.30.0) and this branch (SDK 2.3.0); temporary `HOME`; plus this branch
merged into my local runtime branch and installed as the `headroom` uv
tool.
- Exact command / steps: an SDK 2.3 stdio client starts `headroom mcp
serve`, calls `ClientSession.discover()` (`server/discover`, as Claude
Code does first), falls back to `initialize()` if that is rejected, then
lists tools and calls `headroom_stats`. The server's stderr is captured.
- Observed result: on `main`, `server/discover` is rejected with -32602
and the legacy `initialize` is used; stderr has 94 lines, starting
`WARNING: Failed to validate request: 31 validation errors for
ClientRequest`; 3 tools are listed and the call succeeds. On this branch
the modern `server/discover` is accepted and stderr has 0 lines; 3 tools
are listed and the call succeeds. The installed build behaves the same.
- Not tested: Windows; the memory MCP server against a live client (unit
and contract tests only); Strands agents against a live MCP server
(`tests/integrations/test_strands` and
`tests/test_strands_tokenizer.py`: 80 passed, 25 skipped); a real
network client against the Streamable HTTP transport (the ASGI contract
test only).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a, dependency and server API change
- Stable/default behavior changed: yes; the MCP servers require SDK 2.2+
and speak the modern handshake; the tools and their JSON results are
unchanged
- Kill switch / disable path: none; pin `headroom-ai` to the previous
release to stay on SDK 1
- Unsafe override required: no
- Qualification impact: environments that pin `mcp<2` alongside
`headroom-ai[mcp]` or `[proxy]` no longer resolve
- Rollback path: revert this commit, which restores the `<2.0.0` cap

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Proposed on #2658
(https://github.com/headroomlabs-ai/headroom/pull/2658#issuecomment-6562744017).
If maintainers would rather keep #2658, `ce4d6442` and `274f0672`
(previously `39c574c2` and `c7900848`) can be cherry-picked onto
`tejas/mcp-2x-port` instead, and I'll close this.

`mypy headroom/ccr/mcp_server.py headroom/memory/mcp_server.py
headroom/ccr/mcp_http.py` with SDK 2.3 installed reports one error, in
`headroom/providers/model_metadata.py:79`, which `main` reports too;
none in the changed files. Full `mypy headroom` was not run. No docs
change: the MCP tool names, arguments and results are unchanged.

---------

Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-04 08:46:49 -06:00
2892214881 fix(packaging): use direct CLI module entry point (#2665)
## Description

Corrects the packaged `headroom` console-script entry point so it loads
the concrete Click command from `headroom.cli.main:main` instead of
relying on the package-level `headroom.cli:main` re-export.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Updated `[project.scripts] headroom` in `pyproject.toml` from
`headroom.cli:main` to `headroom.cli.main:main`.

## Testing

- [x] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`) - not needed for this
metadata-only packaging target change
- [ ] Type checking passes (`mypy headroom`) - not needed for this
metadata-only packaging target change
- [ ] New tests added for new functionality - not applicable; this
points the existing console script at the existing CLI command
- [x] Manual testing performed

### Test Output

```text
.\.venv\Scripts\python.exe -c "from importlib.metadata import EntryPoint; ep=EntryPoint(name='headroom', value='headroom.cli.main:main', group='console_scripts'); obj=ep.load(); import click; assert isinstance(obj, click.core.Command); print(obj.name)"
main

.\.venv\Scripts\python.exe -m headroom.cli --help
# exited successfully

.\.venv\Scripts\python.exe -m pytest tests/test_cli/test_main_help_version.py -q
5 passed
```

## Real Behavior Proof

- Environment: Windows checkout using the repository `.venv`.
- Exact command / steps: Loaded the proposed console-script entry point
with `importlib.metadata.EntryPoint`, verified it resolves to a Click
command, checked `python -m headroom.cli --help`, and ran the focused
CLI help/version tests.
- Observed result: `headroom.cli.main:main` resolves successfully to the
CLI command, module help still works, and the focused CLI tests pass.
- Not tested: rebuilding and installing a wheel from this branch; GitHub
package checks have not run because only governance checks are currently
present on the PR.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- not applicable for this one-line entry-point change
- [ ] I have made corresponding changes to the documentation - not
applicable; user-facing CLI behavior is unchanged
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works - existing CLI tests cover the command surface
- [x] New and existing relevant tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Screenshots (if applicable)

N/A - packaging entry-point change only.

## Additional Notes

This PR changes only the console-script target in `pyproject.toml`; it
does not change CLI behavior or command implementation.
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/2665"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
Co-authored-by: jd <jd@headroomlabs.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-11-04 08:27:36 -06:00
a5e68deb64 docs(pypi): job-word summary and keywords, and a PyPI-specific README (#4534)
## Description

Agents that install from PyPI read the package page plus the installed
code and nothing else; in both recorded runs they had to read venv
source to learn the result fields and `HEADROOM_OFFLINE`. The GitHub
README is written for a browser: hero image, badges, perk banner,
relative links that break off GitHub, and a first install command that
pulls `[all]`. The summary ("Cut costs by 50-90%") disagrees with the
README's own measured table, and none of the words in the three web
queries that currently return nothing of ours (tool outputs, chat
history, token cost, fastapi) appear in the summary or keywords.

Depends on #4529 for the `/docs/fastapi` link. Takes effect on PyPI with
the next release.

## Type of Change

- [x] Documentation update

## Changes Made

- `README-pypi.md` (new): no-key `compress()` path, zero-network check
with expected output, result fields, offline semantics (beacon is
proxy/MCP-side), coding-agent path, extras explained, "the PyPI
distribution named `headroom` is a different project".
- `pyproject.toml`: `readme = "README-pypi.md"`, job-word `description`
without a percentage, keywords extended with the job words.
- `Dockerfile`, `e2e/wrap/Dockerfile`, `e2e/init/Dockerfile`: `COPY` the
new readme next to `README.md` (all three build the wheel from
`pyproject.toml`, so maturin needs the declared readme in the build
context); `Dockerfile`'s `source_digest` inputs include it too.

## Testing

- [x] Manual testing performed

### Test Output

```text
uvx maturin sdist -o /tmp/sdist: Built source distribution headroom_ai-0.42.0.tar.gz
tar tzf: headroom_ai-0.42.0/README-pypi.md present
PKG-INFO: Summary: Compress tool outputs, logs, JSON and chat history before each LLM call. ... / Description-Content-Type: text/markdown
```

## Real Behavior Proof

- Environment: macOS arm64, `uvx maturin sdist` on this branch.
- Exact command / steps: build the sdist, list it, read `PKG-INFO`.
- Observed result: `headroom_ai-0.42.0/README-pypi.md` is in the
tarball; `PKG-INFO` has the new `Summary:`, `Description-Content-Type:
text/markdown`, the README body and the new keywords. The one-liner in
the file was run against the published 0.42.0 wheel: `20031 -> 95 FATAL
kept: True`.
- Not tested: the Docker images themselves (CI's docker and e2e jobs
cover them); the wheel build (maturin embeds the same `readme` field;
nothing in `.github/workflows` or `scripts/` pins `README.md` as the
readme).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; documentation and metadata only, no
runtime code path changes
- Minimum rollout channel: n/a
- Stable/default behavior changed: no
- Kill switch / disable path: n/a (revert the PR)
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

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

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-03 23:37:58 -06:00
9bb4b130ff fix(relevance): load the Rust default embedder from Python's pinned snapshot (#4190)
## Description

Parent status: #4152 has merged. The pinned-loader and batch-cap merge
resolution was reviewed at e3a495cbc5. The
original split/stack history is retained below.

**Rebased onto main (`7e0094d6`), 2026-11-03.** The branch is now four
linear commits on top of main, with no merge commits:

- `bfae4ade` fix(relevance): load the Rust default embedder from
Python's pinned snapshot
- `6fbae380` fix(relevance): look up and download the Rust embedder in
one HF cache dir
- `70afece8` fix(relevance): expand ~ and $VAR in the Rust HF cache path
like huggingface_hub
- `62b792f0` fix(relevance): keep an empty HF cache variable, as
huggingface_hub does

What the rebase changed:

- The #4152 commit (`cb1c3a33`) is gone from the branch: main already
has it as `f380692b`. Its files matched main; the only difference was
`uv.lock`, where main's later `filelock>=4.2.1` entry was kept.
- The six main-sync merges (`185dc9b7`, `052977b9`, `029c72ac`,
`4405b12c`, `8b0a10e8`, and the reviewed `e3a495cb`) are linearized
away, so those SHAs are no longer on the branch.
- `embedding.rs` conflicted again with main's batch-size cap (#4507). I
resolved it to the same content as the reviewed merge: every file this
PR touches is byte-identical between `e3a495cb` and the new head
`62b792f0` (`git diff e3a495cb 62b792f0 -- <files changed vs main>` is
empty). The review and qualification below still apply to the content;
only the history and SHAs changed.

Rust `EmbeddingScorer::try_new` used `EmbeddingModel::BGESmallENV15`.
fastembed-rs maps that to a different repo and file from what Python
runs: `Xenova/bge-small-en-v1.5` `onnx/model.onnx` (fp32), always on
`main`. So the two languages never ran the same ONNX file, and the
"byte-equal across languages" claim in both modules was wrong.

This PR makes `try_new` load the same pinned
`Qdrant/bge-small-en-v1.5-onnx-Q` snapshot that #4152 makes Python load.
It adds a cross-language parity fixture checked from both sides, and
replaces the parity claim with measured numbers.

Nothing in production calls `EmbeddingScorer::try_new` today:
`create_scorer` and `HybridScorer` use `default()`, which never loads a
model. This keeps the Rust scorer correct and pinned for when it is
wired in.

No linked issue.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

(This PR's own commits only.)

- `crates/headroom-core/src/relevance/embedding.rs`:
- `try_new` loads the snapshot through
`TextEmbedding::try_new_from_user_defined`, with CLS pooling and static
quantization, which is what fastembed-rs uses for `BGESmallENV15Q`.
- It uses exactly one hub cache directory, resolved like Python's
`huggingface_hub.constants.HF_HUB_CACHE`: `HF_HUB_CACHE` →
`HUGGINGFACE_HUB_CACHE` → `HF_HOME/hub` →
`XDG_CACHE_HOME/huggingface/hub` → `~/.cache/huggingface/hub`, with a
leading `~` expanded. It looks up and downloads only there, so a stale
snapshot in a lower-priority cache is never used. The home directory
comes from `std::env::home_dir`, which falls back to the user database
when `HOME` is unset, as Python's `expanduser` does.
- It finds the snapshot as `snapshots/<sha>` in that directory.
`hf_hub::Cache` resolves through `refs/<rev>`, which Python's
`huggingface_hub` doesn't write for a commit SHA.
- On a miss it downloads with `Repo::with_revision`. `guard_egress` sits
in front of the Hub client and runs only on a cache miss, so a
pre-seeded air-gapped host now loads; previously Rust refused even with
a warm cache.
- `HEADROOM_HF_PIN=off` floats it on `main`, with the same values as
Python's `_resolve_revision`.
  - `try_new_with_model` is unchanged.
- Parity fixture: `tests/parity/record_embedding.py` and
`tests/parity/fixtures/embedding/bge_small_en_v15_pinned.json` (6 texts
× 384 dims, recorded on ORT 1.31.0). The fixture is written one
embedding row per line, so it's 22 lines. Python checks it in CI
(`test-extras` sets `RUN_FASTEMBED_TESTS=1`); Rust checks it under
`RUN_FASTEMBED_TESTS=1`.
- `tests/test_fastembed_pinned_snapshot.py`: the Rust constants name the
same repo, SHA and files as Python; the fixture was recorded at the pin;
plus the gated Python parity check.
- 10 new Rust unit tests in `embedding.rs`: the lookup ignores other
commits and needs every file; the download URL requests the pinned
revision; the offline guard applies on a miss only;
`HEADROOM_HF_PIN=off` floats; the cache directory follows
`huggingface_hub`'s order variable by variable (including an empty
variable and `~`); with no `HOME` it still resolves through the user
database; and the review case: an empty explicit `HF_HUB_CACHE` next to
a complete pinned snapshot and an older `refs/main` under `HOME` finds
neither, for the pinned revision or `main`, while both are found once
`HF_HUB_CACHE` is unset.
- `tests/test_offline_egress_chokepoint.py`: the Rust sweep's regex now
also matches `ApiBuilder::from_cache` / `from_env`. It missed the new
download client, which is guarded; it flags nothing else in `crates/`.
The user-defined model load, which only reads bytes already on disk, is
allowlisted as `cache-only`.
- Docs: the "byte-equal" wording in both embedder modules,
`pyproject.toml` and `onnx_runtime.py` is replaced with measured numbers
and the cross-language keep-equal notes.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

After the rebase, on `62b792f0` (macOS arm64, no `ORT_DYLIB_PATH`, so
the gated model tests skip):

```text
$ cargo test -p headroom-core --lib
test result: ok. 991 passed; 0 failed; 1 ignored
$ cargo clippy -p headroom-core --all-targets -- -D warnings                  # clean
$ cargo clippy -p headroom-core --lib --no-default-features -- -D warnings    # clean
$ cargo fmt --all -- --check                                                  # clean
$ pytest -q tests/test_fastembed_pinned_snapshot.py tests/test_offline_egress_chokepoint.py tests/test_hf_revision_pinning.py
235 passed, 3 skipped
$ ruff check / ruff format --check on the PR's Python files (ruff 0.17.2)     # clean
```

The 7 offline-egress failures noted below no longer reproduce here.

Before the rebase:

```text
$ cargo test -p headroom-core --lib
test result: ok. 985 passed; 0 failed; 1 ignored      # see the note on #4151 below

$ cargo clippy -p headroom-core --all-targets -- -D warnings                  # clean
$ cargo clippy -p headroom-core --lib --no-default-features -- -D warnings    # clean
$ cargo fmt --all -- --check                                                  # clean

$ RUN_FASTEMBED_TESTS=1 ORT_DYLIB_PATH=<onnxruntime 1.31.0 dylib> cargo test -p headroom-core --lib relevance::embedding
test relevance::embedding::tests::fastembed_matches_parity_fixture ... ok
test result: ok. 24 passed; 0 failed

$ RUN_FASTEMBED_TESTS=1 pytest -q tests/test_fastembed_pinned_snapshot.py tests/test_relevance.py \
    tests/test_stateless_writers.py tests/test_hf_revision_pinning.py
71 passed

$ pytest -q tests/test_offline_egress_chokepoint.py
7 failed, 132 passed, 3 skipped
# The 7 are the OTel / Langfuse / Headroom Cloud offline tests, whose extras aren't in this venv;
# the same 7 fail on origin/main here. The Rust sweep tests pass.
```

**Note on #4151:** with `ORT_DYLIB_PATH` set on macOS, a full `cargo
test -p headroom-core --lib` fails
`tokenizer::hf_impl::tests::from_pretrained_invalid_repo_returns_hub_error`
most of the time (5/5 on `afdb60d3`, before the cache change too).
`a_cached_snapshot_is_not_refused_offline` holds `HEADROOM_OFFLINE=1`
under the env lock while ONNX Runtime loads, which is slow there, and
the tokenizer test reads the variable without the lock. That's the race
#4151 fixes; with its commit applied, 6/6 full runs pass. Linux CI
passes either way.

The cache-precedence test was checked against the bug: with the lookup
changed back to also scanning `~/.cache`, it fails on the first case
(pinned revision, empty `HF_HUB_CACHE`).

## Real Behavior Proof
- Exact command / steps: additional maintainer verification on the
main-synced head: cargo test -p headroom-core --locked hf_hub_cache_dir;
cargo test -p headroom-core --locked
expand_vars_matches_python_posixpath_and_ntpath; python -m pytest
tests/test_fastembed_pinned_snapshot.py -q; repeat its fixture cases
with huggingface-hub==2.2.0.
- Observed result: three Rust tests passed across both POSIX and Windows
expansion fixtures and cache-directory selection; Python passed 46 tests
with one gated skip using Hugging Face Hub 1.16.1, and all 36 shared
fixture cases passed separately with locked Hub 2.2.0.

- Environment: macOS arm64; Rust fastembed 5.17.3 with hf-hub 0.5.0;
repo `.venv` (fastembed 0.8.0, onnxruntime 1.23.2) and a second
interpreter on onnxruntime 1.31.0.
- A cold-cache Rust load with `HF_HUB_CACHE=<empty dir>` wrote
`snapshots/52398278…` plus `refs/52398278…` and passed the parity check.
Per-component max |Δ| against the fixture:
  - Rust vs Python on the same ORT (1.31.0): ≤ 1e-6.
  - Python on ORT 1.23.2 vs 1.31.0: ≤ 4.1e-4.
  - The fixture's tolerance is 1e-3.
- For reference, Xenova's fp32 export (what Rust used to load) is ≤
4.7e-4 from the fixture. The old cross-language gap was real but
numerically small, and this fixture bounds drift; it cannot tell the two
exports apart. Model identity is enforced by the pinned SHA and the unit
tests.
- The fixture's new one-row-per-line layout was re-emitted from the
recorded data, not re-recorded: the parsed JSON is identical.
- Not tested: Windows, and Linux outside CI. Rust's gated tests in CI
(they need the model and an ORT dylib, so they stay manual behind
`RUN_FASTEMBED_TESTS=1`). Rust `HybridScorer` thresholds against the
Qdrant export.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: no production path.
`EmbeddingScorer::try_new` loads the Qdrant export instead of Xenova's,
and now loads offline from a warm cache instead of refusing, but nothing
in production calls it today.
- Kill switch / disable path: `HEADROOM_HF_PIN=off` floats it on `main`.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert this PR.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A.

## Additional Notes

- Follow-ups, not in this PR: Rust's Kompress and tokenizer Hub fetches
are still unpinned (there's no Rust `HEADROOM_HF_PIN`), and Rust's gated
embedding tests could get a CI job once one ships an ORT dylib.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4190"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

## Maintainer qualification

The environment-reference mismatch from the previous review is
addressed. The shared corpus covers the reported explicit-cache case,
platform-specific variable syntax, and the two-stage home/hub expansion
ordering. The Rust test runs both POSIX and Windows expansion rules;
Python validates the same corpus against posixpath, ntpath, and fresh
huggingface_hub.constants imports.

A clean current-main sync was published as
052977b9e88ae3bbda96797615b64ee350a2f695; it does not change the
contributor's resolver or fixture files. Qualification used Windows,
Hugging Face Hub 1.16.1 and an isolated locked 2.2.0 target. No model
download or numerical embedding-parity result is claimed by these path
tests; the pre-existing gated numerical-parity test remained skipped.

Hosted checks on the pushed head must finish before approval. No
contributor CI action requested or PR merged.

---------

Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-03 21:31:59 -06:00
Tejas ChopraandClaude Opus 5.5 7e0094d6c8 fix(deps): bump mem0ai, langgraph and langgraph-sdk past open advisories (#4614)
## Description

Clears Dependabot alerts #546, #547 and #548, which Vanta's dependency
vulnerability test flags.

| Package | Before | After | Advisory |
|---|---|---|---|
| mem0ai | 2.0.18 | 2.2.1 | GHSA-5324-3w58-qpp2 (fixed in 2.0.18) |
| langgraph | 1.2.11 | 1.2.19 | GHSA-3fx2-cqw9-xr3c (fixed in 1.2.14) |
| langgraph-sdk | 0.4.6 | 0.4.11 | GHSA-3fx2-cqw9-xr3c (fixed in 0.4.6)
|

#4537 (Dependabot) has since moved `main` to mem0ai 2.0.18,
langgraph-sdk 0.4.6 and posthog 7.79.0, and fixed `Mem0Backend`'s
identity filters. Merged on top of that, this PR still bumps langgraph
past GHSA-3fx2-cqw9-xr3c (1.2.11 → 1.2.19, plus langgraph-checkpoint
4.2.0 → 4.3.1), raises the install-time floors, passes `top_k` to
`Mem0Backend.search`, and fixes `DirectMem0Adapter`, which #4537 did not
touch. posthog stays at 7.79.0. No package is added or removed from the
lock.

The runtime proof below found that Headroom's Mem0 search was already
broken on `main`. Mem0 2.x (including the 2.0.5 we locked) raises
`ValueError` when `user_id` is passed at the top level of `search()` /
`get_all()`. So the second commit fixes the call sites. Without it, the
upgrade could not be shown to work.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `uv lock --upgrade-package mem0ai --upgrade-package langgraph
--upgrade-package langgraph-sdk`
- `pyproject.toml`: floors raised to `mem0ai>=2.0.18` (memory-stack
extra) and `langgraph>=1.2.14` (langgraph extra), so a fresh PyPI
install can't resolve a vulnerable version. `langgraph-sdk>=0.4.6` comes
transitively from langgraph 1.2.14+.
- `headroom/memory/backends/direct_mem0.py`, `mem0.py`: pass `user_id`
inside `filters=` and the limit as `top_k=` to Mem0 `search()` /
`get_all()`. Direct Qdrant writes also store the fact under `data`, the
payload key Mem0 search reads. Points without it were skipped.

## Dependency review (CONTRIBUTING.md)

| | mem0ai 2.2.1 | langgraph 1.2.19 / sdk 0.4.11 / checkpoint 4.3.1 |
posthog 7.79.0 |
|---|---|---|---|
| Why this package | Already a dependency of the optional `memory-stack`
extra | Already a dependency of the optional `langgraph` extra | Not
ours: required by mem0ai |
| Who maintains it | Mem0 (Apache-2.0); 8 releases in the last 90 days,
latest 2026-09-25 | LangChain (MIT); 9 langgraph releases in 90 days,
latest 2026-10-30 | PostHog (MIT); very frequent releases (107 in 90
days) |
| Security history | GHSA-5324-3w58-qpp2 fixed in 2.0.18; PyPI lists no
advisories against 2.2.1 | GHSA-3fx2-cqw9-xr3c fixed in 1.2.14 / sdk
0.4.6; none against the locked versions | None listed against 7.79.0 |
| Native code | None (pure-Python wheel) | None (pure-Python wheels) |
None (pure-Python wheel) |
| Install-time network | None beyond the package index | None | None |
| Runtime network | OpenAI (LLM + embeddings) and Qdrant/Neo4j, as
configured. Also anonymous telemetry to `https://us.i.posthog.com`, on
by default unless `MEM0_TELEMETRY=False` (same as 2.0.5, see below) |
None for graph execution; `langgraph-sdk` only talks to a LangGraph
server if a client is created (Headroom does not) | Used only by mem0
telemetry |
| Why this version | Security patch | Security patch | Pulled by the
mem0 security patch |

Lock: the `python-socks` line that now appears under `lean` is uv
flattening the existing `proxy` extra that `lean` already includes. `uv
lock --check` passes on `main`, and the set of resolved packages is
unchanged (only the five versions above differ).

## Testing

- [x] Unit tests pass: `pytest tests/test_memory
tests/test_integrations/langchain/test_langgraph.py
tests/integrations/test_langgraph.py` → 676 passed
- [x] Linting passes: `ruff check` and `ruff format --check` on the
touched paths
- [x] Type checking: `mypy headroom/memory/backends` reports 8 errors at
`direct_mem0.py:202`, identical on `main` (not from this change)
- [x] New test: `test_search_scopes_by_user_through_filters` fails on
`main` (`search` called with top-level `user_id`/`limit`), passes here
- [x] Manual testing performed (below)

## Real Behavior Proof

**Environment:** macOS arm64, Python 3.12.13, uv 0.12.5. Qdrant 1.15.5
in Docker (`qdrant/qdrant:v1.15.5` on 127.0.0.1:16333). Real `mem0ai
2.2.1`, `qdrant-client 1.17.1`, `posthog 7.79.0` (rerun after merging
`main`). The OpenAI API is replaced by a local OpenAI-compatible stub
(`OPENAI_BASE_URL=http://127.0.0.1:18099/v1`) that returns deterministic
bag-of-words embeddings and a canned extraction. So Mem0, Qdrant and
Headroom code are real, and the LLM is not.

**Mem0 round trip through Headroom** (`DirectMem0Adapter` and
`Mem0Backend`, graph disabled):

```text
optimized save: Memory id ok                          # facts written straight to Qdrant
optimized search top: The billing service is written in Rust 0.802
other user sees: 0                                     # user scoping holds
fallback (Mem0 LLM extraction) save: Memory
fallback search top: The deploy region is eu-west-1
delete: True get after delete: None
Mem0Backend save: True
Mem0Backend search top: The deploy region is eu-west-1
Mem0Backend search other user: 0
Mem0Backend get_all_memories: ['The deploy region is eu-west-1']
```

Before the second commit, the same script failed on the first search
with `ValueError: Top-level entity parameters frozenset({'user_id'}) are
not supported in search()`. Unpacking mem0ai 2.0.5 and calling
`search(user_id=..., limit=...)` raises the same error, so this was
broken on `main` too. Once the call was fixed, search returned `[]`
until facts were also written under `data`.

**LangGraph invocation** (`StateGraph` agent → tool →
`create_compress_tool_messages_node()` → model, `InMemorySaver`
checkpointer) on langgraph 1.2.19 / checkpoint 4.3.1:

```text
final: done | checkpoint resumed messages: 5
tool chars before: 30690 after compress node: 17933
```

**Pre/post dependency resolution** (`uv pip compile` of the extra's
requirement with a vulnerable pin as a constraint):

```text
pre   mem0ai>=2.0.0,<3.0     + mem0ai==2.0.17     => resolves
pre   langgraph>=1.0,<2.0    + langgraph==1.2.13  => resolves
post  mem0ai>=2.0.18,<3.0    + mem0ai==2.0.17     => rejected (Because you require mem0ai>=2.0.18,<3.0 and mem0ai==2.0.17 ...)
post  langgraph>=1.2.14,<2.0 + langgraph==1.2.13  => rejected (Because you require langgraph>=1.2.14,<2.0 and langgraph==1.2.13 ...)
```

This is the regression check for the floors. A pytest that reads
`pyproject.toml` would only restate the constants. The behavioural
regression test is the Mem0 search test above.

**Mem0 telemetry, observed** (PostHog `capture` patched to record
instead of send): `mem0.init`, `mem0.add`, `mem0.search` and
`mem0.notice_displayed` events. Properties are config/OS/version fields
plus `encoded_ids` and `keys`; no memory text or query. 2.0.5 has the
same default (`MEM0_TELEMETRY` defaults to `True`, same host), so this
is not new with the bump.

**Remaining limitations**
- Real OpenAI not exercised (stub). Neo4j graph path not exercised
(`enable_graph=False`).
- Existing Qdrant points written by the old direct path lack `data` and
stay invisible to Mem0 search until re-saved.
- Found while testing, not fixed here (pre-existing on langgraph 1.2.11
too): the compress node returns a new `ToolMessage` without the original
`id`, so `add_messages` appends a compressed copy next to the original
instead of replacing it (5 messages instead of 4). Will follow up
separately.
- Headroom does not set `MEM0_TELEMETRY=False` for memory-stack users.
Separate decision.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: no; optional `memory-stack` /
`langgraph` extras only. Mem0 search goes from always raising to
working.
- Kill switch / disable path: N/A
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

The undici, ip-address, glob and minimatch npm audit failures
(`e2e/wrap/tools`, `plugins/opencode`) and the
`test_v1_compress_timeout_fails_open_quickly` timing failure also fail
on `main` and are not touched here.

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



## Independent review proof

Independently re-reviewed exact head
`3c326036a93a95378114f3f7e47f66471663aaf1` on Windows / CPython 3.12.13.
No new code finding. These checks supplement the author's evidence
above.

Runtime versions: mem0ai 2.2.1, langgraph 1.2.19, langgraph-sdk 0.4.11,
langgraph-checkpoint 4.3.1, langgraph-prebuilt 1.1.0, posthog 7.79.0,
qdrant-client 1.17.1, ormsgpack 1.12.2, xxhash 3.6.0; genuine MiniLM
embeddings through sentence-transformers 5.2.1. The review used an
isolated environment inheriting existing project/embedding dependencies,
with the listed upgrade/framework packages installed separately at their
locked versions. Source imports were verified against the exact-head
checkout. It did not rebuild or recreate every dependency in the full
lock.

For a fresh reproduction, check out the exact head, install/build
Headroom with its `memory-stack`, `langgraph` and development extras
using `uv sync --locked --extra dev --extra memory-stack --extra
langgraph`, and make sentence-transformers 5.2.1 available in the
selected interpreter. This clean bootstrap is a reproduction recipe, not
a claim that the review rebuilt the native extension. Run the following
commands with that interpreter, from the repository root:

```powershell
$env:PYTHONPATH = (Get-Location).Path
python scripts/verify_mem0_agent_scope.py
python scripts/verify_mem0_tenant_scope.py
python scripts/verify_mem0_dependency_boundaries.py
```

All three public committed proof scripts passed: each agent retrieved
its own persisted memory and excluded its sibling; get_all/query
excluded unrelated users; distinct identity tuples generated different
SQLite scope keys and the other tenant retrieved zero messages; SDK
identifiers remained one encoded path segment against an actual loopback
HTTP server; telemetry opt-out created no client/event, and enabled
PostHog capture/shutdown delivered one event to loopback only. MiniLM
weights may require an initial Hugging Face download.

Two additional full diagnostics follow. Save their code as
`review_direct.py` and `review_langgraph.py` outside tracked source,
then run `python review_direct.py` and `python review_langgraph.py` with
the same interpreter and repository-root PYTHONPATH. No OpenAI
credentials are required. These are review diagnostics, not changes to
contributor logic.

<details>
<summary>DirectMem0 actual changed write/search methods: complete
diagnostic</summary>

```python
import asyncio
import os
import tempfile
from importlib.metadata import version

os.environ['MEM0_TELEMETRY'] = 'false'
os.environ['HF_HUB_DISABLE_TELEMETRY'] = '1'
from mem0 import Memory as Mem0
from headroom.memory.backends.direct_mem0 import DirectMem0Adapter, Mem0Config

async def main():
    with tempfile.TemporaryDirectory(prefix='headroom-direct-proof-') as path:
        client = Mem0.from_config({
            'version': 'v1.1',
            'llm': {'provider': 'openai', 'config': {'api_key': 'unused-no-inference'}},
            'embedder': {'provider': 'huggingface', 'config': {
                'model': 'sentence-transformers/all-MiniLM-L6-v2', 'embedding_dims': 384}},
            'vector_store': {'provider': 'qdrant', 'config': {
                'path': path, 'collection_name': 'direct_proof', 'embedding_model_dims': 384}},
            'history_db_path': path + '/history.db'})
        adapter = DirectMem0Adapter(Mem0Config(enable_graph=False, collection_name='direct_proof'))
        adapter._mem0_client = client
        adapter._qdrant_client = client.vector_store.client
        adapter._initialized = True
        # Use the genuine local MiniLM embedder rather than an OpenAI request.
        adapter._embed = lambda text: client.embedding_model.embed(text, 'add')
        fact = 'The billing service is written in Rust'
        ids = await adapter._write_facts_to_qdrant([fact], 'tenant-a', 0.8)
        point = adapter._qdrant_client.retrieve('direct_proof', ids)[0]
        assert point.payload['data'] == fact
        results = await adapter.search_memories(query='billing service programming language', user_id='tenant-a', top_k=1)
        assert len(results) == 1 and results[0].memory.content == fact, results
        assert await adapter.search_memories(query='billing service programming language', user_id='tenant-b', top_k=1) == []
        print(f'mem0ai={version("mem0ai")}: real direct Qdrant data payload, MiniLM search, top_k=1 and tenant isolation PASS')
        client.vector_store.client.close()
        client.db.connection.close()

asyncio.run(main())

```

Observed exit 0: `mem0ai=2.2.1: real direct Qdrant data payload, MiniLM
search, top_k=1 and tenant isolation PASS`. This uses the genuine local
embedder in place of OpenAI transport; it executes Headroom's actual
direct Qdrant write and Mem0 search methods.

</details>

<details>
<summary>Real StateGraph / Headroom compression / checkpoint: complete
diagnostic</summary>

The optional `HEADROOM_REVIEW_NATIVE_CORE` variable lets an existing
compatible native extension be reused. The Windows review pointed it to
an already-built local `_core.pyd`; with a normally built Headroom
checkout, leave it unset. This review did not qualify a fresh native
build.

```python
import importlib.util
import json
import os
import sys
from importlib.metadata import version
import headroom

if os.environ.get('HEADROOM_REVIEW_NATIVE_CORE'):
    spec = importlib.util.spec_from_file_location('headroom._core', os.environ['HEADROOM_REVIEW_NATIVE_CORE'])
    native = importlib.util.module_from_spec(spec)
    sys.modules['headroom._core'] = native
    spec.loader.exec_module(native)
    headroom._core = native

from langchain_core.messages import HumanMessage, AIMessage, ToolMessage
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.checkpoint.memory import InMemorySaver
from headroom.integrations.langchain.langgraph import create_compress_tool_messages_node

content = json.dumps([{'id': i, 'status': 'healthy', 'region': 'us-east-1', 'latency_ms': i % 11, 'detail': 'routine health check'} for i in range(300)])
observed = {}
compress = create_compress_tool_messages_node(min_tokens_to_compress=100)

def agent(state):
    return {'messages': [AIMessage(content='', tool_calls=[{'name': 'health', 'args': {}, 'id': 'call-1'}])]}

def tool(state):
    return {'messages': [ToolMessage(content=content, tool_call_id='call-1', name='health')]}

def compression(state):
    out = compress(state)
    tools = [m for m in out['messages'] if isinstance(m, ToolMessage)]
    observed['after'] = len(tools[-1].content)
    assert observed['after'] < len(content), observed
    return out

graph = StateGraph(MessagesState)
graph.add_node('agent', agent)
graph.add_node('tools', tool)
graph.add_node('compress', compression)
graph.add_node('model', lambda state: {'messages': [AIMessage(content='done')]})
graph.add_edge(START, 'agent')
graph.add_edge('agent', 'tools')
graph.add_edge('tools', 'compress')
graph.add_edge('compress', 'model')
graph.add_edge('model', END)
app = graph.compile(checkpointer=InMemorySaver())
config = {'configurable': {'thread_id': 'review-4614'}}
result = app.invoke({'messages': [HumanMessage(content='Check service health')]}, config)
assert result['messages'][-1].content == 'done'
snapshot = app.get_state(config)
assert snapshot.values['messages'][-1].content == 'done'
print(f'langgraph={version("langgraph")}; checkpoint={version("langgraph-checkpoint")}; final=done; restored_messages={len(snapshot.values["messages"])}; tool_chars={len(content)} -> {observed["after"]}; PASS')

```

Observed exit 0: `langgraph=1.2.19; checkpoint=4.3.1; final=done;
restored_messages=5; tool_chars=32317 -> 13791; PASS`. An isolated
baseline environment with langgraph 1.2.11 / checkpoint 4.2.0 / SDK
0.4.6 produced the identical five restored messages and compression
sizes, exit 0. Thus the disclosed duplicate ToolMessage behavior is
inherited rather than introduced by this upgrade.

</details>

Additional validation: focused memory/LangGraph suite yielded 674
passed, 3 skipped, 8 failures. All eight failures reproduced on current
main `74277d47ecfbca349ddb99f81094c4dd30539d43`: six optional
embedding/configuration failures and two Windows/POSIX-path assumptions.
`uv lock --check --offline` and whitespace verification passed. Required
current-head GitHub checks were all successful when this review was
submitted.

Limits: local embedded Qdrant; no real OpenAI inference or Neo4j graph
path. Optional spaCy models were absent and Mem0 emitted warnings. Full
lock/native rebuild and live cloud infrastructure were not exercised by
these independent diagnostics.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:21:42 +05:30
64f43bdf8f deps: bump ruff from 0.17.0 to 0.17.2 in the pip-minor-patch group across 1 directory (#4380)
Ruff's default `UP035` fix in 0.17.0 can delete comments from a
multi-line deprecated typing import. Headroom enables the UP rules and
invokes `ruff --fix` in pre-commit, so this can discard contributor
explanations during routine checks. Upgrade to 0.17.2, which marks
comment-deleting fixes unsafe, and synchronize the exact dev dependency,
lockfile, and pre-commit revision.

The branch also carries the reviewed glob/minimatch security remediation
from #4599 so the resulting tree passes the npm audit gates. It
preserves the existing exact-path/version exceptions for npm's bundled
dependencies and their November 15 expiry.

## Dependency assessment

- **Why Ruff / this version:** existing project linter and formatter;
this patch fixes a destructive auto-fix in a rule family already enabled
by Headroom. Upstream fix: https://github.com/astral-sh/ruff/pull/29413,
released in https://github.com/astral-sh/ruff/releases/tag/0.17.2. This
is a bug-fix upgrade, with the default unsafe-fix protection retained.
- **Maintenance / security:** maintained by Astral in astral-sh/ruff;
the official 0.17.1 and 0.17.2 releases were published October 15 and
22. PyPI's 0.17.2 response reports no known vulnerability entries at
qualification time; this is not a guarantee about all security history.
- **Install surface:** a development/pre-commit tool, distributed as
platform-native Rust binaries in wheels. PyPI 0.17.2 declares no Python
runtime dependencies and provides 17 wheels; the installed binary runs
successfully. Package installation downloads from the registry; linting
itself was exercised without a service/model/API key. No new
application-runtime library, transitive package version, or dependency
set is added by the Ruff lock update. Lock regeneration also
synchronizes the existing lean-extra python-socks declaration.
- **Carried security fix:** #4599 documents the glob/minimatch rationale
and install surface; the exact manifests, locks, regressions and
exceptions were checked against the reviewed fix. No exception was
broadened or extended.

## Real behavior proof

Windows, Python 3.13.3 for uv lock validation; Node 22.22.0 for OpenCode
tests/build; Node 24.22.2 for E2E dependency regressions. Ruff binaries
were obtained with `uvx --from ruff==VERSION ruff`.

For each Ruff version, write this file and run `ruff check --isolated
--select UP035 --target-version py311 --fix fixture.py`:

```python
from typing import (
    Awaitable,  # preserve this contributor explanation
    Callable,
)
```

Observed: 0.17.0 removes the comment and exits 0 after fixing the
import. Version 0.17.2 preserves the comment, leaves the unsafe fix
unapplied, and exits 1 with the expected UP035 finding. The test
asserted these before/after file contents. This is the intended
protection for Headroom's pre-commit auto-fix path.

Additional validation on the resulting branch:

- `python scripts/verify-ruff-version.py`: Ruff versions aligned at
0.17.2.
- `uv lock --check` passes; `uv export --locked --extra dev --no-hashes
--no-emit-project` selects `ruff==0.17.2`.
- `uvx --from ruff==0.17.2 ruff check . --output-format concise`: all
checks passed.
- Fresh `npm ci --ignore-scripts --no-audit --no-fund` in
`plugins/opencode` and `e2e/wrap/tools`.
- OpenCode: `npm test -- --reporter=dot`: 61 passed; `npm run typecheck`
and `npm run build` passed; `npm audit --json`: zero vulnerabilities.
- E2E tools: `npm exec --yes --package=node@24.22.2 -- node --test
--test-concurrency=1 --test-reporter=tap
dependency-regression.test.cjs`: 3 passed. The exact Python checker
extracted from `.github/workflows/security.yml` accepted only 8 existing
bundled advisory/path entries, until 2026-11-15.
- `git diff --check` passed.

Untested locally: other operating systems, pre-commit environment
creation, application runtime/provider paths, and a production release.
Hosted CI must qualify the current head; local checks do not claim a
rollout.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
2026-11-02 21:16:57 -06:00
4a851ed254 fix(codex): accept multi-line inline tables in Codex config.toml (#4436)
## Description

Codex accepts an inline table split across lines, with a trailing comma,
in `~/.codex/config.toml`:

```toml
env = {
  DINGTALK_Client_ID = "**********",
}
```

That is TOML 1.1 syntax. Headroom reads the Codex config with the
standard library `tomllib`, which only implements TOML 1.0 before Python
3.15, so it rejects the file with `Invalid initial character for a key
part`. The result is what the issue shows: `headroom wrap codex` and
`headroom mcp install` refuse to register MCP servers ("is not valid
TOML ... refusing to overwrite") and session routing fails with "could
not read Codex config for session routing", even though Codex itself is
happy with the file.

`tomlkit` is already a runtime dependency (used for Codex config
recovery) and parses this syntax from 0.15.0. 0.13.3 and 0.14.0 both
fail on it (`Empty key at line 1 col 7`).

The fix adds one helper, `loads_codex_config()`, that parses with
`tomllib` first and only on `TOMLDecodeError` retries with `tomlkit`. If
`tomlkit` rejects the text too, it re-raises the original
`tomllib.TOMLDecodeError`, so every caller keeps its existing `except
tomllib.TOMLDecodeError` handling and its error messages unchanged. All
places that parse the user's Codex config now go through it.

The follow-up commit (`dc193870`) fixes a problem the first commit
exposed: once a multi-line inline table parses, a `profiles = {` table
can carry per-profile `model_provider` / `openai_base_url` keys on their
own indented lines, and the line-based "root key" edits in init, the
provider-scope install and persistent wrap mistook those nested lines
for root assignments. Init and install deleted the profile's provider,
and wrap rewrote it to `headroom` and then skipped adding a real root
`model_provider`. Those edits now only touch lines that are actual root
assignments.

Fixes #4378

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/providers/codex/config_toml.py` (new):
`loads_codex_config(content)`, `tomllib` first, `tomlkit` fallback,
original `tomllib` error if both fail.
- Routed the Codex config parse sites through it (15 call sites, 16
parse calls):
- `headroom/cli/wrap.py`: session routing read, the user-content check
and its fallback in `_inject_codex_provider_config`, and the two "never
write a malformed candidate" checks.
- `headroom/cli/init.py`: provider snapshot check, the candidate check
in `_ensure_codex_provider`, and `_codex_features`.
- `headroom/providers/codex/install.py`: `_codex_credential_store`,
`codex_auth_helper_is_referenced`, and the merged-config check before
writing.
- `headroom/providers/codex/project_context.py`: the `sqlite_home`
lookup.
- `headroom/mcp_registry/codex.py`: `_load_toml`, `_unmergeable_reason`,
and both sides of `_only_server_changed`. This registrar class is shared
with Grok, so a Grok `config.toml` with the same syntax is accepted too.
- Left on `tomllib` on purpose: `_table_path` (parses a single `[table]`
header line) and the auth snippet check in `build_codex_auth_config`
(validates text Headroom generates itself).
- `pyproject.toml` / `uv.lock`: raise the `tomlkit` minimum from
`>=0.13.0` to `>=0.15.0`, the first release that parses multi-line
inline tables. The lock already resolved 0.15.0, so `uv lock` only
changed the specifier line.
- Write paths: the user's text is never re-serialized by this change.
The registrar and the wrap/init injectors still append or splice marker
blocks as text, and the existing `tomlkit` round-trip in wrap keeps the
multi-line table byte for byte (checked below).
- Tests:
- `tests/test_provider_codex_config_toml.py`: the helper on the exact
shape from the issue (multi-line, trailing comma, whitespace-only line,
indented `}`), and that invalid TOML still raises
`tomllib.TOMLDecodeError`.
-
`tests/test_mcp_registry/test_codex_registrar.py::test_register_accepts_multiline_inline_table`:
registering into that config succeeds and the user's text is kept as a
byte-for-byte prefix.
-
`tests/test_cli/test_wrap_codex.py::test_codex_session_launch_settings_accept_multiline_inline_table`:
session routing reads that config and leaves the file untouched.
- Follow-up commit `dc193870` (multi-line inline profile overrides):
- `headroom/providers/codex/config_toml.py`:
`root_assignment_lines(content)` returns the indexes of lines that start
a key/value pair at the document root. It stops at the first table
header and skips lines inside a multi-line inline table, array or
string, with a small scanner that tracks quotes, comments and bracket
depth.
- `headroom/cli/init.py` (`_ensure_codex_provider`) and
`headroom/providers/codex/install.py`
(`_strip_root_provider_assignments`) only drop `model_provider` /
`openai_base_url` lines that are root assignments.
- `headroom/cli/wrap.py`: `_redirect_existing_top_level_keys` and
`_has_redirectable_top_level_key` only look at root assignments. Before,
they matched the key on any line, so a `[profiles.work]` section
override was also rewritten to `headroom` and counted as a root key;
that now stays the user's, matching how init, install and
`_strip_codex_headroom_blocks` already treat `[profiles.*]`.
- Tests:
`test_root_assignment_lines_skip_keys_nested_in_multiline_inline_table`,
`test_ensure_codex_provider_preserves_multiline_inline_profile_overrides`
(init),
`test_provider_scope_preserves_multiline_inline_profile_overrides`
(install) and `test_inject_preserves_multiline_inline_profile_overrides`
(wrap).

## Testing

- [x] Unit tests pass (`pytest`) - Codex, MCP registry, init and Grok
suites: 774 passed, 2 failed (the 2 failures are in
`tests/test_codex_responses_passthrough_bytes.py` and fail the same way
on `main` without this change)
- [x] Linting passes (`ruff check .`) - `ruff check` and `ruff format
--check` on the 9 changed Python files
- [x] Type checking passes (`mypy headroom`) - `mypy` on the 6 changed
source files, no issues
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

New end-to-end tests on `main` (fix stashed):

```text
$ pytest tests/test_mcp_registry/test_codex_registrar.py::test_register_accepts_multiline_inline_table tests/test_cli/test_wrap_codex.py::test_codex_session_launch_settings_accept_multiline_inline_table -q
E   AssertionError: .../.codex/config.toml is not valid TOML (Invalid initial character for a key part (at line 3, column 8)); refusing to overwrite. Fix or remove the file, then re-run.
E   click.exceptions.ClickException: could not read Codex config for session routing: Invalid initial character for a key part (at line 5, column 8)
============================== 2 failed in 0.38s ===============================
```

(`tests/test_provider_codex_config_toml.py` cannot import on `main`
because the helper does not exist yet.)

With the fix:

```text
$ pytest tests/test_provider_codex_config_toml.py tests/test_mcp_registry/test_codex_registrar.py::test_register_accepts_multiline_inline_table tests/test_cli/test_wrap_codex.py::test_codex_session_launch_settings_accept_multiline_inline_table -q
============================== 4 passed in 0.56s ===============================

$ pytest tests/test_provider_codex_config_toml.py tests/test_mcp_registry tests/test_cli/test_wrap_codex.py tests/test_cli/test_init_cli.py tests/test_install/test_codex_install.py tests/test_provider_codex*.py tests/test_provider_grok*.py tests/test_codex*.py -q
FAILED tests/test_codex_responses_passthrough_bytes.py::test_unmutated_zstd_post_forwards_decoded_bytes_and_strips_content_encoding - concurrent.futures._base.CancelledError
FAILED tests/test_codex_responses_passthrough_bytes.py::test_unmutated_plain_post_passes_original_bytes_through - concurrent.futures._base.CancelledError
================== 2 failed, 774 passed, 8 warnings in 50.43s ==================

$ pytest tests/test_codex_responses_passthrough_bytes.py -q   # on main, without this change
========================= 2 failed, 1 warning in 4.09s =========================

$ mypy headroom/cli/init.py headroom/cli/wrap.py headroom/mcp_registry/codex.py headroom/providers/codex/install.py headroom/providers/codex/project_context.py headroom/providers/codex/config_toml.py
Success: no issues found in 6 source files
```

Follow-up commit, the three new write-path tests on the first commit
(`dfe93720`, source changes reverted):

```text
$ pytest tests/test_cli/test_init_cli.py tests/test_install/test_codex_install.py tests/test_cli/test_wrap_codex.py -k multiline_inline_profile -q
FAILED tests/test_cli/test_init_cli.py::test_ensure_codex_provider_preserves_multiline_inline_profile_overrides - AssertionError: assert {} == {'model_provi...y.example/v1'}
FAILED tests/test_install/test_codex_install.py::test_provider_scope_preserves_multiline_inline_profile_overrides - AssertionError: assert {} == {'model_provider': 'company'}
FAILED tests/test_cli/test_wrap_codex.py::TestSubscriptionRouting::test_inject_preserves_multiline_inline_profile_overrides - KeyError: 'model_provider'
====================== 3 failed, 220 deselected in 0.56s =======================
```

With `dc193870`:

```text
$ pytest tests/test_provider_codex_config_toml.py tests/test_cli/test_init_cli.py tests/test_install/test_codex_install.py tests/test_cli/test_wrap_codex.py -k "multiline_inline_profile or root_assignment" -q
======================= 4 passed, 222 deselected in 0.27s =======================

$ pytest tests/test_provider_codex_config_toml.py tests/test_cli/test_init_cli.py tests/test_install/ -q
================== 346 passed, 13 skipped, 1 warning in 3.94s ==================
$ pytest tests/test_cli/test_wrap_codex.py tests/test_cli/test_port_alignment.py -q
============================= 167 passed in 6.01s ==============================
$ pytest tests/test_mcp_registry/ tests/test_provider_codex_install.py tests/test_cli/test_install_cli.py tests/test_cli/test_recover_codex.py -q
============================= 364 passed in 4.71s ==============================
$ pytest tests/test_cli/test_wrap_persistent.py tests/test_codex_project_context.py tests/test_cli/test_wrap_stale_marker.py tests/test_cli/test_wrap_dead_marker_selfheal.py tests/test_provider_codex_runtime.py tests/test_install_tool_env_reconcile.py -q
======================== 4 failed, 261 passed in 9.01s =========================
```

The 4 failures are in `tests/test_cli/test_wrap_persistent.py`
(`AttributeError: '_Manifest' object has no attribute 'runtime_kind'`)
and fail the same way with this PR's changes stashed. `ruff check`,
`ruff format --check` (8 files) and `mypy` on the 4 changed source files
are clean.

tomlkit versions on the issue's snippet:

```text
0.13.3 FAIL Empty key at line 1 col 7
0.14.0 FAIL Empty key at line 1 col 7
0.15.0 {'env': {'A': 'x'}}
```

## Real Behavior Proof

- Environment: macOS 26.2 (Apple Silicon), Python 3.14.7, repo venv with
the `mcp` package installed, a throwaway `HOME`/`CODEX_HOME` whose
`config.toml` holds the issue's config:

  ```toml
  [mcp_servers.dingtalk]
  command = "npx"
  env = {
    DINGTALK_Client_ID = "**********",
    
      }
  ```

- Exact command / steps: `HOME=<tmp>/home CODEX_HOME=<tmp>/home/.codex
python -m headroom.cli mcp install --agent codex`, then compare the
start of the resulting file with the original bytes and count
`[mcp_servers.headroom]` tables. Also called
`wrap._inject_codex_provider_config(8787)` and
`init._ensure_codex_provider(path, 8787)` on the same config to check
the write paths.
- Observed result: before (`main`):

  ```text
codex: install failed (failed): <tmp>/home/.codex/config.toml is not
valid TOML (Invalid initial character for a key part (at line 3, column
8)); refusing to overwrite. Fix or remove the file, then re-run.
  ```

  After:

  ```text
  codex: registered (restart the agent if it was already running)
  ```

The user's original bytes are an exact prefix of the new file and one
`[mcp_servers.headroom]` table was appended. The wrap injector printed
`Codex config: injected Headroom provider (WS + HTTP)`, and in both the
wrap and init outputs the user's multi-line table is still present
verbatim, the file parses, `env` is `{'DINGTALK_Client_ID':
'**********'}` and `model_provider` is `headroom`.
- Follow-up commit: with a throwaway `HOME`/`CODEX_HOME` holding

  ```toml
  model_provider = "openai"
  profiles = {
    work = {
      model_provider = "company",
    },
  }
  ```

I ran `init._ensure_codex_provider`, `install.apply_provider_scope`
(provider scope) and `wrap._inject_codex_provider_config` (same config
without the root key) and parsed the result:

  ```text
  == before (dfe93720)
  init:   root = headroom  work = {}
  install: root = headroom  work = {}
  wrap:   root = None  work = {'model_provider': 'headroom'}
  == after (dc193870)
  init:   root = headroom  work = {'model_provider': 'company'}
  install: root = headroom  work = {'model_provider': 'company'}
  wrap:   root = headroom  work = {'model_provider': 'company'}
  ```

- Not tested: a full `headroom wrap codex` run with a live proxy and the
real Codex CLI, and Python 3.10 (where `tomli` is the first parser; the
`tomlkit` fallback is the same there).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only for Codex configs `tomllib`
rejects but `tomlkit` 0.15 accepts (TOML 1.1 multi-line inline tables).
Valid TOML 1.0 still goes through `tomllib` exactly as before, and text
both parsers reject fails with the same error as before.
- Kill switch / disable path: none needed; the fallback only runs after
`tomllib` has already failed.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the two commits

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`, it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

- Documentation: no user-facing docs describe which TOML syntax the
Codex config may use, so nothing to update.
- Python 3.15's `tomllib` implements TOML 1.1 and parses this config
directly (as noted in the issue thread), so on 3.15 the fallback simply
never runs.
- `tomlkit` is a bit more permissive than `tomllib` only where TOML 1.1
is; it still rejects duplicate keys and malformed tables, so the
existing "refuse to overwrite an unparseable file" guards still trigger
for genuinely broken configs (covered by the existing registrar tests).
- Dependency review for the `tomlkit` minimum bump (`>=0.13.0,<1.0` to
`>=0.15.0,<1.0`):
- Why this package: it is already a direct runtime dependency (Codex
config recovery and the memory MCP block edit in `wrap.py`), so no new
package enters the tree. Writing a TOML 1.1 parser here is not worth it,
and `tomllib` only gains TOML 1.1 in Python 3.15.
- Who maintains it: the Poetry project (`python-poetry/tomlkit`, MIT),
with Frost Ming and Sébastien Eustace as the main maintainers. It is
actively released: 0.13.3 (2025-06), 0.14.0 (2026-01), 0.15.0 (2026-05),
0.15.1 (2026-07), 0.15.2 (2026-10). No GitHub security advisories are
published for the repo.
- Install surface: unchanged. Pure Python, a single `py3-none-any` wheel
(about 41 KB for 0.15.0), no runtime dependencies, no native code, no
install-time or runtime network access. `uv.lock` already resolved
0.15.0 before this PR, so the locked version and hashes do not change;
only the specifier line moves.
- Why this version: required new functionality. 0.15.0 is the first
release with TOML 1.1 support ("feat(spec): update to toml spec v1.1",
python-poetry/tomlkit#456), which is what parses multi-line inline
tables with trailing commas. 0.13.3 and 0.14.0 both reject the issue's
snippet (`Empty key at line 1 col 7`, output above). 0.15.0 also
includes an upstream parser hang fix (python-poetry/tomlkit#470).

---------

Co-authored-by: Abelo9996 <Abelo9996@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-28 23:31:18 -05:00
ShiYuan XiongandJerrettDavis 4ee616453f fix(router): keep small shell results verbatim (#3590) (#4426)
## Description

Fixes #3590. Small shell tool results (default: shorter than 2000
characters) now bypass lossy compression. Byte-lossless folds such as
search grouping may still apply. File reads and searches were already
protected; shell output is deliberately compressible, but a short `ls
-la`, `git status`, or JSON dump is not worth the accuracy loss
described in #3590.

The real proxy-level before/after evidence is in Real Behavior Proof. A
live Claude Code session is still untested.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Added `HEADROOM_SHELL_RESULT_MIN_CHARS` (default `2000`) and
`_is_small_shell_result()`, applied to OpenAI `role:"tool"`, legacy
`role:"function"`, top-level text-block tool messages, and Anthropic
`tool_result` string/list-form paths after the lossless search fold and
before lossy compression.
- Normalized `ContentRouterConfig.bash_tool_names` once and extended it
with the shell aliases already in `headroom.learn._shared` (`shell`,
`local_shell`, `run_shell_command`, `execute_command`, `exec_command`,
`terminal`, `run_command`, `run_terminal_command`).
- Measure a top-level text-block shell result using the combined text
length, so a large result cannot bypass compression merely by splitting
into small blocks.
- Added boundary coverage for both tool/function block shapes, positive
threshold overrides and custom case-insensitive shell names; documented
the combined-length contract in `docs/content/docs/proxy.mdx`.
- Updated the existing proxy-level Bash regression to assert both sides
of the 2000-character floor, fixing the hosted shard-4 failure. Added
kill-switch, malformed/empty-value and diagnostic coverage.
- Carried dependency security remediation requested in review: certifi
and the OpenTelemetry family, three patched Rust crates, and patched npm
locks for docs, SDK, OpenCode and E2E tooling. These use existing
packages, explicit security floors and targeted dependency overrides;
libc platform constraints remain intact.

## Testing

- [x] Hosted CI passes on the current head, including all four Python
test shards
- [x] Changed Python tests passed Ruff in the preceding regression
revision; no Python runtime source changed in this dependency follow-up
- [ ] Full local Python type check passes (Windows/test-double baseline
limitations)
- [x] Regression and dependency-interface coverage added
- [x] Real proxy proof and isolated CLI smoke evidence recorded

### Test Output

Latest follow-up: Windows, Python 3.11 / Node 22.20.0 for the OpenCode
suite, and portable official Node 24.22.1 for E2E CLI qualification. The
portable Node archive's SHA-256 matched nodejs.org's published checksum.

```text
Python shell-floor/web-tool/router/alias/tracing + OpenClaw wrapper/bridge selection:
119 passed, 2 warnings in 10.37s

uv lock --check
Resolved 262 packages

uv tree --locked --python-version 3.10 --package filelock
filelock v4.1.0
uv tree --locked --python-version 3.12 --package filelock
filelock v4.2.4

FileLock 4.2.4 process smoke:
contention times out, release permits next process

cd plugins/opencode
npm test
Test Files  4 passed (4)
Tests       60 passed (60)
npm run typecheck
> node node_modules/@typescript/native/bin/tsc --noEmit
npm run build
DTS Build success
npm audit --package-lock-only --audit-level=low --registry=https://registry.npmjs.org
found 0 vulnerabilities

After merging current upstream main (including #4453):

cd e2e/wrap/tools
node node_modules/openclaw/openclaw.mjs --version
OpenClaw 2026.10.6
npm audit --package-lock-only --audit-level=low --registry=https://registry.npmjs.org
2 vulnerabilities (1 moderate, 1 high)
# limited to npm's bundled copies:
# GHSA-rxp7-6hxx-x8q5 — node_modules/npm/node_modules/ip-address 10.7.2
# GHSA-4qv8-2p9j-2685 and GHSA-xjj6-f33q-929c — node_modules/npm/node_modules/undici 6.29.0
# exact scoped exceptions expire 2026-11-15; no OpenClaw path is excepted

production-lock pip-audit:
No known vulnerabilities found
```

- The Python native extension remains the existing 0.41.0 Windows
wheel's `_core.pyd`; all Python source under test comes from this PR
checkout. No native rebuild or Torch/model inference qualification is
claimed.
- The 3 new OpenCode compatibility tests exercise the actual upstream
`tool.schema` interface and Effect `Primitive.fileParse` TOML
success/error channels, mocking only filesystem I/O. They accompany the
explicit Zod/TOML overrides.
- E2E CLI checks used isolated `OPENCLAW_STATE_DIR` /
`OPENCLAW_CONFIG_PATH`, with no model request or modification of the
user's normal OpenClaw configuration. E2E dependencies were installed
with lifecycle scripts disabled. The full Docker/model E2E suite was not
run locally.
- Earlier unchanged docs/SDK lock remediation passed: SDK **351 passed,
33 skipped** plus typecheck/build; docs typecheck/build with 185 static
pages; both npm audits were zero. The previous head also passed the
hosted Rust security audit.
- Full local Python suite was not rerun. The earlier remote-timeout
float-boundary failure remains outside this change.

## Real Behavior Proof

- Environment: Windows 10 x64, Python 3.11.0, Headroom source `main` at
`e995eb9` (0.41.1-dev), native `_core` from the 0.41.0 wheel because no
Rust toolchain is available locally. `HEADROOM_DISABLE_KOMPRESS=1` keeps
the strategy deterministic; the guard sits before strategy selection, so
the same path applies when Kompress is enabled.
- Exact command / steps: local harness (not committed) `python
proof-3590/run_proof.py` starts the source-tree proxy in `--mode token`
with `HEADROOM_MIN_TOKENS=0` and a local OpenAI-compatible upstream, and
sends a chat request containing a Bash `ps aux` tool result (1719 chars)
followed by later turns. The upstream records the transformed request
body.
- Observed result: `HEADROOM_SHELL_RESULT_MIN_CHARS=0` produced
`compressed=1`, `router:tabular:0.85`, 802 -> 697 tokens (saved 105),
and upstream received a 1455-char schema representation. Default `2000`
produced `shell_small_result: 1`, `compressed=0`, 802 -> 802 tokens, and
upstream received the original 1719-char output byte-for-byte.
- Review follow-up proof: `python proof-3590/run_block_review.py` ran
the real proxy against the same local upstream without replacing its
compressor. A 1719-character shell result split into two text blocks
stayed unchanged; a 3438-character result split into two 1719-character
blocks remained compressible. The previous PR revision incorrectly
protected both large-result fragments. This harness is local, not part
of the PR.
- Not tested: a live `headroom wrap claude` session; the ML Kompress
path; Linux/macOS; the full suite (one pre-existing baseline failure).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; ContentRouter default path.
- Minimum rollout channel: default proxy.
- Stable/default behavior changed: yes. Shell results between
`min_chars_for_block_compression` (500) and
`HEADROOM_SHELL_RESULT_MIN_CHARS` (2000) now stay verbatim instead of
taking lossy compression. At ~1500 chars (~375 tokens), this keeps
roughly 325 extra tokens per result for the life of the context.
- Kill switch / disable path: `HEADROOM_SHELL_RESULT_MIN_CHARS=0`.
- Unsafe override required: no.
- Qualification impact: compression ratio may decrease for small shell
outputs; no API or correctness changes.
- Rollback path: revert this commit or set
`HEADROOM_SHELL_RESULT_MIN_CHARS=0`.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A — no UI changes.

## Additional Notes

This follows the [dependency-remediation
review](https://github.com/headroomlabs-ai/headroom/pull/4426#pullrequestreview-5636487191).
It does not disable audits, ignore advisories, reduce audit severity, or
use `npm audit fix --force`.

- **Python:** certifi/OpenTelemetry/Rust fixes from the prior revision
remain. This follow-up raises setuptools to **84.1.0** for the Windows
wheel namespace traversal advisory and uses FileLock **4.2.4** on Python
≥3.11. The universal lock remains resolvable with the published Python
≥3.10 contract. **Python 3.10 now selects FileLock 4.1.0, but it remains
below the 4.2.1 security floor** because fixed releases require ≥3.11;
this is not presented as all-interpreter remediation.
- **OpenCode:** pin security overrides **Zod 4.6.7** and **TOML 5.0.1**
without downgrading the plugin or replacing its pinned Effect version.
TOML crosses a major version (4.3.0 → 5.0.1); its Node ≥20 floor and
consumed `parse(content)` API are unchanged. The added tests validate
the exercised schema and Effect parsing contracts, not every possible
TOML consumer. This override needs normal maintainer dependency review.
- **E2E:** the original remediation moved OpenClaw to 2026.10.5; the
upstream sync now brings **OpenClaw 2026.10.6** with **Undici 8.12.3**
and a Node floor of **≥24.22.1 <25 or ≥26.12.1**. The only remaining raw
npm findings are npm's published bundled copies, handled by the exact,
expiring E2E-only exception policy described below.
- Dependency packages and runtime floors were checked against the
upstream registry metadata. Locks use public registries and retain
existing libc platform constraints.

### Security qualification after upstream sync

Merge commit `e09d37c9274c812f26e994d01a623542a4a7ec31` brings this
branch to upstream `main` through `a616232`, including
[#4453](https://github.com/headroomlabs-ai/headroom/pull/4453). That
upstream change establishes the repository's current security policy for
the dependency cases that previously blocked this PR:

- **Production Python lock:** Python ≥3.11 resolves Pillow 13.0.0 and
FileLock 4.2.4. The current lock passes `uv lock --check`; an equivalent
export of the production `all` set passes `pip-audit 2.10.1 --no-deps
--disable-pip` with **no known vulnerabilities**.
- **Published-package resolution:** FastEmbed still caps Pillow below 13
when ordinary pip resolves package metadata. Upstream now disables image
decoding on Pillow below 13 and separately audits the pip-resolved set,
accepting only Pillow findings covered by that tested decoder guard.
This is a bounded runtime mitigation, not a claim that the older Pillow
release has no advisories.
- **E2E npm lock:** OpenClaw 2026.10.6 uses fixed Undici 8.12.3. Raw npm
audit now reports only npm 12.2.1's bundled Undici 6.29.0 and ip-address
10.7.2 copies. Because npm does not allow overrides to replace its
published bundled contents and no newer release is available, upstream
accepts only the three exact advisory/path/version pairs in
`e2e/wrap/tools/npm-audit-exceptions.json`, only for the non-shipping
E2E harness, and only until **2026-11-15**. The workflow fails on any
extra finding, version/path mismatch, stale exception or expiry.
- **Python 3.10:** the lock now selects FileLock 4.1.0, but it remains
below the 4.2.1 security floor because fixed releases require Python
≥3.11. This supported-interpreter limitation is documented by the
upstream policy and is not represented as universal remediation.

The earlier OpenCode standalone-wheel mismatch remains fixed by
`dee73be75cf81bb67a73573861f1b3ed4067a2bf`: typecheck, build, all 60
plugin tests and the standalone build passed locally, both generated
artifacts matched their Python-shipped paths byte-for-byte, and the
shipped bundle imported with the expected `headroom` id and both
`server`/`setup` entry points.

### Current merge status

- Current head `ab93d7917a6660c704069bb87b6c02f9c744cebc` is mergeable;
all router/documentation inline review threads are resolved.
- JerrettDavis approved this head on 2026-10-24, superseding the earlier
security-related change requests.
- All 12 pull-request workflows on this head completed successfully,
including
[CI](https://github.com/headroomlabs-ai/headroom/actions/runs/40122163824)
(all four Python test shards),
[Security](https://github.com/headroomlabs-ai/headroom/actions/runs/40122163777),
wheel builds/import smoke tests, OpenCode, docs, and Docker E2E checks.
The workflows are no longer awaiting approval.
- The PR remains open, awaiting maintainer merge.
- A live Claude Code/model session, the ML Kompress path, a native
rebuild and the full Docker/model E2E suite remain unverified locally;
the hosted results above are separate from the recorded local
qualification.

Implemented and verified with AI assistance.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-28 23:31:00 -05:00
CtrlCreeperandJerrettDavis 79181ca0fe fix(proxy): install SOCKS support for websocket proxies (#3357)
## Description

Install the SOCKS transport dependency required when `websockets`
discovers a system SOCKS proxy. Without it, Codex Responses WebSocket
relay logs `connecting through a SOCKS proxy requires python-socks` and
cannot establish the upstream WebSocket.


## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Add `python-socks[asyncio]>=2.7.1` to the `proxy` extra.
- Regenerate `uv.lock`, resolving `python-socks` 3.1.1. Existing package
versions are unchanged relative to the refreshed main parent.
- Add a package-contract regression test that asserts
`headroom-ai[proxy]` includes the SOCKS transport dependency.

## Testing

- [x] Focused optional-dependency tests pass
- [x] Full branch Ruff lint and formatting checks pass
- [ ] Type checking
- [x] Package-contract regression test added
- [x] Manual SOCKS runtime verification performed

### Test Output

```text
$ python -m pytest tests/test_optional_dependencies.py -q
3 passed
$ uv lock --check
Resolved 252 packages in 5ms
$ ruff check .
All checks passed!
$ ruff format --check .
1715 files already formatted
```

Validation used Python 3.12.11 and Ruff 0.16.8. Comparing package
versions against the refreshed main parent found no existing package
version changes; only `python-socks` 3.1.1 was added. The full test
suite was not rerun locally. The existing hosted `test (2)` failure is
`test_category_losing_its_last_pattern_drops_its_heading`, which the
maintainer previously reproduced on main.

## Real Behavior Proof

- Environment: macOS 26.6.2, Apple Silicon arm64, Python 3.12.11,
`websockets` 16.0, locked `python-socks` 3.1.1, live SOCKS proxy at
`127.0.0.1:7897`, existing Sub2API OpenAI-compatible provider.
- Exact steps: create an isolated environment containing
`websockets==16.0` and no `python-socks`. Set
`wss_proxy=socks5://127.0.0.1:7897` so `websockets` automatically
discovers the SOCKS proxy. Call `websockets.connect(<real upstream
/v1/responses WebSocket URL>, additional_headers=<existing bearer>,
ssl=<configured TLS context>, open_timeout=30)` without an explicit
proxy argument. Repeat with `python-socks[asyncio]==3.1.1` installed,
using the same endpoint, proxy, credential, and TLS context.
- Installation commands:

```sh
uv venv <before-env> --python 3.12
uv pip install --python <before-env>/bin/python websockets==16.0
uv pip install --python <after-env>/bin/python 'python-socks[asyncio]==3.1.1'
```

Captured runtime output on 2026-10-07:

```text
# Before
Python: 3.12.11
websockets: 16.0 ; python-socks: not installed
Discovery: wss_proxy=socks5://127.0.0.1:7897; provider: existing Sub2API endpoint
Upstream WebSocket handshake: ImportError connecting through a SOCKS proxy requires python-socks

# After
Python: 3.12.11
websockets: 16.0 ; python-socks: 3.1.1
Discovery: wss_proxy=socks5://127.0.0.1:7897; provider: existing Sub2API endpoint
Upstream WebSocket handshake: InvalidStatus server rejected WebSocket connection: HTTP 426
```

- Observed result: the missing transport error is gone and the real
upstream returns an HTTP handshake response after connecting through
SOCKS. The upstream's HTTP 426 remains; this is not evidence of a
successful upstream WebSocket session.
- Provider/model scope: this is a transport/handshake check, so no model
request was sent. The fresh validation above specifically verifies the
locked 3.1.1 transport rather than claiming a model completion over
WebSocket.
- Version clarification: the original manual observation preceded the
refreshed lockfile. This new before/after run explicitly tests the
currently locked 3.1.1; it does not claim every version allowed by
`>=2.7.1` was tested.
- Not tested: clean install of a built Headroom distribution,
Linux/Windows runtime, successful upstream WebSocket inference, or the
full suite.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: `headroom-ai[proxy]` and extras that
include it install one pure-Python SOCKS transport dependency; no
request routing or compression behavior changes without a SOCKS proxy.
- Kill switch / disable path: remove SOCKS proxy configuration from the
process/system environment.
- Unsafe override required: no.
- Qualification impact: package extras and lockfile only.
- Rollback path: revert this commit or deploy the prior package release.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A.

## Additional Notes

### Dependency review

- **Why this package:** `websockets` delegates its optional SOCKS
transport to `python-socks`; adding the `asyncio` extra supplies the API
its runtime imports. Reimplementing SOCKS in Headroom would duplicate
that upstream transport without changing the integration point.
- **Maintainer and activity:** upstream is
[romis2012/python-socks](https://github.com/romis2012/python-socks),
maintained under the `romis2012` account. The repository is not
archived. Recent GitHub releases include 2.8.2 (2026-06-23), 3.0.0
(2026-08-11), and 3.1.0/3.1.1 (2026-09-08).
- **Security history checked:** an [OSV](https://osv.dev/) query for
PyPI `python-socks` 3.1.1 on 2026-10-07 returned no advisory records for
that version. This is a bounded database check, not a claim that the
package has never had a security issue.
- **Install surface:** the locked wheel is `py3-none-any` (pure Python).
On Python <3.11, the `asyncio` extra additionally requires
`async-timeout>=5.0.1`; on Python >=3.11 it adds no extra dependency.
The `trio` and `anyio` extras are not selected. Installation downloads
the package from PyPI; using the transport connects to the configured
SOCKS proxy and upstream. No separate native build or model download is
needed by this dependency.
- **Why this version:** the new dependency is needed for SOCKS
functionality in `websockets`, not a cosmetic upgrade. The requirement
remains `python-socks[asyncio]>=2.7.1`; the refreshed lock resolves
3.1.1, and the current runtime proof tests that exact release. Existing
package versions are unchanged relative to the refreshed main parent.

The package-contract test verifies the install extra. The real network
handshake above separately verifies runtime transport discovery.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3357"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->
## Maintainer qualification — current main refresh

Current head: `0caa86656b9876705bfd80bd590070159e70df27`, containing
main `01d9194854233ef6ed04005cf0a5b8c32bf65d6d`.

The metadata/lock conflict retains current main's packaging and adds the
original `python-socks[asyncio]>=2.7.1` proxy dependency. The
regenerated lock preserves all 251 main package identities and all
existing non-project package records, adding only `python-socks`
**3.1.1**. Current qualification targets that locked release; any
earlier 3.0.0 report is historical rather than evidence for the
currently locked package.

Validation: three optional-dependency tests pass; Ruff, formatting, and
changed-file whitespace checks pass. A controlled runtime check on
Windows with Python **3.12.13**, `python-socks` **3.1.1**, and
`websockets` **16.0** established a WebSocket through a loopback SOCKS5
server and round-tripped `headroom-socks-runtime-probe`. Captured
output: `PASS loopback WebSocket through SOCKS5: Python 3.12.13,
python-socks 3.1.1, websockets 16.0; no provider/model used`.

This is a local transport smoke check, with no provider/model or
external provider request. It establishes the selected transport
dependency loads and works together with the WebSocket client; it does
not claim production-provider qualification. Hosted checks on the
refreshed head still require completion, and the existing
dependency-provenance review remains available for reconciliation. No PR
merge performed.
Dependency provenance for the currently locked **3.1.1** release: PyPI
and installed wheel metadata identify
`https://github.com/romis2012/python-socks`; the upstream repository is
not archived and reports activity on **2026-09-08**. The license is
**Apache-2.0**. The installed wheel is pure Python (`Root-Is-Purelib:
true`, `py3-none-any`). The selected asyncio extra requires
`async-timeout>=5.0.1` only on Python below 3.11; Trio and AnyIO
dependencies are optional extras and are not selected by this change. A
targeted OSV query for PyPI `python-socks` **3.1.1** on **2026-10-09**
returned no vulnerability records. Captured package metadata, repository
metadata, OSV response, and the controlled transport output support this
current-release qualification.

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-28 17:53:51 -05:00
09b7e8c1e4 fix(packaging): rename the sandbox extra to lean and correct SECURITY.md claims (#3727)
**Revised 2026-10-05 after review:** tests now patch the deployment root
directly (never HOME) and assert POSIX modes only where enforced, the
supported-versions test follows the latest-release policy, and runner
scripts are recreated rather than truncated so a key is never written at
an old 0755 mode.

## Description

Security-remediation item A-10 (P-21, P-22). Renames the misleading
`sandbox` extra to `lean` (keeping `sandbox` as a deprecated alias for
one release, so `pip install "headroom-ai[sandbox]"` keeps working; not
a breaking change), corrects SECURITY.md's credential claims, and makes
the `headroom install --env` credential-persistence path owner-only and
documented. Details below.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update

## Changes Made

- `pyproject.toml`: `sandbox` extra renamed to `lean`; `sandbox =
["headroom-ai[lean]"]` deprecated alias; `uv.lock` regenerated (`uv lock
--check` clean).
- CI `python-314-wheels`, `run-all-plugins.sh` and the installation
guide now use `[lean]`.
- SECURITY.md: latest-release support policy (from main); discloses the
Copilot OAuth token and the `install --env` persistence path with its
modes.
- `headroom/install/paths.py`: `chmod_owner_only` verifies and reports
the mode it set.
- `headroom/install/state.py`: profile dir 0700 / manifest 0600 on every
save; warns if the directory cannot be narrowed.
- `headroom/install/supervisors.py`: runner scripts 0700 (`.ps1` 0600),
created fresh (old file removed first, so `O_TRUNC` cannot keep a 0755
mode while secrets are written), fail closed on POSIX if the mode cannot
be set.
- Tests: deployment writes are routed through a monkeypatched deploy
root; POSIX-mode assertions are skipped where modes are not enforced
(Windows).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ LITELLM_LOCAL_MODEL_COST_MAP=True uv run --frozen --extra dev --extra proxy pytest -q \
    tests/test_packaging_extras_and_security_docs.py tests/test_install/ tests/test_optional_dependencies.py
209 passed, 7 skipped
$ ruff check / ruff format --check (touched files)   -> clean
$ uv lock --check                                    -> Resolved 251 packages
```

Fail-before (2026-10-05 revision):

```text
test_rewriting_an_old_script_never_writes_secrets_at_its_old_mode   (fix reverted) FAILED assert 493 == 448 (0755 != 0700)
test_security_policy_supports_the_latest_release_without_a_version_number
                                                     (pinned 0.39.x table restored) FAILED
test_unrestrictable_profile_dir_warns_and_still_saves with Path.home() forced to ignore $HOME (as on Windows):
  previous version wrote <fake-home>/.headroom/deploy/default/manifest.json; new version writes nothing outside tmp_path
```

## Real Behavior Proof

- Environment: macOS (Darwin 25.6), CPython 3.14 via `uv run --frozen`,
branch head after merging main.
- Exact command / steps: with `HEADROOM_WORKSPACE_DIR` pointed at a temp
dir containing a pre-existing 0755 `deploy/default/` and 0755
`run-headroom.sh` (simulating a profile from an earlier version), ran
the real `build_manifest(..., extra_env={"ANTHROPIC_API_KEY": ...})` ->
`save_manifest` -> `render_runner_scripts`, then `stat` on every file.
- Observed result: `default/` 0700, `manifest.json` 0600,
`run-headroom.sh` 0700, `ensure-headroom.sh` 0700. `uv.lock` records
`headroom-ai[lean]` under marker `extra == 'sandbox'`, so the alias
resolves.
- Not tested: Windows end-to-end (ACL behaviour; mode assertions are
skipped there by design), a real `pip install "headroom-ai[sandbox]"`
from a published wheel, supervisor registration (launchd/systemd).

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a (install-time file modes and packaging
metadata).
- Stable/default behavior changed: yes - deployment profile dirs and
runner scripts are owner-only after the next `headroom install apply`
(see release note below). `[sandbox]` keeps installing the same
dependencies.
- Kill switch / disable path: none; re-running an older version restores
old modes.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert the PR; existing files keep their narrowed
modes, which is harmless.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

History of the change and the earlier review rounds follows.

---

Security-remediation item **A-10** (P-21, P-22). Two documentation
defects, each of which leads a reader to a false premise about the
product.

## 1. The `sandbox` extra promises isolation it does not provide

`headroom-ai[sandbox]` is a **dependency profile** — a torch-free subset
of `[all]`. It provides no isolation, no confinement and no privilege
reduction of any kind. The name invites exactly the wrong assumption,
and "we run it in the sandbox extra" is the kind of sentence that ends
up in someone's control narrative.

Renamed to **`lean`**, which describes what it actually is. `sandbox` is
kept as a deprecated alias forwarding to `[lean]` for one release,
because our own `python-314-wheels` CI job installs it
(`.github/workflows/ci.yml:218`) and so may customers. The alias
forwards rather than duplicating the dependency list, so the two cannot
drift.

## 2. SECURITY.md is stale and overclaims

- **Supported-versions table sat at 0.27.x** while the code ships 0.38.0
— four minor releases behind. A lagging table is worse than none: it
tells a reporter their release is unsupported when it is the current
one.
- **"No credential storage: We never store or log API keys"** is broader
than the code supports. `headroom/copilot_auth.py:646` persists the
GitHub Copilot OAuth refresh token to `~/.headroom/copilot_auth.json`.
It does so correctly — `chmod 0600` at `:648` — but it *is* stored, and
a blanket denial is the sort of claim a customer's security reviewer
checks.

The replacement says what is actually true: provider API keys are read
from the environment and forwarded without being written to disk; the
Copilot OAuth token is the one deliberate exception; and
request/response bodies may reach the runtime log when logging is
enabled, so that log is sensitive.

## Tests (original revision)

`tests/test_packaging_extras_and_security_docs.py` — four tests, all
failing before and passing after:

```
FAILED test_sandbox_alias_still_resolves_to_the_lean_profile
FAILED test_lean_profile_stays_torch_free
FAILED test_security_policy_supported_versions_match_the_shipped_version
FAILED test_security_policy_does_not_claim_blanket_no_credential_storage
4 failed  ->  4 passed
```

Method: commit, `git checkout origin/main -- pyproject.toml SECURITY.md`
(keeping the new tests), run, restore.

The version-table test is the one that matters most — main now documents
"latest release on PyPI" as the supported version, and the test (renamed
`test_security_policy_supports_the_latest_release_without_a_version_number`)
pins that and fails if a hard-coded version row returns, so **the table
cannot silently rot again**. That drift, not the wrong number, is the
actual defect.

`test_lean_profile_stays_torch_free` guards the profile's whole reason
for existing: adding a torch-pulling extra to it now fails the build by
name.

## Not done here

The backlog pairs this with a deprecation *warning* on the old extra
name. pip has no mechanism to warn on an extra at install time, so the
alias plus the comment is the available remedy; removal is noted for
after 0.39.x.

Ruff 0.16.7 `check` + `format --check` clean.

---

## Follow-up: the credential-persistence path (review of this PR)

@JerrettDavis blocked the first version because the SECURITY.md
*correction* was
itself inaccurate — it claimed provider API keys are not written to
disk, which
`headroom install --env KEY=VALUE` falsifies. Addressed in 3da8b955 by
disclosing the path accurately **and** narrowing its permissions.

What the trace found: `--env` values are merged into
`DeploymentManifest.base_env`
and persisted verbatim — into `manifest.json` *and*, as cleartext
`export` lines,
into the generated `run-headroom.sh` / `ensure-headroom.sh`. The
manifest was
already 0600, but only incidentally (via `mkstemp`), with nothing
pinning it. The
runner scripts were **0755** and the profile directory **0755** — a live
API key
in a world-readable file.

Persistence is kept: supervisors start from a bare environment, so
`--env` is the
only channel that reaches a supervised proxy. Redacting secret-valued
entries
would leave existing installs starting a proxy with no credential — a
silent 401
after upgrade. Instead: manifest 0600, runner scripts 0700 (0600 for the
`.ps1`),
profile directory 0700, applied on every save so pre-existing profiles
are
narrowed too; scripts created via `os.open(..., mode)` so no
world-readable window
exists between write and chmod.

SECURITY.md now names the files, the modes, that owner-only is not
encryption,
that rotation means re-running `install apply`, and that the Docker
runtime also
places the value in the container command line (`ps`-visible). The
`--env` help
text says the same.

The policy test now drives the real path — `build_manifest` →
`save_manifest` →
`render_runner_scripts` with a provider key against a fake `$HOME` —
asserts the
key really lands in both files, and **parses the documented octal modes
back out
of SECURITY.md** to compare against `stat()`, so the document and the
code cannot
drift apart again.

```
FAILED test_install_env_persists_a_provider_key_exactly_as_the_policy_describes
FAILED test_security_policy_discloses_the_persistent_install_credential_path
FAILED test_save_manifest_writes_owner_only
FAILED test_save_manifest_narrows_a_profile_directory_created_before_this_change
FAILED test_render_runner_scripts_are_owner_only_because_they_export_secrets
       (run-headroom.sh is 0755, exposing an API key)
FAILED test_render_unix_runner_narrows_a_script_written_by_an_earlier_version
6 failed  ->  315 passed
```

### ⚠️ Release note — behaviour change

Existing deployment profiles are **re-permissioned on the next `headroom
install
apply`**: `~/.headroom/deploy/<profile>/` and its runner scripts drop
group and
other bits (0755 -> 0700). Anyone reading or executing `run-headroom.sh`
as a
different, non-root user must now do so as the owner. No supported
supervisor
configuration does this — user scope runs as the installing user, system
scope as
root — but it changes the mode of files that already exist on customer
machines.
`--env` itself is unchanged: no value is dropped, redacted or relocated.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3727"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 14:56:54 -07:00
Tejas ChopraandClaude Fable 5.1 3c6f82b060 deps: require Python 3.11; clear Dependabot alerts in the 3.10 lock fork (#4517)
## Description

Vanta/Dependabot report 64 open alerts on this repo. 59 of them are
pillow, filelock and virtualenv versions that exist only in the Python
3.10 split of `uv.lock`: the patched releases (pillow 13, filelock 4.2)
require Python 3.11, so Dependabot could not open a fix PR. Python 3.10
reached end of life in October 2026 and CI already tests only 3.11, 3.12
and 3.14.

The second commit also fixes the two `security.yml` jobs that fail on
`main` today: pip-audit (litellm CVE-2026-114612) and the e2e npm audit
(three undici advisories published after #4453 for the copy bundled
inside npm).

## Type of Change

- [x] Breaking change: `pip install headroom-ai` now refuses Python 3.10
- [x] Bug fix: security patches

## Changes Made

- `requires-python = ">=3.11"`; drop the 3.10 classifier and the `tomli`
backport dependency
- pillow override and filelock floor lose their `python_version` markers
- mypy `python_version = "3.11"`; the three `tomli` import fallbacks in
`headroom/` become plain `import tomllib`
- ruff `target-version` stays `py310` with a note: moving it raises 213
pyupgrade findings (UP017/UP036/UP041/UP042), a separate mechanical PR
- `uv.lock` re-resolved: pillow 13.0.0, filelock 4.2.4, virtualenv
21.14.13 (single entry each, the 3.10 fork is gone)
- gitpython 3.1.62 → 3.2.1, strands-agents 1.24.0 → 1.62.0, litellm
1.101.0 → 1.101.3
- `e2e/wrap/tools/npm-audit-exceptions.json`: three further undici 6.x
advisories added at the existing exact path and version, expiry
unchanged (2026-11-15)
- README, CONTRIBUTING and the Dockerfile comment updated

Clears 61 of the 64 Dependabot alerts. The remaining 3 (undici,
ip-address) live inside the bundled dependencies of the `npm` package in
`e2e/wrap/tools/package-lock.json`; npm 12.2.1 is the newest release and
still ships them, so there is no bump available yet.

## Dependencies & supply chain

**gitpython 3.1.62 → 3.2.1.** Already a dependency; bumped for a
security patch (CVE-2026-114145). Maintained by the gitpython-developers
org (Sebastian Thiel), monthly-ish releases, long advisory history with
prompt fixes. Install surface unchanged: pure-Python wheel
(`py3-none-any`), one runtime dependency (`gitdb`), no native code, no
install-time or runtime network of its own.

**strands-agents 1.24.0 → 1.62.0.** Already a dependency behind the
`[strands]` extra; bumped for a security patch (CVE-2026-115419, fixed
in 1.43.0; the lock takes the current release). Maintained by AWS
(strands-agents org, `opensource@amazon.com`), weekly releases. Install
surface: pure-Python wheel, no native code. Declared dependencies grow
by two, `httpx` and `pyyaml`, both already in the lock for other
packages, so no new transitive packages are introduced. Runtime network
is unchanged: it calls the model provider the user configures, as
before.

**litellm 1.101.0 → 1.101.3.** Already a core dependency; patch bump for
CVE-2026-114612, the smallest fix that keeps the `filelock>=4.2.1` floor
resolvable (litellm 1.106 caps filelock <4). No change to maintainers or
install surface.

**pillow, filelock, virtualenv.** No new packages; the lock now holds
the single patched version the 3.11+ fork already had.

## Testing

- [x] Linting passes (`ruff check .`, `ruff format --check .`)
- [x] Type checking passes (`mypy headroom`): 1 error, identical to main
(`langchain/chat_model.py:380`)
- [x] Unit tests (targeted, see below)

### Test Output

```text
$ pytest -q tests/test_litellm_optional.py tests/test_dependency_overrides.py tests/test_release_workflows.py tests/test_image_decoder_guard.py tests/test_optional_dependencies.py tests/test_onnx_dependency_contract.py
74 passed in 3.07s

$ grep -rl -E "headroom\.release_version|headroom\.providers\.codex\.project_context|headroom\.cli\.wrap" tests | xargs pytest -q
4 failed, 1043 passed in 28.03s     # same 4 in tests/test_cli/test_wrap_persistent.py fail on main

$ uv run --extra strands --extra dev -m pytest -q tests/integrations/test_strands tests/test_strands_tokenizer.py
18 failed, 87 passed in 52.30s      # the 18 are *Real classes needing live AWS Bedrock creds; main fails the same 18 on 1.24.0

$ uv export --frozen --no-dev --no-emit-project --no-hashes --extra all --format requirements-txt > requirements-prod.txt
$ uvx pip-audit==2.10.1 -r requirements-prod.txt --no-deps --disable-pip
No known vulnerabilities found

$ cd e2e/wrap/tools && npm audit --package-lock-only --json > audit.json && <security.yml check script>
unexpected: []  stale: []  seen: 6
```

## Real Behavior Proof

- Environment: macOS 27.2 arm64; uv-managed CPython 3.11.16 and 3.10;
the lock from this branch.
- Exact command / steps:
  ```text
$ uv run --python 3.11 --all-extras python -c "import sys, platform,
headroom, PIL, filelock, virtualenv, git, strands, litellm,
importlib.metadata as m; ..."
$ uv venv -p 3.10 /tmp/py310-venv && uv pip install --python
/tmp/py310-venv/bin/python --dry-run .
  ```
- Observed result:
  ```text
  macOS-27.2-arm64-arm-64bit
  python 3.11.16
  pillow 13.0.0
  filelock 4.2.4
  virtualenv 21.14.13
  gitpython 3.2.1
  strands-agents 1.62.0
  litellm 1.101.3

(3.10) ... headroom-ai==0.42.0 depends on Python>=3.11, we can conclude
that headroom-ai==0.42.0 cannot be used.
And because only headroom-ai==0.42.0 is available and you require
headroom-ai, we can conclude that your requirements are unsatisfiable.
  ```
- Not tested: Linux and Windows installs (CI wheel matrix covers them);
a live Bedrock run of the strands integration; the Docker image build.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: installs on Python 3.10 are refused
at resolve time; no runtime behavior change on 3.11+
- Kill switch / disable path: n/a
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the PR

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] New and existing unit tests pass locally with my changes (targeted
runs above; pre-existing failures noted)
- [x] I did **not** edit `CHANGELOG.md`
- [ ] New tests added: n/a, dependency and metadata change; existing
contract tests cover the floor and the pillow override

## Additional Notes

Follow-ups, not in this PR:
- ruff `target-version = "py311"` plus the pyupgrade fixes
- remaining `tomli` fallbacks in `tests/` and the `sys.version_info <
(3, 11)` branches they guard
- `python_version < '3.11'` branches in the onnxruntime markers (now
dead but harmless)
- `pyo3` `abi3-py310` in `Cargo.toml` could move to `abi3-py311`
- the 3 remaining Dependabot alerts (bundled undici/ip-address in npm)
until an npm release replaces them

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-28 07:28:07 -07:00
JD Davisandgithub-actions[bot] 17d38e5699 chore: release 0.42.0 (#4228)
🤖 I have created a release *beep* *boop*
---


##
[0.42.0](https://github.com/headroomlabs-ai/headroom/compare/v0.41.0...v0.42.0)
(2026-10-26)


### Features

* **pipeline:** put per-request saved tokens on OutcomeSnapshot
([#4231](https://github.com/headroomlabs-ai/headroom/issues/4231))
([8cedf7b](https://github.com/headroomlabs-ai/headroom/commit/8cedf7be4decfb3a0da42e4e955b6a3301a66dc9))
* **proxy:** let turn hooks rewrite OpenAI Responses requests on HTTP
and WebSocket
([#4232](https://github.com/headroomlabs-ai/headroom/issues/4232))
([fbf7bc3](https://github.com/headroomlabs-ai/headroom/commit/fbf7bc3278c11975299b9bd0a2ecf200dfd25a05))
* **proxy:** report the same tool savings on gateway /v1/compress as the
proxy path
([#4467](https://github.com/headroomlabs-ai/headroom/issues/4467))
([a904210](https://github.com/headroomlabs-ai/headroom/commit/a90421083a781990b877d34fdaba0bc1b6cf6c4d))
* **savings:** add the per-request counterfactual savings record
([#4236](https://github.com/headroomlabs-ai/headroom/issues/4236))
([2912b7b](https://github.com/headroomlabs-ai/headroom/commit/2912b7b620d7abd39828db73e4f326b9a041d309))


### Bug Fixes

* **batch:** preserve live contexts during capacity cleanup
([#4210](https://github.com/headroomlabs-ai/headroom/issues/4210))
([2cbdd22](https://github.com/headroomlabs-ai/headroom/commit/2cbdd22a65789676d9ebbd9e2b6a908e7f8fad95))
* **batch:** preserve native Gemini continuation tools
([#4211](https://github.com/headroomlabs-ai/headroom/issues/4211))
([8757458](https://github.com/headroomlabs-ai/headroom/commit/875745889ff065208d3a32aa583881468ae7c41d))
* **cache:** bound the router's compression cache, keep the rest in
SQLite
([#4357](https://github.com/headroomlabs-ai/headroom/issues/4357))
([b196424](https://github.com/headroomlabs-ai/headroom/commit/b196424e35df0afc0c8576aea1950ed16b00e027))
* **cache:** keep indented lines intact in OpenAI whitespace
normalization
([#4343](https://github.com/headroomlabs-ai/headroom/issues/4343))
([2480100](https://github.com/headroomlabs-ai/headroom/commit/248010091578e1f05ebcf65c8146bb57f9fb4e00))
* **cache:** keep prefix-tracker state across a graceful proxy restart
([#4299](https://github.com/headroomlabs-ai/headroom/issues/4299))
([62b3bed](https://github.com/headroomlabs-ai/headroom/commit/62b3bedaba988de87e38b1a58c11d28baaba7dbf))
* **ccr:** recognize client-owned MCP retrieval aliases
([#4165](https://github.com/headroomlabs-ai/headroom/issues/4165))
([89545fb](https://github.com/headroomlabs-ai/headroom/commit/89545fbdf3873f75461f71a03c89b1f9c64d650d))
* **ccr:** stream the buffered CCR upstream request so idle-killing
networks cannot cut it
([#4206](https://github.com/headroomlabs-ai/headroom/issues/4206))
([ca6ba34](https://github.com/headroomlabs-ai/headroom/commit/ca6ba3486c09badecb1bfe99ddabf562c9f01c77))
* **ci:** pin checkout in release notification smoke workflow
([#4399](https://github.com/headroomlabs-ai/headroom/issues/4399))
([70273db](https://github.com/headroomlabs-ai/headroom/commit/70273db0af392e8f971d42e21484656676255d0b))
* **copilot:** detect COPILOT_API_URL in cli-main.js for Copilot CLI
&gt;= 1.0.93
([#4450](https://github.com/headroomlabs-ai/headroom/issues/4450))
([043fe09](https://github.com/headroomlabs-ai/headroom/commit/043fe09d8c620201045619bcbcd88e26e2c6e71f))
* **copilot:** preserve native inline OAuth identity
([#4144](https://github.com/headroomlabs-ai/headroom/issues/4144))
([ad62166](https://github.com/headroomlabs-ai/headroom/commit/ad62166ba3056e5b98fc5bfee19f0c9b6c316e8d))
* **deps:** bump rustls to 0.23.46 for RUSTSEC-2026-0346..0349
([#4222](https://github.com/headroomlabs-ai/headroom/issues/4222))
([132dbc7](https://github.com/headroomlabs-ai/headroom/commit/132dbc76995cdbecc25b4f647dbf919351cd5f7f))
* **deps:** patch OpenClaw Undici and narrow E2E audit exceptions
([#4453](https://github.com/headroomlabs-ai/headroom/issues/4453))
([1be699f](https://github.com/headroomlabs-ai/headroom/commit/1be699f68ee884c5c319cee9841ca304e448873c))
* **deps:** require hf-xet&gt;=1.6.0 so a Hub download can't crash
Python at exit
([#4192](https://github.com/headroomlabs-ai/headroom/issues/4192))
([9e5dac7](https://github.com/headroomlabs-ai/headroom/commit/9e5dac7c74979abd8d1b9ad9615443b76e42b530))
* **deps:** require mcp&gt;=1.30.0 for CVE-2026-59951
([#4239](https://github.com/headroomlabs-ai/headroom/issues/4239))
([2f7a83a](https://github.com/headroomlabs-ai/headroom/commit/2f7a83a91d3ca33a79b5c41b8095f6454b5bfb43))
* **gateway:** keep input_includes_cache when re-drive usage is merged
([#4423](https://github.com/headroomlabs-ai/headroom/issues/4423))
([3f94144](https://github.com/headroomlabs-ai/headroom/commit/3f941446bfbeb0b66cf6eb4a1ddf254e17d0c2a4))
* **gemini:** keep snake_case inline_data and function parts when
compressing
([#4290](https://github.com/headroomlabs-ai/headroom/issues/4290))
([4bf1bf5](https://github.com/headroomlabs-ai/headroom/commit/4bf1bf55d175ad047c32cc3049aeff51126424c8))
* **image:** clear last_result before each compress() call
([#4341](https://github.com/headroomlabs-ai/headroom/issues/4341))
([19c91a8](https://github.com/headroomlabs-ai/headroom/commit/19c91a870fac09f824001197e72c8929698ea0b8))
* **image:** flatten transparent images onto white before re-encoding as
JPEG ([#4296](https://github.com/headroomlabs-ai/headroom/issues/4296))
([9f5cfcf](https://github.com/headroomlabs-ai/headroom/commit/9f5cfcfd2bb90097f79144ff3821fc7db9fe36d5))
* **install:** keep the HuggingFace cache on a writable mount in Docker
presets
([#4207](https://github.com/headroomlabs-ai/headroom/issues/4207))
([#4209](https://github.com/headroomlabs-ai/headroom/issues/4209))
([7b6cb77](https://github.com/headroomlabs-ai/headroom/commit/7b6cb7790552ac10f0135013337ea4a09a9e951e))
* **kompress:** skip the local model download when a remote endpoint is
set ([#4234](https://github.com/headroomlabs-ai/headroom/issues/4234))
([ff36931](https://github.com/headroomlabs-ai/headroom/commit/ff3693165344410eaf2882209648e504f9d3eaf0))
* **kompress:** time each model-load stage and stop false not-ready
warnings during warm-up
([#4195](https://github.com/headroomlabs-ai/headroom/issues/4195))
([89b229c](https://github.com/headroomlabs-ai/headroom/commit/89b229ce5feaeb8710f4e226a47697426231ca55))
* **learn:** anchor the managed block on its last start marker, append
when no end marker
([#4342](https://github.com/headroomlabs-ai/headroom/issues/4342))
([45dacc1](https://github.com/headroomlabs-ai/headroom/commit/45dacc1f94a4343c76a6e257143d22d67dc713f0))
* **learn:** keep the digest's loop section inside its budget
([#4269](https://github.com/headroomlabs-ai/headroom/issues/4269))
([506ba16](https://github.com/headroomlabs-ai/headroom/commit/506ba16c4a7f231b177d28066bcda389133a5e91))
* **logs:** count omitted levels from dropped lines
([#4141](https://github.com/headroomlabs-ai/headroom/issues/4141))
([023dd1b](https://github.com/headroomlabs-ai/headroom/commit/023dd1bc5402dcebf52a5ed3cf6a2a2878a524d9))
* **mcp:** accept the JSONC opencode config that wrap and install
already accept
([#4297](https://github.com/headroomlabs-ai/headroom/issues/4297))
([9202948](https://github.com/headroomlabs-ai/headroom/commit/9202948c1e57a4ab8daa7c00c400605844c19f4f))
* **memory:** bound retrieval queries before embedding
([#4244](https://github.com/headroomlabs-ai/headroom/issues/4244))
([8c07cf4](https://github.com/headroomlabs-ai/headroom/commit/8c07cf4a0fff1b67da1b542dc746b0b4a0e952e6))
* **memory:** ignore incidental cwd prose
([#4166](https://github.com/headroomlabs-ai/headroom/issues/4166))
([3765439](https://github.com/headroomlabs-ai/headroom/commit/37654390b60ccb7658bb96a2f177b8666c7b7273))
* **memory:** log storage and SQLite failures that currently make
retrieval miss silently
([#4111](https://github.com/headroomlabs-ai/headroom/issues/4111))
([4e6e955](https://github.com/headroomlabs-ai/headroom/commit/4e6e955cad0bff318e30bd4f24e934a23f57e9c6))
* **memory:** resolve partial IDs beyond the first 1000 records
([#4389](https://github.com/headroomlabs-ai/headroom/issues/4389))
([c4ea31b](https://github.com/headroomlabs-ai/headroom/commit/c4ea31b156478adde015833074ad7278230b4512))
* **memory:** treat a cwd with no UTF-8 form as unresolved instead of
raising
([#4167](https://github.com/headroomlabs-ai/headroom/issues/4167))
([760c05e](https://github.com/headroomlabs-ai/headroom/commit/760c05e1b0ff8c34443f5d6eba0c4ff36f171eb2))
* **openai:** read Responses cache_write_tokens instead of inferring
writes
([#4237](https://github.com/headroomlabs-ai/headroom/issues/4237))
([4630602](https://github.com/headroomlabs-ai/headroom/commit/46306024e74b3a44aca17fb70c1416f96b2a0b53))
* **openai:** recompress cached Responses units whose CCR entries
expired
([#4146](https://github.com/headroomlabs-ai/headroom/issues/4146))
([8f7b419](https://github.com/headroomlabs-ai/headroom/commit/8f7b41998076727d08e5db4ee57c8bd579988c30))
* **opencode:** do not rewrite an OpenCode config that fails to parse
([#4424](https://github.com/headroomlabs-ai/headroom/issues/4424))
([0fe0a59](https://github.com/headroomlabs-ai/headroom/commit/0fe0a597c1929bcb4a7372e6689fd62410bad9d2))
* **opencode:** restore process env keys on transport dispose
([#4430](https://github.com/headroomlabs-ai/headroom/issues/4430))
([d17bac8](https://github.com/headroomlabs-ai/headroom/commit/d17bac8d64dd74ade81638ac7170715851c9704b))
* **pricing:** suppress litellm's Provider List banner that corrupts
perf JSON
([#4197](https://github.com/headroomlabs-ai/headroom/issues/4197))
([e01ad35](https://github.com/headroomlabs-ai/headroom/commit/e01ad350dc71d44f1a4e07df5ea4e45fa39a4773))
* **proxy:** accept HEADROOM_MEMORY_INJECTION_MODE=tool
([#4395](https://github.com/headroomlabs-ai/headroom/issues/4395))
([f89c928](https://github.com/headroomlabs-ai/headroom/commit/f89c9282a8216b8e168c29d85c6f13c5ce7d6301))
* **proxy:** bound per-model state keyed by the client model string
([#4407](https://github.com/headroomlabs-ai/headroom/issues/4407))
([33e5f67](https://github.com/headroomlabs-ai/headroom/commit/33e5f67464286961f37d09298d31c5022d275a32))
* **proxy:** copy cached tool compaction results (hardening)
([#4410](https://github.com/headroomlabs-ai/headroom/issues/4410))
([a256231](https://github.com/headroomlabs-ai/headroom/commit/a25623109d5075276af057e79c3ed3e309906563))
* **proxy:** count output tokens from CRLF-framed SSE streams too
([#4298](https://github.com/headroomlabs-ai/headroom/issues/4298))
([755293d](https://github.com/headroomlabs-ai/headroom/commit/755293dd68d495b6fcec15fd47d324c3ce5eeefa))
* **proxy:** do not rebuild a failed turn-hook re-drive as HTTP 200
([#4398](https://github.com/headroomlabs-ai/headroom/issues/4398))
([f59c8ff](https://github.com/headroomlabs-ai/headroom/commit/f59c8ffcd80f19564cf041d1fa4eb6247f2e1d01))
* **proxy:** drop web_search_call history from a Responses request with
no web_search tool
([#4202](https://github.com/headroomlabs-ai/headroom/issues/4202))
([2a70d12](https://github.com/headroomlabs-ai/headroom/commit/2a70d128195575cbc52129a5287a9a3ccc097744))
* **proxy:** honor bypass header and license gate in Anthropic batch
create
([#4411](https://github.com/headroomlabs-ai/headroom/issues/4411))
([4fd9cdd](https://github.com/headroomlabs-ai/headroom/commit/4fd9cddfd2e9cbbe38ab0b9d3acc6bc6f934a6e2))
* **proxy:** import Response at runtime in the Bedrock handler
([#4397](https://github.com/headroomlabs-ai/headroom/issues/4397))
([51e4ae3](https://github.com/headroomlabs-ai/headroom/commit/51e4ae36a5751fc494c0b583d37e62213e5a08a9))
* **proxy:** judge NAT64 upstream addresses by their embedded IPv4
([#4179](https://github.com/headroomlabs-ai/headroom/issues/4179))
([486afaa](https://github.com/headroomlabs-ai/headroom/commit/486afaac7426fa1d6735fe2ce6ae37630d9d11ae))
* **proxy:** keep in-period costs in the budget ledger when the entry
cap is reached
([#4448](https://github.com/headroomlabs-ai/headroom/issues/4448))
([41c15b3](https://github.com/headroomlabs-ai/headroom/commit/41c15b311cd5ab34d5108569eef4249a60973f96))
* **proxy:** keep negative compression savings across restart
([#4406](https://github.com/headroomlabs-ai/headroom/issues/4406))
([bebe24c](https://github.com/headroomlabs-ai/headroom/commit/bebe24c5ff0e815ac87937d9ecb1633a5091ab64))
* **proxy:** keep tool deferral for GitHub Copilot upstream
([#4356](https://github.com/headroomlabs-ai/headroom/issues/4356))
([217b658](https://github.com/headroomlabs-ai/headroom/commit/217b658845389e32a02760d75886de20d60e2ba3))
* **proxy:** let HEADROOM_LOG_LEVEL=debug turn on Headroom's own debug
logs ([#4137](https://github.com/headroomlabs-ai/headroom/issues/4137))
([00093ce](https://github.com/headroomlabs-ai/headroom/commit/00093ceddcf42c3936a96ea5f280af2d0e1b2e47))
* **proxy:** make handler failures debuggable from the logs
([#4127](https://github.com/headroomlabs-ai/headroom/issues/4127))
([7dc20b6](https://github.com/headroomlabs-ai/headroom/commit/7dc20b6fe027cf262c5e2d0415f0dbb2032ac73b))
* **proxy:** net tools a turn hook adds against the saving it books
([#4057](https://github.com/headroomlabs-ai/headroom/issues/4057))
([85520c2](https://github.com/headroomlabs-ai/headroom/commit/85520c2941ed6b2c4cd4bfd9f747b24227a256aa))
* **proxy:** record a stream the client closes after its terminal event
as completed
([#4286](https://github.com/headroomlabs-ai/headroom/issues/4286))
([762a337](https://github.com/headroomlabs-ai/headroom/commit/762a337bbeba268ae1e172c7a7de1e374231e32c))
* **proxy:** record outcome when a passthrough stream ends mid-character
([#4429](https://github.com/headroomlabs-ai/headroom/issues/4429))
([75cfbba](https://github.com/headroomlabs-ai/headroom/commit/75cfbba91d9bb2ff55df3949eddd4452dd9fb661))
* **proxy:** report disabled Kompress at startup
([#4217](https://github.com/headroomlabs-ai/headroom/issues/4217))
([430ea4f](https://github.com/headroomlabs-ai/headroom/commit/430ea4f4ebaeb0b217e237084963b64775bef24a))
* **proxy:** report read maturation as inert in cache mode
([#4198](https://github.com/headroomlabs-ai/headroom/issues/4198))
([ba82453](https://github.com/headroomlabs-ai/headroom/commit/ba824539d6f80c3e056f299789c1cf079a4693fe))
* **proxy:** show turn-hook savings in /stats extension_savings, incl.
Codex WS
([#4233](https://github.com/headroomlabs-ai/headroom/issues/4233))
([1d112cd](https://github.com/headroomlabs-ai/headroom/commit/1d112cd36c9aee765ec3b550773de0c93c6d79be))
* **proxy:** snapshot the original messages when a turn hook can edit
them ([#4241](https://github.com/headroomlabs-ai/headroom/issues/4241))
([df11f27](https://github.com/headroomlabs-ai/headroom/commit/df11f2749862a0090db11f7fca3e7dc42a75b612))
* **relevance:** load the default embedder from one pinned snapshot
([#4152](https://github.com/headroomlabs-ai/headroom/issues/4152))
([f380692](https://github.com/headroomlabs-ai/headroom/commit/f380692b463637e90de84f1b5cc29c7ae9f7b969))
* **savings:** key a Responses conversation on its thread, not the
shared session
([#4440](https://github.com/headroomlabs-ai/headroom/issues/4440))
([11f743d](https://github.com/headroomlabs-ai/headroom/commit/11f743dd90e9f60cf01805a23514bd06440dd2d2))
* **sdk:** preserve Vercel AI SDK file and image parts through
compression
([#4048](https://github.com/headroomlabs-ai/headroom/issues/4048))
([1668a6c](https://github.com/headroomlabs-ai/headroom/commit/1668a6c0dd73cd8a1b9d7fc5eae297149e8f7d93))
* **security:** restrict the Windows runtime log via NTFS ACL, not just
warn ([#4135](https://github.com/headroomlabs-ai/headroom/issues/4135))
([125a703](https://github.com/headroomlabs-ai/headroom/commit/125a703a65c574e9db809f95eefdc70407e0250e))
* **smart-crusher:** match audit-safe protected_patterns against
unescaped text
([#4294](https://github.com/headroomlabs-ai/headroom/issues/4294))
([e11afdb](https://github.com/headroomlabs-ai/headroom/commit/e11afdbdf8a729e50553681143d0f925b71fcd83))
* **storage:** normalize timezone-aware JSONL time filters
([#4063](https://github.com/headroomlabs-ai/headroom/issues/4063))
([bf34ccf](https://github.com/headroomlabs-ai/headroom/commit/bf34ccf58861a687e814abf1a158885987add9ae))
* **tabular:** pass tables with repeated header names through verbatim
([#4278](https://github.com/headroomlabs-ai/headroom/issues/4278))
([ed3195b](https://github.com/headroomlabs-ai/headroom/commit/ed3195beef1dcfbb0219c2da9b59984167c81c01))
* **telemetry:** give empty-item compressions a stable tool signature
([#4396](https://github.com/headroomlabs-ai/headroom/issues/4396))
([a79def4](https://github.com/headroomlabs-ai/headroom/commit/a79def4dd1b7217a75ce6c4eebd0b06ea3a70c1d))
* **telemetry:** let HEADROOM_TELEMETRY=off stop the anonymous beacon
([#4235](https://github.com/headroomlabs-ai/headroom/issues/4235))
([1a40b3c](https://github.com/headroomlabs-ai/headroom/commit/1a40b3ce67ad9e155ba768e8d05cec4c872c7f99))
* **transforms:** keep the fences of a code block passed through for a
protected tag
([#4292](https://github.com/headroomlabs-ai/headroom/issues/4292))
([02958c6](https://github.com/headroomlabs-ai/headroom/commit/02958c6ffe41a1d3466c21558670875df87384ae))
* **transforms:** log the compression failures that silently become "no
savings"
([#4092](https://github.com/headroomlabs-ai/headroom/issues/4092))
([580cc83](https://github.com/headroomlabs-ai/headroom/commit/580cc83a9a412123040978447a2c9b77c08670b0))
* **zcode:** skip providers that point at the Headroom proxy itself
([#4413](https://github.com/headroomlabs-ai/headroom/issues/4413))
([9ac1b52](https://github.com/headroomlabs-ai/headroom/commit/9ac1b52c2762bbc40d3e459e5f87cd4bbfbde8aa))


### Dependencies

* Bump base64 from 0.22.1 to 0.23.1
([#4029](https://github.com/headroomlabs-ai/headroom/issues/4029))
([8d468d4](https://github.com/headroomlabs-ai/headroom/commit/8d468d455c2e3c195cc2975bbc13e63d6b85ef59))
* Bump ruff from 0.16.8 to 0.17.0 in the pip-minor-patch group across 1
directory
([#4026](https://github.com/headroomlabs-ai/headroom/issues/4026))
([de3f639](https://github.com/headroomlabs-ai/headroom/commit/de3f639803f1f172f65c05c165bfab92c0bec9e8))
* Bump the cargo-minor-patch group across 1 directory with 12 updates
([#4186](https://github.com/headroomlabs-ai/headroom/issues/4186))
([683c9a6](https://github.com/headroomlabs-ai/headroom/commit/683c9a6120c309e84e4848378dbe3891d064f82e))
* Bump the npm-minor-patch group across 2 directories with 16 updates
([#4218](https://github.com/headroomlabs-ai/headroom/issues/4218))
([07c8bbf](https://github.com/headroomlabs-ai/headroom/commit/07c8bbf1edcc143a7fe97b9e29214355cc371a19))
* Bump the npm-minor-patch group across 3 directories with 12 updates
([#4219](https://github.com/headroomlabs-ai/headroom/issues/4219))
([1f71cb3](https://github.com/headroomlabs-ai/headroom/commit/1f71cb3d64e1586c97331a3482aae84558741102))
* Update huggingface-hub requirement from &lt;2.0,&gt;=1.5.0 to
&gt;=1.5.0,&lt;3.0
([#4027](https://github.com/headroomlabs-ai/headroom/issues/4027))
([fcf3db8](https://github.com/headroomlabs-ai/headroom/commit/fcf3db8e70d15aef0d80a561cf5d0e45e918a338))


### Code Refactoring

* **integrations:** share the local/cloud compress backend of asgi and
litellm_callback
([#4124](https://github.com/headroomlabs-ai/headroom/issues/4124))
([58caafb](https://github.com/headroomlabs-ai/headroom/commit/58caafb59b40c00b35ceee6237ef2289df71f25d))
* **transforms:** share one CCR persist helper for the Rust-backed
compressors
([#4094](https://github.com/headroomlabs-ai/headroom/issues/4094))
([ea947ca](https://github.com/headroomlabs-ai/headroom/commit/ea947ca421ee6d6b8f15a9ed522c3a3bea5a3225))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-10-26 18:03:36 -05:00
Tejas ChopraandClaude Opus 5.5 a616232d75 feat(compress): share /v1/compress sessions across replicas via Redis (#4369)
Stacked on #4368 (Redis CCR store); merge that first.

## Why
A session-aware `/v1/compress` turn must return the prefix it returned
last turn byte for byte, or the provider's prompt cache misses. That
state (the session's prefix tracker) lived only in the memory of the
replica that served the turn, so a gateway with several replicas had to
pin sessions (`session_affinity`). Kong's AI Gateway runs several
instances without sticky sessions.

## Change
With `HEADROOM_COMPRESS_SESSION_STORE=redis://…`
(`headroom/cache/shared_sessions.py`), every replica keeps each session
in Redis too:

- **Messages, stored once by digest** (`…:msgs`). The original and
returned transcripts mostly share messages, and each turn mostly repeats
the last one, so a turn writes only what Redis lacks: the messages it
added, plus any whose bytes changed (a moved cache marker, an edit, a
compaction). Unreferenced messages are pruned.
- **Metadata** (`…:meta`): the tracker's counters, its transcripts as
digest lists, and a random write token.
- **Before a turn**, the replica reads the token. If another replica
wrote since, it reads the metadata and only the messages it lacks, each
checked against its digest. The turn then seeds its compression cache
from that tracker, as after a restart.
- **After the turn**, it writes the new messages, then the metadata via
a Lua compare-and-set on the token.
- A random token, not a counter: a lost key or a failover can't leave a
replica trusting stale state.
- The script also detects a messages hash that `maxmemory` evicted on
its own; the writer then stores the session whole.
- A replica that finds corrupt or evicted state claims the token and
rewrites the session whole.
- **Usage relay:** fetches under the session's turn lock, and installs
only if no local turn installed a tracker meanwhile.
- **Failures:** a Redis error or corrupt value never fails a turn. The
replica serves from its own memory, as without the store. Clock skew
between replicas is tolerated.
- **CCR:** the setting also selects #4368's Redis CCR store unless
`HEADROOM_CCR_BACKEND` names another, so markers in a replayed
transcript resolve on any replica.
- **`SessionTrackerStore`** gains `encode_shared` / `decode_shared` (the
restart file's per-tracker encoding, split into metadata and message
table) and `install`.

## Results
**Real run:** 3 proxy processes on one Redis-protocol server (fakeredis
TCP server; no Redis on the test machine), a 20-turn `mode: "ccr"`
session sent round-robin:
- every turn's returned prefix was byte-identical to the previous
turn's;
- the CCR marker resolved via `/v1/retrieve` on all three replicas;
- Redis received **378 KB** over the 20 turns. Writing the whole
transcript every turn would have been about 4.9 MB, growing with the
square of the session length.

**Tests:** `tests/test_compress_session_shared.py`, each failure mode
mutation-checked:
- a stale replica reloads newer state;
- without the store, the other replica starts cold;
- a turn writes only the messages Redis lacks;
- a fully lost key is rewritten;
- a messages hash evicted on its own is rewritten;
- corrupt state is repaired by another replica;
- unreferenced messages are pruned;
- a writer whose clock runs ahead is trusted;
- the usage relay reaches and publishes a session served elsewhere;
- an outage or corrupt values never fail a turn;
- the CCR store follows the session store;
- a URL that isn't Redis stops startup.

818 proxy, gateway, session and restart tests pass. ruff and mypy are
clean.

## Notes
- Redis holds transcripts and tool output verbatim. Use `rediss://` with
authentication on a private network; plain `redis://` to a remote host
logs a warning.
- Re-drive turns still need affinity: they park a live in-process task
between two HTTP calls.
- About 540 added lines (excluding `uv.lock`), around 200 of them tests.
The `prefix_tracker` refactor can split out if reviewers prefer.

## Real Behavior Proof
- **Environment:** macOS 26.7.1 (arm64), Python 3.12.13, redis-py 8.1.0.
Redis is a fakeredis 2.40.0 `TcpFakeServer`, which speaks the Redis
protocol over TCP; no Redis server was on the test machine. Docker was
not available.
- **Configuration:** every replica has
`HEADROOM_COMPRESS_SESSION_STORE=redis://127.0.0.1:6391/0` (the CCR
store follows it) and its own `HEADROOM_WORKSPACE_DIR`.
- **Steps:**
  1. Start the fake server:
`python -c "from fakeredis import TcpFakeServer;
TcpFakeServer(('127.0.0.1', 6391),
server_type='redis').serve_forever()"`
  2. Start three proxies, one each on ports 8901, 8902 and 8903:
`HEADROOM_COMPRESS_SESSION_STORE=redis://127.0.0.1:6391/0
HEADROOM_WORKSPACE_DIR=<own dir> python -m headroom.cli proxy --port
<port>`
3. Drive one session for 20 turns, round-robin across the three: `POST
/v1/compress` with `{"messages": …, "session_id": "kong-e2e", "mode":
"ccr"}`. The transcript is the 25 KB tool history from
`tests/test_compress_session_mode.py`. Every third turn adds a 120-row
grep result; the other turns add a user line.
  4. After each turn, check:
- the returned messages start with the previous turn's returned
messages, byte for byte;
     - how many bytes the turn wrote to the `:msgs` hash.
5. Fetch each `<<ccr:hash>>` marker via `GET /v1/retrieve/{hash}` on all
three proxies.
- **Result** (after the review fixes, at 95b2d93a):
  - every turn's prefix is byte-identical to the previous turn's;
- Redis received 378 KB in total (63 KB at most in one turn), against
about 4.9 MB if the whole transcript were rewritten each turn;
  - the CCR marker resolved on all three replicas.
- **Not tested:**
- a real Redis or Redis Cluster (the Lua script and hash-tagged keys are
written for it);
  - TLS (`rediss://`) and AUTH;
  - Kong's AI Gateway in front of the replicas;
  - Windows;
  - real `maxmemory` eviction (simulated in tests by deleting keys);
  - sustained load.

## Dependencies and scope
- **No new runtime dependency:** this uses #4368's `[redis]` extra.
- **Dev only:** the `fakeredis` requirement becomes `fakeredis[lua]`,
which adds `lupa` so the tests run the compare-and-set Lua script
exactly as Redis would.
- **Why this feature:** Kong's AI Gateway runs several Headroom
instances with no sticky sessions and asked for session state in Redis.
It is opt-in: nothing changes unless `HEADROOM_COMPRESS_SESSION_STORE`
is set.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4369"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 23:52:06 -07:00
Tejas ChopraandClaude Opus 5.5 185454be49 feat(ccr): Redis backend, one CCR store for every replica (#4368)
## Why
A `<<ccr:hash>>` marker points at an original kept by the replica that
compressed it. Behind a gateway that spreads requests across replicas,
the retrieval can land on a replica that doesn't have it. Kong's AI
Gateway runs several Headroom instances without sticky sessions. The
`headroom.ccr_backend` entry point allowed a Redis store, but none
shipped.

## Change
- **Backend:** `HEADROOM_CCR_BACKEND=redis` + `HEADROOM_REDIS_URL`
(`headroom/cache/backends/redis.py`). One key per entry
(`<prefix>:ccr:<hash>`), stored as JSON and expiring with the entry's
TTL. A plugin registered as `redis` still takes precedence.
- **Connection helper** `headroom/cache/redis_client.py`, shared with
the follow-up sessions PR:
  - checks the URL scheme;
  - 1 s timeouts;
- `HEADROOM_REDIS_KEY_PREFIX` (default `headroom`; glob-escaped in SCAN
patterns);
- warns on plain `redis://` to a remote host, since Redis holds tool
output verbatim.
- Its `Guard` makes any Redis error a miss and logs when each kind of
call starts and stops failing. It skips Redis for 5 s after a connection
error, so an outage never fails or stalls a request.
- **`CompressionStore`** keeps no per-process cap or eviction/expiration
index for a backend that expires entries itself (`expires_entries`).
Counting the store would SCAN the shared keyspace on every write,
rebuilding the index would read every replica's entries under the store
lock, and a per-replica cap would evict other replicas' live entries.
- Optional extra: `[redis]`.

## Tests
`tests/test_ccr_redis_backend.py`:
- a marker stored by one replica is retrieved on another;
- Redis TTL matches the entry's TTL;
- key prefixes isolate deployments, including glob characters in a
prefix;
- Redis down is a miss;
- a corrupt entry is a miss;
- env selection, and fallback on a bad URL;
- back-off after a connection error;
- no SCAN and no index growth on new stores, 300 re-stores and
retrievals;
- a Redis that reads but refuses writes logs once.

1317 CCR, store and retrieve tests pass. ruff and mypy are clean.

**Real run:** 3 proxy processes shared one Redis-protocol server
(fakeredis TCP server; no Redis on the test machine). A marker returned
by one replica resolved via `GET /v1/retrieve/{hash}` on all three.

Docs (configuration page, security model) follow in the docs PR.

## Real Behavior Proof
- **Environment:** macOS 26.7.1 (arm64), Python 3.12.13, redis-py 8.1.0.
Redis is a fakeredis 2.40.0 `TcpFakeServer`, which speaks the Redis
protocol over TCP; no Redis server was on the test machine. Docker was
not available.
- **Configuration:** every replica has
`HEADROOM_COMPRESS_SESSION_STORE=redis://127.0.0.1:6391/0` (the CCR
store follows it) and its own `HEADROOM_WORKSPACE_DIR`.
- **Steps:**
  1. Start the fake server:
`python -c "from fakeredis import TcpFakeServer;
TcpFakeServer(('127.0.0.1', 6391),
server_type='redis').serve_forever()"`
  2. Start three proxies, one each on ports 8901, 8902 and 8903:
`HEADROOM_COMPRESS_SESSION_STORE=redis://127.0.0.1:6391/0
HEADROOM_WORKSPACE_DIR=<own dir> python -m headroom.cli proxy --port
<port>`
3. Drive one session for 20 turns, round-robin across the three: `POST
/v1/compress` with `{"messages": …, "session_id": "kong-e2e", "mode":
"ccr"}`. The transcript is the 25 KB tool history from
`tests/test_compress_session_mode.py`. Every third turn adds a 120-row
grep result; the other turns add a user line.
  4. After each turn, check:
- the returned messages start with the previous turn's returned
messages, byte for byte;
     - how many bytes the turn wrote to the `:msgs` hash.
5. Fetch each `<<ccr:hash>>` marker via `GET /v1/retrieve/{hash}` on all
three proxies.
- **Result** (after the review fixes, at 95b2d93a):
  - every turn's prefix is byte-identical to the previous turn's;
- Redis received 378 KB in total (63 KB at most in one turn), against
about 4.9 MB if the whole transcript were rewritten each turn;
  - the CCR marker resolved on all three replicas.
- **Not tested:**
- a real Redis or Redis Cluster (the Lua script and hash-tagged keys are
written for it);
  - TLS (`rediss://`) and AUTH;
  - Kong's AI Gateway in front of the replicas;
  - Windows;
  - real `maxmemory` eviction (simulated in tests by deleting keys);
  - sustained load.

## Dependencies
- **`redis` (redis-py, `>=5.0`)**, in a new optional extra `[redis]`. It
is the Redis project's own Python client (maintained by Redis Inc.),
MIT-licensed and pure Python. Only deployments that set a Redis URL
install it; the default install and the other extras are unchanged. The
5.0 floor gives `register_script`/`scan_iter`/`from_url` with socket
timeouts as used here.
- **`fakeredis` (dev only, `>=2.20.0`)** runs the tests against an
in-process Redis without a server. 2.20 is the first release whose
`TcpFakeServer` and pipeline behaviour the tests rely on.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4368"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 23:48:33 -07:00
1be699f68e fix(deps): patch OpenClaw Undici and narrow E2E audit exceptions (#4453)
## Description

Includes the approved #4358 as its prerequisite. This PR targets main so
the complete integration workflows qualify the combined repair; its diff
will shrink to this follow-up once #4358 lands. Replace OpenClaw's
affected Undici copy instead of excepting it, and reduce the E2E audit
exceptions from seven advisory/path pairs to three.

OpenClaw 2026.10.2 lists Undici in `bundleDependencies`. Version
2026.10.6 removes it from that bundle, allowing a targeted, same-major
override to install fixed Undici 8.12.3. npm 12.2.1 still bundles its
own affected copies; this PR retains only those existing, expiring
exceptions.

## Type of Change

- [x] Bug fix

## Changes Made

- Pin the existing E2E OpenClaw CLI to 2026.10.6 and override only its
Undici dependency to 8.12.3.
- Regenerate the E2E lockfile; keep Codex and the npm override
unchanged.
- Remove every OpenClaw exception and the now-stale advisory, preserving
the parent's exact bundled-version checks and 2026-11-15 expiry.
- Update the Dockerfile comment to the actual Node requirement: 24.22.1
in the Node 24 line. Its NodeSource installation already selects that
line.

## Dependency and install-surface assessment

This updates an existing upstream-maintained CLI for a security fix,
rather than adding a replacement package. The fixed Undici remains in
the same major line. The graph is used only by the Docker wrap E2E
harness and is not shipped in Headroom's wheel or SDK. Normal
installation runs OpenClaw's existing lifecycle scripts and fetches
packages from the registry; those scripts were inspected, then exercised
inside a fresh Linux container without host credentials. No application
compression or routing logic changes.

## Testing

- [x] Manual testing performed
- [x] Dependency installation and runtime resolution verified

### Test Output

```text
OpenClaw runtime resolves Undici 8.12.3
OpenClaw 2026.10.6 (fe06181)
Installed audit: only npm bundled copies remain
{ info: 0, low: 0, moderate: 1, high: 1, critical: 0, total: 2 }
parent: 9 audit-guard cases passed
child: 9 audit-guard cases passed
git diff --check: passed
```

The guard accepts the current scoped findings and rejects a new
advisory, wrong path, expired exception, stale exception, audit error,
changed version, non-bundled copy, and missing inherited-advisory entry.
A raw audit remains nonzero for npm's bundled dependencies; this PR does
not claim those packages are patched.

## Real Behavior Proof

- Environment: fresh Linux amd64 Docker container,
`node:24.22.1-bookworm-slim`, Node 24.22.1 / npm 11.19.1, normal `npm
ci` with lifecycle scripts enabled.
- Exact command / steps: copy the two committed package files into a
fresh container volume; run `npm ci --no-audit --no-fund`; resolve
`undici/package.json` using
`createRequire('/work/node_modules/openclaw/package.json')` and assert
version 8.12.3; run `node node_modules/openclaw/openclaw.mjs --version`
and `--help`; run `npm audit --json` and assert that every remaining
affected node is under `node_modules/npm/`.
- Observed result: installation, exact runtime-resolution assertion,
version, and help all succeeded. Both installed-tree and lockfile audits
leave only npm's bundled Undici 6.29.0 and ip-address 10.7.2. The parent
workflow's guard passes with the narrowed exceptions and rejects all
eight negative cases.
- Not tested: a billed provider request or live production deployment.
Hosted Docker agent/integration scenarios have now passed. Hosted
qualification on head 63c3abc5b3 is
complete: all reported checks are terminal with no failures or pending
checks, including the full Security, build, test, and Docker integration
workflows.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; E2E dependency data only.
- Minimum rollout channel: existing E2E test environment.
- Stable/default behavior changed: this follow-up patches only the
harness CLI. The included parent retains its explicitly documented
affected-Pillow decoder guard.
- Kill switch / disable path: revert this dependency commit.
- Unsafe override required: none; the override selects a compatible
fixed Undici 8.x patch. The parent's existing, bounded npm exceptions
remain explicit.
- Qualification impact: package installation, CLI startup, runtime
dependency resolution, and audit guarding were verified in isolation.
- Rollback path: revert the four-file change.

## Review Readiness

- [x] I performed self-review
- [x] This PR is ready for human merge review; the complete hosted check
set passed

## Checklist

- [x] I did not edit CHANGELOG.md.
- [x] The exception scope is reduced, not expanded.
- [x] No contributor correctness logic was modified.

Python lint/type checks and new production unit tests are not applicable
to these dependency/data changes. Independent human approval is
required; this is an author-side qualification record.

---------

Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Tejas Chopra <tejas@headroomlabs.ai>
2026-10-23 23:11:35 -07:00
Kenneth WongandKenneth Wong f380692b46 fix(relevance): load the default embedder from one pinned snapshot (#4152)
## Description

The supply-chain pin on the default relevance embedder never took
effect. `EmbeddingScorer` passed `revision="52398278…"` to fastembed's
`TextEmbedding`, which accepts it and then drops it before
`snapshot_download` (fastembed 0.8.0 and 0.9.0:
`OnnxTextEmbedding.__init__` calls `download_model(...)` without
`**kwargs`). So the model floated on
`Qdrant/bge-small-en-v1.5-onnx-Q@main`, cached under the system temp
dir.

Today the floating `main` (`aa8f8b0`) differs from the pin only in
`README.md`, so no unreviewed weights have shipped. The pin just wasn't
protecting anything.

This PR makes the Python default model load the pinned snapshot and adds
tests that would have caught the dropped revision. The Rust
`EmbeddingScorer::try_new` change that was in this PR is now its own PR,
stacked on this one: #4190.

No linked issue.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/onnx_runtime.py`: pin `Qdrant/bge-small-en-v1.5-onnx-Q` at
`52398278842ec682c6f32300af41344b1c0b0bb2` in `_PINNED_REVISIONS`, so
`HEADROOM_HF_PIN=off` applies to it like every other pinned repo.
- `headroom/relevance/embedding.py`:
- The default model resolves its 5 files through
`hf_hub_download_local_first`, which is pinned, cache-first and guarded
on a miss.
- fastembed then gets only the snapshot directory as
`specific_model_path`. That construction runs with the Hub forced
offline, so a future fastembed that ignored the path would fail instead
of downloading an unpinned copy.
  - Other catalog models keep the existing `_load_text_embedding` path.
- The air-gapped error for the default model names the exact snapshot
and the command that seeds it, and says a fastembed cache is no longer
read (details under Release note).
- The private `_DEFAULT_MODEL_PINNED_REVISION` / `_pinned_revision` are
removed.
- `_load_text_embedding` now types its kwargs `dict[str, Any]`, fixing 8
mypy errors that only appear with fastembed installed.
- `pyproject.toml` / `uv.lock`: `fastembed>=0.6.0`.
`specific_model_path` first appears in fastembed v0.6.0; it isn't in
v0.4.x or v0.5.x. The lock still resolves 0.8.0; only the
`requires-dist` specifier changes.
- `.github/workflows/ci.yml` (`test-extras`):
- The prefetch warms the pinned snapshot through the loader's own
resolver, and the cache entry's key carries the SHA. The old prefetch
warmed fastembed's own cache, which the offline relevance tests would
now miss: `conftest.py:199` turns that into silent skips.
- The job runs the new test file, and the unused `FASTEMBED_CACHE_PATH`
is gone.
- Tests:
  - New `tests/test_fastembed_pinned_snapshot.py`:
    - the pinned revision reaches every file download;
- fastembed gets only the snapshot directory, built with the Hub forced
offline;
    - `HEADROOM_HF_PIN=off` floats;
    - files resolved from two different snapshots are refused;
- a cold cache while offline degrades without a download, and the error
names `repo@sha` and `--revision <sha>`;
    - real fastembed skips the Hub when given `specific_model_path`.
- `tests/test_stateless_writers.py`: the three `_pinned_revision` tests
are removed with the helper; `tests/test_hf_revision_pinning.py` covers
`_resolve_revision`.
- `tests/test_offline_egress_chokepoint.py`: `relevance/embedding.py`'s
cache-only count goes from 1 to 2 for the `_load_default_model`
construction.

## Release note

> **relevance:** the default embedder (`BAAI/bge-small-en-v1.5`) now
loads from the pinned snapshot
`Qdrant/bge-small-en-v1.5-onnx-Q@52398278842ec682c6f32300af41344b1c0b0bb2`
in the HuggingFace hub cache (`HF_HUB_CACHE` / `HF_HOME/hub` /
`~/.cache/huggingface/hub`), not from fastembed's cache. Existing
installs download ~67 MB once. Air-gapped hosts that pre-seeded the
fastembed cache must re-seed, e.g. `hf download
Qdrant/bge-small-en-v1.5-onnx-Q model_optimized.onnx tokenizer.json
tokenizer_config.json special_tokens_map.json config.json --revision
52398278842ec682c6f32300af41344b1c0b0bb2`. Without that, relevance
scoring falls back to BM25, and the error message says how to re-seed.

`CHANGELOG.md` is generated from the PR title, so this text is here for
whoever writes the release notes.

## Dependency Change (`fastembed>=0.4.0` → `>=0.6.0`)

This raises the minimum version of an existing dependency; no package is
added. `uv.lock` still resolves `fastembed 0.8.0`. The only lock change
is the `requires-dist` specifier, so the locked install set is
byte-for-byte the same.

- **Why this package:** it's already the `relevance` extra's embedder
(since Stage 3c.1). This PR adds no package and swaps none.
- **Who maintains it:** Qdrant (`qdrant/fastembed`), Apache-2.0,
actively released (0.6.0 on 2025-02-26 through 0.9.0 on 2026-10-07). The
GitHub Advisory Database has no advisories for `fastembed` (pip).
- **Install surface:** unchanged for the locked install (0.8.0).
Installs that resolve their own versions lose access to 0.4.x/0.5.x.
Runtime network shrinks: given `specific_model_path`, fastembed makes no
Hub call, and the only download is Headroom's own pinned,
offline-guarded `hf_hub_download_local_first`.
- **Why this version:** `specific_model_path` on `TextEmbedding` first
appears in v0.6.0, and the pinned-snapshot load depends on it.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ HOME=$(mktemp -d) pytest -q tests/test_fastembed_pinned_snapshot.py tests/test_offline_egress_chokepoint.py \
    tests/test_relevance.py tests/test_relevance_extra.py tests/test_stateless_writers.py tests/test_hf_revision_pinning.py
7 failed, 209 passed, 3 skipped
# The 7 failures are TestOtlpExporterOffline / TestLangfuseExporterOffline / TestStartupRefusal /
# TestHeadroomCloudCompressionOffline: the OTel and Cloud extras aren't in this venv. The same 7 fail on
# origin/main (f1bc2609) here.

$ mypy headroom            # with fastembed 0.8.0 installed
Success: no issues found in 569 source files
$ ruff check .             # All checks passed!
$ ruff format --check .    # 1790 files already formatted
```

## Real Behavior Proof
- Exact command / steps: additional maintainer verification on
Windows/Python 3.12.13: python -m pytest
tests/test_fastembed_pinned_snapshot.py
tests/test_offline_egress_chokepoint.py tests/test_stateless_writers.py
-q.
- Observed result: the additional maintainer run passed all 160 selected
tests on b3eb7f349c, using the available
development native extension for startup; no fresh Rust implementation
qualification is claimed.

- Environment: macOS arm64, repo `.venv` (fastembed 0.8.0 = `uv.lock`),
rebased on `origin/main` `f1bc2609`.
- Default load: `EmbeddingScorer().score("authentication failed for user
admin", "login error")` loads from
`~/.cache/huggingface/hub/models--Qdrant--bge-small-en-v1.5-onnx-Q/snapshots/52398278842ec682c6f32300af41344b1c0b0bb2`
and scores 0.7389. `origin/main` loads
`<tmp>/fastembed_cache/…/snapshots/aa8f8b06…` (the floating `main`,
under `$TMPDIR`).
- Air-gapped re-seed, from an empty `HF_HOME`:
1. `HEADROOM_OFFLINE=1` gives `Embedding model 'BAAI/bge-small-en-v1.5'
is unavailable: HEADROOM_OFFLINE is set: … Pre-seed the HuggingFace hub
cache with Qdrant/bge-small-en-v1.5-onnx-Q@52398278… (`hf download …
--revision 52398278…`), or use the BM25-only scorer. A fastembed cache
seeded for an older Headroom is not read for this model.`
  2. I ran the `hf download` command from that message as printed.
  3. `HEADROOM_OFFLINE=1 HF_HUB_OFFLINE=1` then loads and scores 0.7389.
4. With `HEADROOM_HF_PIN=off`, the message names `@main` and `--revision
main` instead.
- Not tested: Windows, and Linux outside CI. fastembed 0.6.x/0.7.x at
runtime (the 0.6.0 floor comes from reading the v0.6.0 tag's source).

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: N/A. This is the default code path, with no
flag.
- Stable/default behavior changed: yes. The default relevance model
loads the pinned snapshot from the standard HF hub cache, not
fastembed's temp-dir cache, so existing installs download ~67 MB once.
The model files are byte-identical to what `main` served; only
`README.md` differs.
- Kill switch / disable path: `HEADROOM_HF_PIN=off` floats it on `main`.
Air-gapped hosts re-seed as described in the Release note.
- Unsafe override required: no.
- Qualification impact: none expected. Same weights and tokenizer as the
current floating `main`.
- Rollback path: revert this PR. Nothing persistent changes beyond an
extra snapshot in the HF cache.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A.

## Additional Notes

- `_load_text_embedding` was typed `kwargs: dict[str, str]`, which made
mypy report 8 `arg-type` errors on `TextEmbedding(**kwargs)` whenever
fastembed is installed in the type-checking environment. CI's mypy run
doesn't install fastembed, so it never saw them.
- Follow-ups, not in this PR: Rust's Kompress and tokenizer Hub fetches
are still unpinned (there's no Rust `HEADROOM_HF_PIN`).

Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
2026-10-20 19:45:26 -05:00
gglucassandClaude Opus 5.5 62b3bedaba fix(cache): keep prefix-tracker state across a graceful proxy restart (#4299)
## Description

Every proxy restart rewrites the prompt cache of every warm
conversation. After a restart the proxy has no `PrefixCacheTracker` for
the conversation, so it compresses the whole history afresh, the early
messages come out as different bytes than the prefix it forwarded before
the restart, and the provider re-writes the cache from the first changed
message.

Measured on 2026-10-19 on one Mac running Claude Code through the proxy:
after each graceful restart (app relaunches for updates: proxy SIGTERM'd
and respawned), the next request of every active session read only ~25k
cached tokens (tools + system) and re-wrote the rest, up to 247k, 310k,
361k and 432k tokens at a time. The restart-aligned rewrites came to
about 4.6M tokens of 1h cache writes that day (2x the input price),
about a quarter of all cache writes. A client-side integrity probe
reported `kind=tracker_reset, stable_messages=861,
first_changed_message=3`.

This adds an opt-in `HEADROOM_PREFIX_STATE_FILE=<path>`. When set, the
proxy saves the `SessionTrackerStore` on graceful shutdown and restores
it at startup, before serving, so the first request after a restart
replays byte-identical frozen-prefix bytes. Unset, nothing changes. The
file holds conversation content, so it is never a default.

Related but different: #4156 (away recap replaces the lineage), #4287
(CCR proactive expansion rewrites), #4204 (deferred tool loads in the
lineage key), #4284 (mid-history divergence starts a cold lineage).

No existing issue; found while auditing one machine's token usage.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `SessionTrackerStore.save_state` / `load_state`
(`headroom/cache/prefix_tracker.py`). Per tracker: turn number, cached
token and message counts, last original and last forwarded messages, the
per-turn states that lineage resolution resumes, provider, last activity
and observed cache TTL; per lineage: session id, cache affinity and the
recent snapshot history. So `resolve_tracker` matches the next request
to the restored tracker, forks included. Each distinct message is stored
once per tracker (successive turns, snapshots and the original/forwarded
pairs mostly repeat), and new lineage keys and turn ids continue past
the restored ones.
- CCR entries ride along (review: retrieval integrity). Per tracker,
`save_state` collects every CCR reference in its saved messages and
read-maturation state (`hash=<hex>` markers and SmartCrusher's
`<<ccr:<hex>`) and writes the live `CompressionStore` entries behind
them (new `CompressionStore.export_entries`, which reads without
counting a retrieval). A tracker and its entries count against the size
cap together, so a tracker is never saved without them. `load_state`
re-stores them (`import_entries`) with their original expiry, before any
tracker is installed, so a replayed marker resolves from the first
request even with `HEADROOM_CCR_BACKEND=memory`. An entry a persistent
backend still holds is left as it is; a malformed one rejects the file.
- Restore keeps only trackers still inside the store's own retention
(last activity plus the observed or configured cache TTL and its cleanup
margin, at least the session TTL), the same rule the live store uses.
NaN or future timestamps are dropped.
- Versioned schema (`version: 1`). Any read, parse or validation error
logs one warning and leaves the store empty; the whole file is validated
before anything is installed. The file is written atomically
(`headroom.fsutil.write_text`: temp file, fsync, rename) at mode 0600:
an existing file is tightened to 0600 in place, never unlinked first, so
a failed write (ENOSPC) keeps the previous snapshot. Deleted after a
successful load. Stateless mode (`persistence_allowed`) neither writes
nor reads it (a stateless start used to load, and so delete, a
snapshot). Ignored with multiple workers (one file cannot hold N
per-process stores).
- Size cap: the 256 most recently active trackers and at most 64 MB,
newest first; whatever does not fit starts cold, as everything did
before.
- `HeadroomProxy.startup()` loads, `HeadroomProxy.shutdown()` saves as
its first step, before any await, so the shutdown step timeout cannot
cut it short. No periodic writes.
- Token-mode `CompressionCache` seed: a restored tracker has no
`CompressionCache` behind it in the new process, so the freeze computed
from that cache froze nothing: the pipeline recompressed messages the
provider cached, read maturation rewrote Reads inside the cached prefix,
and beyond the provider-confirmed floor the overlay declined a larger
previous form. One shared `seed_restored_compression_cache` seeds the
session's cache from the restored original/forwarded pair
(`update_from_result`) on the first request, on all three token-mode
paths: Anthropic `/v1/messages`, OpenAI `/v1/chat/completions`, and the
session-aware `/v1/compress` (sidecar). It gives the same freeze count
as before the restart.
- `ReadMaturationManager.export_state` / `validate_state` /
`restore_state`: matured markers, booked ids and replay token deltas
ride along with the tracker, so a matured Read's removal is not booked
as savings again on every request after a restart. The saved state is
validated at load with the rest of the file, so a bad entry rejects the
file instead of failing a request.
- `tests/test_anthropic_fork_lineage_cache.py`: `_drive` accepts a
shared provider-cache model and config overrides, so a second call is a
proxy restart in front of a warm provider cache.
- Documented the variable in `docs/content/docs/configuration.mdx`.
- `pyproject.toml` / `uv.lock` (review: Dependency audit): the `aiohttp`
constraint floor is now `>=3.14.4` (CVE-2026-111063, CVE-2026-111064 and
GHSA-2g87-pp6c-29x5, all fixed in 3.14.4), relocked with `uv lock
--upgrade-package aiohttp==3.14.4`. Only aiohttp (3.14.3 -> 3.14.4) and
yarl (1.22.0 -> 1.25.1, which 3.14.4 requires) move. Main still resolves
3.14.3, so the same commit is on #4299, #4286, #4285 and #4269.

Remaining gaps (unchanged by this PR, none of them changes forwarded
message bytes):
- Session-sticky `anthropic-beta` union (`HEADROOM_BETA_HEADER_STICKY`):
in memory, so after a restart a session's sticky set starts from the
client's own header again. Headers only.
- Output shaper: stateless per request (byte-stable steering text,
effort from the current request's structure), so nothing to persist.
- Gemini and Bedrock paths resume the restored tracker and its overlay
replay; they keep no token-mode `CompressionCache`, so there is nothing
to seed. A crash or SIGKILL still loses everything, by design (no
periodic writes).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
# New regression tests for the review findings, run against the c141e2ec source
# (headroom/ stashed, new tests kept): all six fail, the 15 earlier tests pass.
$ uv run --frozen --extra dev pytest tests/test_prefix_tracker_restart.py -q
FAILED tests/test_prefix_tracker_restart.py::test_restored_retrieval_references_resolve_to_their_originals
FAILED tests/test_prefix_tracker_restart.py::test_a_stateless_proxy_leaves_a_saved_snapshot_alone
FAILED tests/test_prefix_tracker_restart.py::test_a_failed_save_keeps_the_previous_snapshot
FAILED tests/test_prefix_tracker_restart.py::test_saved_ccr_entries_resolve_after_a_restart
FAILED tests/test_prefix_tracker_restart.py::test_openai_token_mode_replays_its_prefix_after_a_restart
FAILED tests/test_prefix_tracker_restart.py::test_compress_sidecar_session_replays_its_prefix_after_a_restart
6 failed, 15 passed in 8.10s
# Why, in order: hash=cc146b21626392f0dee9890c no longer resolves; the stateless start
# deleted the snapshot; ENOSPC left no snapshot; retrieve() returns None; the OpenAI chat
# and /v1/compress paths re-compressed message 2 under the new query.

# Head c379245e:
$ uv run --frozen --extra dev pytest tests/test_prefix_tracker_restart.py -q
21 passed in 9.50s

$ uv run --frozen --extra dev pytest tests/test_prefix_tracker_restart.py tests/test_anthropic_fork_lineage_cache.py \
    tests/test_cache/test_prefix_tracker.py tests/test_compression_store.py tests/test_ccr_sqlite_backend.py \
    tests/test_issue_2671_block_growth_cache.py tests/test_cache_mode_cold_start.py tests/test_cache_prefix_overlay.py \
    tests/test_cross_turn_cache_safety.py tests/test_session_engine.py tests/test_read_maturation.py \
    tests/test_read_maturation_handler_nobust.py tests/test_graceful_shutdown.py tests/test_proxy_handlers_batch.py \
    tests/test_cache_control_move_bust.py tests/test_startup_log_noise.py tests/test_proxy_openai_cache_stability.py \
    tests/test_compress_session_mode.py tests/test_proxy_anthropic_cache_stability.py tests/test_ccr_row_drop_store_bridge.py \
    tests/test_bedrock_prefix_tracker_wiring.py -q
486 passed, 1 skipped in 46.92s

$ uv run --frozen --extra dev pytest tests/test_anthropic_*.py tests/test_proxy_anthropic_*.py tests/test_proxy_openai*.py \
    tests/test_openai_chat_*.py tests/test_cache_aligner_prefix_stability.py tests/test_cache_prefix_safety.py tests/test_cold_prefix.py \
    tests/test_gemini_prefix_freeze.py tests/test_prefix_tracker_client_rewrote_reply.py tests/test_tool_injection*.py tests/test_ccr_*.py -q
737 passed, 16 skipped in 51.45s

$ uvx ruff@0.17.0 check headroom tests
All checks passed!
$ uvx ruff@0.17.0 format --check headroom tests
1606 files already formatted
$ uv run --frozen --extra dev mypy headroom/cache/prefix_tracker.py headroom/cache/compression_store.py \
    headroom/proxy/handlers/anthropic.py headroom/proxy/handlers/openai.py headroom/proxy/server.py
Success: no issues found in 5 source files
```

## Real Behavior Proof

- Environment: macOS 27 (arm64), this branch at c379245e, the real proxy
process (`python -m headroom.cli proxy --port 6811 --no-http2
--no-rate-limit --mode token --read-maturation
--read-maturation-quiesce-turns 1 --read-maturation-min-size-bytes 200
--disable-kompress --no-subscription-tracking`,
`HEADROOM_ROLLOUT_CHANNEL=beta`, clean `HOME` and workspace,
`HEADROOM_PREFIX_STATE_FILE` set, `HEADROOM_CCR_BACKEND=memory`,
`HEADROOM_BACKGROUND_COMPRESSION=1`) in front of the live Anthropic API,
driven by Claude Code 2.1.303 (`claude -p --model haiku`,
`ANTHROPIC_BASE_URL=http://127.0.0.1:6811`). Each restart is a SIGTERM
(graceful shutdown) and a fresh process.
- Exact command / steps: one Claude Code session through the proxy,
three graceful restarts, the last one without the state file as the
control:
1. Turn 1: `claude -p` reads three files (4.8, 17 and 8.9 KB) one per
turn, 5 requests through the proxy. SIGTERM: `SessionTrackerStore: saved
2 of 2 prefix trackers (181266 bytes)`; file mode `-rw-------`; it holds
2 CCR entries, for the two Reads that read maturation had replaced with
`Retrieve original: hash=` markers.
2. Restart: `restored 2 of 2 prefix trackers`, file deleted. `GET
/v1/retrieve/3a739d6ec5febcd49d0cfc0e` and
`/v1/retrieve/2ee4d4d435432b4cca9b72af` on the new process: HTTP 200,
`original_content` equal to the pre-restart entries (5,129 and 18,525
chars, the Read outputs of the two files). With the in-process CCR
store, c141e2ec loses such entries at a restart (the reviewer's
reproduction;
`test_restored_retrieval_references_resolve_to_their_originals` fails on
it).
3. `claude -p --resume`, then SIGTERM + restart with the state file
again, then `claude -p --resume` again (one request each, no tools).
4. Control: SIGTERM, snapshot moved aside, restart without
`HEADROOM_PREFIX_STATE_FILE`, `claude -p --resume`.
- Observed result: after a restart with the state file the first request
read 99% of its prefix from the provider cache and both restored
retrieval hashes resolved; the control re-wrote everything after the
system prompt (proxy `PERF` lines, which match Claude Code's reported
usage):

  | First request after a restart | cache_read | cache_write | hit |
  |---|---|---|---|
  | With the state file, resume after a resume | 40,406 | 514 | 99% |
| Without the state file (control), same history | 26,053 | 11,250 | 70%
|

With the state file the proxy forwarded messages 0-10 byte-identical to
what it forwarded before the restart (compared from the saved snapshots,
`cache_control` positions excluded since Claude Code moves its
breakpoint every turn), and froze 14 of 15 messages. In the control, the
forwarded bytes changed from message 1, and the third Read, verbatim
inside the cached prefix, matured into a new marker (10,205 -> 368
chars), so everything after the system prompt was re-written.
- Not tested: Kompress itself (`--disable-kompress`; the unit suite uses
a deterministic stand-in). Windows file modes. The OpenAI chat and
`/v1/compress` seeds against a live OpenAI endpoint (covered by the
handler-level restart tests above with a query-dependent compressor).
The very first `--resume` of a `claude -p` session (step 3's first
request) read only 26,053 tokens and wrote 14,845, although the client's
messages and the proxy's forwarded messages 0-10 were byte-identical to
the pre-restart request; the read stopped at the system-prompt
breakpoint, so the change is most likely in the system/tools part of the
request, which I did not capture. The resume after it, across another
restart, read 99%.

## Runtime Rollout Safety

- Rollout-managed feature(s): None; opt-in environment variable
`HEADROOM_PREFIX_STATE_FILE`, unset by default.
- Minimum rollout channel: Stable.
- Stable/default behavior changed: No; with the variable unset nothing
is read or written and no code path changes (the new handler branches
only fire on a tracker restored from the file, and the CCR export/import
only runs inside save/load).
- Kill switch / disable path: Unset `HEADROOM_PREFIX_STATE_FILE`.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Unset the variable or revert this PR; a leftover state
file is inert without the variable. The file format is still `version:
1` (now with a `ccr` list); a file written by c141e2ec has no `ccr` list
and is rejected at load, which starts cold.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

Not applicable.

## Additional Notes

- Review follow-up (c379245e): CCR entries are saved with their trackers
(P1), the seed covers the OpenAI chat and `/v1/compress` token paths, a
failed save keeps the previous snapshot, and stateless mode no longer
loads (and deletes) a snapshot. Each has a regression test that fails on
c141e2ec.
- Caller isolation: the restored store has exactly the keys, lineages
and retention the in-memory store had at shutdown, and replay still
requires the caller to send the same original messages; see the reply on
that thread for the full reasoning.
- The full `pytest tests` run was not repeated for this head (shared
machine); the focused runs above cover every module the change touches.
- Size cap choice: 256 trackers covers many concurrent Claude Code
sessions plus their subagents; 64 MB bounds shutdown time (encoding is
synchronous) and disk use.

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

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4299"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 19:44:00 -05:00
dependabot[bot]andJerrettDavis fcf3db8e70 deps: Update huggingface-hub requirement from <2.0,>=1.5.0 to >=1.5.0,<3.0 (#4027)
## Description

Apply the intended Hugging Face Hub range change to the actual
requirement, not only its comment.

## Type of Change

- [x] Bug fix / dependency security and qualification

## Changes Made

Synced with upstream `main`
(`486afaac7426fa1d6735fe2ce6ae37630d9d11ae`). No contributor
implementation logic changed. Tested head:
`c51c9f10196ecfdfb944a84a8f5adc008b48b912`. Includes the reviewed
dependency-floor fix from #4239 because the vulnerable version was still
permitted by shipping extras.

## Dependency assessment

The embedding extra now declares huggingface-hub>=1.5.0,<3.0, matching
the Dependabot range-update intent. Hugging Face maintains the existing
model-download client; no new dependency is introduced. The wider range
permits the supported 2.x API surface and avoids forcing older hub
versions in environments using current Hugging Face tooling. Model
repository/network/cache surfaces remain the same. Also applies the
reviewed MCP CVE-2026-59951 floor and retains its SDK v1 cap.

## Testing

Tokenizer timeout/allowlist plus MCP dependency-contract tests: 23
passed with the locked huggingface-hub 1.16.1 and 23 passed with an
isolated huggingface-hub 2.2.0 overlay. hf_hub_download,
snapshot_download and HfApi imports succeed on 2.2.0. uv lock --check
passed. Actual remote model downloads were not performed.

### Test Output

```text
Tokenizer timeout/allowlist plus MCP dependency-contract tests: 23 passed with the locked huggingface-hub 1.16.1 and 23 passed with an isolated huggingface-hub 2.2.0 overlay. hf_hub_download, snapshot_download and HfApi imports succeed on 2.2.0. uv lock --check passed. Actual remote model downloads were not performed.
```

## Real Behavior Proof

- Environment: Windows, PowerShell; installed Python/uv, Node/npm/Bun
and Rust tooling as applicable. No live provider/model used.
- Exact commands / steps:

```text
uv run --frozen --extra dev pytest -q tests/test_huggingface_tokenizer_timeout.py tests/test_huggingface_tokenizer_allowlist.py tests/test_mcp_dependency_contract.py
Repeat with --with "huggingface-hub>=2,<3"
uv lock --check
python -m pytest -q tests/test_mcp_dependency_contract.py
git diff --check
```

- Observed result: Tokenizer timeout/allowlist plus MCP
dependency-contract tests: 23 passed with the locked huggingface-hub
1.16.1 and 23 passed with an isolated huggingface-hub 2.2.0 overlay.
hf_hub_download, snapshot_download and HfApi imports succeed on 2.2.0.
uv lock --check passed. Actual remote model downloads were not
performed.
- Not tested: live model/provider traffic and full Docker E2E locally;
hosted cross-platform checks are running on the pushed head. Read hosted
results before merging. Focused checks are not a claim of complete
platform qualification.

## Runtime Rollout Safety

- Rollout-managed features: none added or enabled.
- Minimum rollout channel: unchanged.
- Stable/default behavior changed: dependency versions/ranges and
associated install metadata only; no feature rollout defaults changed.
- Kill switch / disable path: existing optional extras and plugin opt-in
paths remain available.
- Unsafe override required: no runtime qualification bypass. Security
dependency override is documented above where applicable.
- Qualification impact: hosted checks and the focused evidence above
must pass; no existing gate is removed.
- Rollback path: revert this dependency change and restore its prior
lockfiles together; retain the patched MCP minimum or another reviewed
security remediation.

## Review Readiness

- [x] Maintainer self-review and focused verification performed.
- [x] All hosted checks passed on the reviewed head. Ready for final
human merge review.

## Checklist

- [x] No contributor implementation logic rewritten.
- [x] Committed lockfiles checked against the changed manifests.
- [x] No manual CHANGELOG.md changes.
- [x] Known limitations recorded above.

## Original Dependabot update

Updates the requirements on
[huggingface-hub](https://github.com/huggingface/huggingface_hub) to
permit the latest version.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/huggingface/huggingface_hub/releases">huggingface-hub's
releases</a>.</em></p>
<blockquote>
<h2>v2.1.1</h2>
<p>[CLI] Rename 'hf spaces zero-gpu-quota' to 'hf spaces zero-gpu
quota'- <a
href="https://redirect.github.com/huggingface/huggingface_hub/issues/5055">#5055</a></p>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/huggingface/huggingface_hub/compare/v2.1.0...v2.1.1">https://github.com/huggingface/huggingface_hub/compare/v2.1.0...v2.1.1</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/bd4a76030582d118e28dc9ad6c7a5911ea76176b"><code>bd4a760</code></a>
Release: v2.1.1</li>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/cb1755f353eec5d1048e6be112f5b3502492bcde"><code>cb1755f</code></a>
[CLI] Rename 'hf spaces zero-gpu-quota' to 'hf spaces zero-gpu quota'
(<a
href="https://redirect.github.com/huggingface/huggingface_hub/issues/5055">#5055</a>)</li>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/43372b60841b5b9ee2724e1c9c19c3fede6d54b6"><code>43372b6</code></a>
Release: v2.1.0</li>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/efa122c2cf1376230846da3a563254930828c424"><code>efa122c</code></a>
Release: v2.1.0.rc0</li>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/0b26b50b61e01b5bcf69dd6ef6d9c3c847075b36"><code>0b26b50</code></a>
[Spaces] Add get_zero_gpu_quota and hf spaces zero-gpu-quota (<a
href="https://redirect.github.com/huggingface/huggingface_hub/issues/5040">#5040</a>)</li>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/604252e46e9eb59ca4b88b71f511dc6ba944350f"><code>604252e</code></a>
[HfApi] Add visibility to create_bucket (<a
href="https://redirect.github.com/huggingface/huggingface_hub/issues/5053">#5053</a>)</li>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/4c88ea6e0f322bb866c6735abd350631bcc4e8cf"><code>4c88ea6</code></a>
[Repos] Warn when duplicated repo files are still being copied (<a
href="https://redirect.github.com/huggingface/huggingface_hub/issues/5041">#5041</a>)</li>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/3bb08e20a3df06a9c3b2b93fe716c2f7dd8b8b2d"><code>3bb08e2</code></a>
[Endpoints] Migrate catalog to the new /api/v1 API (<a
href="https://redirect.github.com/huggingface/huggingface_hub/issues/4928">#4928</a>)</li>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/b5e3a129cea92b2d129c580f38526d95ec4e0d0b"><code>b5e3a12</code></a>
[HfApi] Support resource_group_id in duplicate_repo (<a
href="https://redirect.github.com/huggingface/huggingface_hub/issues/5038">#5038</a>)</li>
<li><a
href="https://github.com/huggingface/huggingface_hub/commit/60fdb08c559dbda4a9087dfc56765f6ecd4895a1"><code>60fdb08</code></a>
[Docs] Fix duplicated words in docstring and comments (<a
href="https://redirect.github.com/huggingface/huggingface_hub/issues/5052">#5052</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/huggingface/huggingface_hub/compare/v1.5.0...v2.1.1">compare
view</a></li>
</ul>
</details>
<br />


Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)


</details>
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4027"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-15 21:50:18 -05:00
dependabot[bot]andJerrettDavis de3f639803 deps: Bump ruff from 0.16.8 to 0.17.0 in the pip-minor-patch group across 1 directory (#4026)
## Description

Align the Ruff project requirement, committed lockfile and pre-commit
hook at 0.17.0.

## Type of Change

- [x] Bug fix / dependency security and qualification

## Changes Made

Synced with upstream `main`
(`486afaac7426fa1d6735fe2ce6ae37630d9d11ae`). No contributor
implementation logic changed. Tested head:
`2c9390dd72431daa350a764332e602a382319413`. Includes the reviewed
dependency-floor fix from #4239 because the vulnerable version was still
permitted by shipping extras.

## Dependency assessment

Astral maintains Ruff. Keeping the linter executable and pre-commit hook
at the requested version fixes the repository's version-contract failure
and prevents developers and CI from applying different rule/format
versions. Ruff is a development-only native executable, not a shipped
runtime dependency. Also applies the reviewed MCP CVE-2026-59951
shipping dependency floor while retaining the SDK v1 cap.

## Testing

Before: scripts/verify-ruff-version.py failed against the old lock/hook
pins. After: python scripts/verify-ruff-version.py reports Ruff versions
aligned at 0.17.0. uv run --frozen --extra dev ruff check . and ruff
format --check . passed. Branch dependency contract: 1 passed; uv lock
--check passed.

### Test Output

```text
Before: scripts/verify-ruff-version.py failed against the old lock/hook pins. After: python scripts/verify-ruff-version.py reports Ruff versions aligned at 0.17.0. uv run --frozen --extra dev ruff check . and ruff format --check . passed. Branch dependency contract: 1 passed; uv lock --check passed.
```

## Real Behavior Proof

- Environment: Windows, PowerShell; installed Python/uv, Node/npm/Bun
and Rust tooling as applicable. No live provider/model used.
- Exact commands / steps:

```text
python scripts/verify-ruff-version.py
uv run --frozen --extra dev ruff check .
uv run --frozen --extra dev ruff format --check .
uv lock --check
python -m pytest -q tests/test_mcp_dependency_contract.py
git diff --check
```

- Observed result: Before: scripts/verify-ruff-version.py failed against
the old lock/hook pins. After: python scripts/verify-ruff-version.py
reports Ruff versions aligned at 0.17.0. uv run --frozen --extra dev
ruff check . and ruff format --check . passed. Branch dependency
contract: 1 passed; uv lock --check passed.
- Not tested: live model/provider traffic and full Docker E2E locally;
hosted cross-platform checks are running on the pushed head. Read hosted
results before merging. Focused checks are not a claim of complete
platform qualification.

## Runtime Rollout Safety

- Rollout-managed features: none added or enabled.
- Minimum rollout channel: unchanged.
- Stable/default behavior changed: dependency versions/ranges and
associated install metadata only; no feature rollout defaults changed.
- Kill switch / disable path: existing optional extras and plugin opt-in
paths remain available.
- Unsafe override required: no runtime qualification bypass. Security
dependency override is documented above where applicable.
- Qualification impact: hosted checks and the focused evidence above
must pass; no existing gate is removed.
- Rollback path: revert this dependency change and restore its prior
lockfiles together; retain the patched MCP minimum or another reviewed
security remediation.

## Review Readiness

- [x] Maintainer self-review and focused verification performed.
- [x] All hosted checks passed on the reviewed head. Ready for final
human merge review.

## Checklist

- [x] No contributor implementation logic rewritten.
- [x] Committed lockfiles checked against the changed manifests.
- [x] No manual CHANGELOG.md changes.
- [x] Known limitations recorded above.

## Original Dependabot update

Bumps the pip-minor-patch group with 1 update in the / directory:
[ruff](https://github.com/astral-sh/ruff).

Updates `ruff` from 0.16.8 to 0.17.0
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/ruff/releases">ruff's
releases</a>.</em></p>
<blockquote>
<h2>0.17.0</h2>
<h2>Release Notes</h2>
<p>Released on 2026-10-09.</p>
<p>The executables in our macOS and Windows release archives and
<code>ruff</code> wheels are now code-signed. macOS executables are
signed with an Apple Developer ID certificate and notarized by Apple.
Windows executables have timestamped Authenticode signatures from Azure
Artifact Signing. This enables verification of the release publisher and
binary integrity, supports publisher-based allowlisting, and should
reduce security warnings and antivirus false positives.</p>
<h3>Breaking changes</h3>
<ul>
<li>
<p>Update the default and latest Python versions for 3.15 (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28792">#28792</a>)</p>
<p>Ruff now defaults to Python 3.11 instead of 3.10 when no Python
version is configured through <a
href="https://docs.astral.sh/ruff/settings/#target-version"><code>target-version</code></a>
or <a
href="https://docs.astral.sh/ruff/configuration/#inferring-the-python-version"><code>requires-python</code></a>.
When checking for syntax errors without a configured Python version,
Ruff now defaults to Python 3.15 instead of 3.14.</p>
</li>
<li>
<p>Update the default rule set (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28786">#28786</a>)</p>
<p>Several of the <code>flake8-datetimez</code> rules (<a
href="https://docs.astral.sh/ruff/rules/call-datetime-without-tzinfo/"><code>DTZ001</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-datetime-now-without-tzinfo/"><code>DTZ005</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-datetime-fromtimestamp/"><code>DTZ006</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-datetime-strptime-without-zone/"><code>DTZ007</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-date-today/"><code>DTZ011</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-date-fromtimestamp/"><code>DTZ012</code></a>,
and <a
href="https://docs.astral.sh/ruff/rules/datetime-min-max/"><code>DTZ901</code></a>)
are no longer enabled by default, while <a
href="https://docs.astral.sh/ruff/rules/undefined-local-with-nested-import-star-usage/"><code>undefined-local-with-nested-import-star-usage</code></a>
(<code>F406</code>), which corresponds to a syntax error, is now enabled
by default.</p>
</li>
<li>
<p>Update Rust crate quick-junit to 0.8.0 (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27295">#27295</a>)</p>
<p>JUnit output now uses a <code>skipped</code> attribute instead of
<code>disabled</code> on <code>&lt;testsuite&gt;</code> elements and
includes a <code>skipped</code> attribute on the root
<code>&lt;testsuites&gt;</code> element.</p>
</li>
<li>
<p>[<code>flake8-import-conventions</code>] Add <code>datetime as
dt</code> as a conventional alias (<code>ICN001</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28790">#28790</a>)</p>
</li>
<li>
<p>Support Unicode dummy variable names (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28722">#28722</a>)</p>
<p>The default <a
href="https://docs.astral.sh/ruff/settings/#lint_dummy-variable-rgx"><code>lint.dummy-variable-rgx</code></a>
now recognizes underscore-prefixed Unicode names, such as
<code>_次</code>, as dummy variables.</p>
</li>
<li>
<p>Update to Unicode 17 (<a
href="https://redirect.github.com/astral-sh/ruff/pull/21229">#21229</a>,
<a
href="https://redirect.github.com/astral-sh/ruff/pull/28784">#28784</a>)</p>
<p>Ruff now uses Unicode 17 data for identifier normalization and named
character escapes (<code>&quot;\N{...}&quot;</code>).</p>
</li>
<li>
<p>Always show unsafe and display-only fixes in the CLI (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27810">#27810</a>)</p>
<p>The default <code>full</code> output format now shows unsafe fixes
and suggestions requiring manual review, regardless of the <a
href="https://docs.astral.sh/ruff/settings/#unsafe-fixes"><code>unsafe-fixes</code></a>
setting. Actually applying unsafe fixes still requires explicit
opt-in.</p>
</li>
<li>
<p>Remove the Python dependency from conda-forge builds (<a
href="https://redirect.github.com/conda-forge/ruff-feedstock/pull/361">conda-forge/ruff-feedstock#361</a>)</p>
<p>The conda-forge build no longer depends on Python, now supports
linux-riscv64, win-arm64, and linux-ppc64le platforms, and now includes
shell completions. However, no longer depending on Python means that
<code>python -m ruff</code> and <code>import ruff</code> will no longer
work. Use <code>ruff</code> directly from <code>PATH</code> instead.
PyPI installations and those from the standalone installer are
unaffected.</p>
</li>
<li>
<p>Remove support for ruff-lsp (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28750">#28750</a>)</p>
<p>Support for <code>ruff-lsp</code>, the legacy Python language server
<a
href="https://github.com/astral-sh/ruff/releases/tag/0.9.5">deprecated
in Ruff v0.9.5</a>, has been removed. The Ruff VS Code extension now
always uses the native language server; <code>ruff.nativeServer</code>
is deprecated and ignored. See the <a
href="https://docs.astral.sh/ruff/editors/migration/">migration
guide</a>.</p>
</li>
</ul>
<h3>Stabilization</h3>
<p>The following rules have been stabilized and are no longer in
preview:</p>
<ul>
<li><a
href="https://docs.astral.sh/ruff/rules/lazy-import-mismatch"><code>lazy-import-mismatch</code></a>
(<code>TID254</code>)</li>
<li><a
href="https://docs.astral.sh/ruff/rules/lazy-import-immediately-resolved"><code>lazy-import-immediately-resolved</code></a>
(<code>TID255</code>)</li>
<li><a
href="https://docs.astral.sh/ruff/rules/os-path-commonprefix"><code>os-path-commonprefix</code></a>
(<code>RUF071</code>)</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md">ruff's
changelog</a>.</em></p>
<blockquote>
<h2>0.17.0</h2>
<p>Released on 2026-10-09.</p>
<p>The executables in our macOS and Windows release archives and
<code>ruff</code> wheels are now code-signed.
macOS executables are signed with an Apple Developer ID certificate and
notarized by Apple. Windows
executables have timestamped Authenticode signatures from Azure Artifact
Signing. This enables
verification of the release publisher and binary integrity, supports
publisher-based allowlisting,
and should reduce security warnings and antivirus false positives.</p>
<h3>Breaking changes</h3>
<ul>
<li>
<p>Update the default and latest Python versions for 3.15 (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28792">#28792</a>)</p>
<p>Ruff now defaults to Python 3.11 instead of 3.10 when no Python
version is configured through
<a
href="https://docs.astral.sh/ruff/settings/#target-version"><code>target-version</code></a>
or
<a
href="https://docs.astral.sh/ruff/configuration/#inferring-the-python-version"><code>requires-python</code></a>.
When
checking for syntax errors without a configured Python version, Ruff now
defaults to Python 3.15
instead of 3.14.</p>
</li>
<li>
<p>Update the default rule set (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28786">#28786</a>)</p>
<p>Several of the <code>flake8-datetimez</code> rules
(<a
href="https://docs.astral.sh/ruff/rules/call-datetime-without-tzinfo/"><code>DTZ001</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-datetime-now-without-tzinfo/"><code>DTZ005</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-datetime-fromtimestamp/"><code>DTZ006</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-datetime-strptime-without-zone/"><code>DTZ007</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-date-today/"><code>DTZ011</code></a>,
<a
href="https://docs.astral.sh/ruff/rules/call-date-fromtimestamp/"><code>DTZ012</code></a>,
and
<a
href="https://docs.astral.sh/ruff/rules/datetime-min-max/"><code>DTZ901</code></a>)
are no longer enabled by default,
while <a
href="https://docs.astral.sh/ruff/rules/undefined-local-with-nested-import-star-usage/"><code>undefined-local-with-nested-import-star-usage</code></a>
(<code>F406</code>), which corresponds to a syntax error, is now enabled
by default.</p>
</li>
<li>
<p>Update Rust crate quick-junit to 0.8.0 (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27295">#27295</a>)</p>
<p>JUnit output now uses a <code>skipped</code> attribute instead of
<code>disabled</code> on <code>&lt;testsuite&gt;</code> elements and
includes a <code>skipped</code> attribute on the root
<code>&lt;testsuites&gt;</code> element.</p>
</li>
<li>
<p>[<code>flake8-import-conventions</code>] Add <code>datetime as
dt</code> as a conventional alias (<code>ICN001</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28790">#28790</a>)</p>
</li>
<li>
<p>Support Unicode dummy variable names (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28722">#28722</a>)</p>
<p>The default <a
href="https://docs.astral.sh/ruff/settings/#lint_dummy-variable-rgx"><code>lint.dummy-variable-rgx</code></a>
now recognizes underscore-prefixed Unicode names, such as
<code>_次</code>, as dummy variables.</p>
</li>
<li>
<p>Update to Unicode 17 (<a
href="https://redirect.github.com/astral-sh/ruff/pull/21229">#21229</a>,
<a
href="https://redirect.github.com/astral-sh/ruff/pull/28784">#28784</a>)</p>
<p>Ruff now uses Unicode 17 data for identifier normalization and named
character escapes (<code>&quot;\N{...}&quot;</code>).</p>
</li>
<li>
<p>Always show unsafe and display-only fixes in the CLI (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27810">#27810</a>)</p>
</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/astral-sh/ruff/commit/5b27c1ccfaa230fb195855f5cf3404a21e3379cd"><code>5b27c1c</code></a>
Bump version to 0.17.0 (<a
href="https://redirect.github.com/astral-sh/ruff/issues/29259">#29259</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/8f362bf4cb5dbad095ac416602496705d41fc843"><code>8f362bf</code></a>
Integrate vendored Unicode names into Ruff</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/88a50d695c1142294bb4c780fad47d3306173885"><code>88a50d6</code></a>
Revert upstream Unicode loose matching</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/276832aa91f2086a6ec880884fcdd987991cddf2"><code>276832a</code></a>
Revert upstream Unicode alias normalization</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/26911caa2800758779965510d2f222b438abbb38"><code>26911ca</code></a>
Vendor unicode_names2 from upstream</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/27e3797508d1a7ad69e4900d51e38d78785aaf73"><code>27e3797</code></a>
[<code>ruff</code>] Stabilize <code>os-path-commonprefix</code>
(<code>RUF071</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28764">#28764</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/bbb52c1267cf39aba67e54c2b5800878d23073a9"><code>bbb52c1</code></a>
[<code>flake8-tidy-imports</code>] Stabilize
<code>lazy-import-immediately-resolved</code> (`TID255...</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/5aa9cbd3a49d32b24ac21fa7797ca87a330792a2"><code>5aa9cbd</code></a>
[<code>flake8-tidy-imports</code>] Stabilize
<code>lazy-import-mismatch</code> (<code>TID254</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28760">#28760</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/dba1bc893aedfeea2064c4e8e764135f0d44dc3f"><code>dba1bc8</code></a>
[<code>flake8-import-conventions</code>] Add <code>datetime as dt</code>
as a conventional alias (`...</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/ef23c9c39eb3029bab0139c3ea7ae6d95c4131e0"><code>ef23c9c</code></a>
Update default and latest Python versions for 3.15 (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28792">#28792</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/astral-sh/ruff/compare/0.16.8...0.17.0">compare
view</a></li>
</ul>
</details>
<br />

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-15 21:50:07 -05:00
dependabot[bot]andJD Davis e51f6b35e4 ci: Bump astral-sh/setup-uv from 10.2.0 to 10.3.0 in the actions-minor-patch group (#4220)
## Description

Qualify setup-uv v10.3.0 in the shipping dependency-audit job and
exclude vulnerable MCP SDK versions.

## Type of Change

- [x] Bug fix / dependency security and qualification

## Changes Made

Synced with upstream `main`
(`486afaac7426fa1d6735fe2ce6ae37630d9d11ae`). No contributor
implementation logic changed. Tested head:
`85e8f27185ce8b5b99a3d32b8a2575fe3787d108`. Includes the reviewed
dependency-floor fix from #4239 because the vulnerable version was still
permitted by shipping extras.

## Dependency assessment

Astral maintains setup-uv and uv. v10.3.0 adds Python architecture
support and known checksums for uv 0.13.0; the audit job installs
current uv, so maintaining verified installer support matters to its
supply-chain gate. This action downloads uv on the runner; it adds no
package to the shipped Python runtime. The reviewed MCP CVE-2026-59951
prerequisite is included without lifting the SDK v1 cap.

## Testing

Branch dependency contract: 1 passed. uv lock --check: passed.
Equivalent shipping proxy+mcp export audited on #4221: no known
vulnerabilities. Hosted dependency-audit exercises the updated action.

### Test Output

```text
Branch dependency contract: 1 passed. uv lock --check: passed. Equivalent shipping proxy+mcp export audited on #4221: no known vulnerabilities. Hosted dependency-audit exercises the updated action.
```

## Real Behavior Proof

- Environment: Windows, PowerShell; installed Python/uv, Node/npm/Bun
and Rust tooling as applicable. No live provider/model used.
- Exact commands / steps:

```text
uv export --frozen --no-dev --extra proxy --extra mcp --no-emit-project --format requirements-txt
uvx pip-audit --no-deps --disable-pip -r <exported requirements>
uv lock --check
python -m pytest -q tests/test_mcp_dependency_contract.py
git diff --check
```

- Observed result: Branch dependency contract: 1 passed. uv lock
--check: passed. Equivalent shipping proxy+mcp export audited on #4221:
no known vulnerabilities. Hosted dependency-audit exercises the updated
action.
- Not tested: live model/provider traffic and full Docker E2E locally;
hosted cross-platform checks are running on the pushed head. Read hosted
results before merging. Focused checks are not a claim of complete
platform qualification.

## Runtime Rollout Safety

- Rollout-managed features: none added or enabled.
- Minimum rollout channel: unchanged.
- Stable/default behavior changed: dependency versions/ranges and
associated install metadata only; no feature rollout defaults changed.
- Kill switch / disable path: existing optional extras and plugin opt-in
paths remain available.
- Unsafe override required: no runtime qualification bypass. Security
dependency override is documented above where applicable.
- Qualification impact: hosted checks and the focused evidence above
must pass; no existing gate is removed.
- Rollback path: revert this dependency change and restore its prior
lockfiles together; retain the patched MCP minimum or another reviewed
security remediation.

## Review Readiness

- [x] Maintainer self-review and focused verification performed.
- [x] All hosted checks passed on the reviewed head. Ready for final
human merge review.

## Checklist

- [x] No contributor implementation logic rewritten.
- [x] Committed lockfiles checked against the changed manifests.
- [x] No manual CHANGELOG.md changes.
- [x] Known limitations recorded above.

## Original Dependabot update

Bumps the actions-minor-patch group with 1 update:
[astral-sh/setup-uv](https://github.com/astral-sh/setup-uv).

Updates `astral-sh/setup-uv` from 10.2.0 to 10.3.0
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/setup-uv/releases">astral-sh/setup-uv's
releases</a>.</em></p>
<blockquote>
<h2>v10.3.0 🌈 Add Python architecture selection</h2>
<h2>Changes</h2>
<p>This release adds the <code>python-arch</code> input to select a
Python architecture independently of the Python version. With
<code>uv</code> 0.13.0 or later, set <code>python-arch: x86_64</code> to
use x64 Python on Windows ARM64 runners.</p>
<p>It also includes embedded checksums for <code>uv</code> releases
through 0.13.0.</p>
<ul>
<li>Use macOS 15 runners for tests <a
href="https://github.com/charliermarsh"><code>@​charliermarsh</code></a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1081">#1081</a>)</li>
</ul>
<h2>🚀 Enhancements</h2>
<ul>
<li>Add <code>python-arch</code> support <a
href="https://github.com/zanieb"><code>@​zanieb</code></a> (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1079">#1079</a>)</li>
</ul>
<h2>🧰 Maintenance</h2>
<ul>
<li>chore: update known checksums for 0.13.0 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1089">#1089</a>)</li>
<li>chore: update known checksums for 0.12.24 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1084">#1084</a>)</li>
<li>chore: update known checksums for 0.12.23 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1082">#1082</a>)</li>
<li>chore: update known checksums for 0.12.22 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1080">#1080</a>)</li>
<li>chore: update known checksums for 0.12.21 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1078">#1078</a>)</li>
<li>chore: update known checksums for 0.12.20 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1076">#1076</a>)</li>
<li>chore: update known checksums for 0.12.19 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1068">#1068</a>)</li>
<li>chore: update known checksums for 0.12.18 @<a
href="https://github.com/apps/github-actions">github-actions[bot]</a>
(<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1065">#1065</a>)</li>
</ul>
<h2>⬆️ Dependency updates</h2>
<ul>
<li>chore(deps): bump zizmorcore/zizmor-action from 0.6.2 to 0.6.3 @<a
href="https://github.com/apps/dependabot">dependabot[bot]</a> (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1077">#1077</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/1c37ad07a6a961277cf70c0d37d6f313000f5884"><code>1c37ad0</code></a>
chore: update known checksums for 0.13.0 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1089">#1089</a>)</li>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/b3c9b5fc56ebc90760c43b1ac9552c0d1705d3ca"><code>b3c9b5f</code></a>
chore: update known checksums for 0.12.24 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1084">#1084</a>)</li>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/b06acff4b6a41bdd9cdac56507ead0bd7734e757"><code>b06acff</code></a>
Add <code>python-arch</code> support (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1079">#1079</a>)</li>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/c84232ca4fde9b022e20a930bfbbecd386b56fdf"><code>c84232c</code></a>
chore: update known checksums for 0.12.23 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1082">#1082</a>)</li>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/51fdd265d38a27ffcbca0da885510bc6fcc0ff55"><code>51fdd26</code></a>
Use macOS 15 runners for tests (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1081">#1081</a>)</li>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/a96208bed1fb5efb8da349c9bcc6cc58af9e7d74"><code>a96208b</code></a>
chore: update known checksums for 0.12.22 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1080">#1080</a>)</li>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/0e3884b860e20d3f4d5daa2347130beb51ccde47"><code>0e3884b</code></a>
chore: update known checksums for 0.12.21 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1078">#1078</a>)</li>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/bcf05803b55ef01a5ec6368521ee1b42f97bc438"><code>bcf0580</code></a>
chore: update known checksums for 0.12.20 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1076">#1076</a>)</li>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/b92a892142bde7280cd163c2abff341413314f9f"><code>b92a892</code></a>
chore(deps): bump zizmorcore/zizmor-action from 0.6.2 to 0.6.3 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1077">#1077</a>)</li>
<li><a
href="https://github.com/astral-sh/setup-uv/commit/227a0f6bea25cde3444f52decccf4a18de6635f4"><code>227a0f6</code></a>
chore: update known checksums for 0.12.19 (<a
href="https://redirect.github.com/astral-sh/setup-uv/issues/1068">#1068</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/astral-sh/setup-uv/compare/v10.2.0...v10.3.0">compare
view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=astral-sh/setup-uv&package-manager=github_actions&previous-version=10.2.0&new-version=10.3.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions


</details>
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4220"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-15 21:46:32 -05:00
9e5dac7c74 fix(deps): require hf-xet>=1.6.0 so a Hub download can't crash Python at exit (#4192)
## Description

A Python process that has downloaded from the Hugging Face Hub can crash
at exit. hf-xet (pulled in by `huggingface-hub`) keeps its worker
threads alive after a download. Before 1.6.0 it was built with pyo3's
`auto-initialize`, so a worker that runs while the interpreter shuts
down calls `Py_InitializeEx` and segfaults:

```text
EXC_BAD_ACCESS (SIGSEGV), faulting thread "hf-xet-10"
  libpython3.10.dylib  dict_dealloc
  libpython3.10.dylib  _PyImport_FixupExtensionObject
  libpython3.10.dylib  pycore_interp_init
  libpython3.10.dylib  Py_InitializeFromConfig
  libpython3.10.dylib  Py_InitializeEx
  hf_xet.abi3.so       ...
```

A rarer variant aborts on the main thread with `Fatal Python error:
_Py_FatalError_TstateNULL` (`subtype_dealloc` ← `gc_collect_main` ←
`finalize_modules` ← `Py_FinalizeEx`), with the hf-xet runtime's threads
still alive. hf-xet 1.5.1 fixed the progress thread that caused that
one, and 1.6.0 dropped `auto-initialize`.

For Headroom this shows up as an intermittent exit code 139 (or 134)
from pytest runs that download a model, and it can hit any CLI or proxy
process at exit after a Hub download. Nothing is lost by then, but it's
a crash report and a non-zero exit.

No linked issue.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `pyproject.toml`: `hf-xet>=1.6.0` in `[project].dependencies`, with
`huggingface-hub`'s own platform marker for hf-xet (`platform_machine ==
'AMD64' or … 'x86_64'`) and a comment saying why. hf-xet is already in
every install, through `litellm` → `tokenizers` → `huggingface-hub` →
`hf-xet` (no markers on that chain), so this installs nothing new on any
platform. It only raises the minimum, and it reaches the published
wheel. (The first commit had it in `[tool.uv] constraint-dependencies`,
which never reaches the wheel; see review.)
- `uv.lock`: hf-xet 1.5.0 → 1.6.0. I relocked with uv 0.11.0 because
newer uv (0.13) rewrites the lock format (`revision = 3` → `5`) and
unrelated markers. The diff is only the hf-xet entry and its requirement
line, and `uv lock --check` passes.

## Dependency Change (`hf-xet` 1.5.0 → 1.6.0)

- **Why this package:** it's not added. It's already a transitive
dependency via `huggingface-hub`, used for Xet-backed Hub downloads.
This sets a floor only.
- **Who maintains it:** Hugging Face (`huggingface/xet-core`),
Apache-2.0, released regularly (1.5.1 on 2026-06-08, 1.5.2 on
2026-07-16, 1.6.0 on 2026-08-03, 1.7.0 on 2026-10-06).
- **Install surface:** the same 16 wheels as 1.5.2 and 1.7.0:
`cp38-abi3` and `cp314t` for macOS x86_64/arm64, manylinux
x86_64/aarch64, musllinux x86_64/aarch64 and Windows amd64/arm64. 1.5.x
also shipped `cp313t` (free-threaded 3.13) wheels; 1.6.0 doesn't, so
that build would compile from the sdist. `requires-python` is `>=3.8`,
unchanged.
- **Why this version and not 1.5.2 or 1.7.0:**
  - 1.5.2 still crashes: 5 of 40 runs in the repro below.
- 1.6.0 is the release that drops `auto-initialize`, and it's been out
for over two months.
- 1.7.0 also passes, but it adds client-side telemetry reports for each
upload and download. That's new data leaving the machine, which deserves
its own decision for `HEADROOM_OFFLINE` users, not a ride-along in a
crash fix. The floor allows 1.7.0, so anyone who resolves on their own
gets it.
- **Scope:** it's a runtime floor in the wheel's metadata
(`Requires-Dist: hf-xet>=1.6.0 ; platform_machine == …`), so pip and uv
upgrade an existing hf-xet 1.5.x. Verified with a wheel built from this
branch: over an environment with hf-xet 1.5.0, installing the published
`headroom-ai==0.40.0` keeps 1.5.0, and installing this wheel upgrades it
(to 1.7.0, the newest the floor allows).

## Testing

- [x] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`) (no Python changed)
- [ ] Type checking passes (`mypy headroom`) (no Python changed)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
# Repro: 40 runs of one test that downloads from the Hub, each with an empty HOME so the
# download really happens; hf-xet swapped in through a PYTHONPATH overlay, macOS 27 / Python 3.10.18
$ for i in $(seq 40); do HOME=$(mktemp -d) pytest -q \
    tests/test_proxy_project_savings.py::test_middleware_binds_project_header_to_context; done
hf-xet 1.5.0: 7/40 runs exit 139 (SIGSEGV, stack above)
hf-xet 1.5.2: 5/40 runs exit 139
hf-xet 1.6.0: 0/40
hf-xet 1.7.0: 0/40

$ uv lock --check            # uv 0.11.0
Resolved 251 packages

# hf-xet 1.6.0, empty HOME: Hub-download, pricing/savings, relevance and egress tests
$ pytest -q tests/test_hf_revision_pinning.py tests/test_proxy_project_savings.py tests/test_bundled_tools_savings.py \
    tests/test_*pric*.py tests/test_cost*.py tests/test_*savings*.py tests/test_offline_egress_chokepoint.py tests/test_relevance.py
5 failed, 730 passed, 5 skipped
# The 5 are TestOtlpExporterOffline / TestLangfuseExporterOffline / TestStartupRefusal: the OTel extras
# aren't in this venv, and they fail the same way on main here.
```

### Wheel metadata and upgrade

```text
$ maturin build --profile dev        # from this branch
$ unzip -p headroom_ai-0.40.0-cp310-abi3-macosx_11_0_arm64.whl '*.dist-info/METADATA' | grep hf-xet
Requires-Dist: hf-xet>=1.6.0 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'

# fresh Python 3.12 venvs, each starting with hf-xet==1.5.0 + huggingface-hub installed
$ uv pip install headroom-ai==0.40.0      # published
hf-xet 1.5.0 -> 1.5.0   (kept: the crash stays)
$ uv pip install ./headroom_ai-0.40.0-…whl  # this branch
hf-xet 1.5.0 -> 1.7.0   (upgraded); `import headroom` works
```

## Real Behavior Proof

- Environment: macOS 27.0.1 (Apple M5), the repo's `.venv` (Python
3.10.18, huggingface-hub 1.16.1), `main` at `f1bc2609`.
- First seen as a `Fatal Python error … Garbage-collecting` at the end
of a pricing test run. macOS crash reports from the repro loops show the
`Py_InitializeEx` segfault on an `hf-xet-N` thread every time (12
reports from the 1.5.0 and 1.5.2 loops).
- Not tested: Linux and Windows. I don't know how often it happens on CI
runners; it's timing-dependent.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: only the locked hf-xet version.
Download behavior is the same.
- Kill switch / disable path: N/A.
- Unsafe override required: no.
- Qualification impact: none expected.
- Rollback path: revert this PR.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A.

## Additional Notes

No regression test is added: the crash is a timing race at interpreter
teardown, so a test would be flaky by design. The repro loop above is
the check.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4192"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

- The first run of the `template` check failed on a GitHub API `HTTP
500` in its "Ensure governance labels exist" step, before it looked at
this description. Re-running needs admin rights, so I added this note to
trigger it again.

---------

Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-15 16:35:51 -05:00
JD Davisandgithub-actions[bot] 76133cff59 chore: release 0.41.0 (#4002)
🤖 I have created a release *beep* *boop*
---


##
[0.41.0](https://github.com/headroomlabs-ai/headroom/compare/v0.40.0...v0.41.0)
(2026-10-13)


### Features

* **antigravity:** add native Google Antigravity IDE integration
([#3817](https://github.com/headroomlabs-ai/headroom/issues/3817))
([cd4367b](https://github.com/headroomlabs-ai/headroom/commit/cd4367b040bf80b7358f100da54994f6d5fbfcfe))
* **opencode:** support the OpenCode 2.x plugin API
([#3999](https://github.com/headroomlabs-ai/headroom/issues/3999))
([1d4b357](https://github.com/headroomlabs-ai/headroom/commit/1d4b357ca745549382e1ed9a3a6d39b5df52d3d5))
* **plugins:** add headroom-snip Claude Code mod that animates
compression
([#3980](https://github.com/headroomlabs-ai/headroom/issues/3980))
([17abee2](https://github.com/headroomlabs-ai/headroom/commit/17abee2721c1946bc8903d623bec91ff6e531c17))
* **proxy:** native spend/savings stats + dashboard for the Rust proxy
([#2321](https://github.com/headroomlabs-ai/headroom/issues/2321))
([70b21c1](https://github.com/headroomlabs-ai/headroom/commit/70b21c12c41cd128c7b8700c33b29b687de567a4))
* **router:** add max_output_tokens condition to ModelRoute
([#3898](https://github.com/headroomlabs-ai/headroom/issues/3898))
([01185e3](https://github.com/headroomlabs-ai/headroom/commit/01185e32d393c02ae63b104429f6dbfc6cdd1da0))
* **savings:** per-agent attribution in history checkpoints and rollups
([#2627](https://github.com/headroomlabs-ai/headroom/issues/2627))
([489de46](https://github.com/headroomlabs-ai/headroom/commit/489de468258584c69c90c798397d81e0b35ace67))
* show the Headroom for Teams offer in the dashboard, docs, llms.txt and
release notes
([#3991](https://github.com/headroomlabs-ai/headroom/issues/3991))
([1ad92f0](https://github.com/headroomlabs-ai/headroom/commit/1ad92f0cbc3dea27676e253588100f64a2af6994))


### Bug Fixes

* **anthropic:** route /api/hello connectivity probes to Anthropic
([#3336](https://github.com/headroomlabs-ai/headroom/issues/3336))
([#4059](https://github.com/headroomlabs-ai/headroom/issues/4059))
([931e5b9](https://github.com/headroomlabs-ai/headroom/commit/931e5b9666f4022feb38abadfbdb77c96c69e95a))
* **beacon:** stop Cloudflare logging senders' IP addresses
([#4018](https://github.com/headroomlabs-ai/headroom/issues/4018))
([db983ba](https://github.com/headroomlabs-ai/headroom/commit/db983bacc616fec3d622e8a039b47135b1ad4166))
* **cache:** keep cache mode when Claude Code re-serializes its last
reply ([#4003](https://github.com/headroomlabs-ai/headroom/issues/4003))
([aeb09f8](https://github.com/headroomlabs-ai/headroom/commit/aeb09f8d1884318d27b05b440b44c603e1c0d727))
* **cache:** retain prefix trackers for the provider cache lifetime
([#4023](https://github.com/headroomlabs-ai/headroom/issues/4023))
([9553d42](https://github.com/headroomlabs-ai/headroom/commit/9553d4292f949224105bfee8c29f4979a2c3092a))
* **cache:** stop Claude Code forks from cold-starting the
conversation's lineage
([#4043](https://github.com/headroomlabs-ai/headroom/issues/4043))
([1cf4d05](https://github.com/headroomlabs-ai/headroom/commit/1cf4d053d2bae276280dd3b71ebcf00cfd4d9cfc))
* **ccr:** serve headroom_retrieve when the model calls it alongside
client tools
([#4034](https://github.com/headroomlabs-ai/headroom/issues/4034))
([01d9194](https://github.com/headroomlabs-ai/headroom/commit/01d9194854233ef6ed04005cf0a5b8c32bf65d6d))
* **cli:** name the broken Codex config, write init configs atomically,
keep the identity check
([#4129](https://github.com/headroomlabs-ai/headroom/issues/4129))
([976aa71](https://github.com/headroomlabs-ai/headroom/commit/976aa714ef3e19174dc0cb586cee7b20d064e4ef))
* **cli:** pass configured SSL context to stdlib urlopen calls
([#4011](https://github.com/headroomlabs-ai/headroom/issues/4011))
([22d0905](https://github.com/headroomlabs-ai/headroom/commit/22d0905a73d1498e1a3658427687416373c1d4a1))
* **cli:** say why the proxy failed to start
([#4120](https://github.com/headroomlabs-ai/headroom/issues/4120))
([f3d240b](https://github.com/headroomlabs-ai/headroom/commit/f3d240bcae5f12d87925b5fa46d36eecff19ba2d))
* **codex:** make unwrap codex remove headroom init routing
([#3920](https://github.com/headroomlabs-ai/headroom/issues/3920))
([3260795](https://github.com/headroomlabs-ai/headroom/commit/326079517b40d2bbec6d2c7a453b22be9b8b6755))
* **codex:** preserve auth.json API keys through Headroom
([#3355](https://github.com/headroomlabs-ai/headroom/issues/3355))
([a6523b1](https://github.com/headroomlabs-ai/headroom/commit/a6523b19678af49ed1039fe946ae0cfee2181509))
* **copilot:** honour GitHub's advertised Business/Enterprise host by
default
([#4155](https://github.com/headroomlabs-ai/headroom/issues/4155))
([1dc7a18](https://github.com/headroomlabs-ai/headroom/commit/1dc7a183f55db35188aefa95f9cd4aed18377862))
* **copilot:** send VS Code next-edit requests to the completions host
([#4188](https://github.com/headroomlabs-ai/headroom/issues/4188))
([22a1296](https://github.com/headroomlabs-ai/headroom/commit/22a1296cfabc855f9bc6e36a1bcb0f9e788f75a5))
* **dashboard:** keep savings profile visible in light mode
([#2544](https://github.com/headroomlabs-ai/headroom/issues/2544))
([4e4f49d](https://github.com/headroomlabs-ai/headroom/commit/4e4f49d058846c44ae6061edd5a53776c03a0507))
* **dashboard:** show the effective value in settings enum selects
([#4032](https://github.com/headroomlabs-ai/headroom/issues/4032))
([20ce054](https://github.com/headroomlabs-ai/headroom/commit/20ce054f8d34af50106daa0c8aa518231e17004b))
* **deps:** bump quinn-proto to 0.11.19 for RUSTSEC-2026-0338..0342
([#4178](https://github.com/headroomlabs-ai/headroom/issues/4178))
([49751ec](https://github.com/headroomlabs-ai/headroom/commit/49751ec4c797c9ff8ae7e3cdfed6c8372c7fbfcd))
* **deps:** clear the two high npm advisories failing the Security
workflow
([#4004](https://github.com/headroomlabs-ai/headroom/issues/4004))
([5a516b5](https://github.com/headroomlabs-ai/headroom/commit/5a516b54afd50156521638645a9063992e395a7b))
* **deps:** recommend headroom-ai for optional extras
([#4046](https://github.com/headroomlabs-ai/headroom/issues/4046))
([f1bc260](https://github.com/headroomlabs-ai/headroom/commit/f1bc260948c159549d6937e9c4d2cf969256f2bb))
* **deps:** support Intel macOS ONNX Runtime resolution
([#3823](https://github.com/headroomlabs-ai/headroom/issues/3823))
([51ec6e8](https://github.com/headroomlabs-ai/headroom/commit/51ec6e8ffef8d3c76b0dc7b283c8c5eabcd6acc2))
* **docker:** adds mount for the litellm config dir
([#2454](https://github.com/headroomlabs-ai/headroom/issues/2454))
([64a661d](https://github.com/headroomlabs-ai/headroom/commit/64a661d5b4898d97061bfcaa10caad477b319b37))
* **gateway:** report why /v1/compress/response rejected a body
([#4081](https://github.com/headroomlabs-ai/headroom/issues/4081))
([5cac7ab](https://github.com/headroomlabs-ai/headroom/commit/5cac7ab693c2f1e3d8dbbe4756f0e7f6fa0687d6))
* **grok:** attribute api.x.ai chat outcomes as provider xai, recognize
grok-shell UA
([#2626](https://github.com/headroomlabs-ai/headroom/issues/2626))
([b1fb162](https://github.com/headroomlabs-ai/headroom/commit/b1fb162b622327102832f15b2ca14a4613da9fcd))
* **install/windows:** back persistent-service with an always-on task
([#1866](https://github.com/headroomlabs-ai/headroom/issues/1866))
([#2460](https://github.com/headroomlabs-ai/headroom/issues/2460))
([5682883](https://github.com/headroomlabs-ai/headroom/commit/5682883bb03472caeb510d6ff84070d5558d0f62))
* **install:** distinguish protocol targets in status
([#4040](https://github.com/headroomlabs-ai/headroom/issues/4040))
([79f2c27](https://github.com/headroomlabs-ai/headroom/commit/79f2c2781a1e6d5a13c75ae233e01c6d8d910ef1))
* **install:** keep an explicitly empty dashboard allowlist on Windows
PowerShell 5.1
([#4012](https://github.com/headroomlabs-ai/headroom/issues/4012))
([c195a12](https://github.com/headroomlabs-ai/headroom/commit/c195a1220f8d3525879c87486bd63d96e870e648))
* **install:** preserve OpenCode edits during reactivation
([#4022](https://github.com/headroomlabs-ai/headroom/issues/4022))
([40955b0](https://github.com/headroomlabs-ai/headroom/commit/40955b0eef2e509aad1a200db9cfa0762ca457ce))
* **learn:** decode sanitized pattern-id markers and keep visible-text
dedup keys
([#3956](https://github.com/headroomlabs-ai/headroom/issues/3956))
([ec1ba70](https://github.com/headroomlabs-ai/headroom/commit/ec1ba70c974fb0729870bfd444cdc1152a1b4301))
* **learn:** make live traffic learning use the shared error classifier
([#4110](https://github.com/headroomlabs-ai/headroom/issues/4110))
([e6eaa41](https://github.com/headroomlabs-ai/headroom/commit/e6eaa411791750884a7eb2594d0b86f9e4100f81))
* **learn:** pin the learned verbosity level on a cache-mode proxy
([#4033](https://github.com/headroomlabs-ai/headroom/issues/4033))
([71663b4](https://github.com/headroomlabs-ai/headroom/commit/71663b44e26fc2e0ad7d52c0b264aa7500926900))
* **logging:** add payload-safe helpers for exceptions, URLs, ids and
repeat warnings
([#4138](https://github.com/headroomlabs-ai/headroom/issues/4138))
([bebe559](https://github.com/headroomlabs-ai/headroom/commit/bebe5593ea4abaf326215c7236586b38e7b325a5))
* **onnx:** stop magika's ORT intra-op pool from spinning idle cores
([#4189](https://github.com/headroomlabs-ai/headroom/issues/4189))
([2016dc6](https://github.com/headroomlabs-ai/headroom/commit/2016dc6d6064926790b9c843fbf1798d2e660524))
* **openclaw:** preserve tool-call thought signatures
([#4038](https://github.com/headroomlabs-ai/headroom/issues/4038))
([37f3f9e](https://github.com/headroomlabs-ai/headroom/commit/37f3f9efe16f6b1ff94e03dbae85a27e387097a2))
* **plugins/openclaw:** keep compression system-prompt notice
cache-stable
([#3811](https://github.com/headroomlabs-ai/headroom/issues/3811))
([f885187](https://github.com/headroomlabs-ai/headroom/commit/f8851878a4feb0b64df8a5b22a89ebb198199bdf))
* **pricing:** reconcile cache billing with model-specific LiteLLM rates
([#3033](https://github.com/headroomlabs-ai/headroom/issues/3033))
([463c1a4](https://github.com/headroomlabs-ai/headroom/commit/463c1a43e30fc33cb256a3f455daf28043e53b05))
* **providers:** drop the shadowed POST /v1/messages route spec
([#4075](https://github.com/headroomlabs-ai/headroom/issues/4075))
([69a16cb](https://github.com/headroomlabs-ai/headroom/commit/69a16cb59c0fe4b8233caf5824e34e5772f48d81))
* **proxy/bedrock:** record the real upstream status on InvokeModel
outcomes
([#4025](https://github.com/headroomlabs-ai/headroom/issues/4025))
([159daa2](https://github.com/headroomlabs-ai/headroom/commit/159daa25a0886fb5c5808e37d62fe8cf4971290a))
* **proxy/streaming:** tolerate malformed upstream SSE events
([#2558](https://github.com/headroomlabs-ai/headroom/issues/2558))
([d091fbd](https://github.com/headroomlabs-ai/headroom/commit/d091fbd9f2ccc522de87350c0bc7a85f0de230eb))
* **proxy:** astgrep disk verify truncation
([#3192](https://github.com/headroomlabs-ai/headroom/issues/3192))
([1fb4cba](https://github.com/headroomlabs-ai/headroom/commit/1fb4cbaea0dcc62aa092bac3af04991d994207d0))
* **proxy:** break the compact-every-turn loop near the real context
window
([#2942](https://github.com/headroomlabs-ai/headroom/issues/2942))
([76cceeb](https://github.com/headroomlabs-ai/headroom/commit/76cceeb48728a4f179626e43f1ec23d1f7cebd79))
* **proxy:** classify failed streams as failed requests
([#3747](https://github.com/headroomlabs-ai/headroom/issues/3747))
([42d4f58](https://github.com/headroomlabs-ai/headroom/commit/42d4f58b434bdca8f81cabf5f00d6e8e02a7fb2c))
* **proxy:** don't retry a 429/529 that cannot succeed within the
backoff cap
([#3992](https://github.com/headroomlabs-ai/headroom/issues/3992))
([a961a6f](https://github.com/headroomlabs-ai/headroom/commit/a961a6fea083a9a739df40d1371e1e7ec108516d))
* **proxy:** don't send a memory continuation with unanswered client
tool calls
([#4009](https://github.com/headroomlabs-ai/headroom/issues/4009))
([#4013](https://github.com/headroomlabs-ai/headroom/issues/4013))
([87e05b6](https://github.com/headroomlabs-ai/headroom/commit/87e05b68b8aa578f1439abfc8006b38cd09db14d))
* **proxy:** forward x-litellm-key-* headers on streaming path
([#2532](https://github.com/headroomlabs-ai/headroom/issues/2532))
([33ade5b](https://github.com/headroomlabs-ai/headroom/commit/33ade5b0e1019adf34d9fd888cc105d4bc23935e))
* **proxy:** ignore defer_loading when measuring a turn hook's tool
delta ([#4056](https://github.com/headroomlabs-ai/headroom/issues/4056))
([f8212a3](https://github.com/headroomlabs-ai/headroom/commit/f8212a39dcc5b03a75e98b60a8ecdef81a0f48ed))
* **proxy:** keep Claude Haiku 5.5 mid-conversation system messages in
place ([#4153](https://github.com/headroomlabs-ai/headroom/issues/4153))
([a9eb2a7](https://github.com/headroomlabs-ai/headroom/commit/a9eb2a7b6fe6b75042646284109846da46939649))
* **proxy:** keep leading Anthropic system payloads valid
([#3671](https://github.com/headroomlabs-ai/headroom/issues/3671))
([d9e29bb](https://github.com/headroomlabs-ai/headroom/commit/d9e29bb2600a746dea80caa7721f0fb98109589c))
* **proxy:** log the savings and metrics failures that currently vanish
([#4084](https://github.com/headroomlabs-ai/headroom/issues/4084))
([2800932](https://github.com/headroomlabs-ai/headroom/commit/2800932e1827400cf41be1cff6154f78f691ccce))
* **proxy:** read stream cache usage from message_delta; keep Fireworks
sessions on one replica
([#4174](https://github.com/headroomlabs-ai/headroom/issues/4174))
([30b22df](https://github.com/headroomlabs-ai/headroom/commit/30b22df7fda6163c576c8f720982bf1ca48762c3))
* **proxy:** record the provider's billed input count on streamed turns
([#4052](https://github.com/headroomlabs-ai/headroom/issues/4052))
([a9815bb](https://github.com/headroomlabs-ai/headroom/commit/a9815bbb5fa2d2347ceeeac0f01cc9f041e2ded2))
* **proxy:** say why proxy.log is missing and why a knob or extension
was ignored
([#4088](https://github.com/headroomlabs-ai/headroom/issues/4088))
([72302a3](https://github.com/headroomlabs-ai/headroom/commit/72302a3998104a400765fa7e21177ed59f429f38))
* **release:** synchronize editable uv lock version
([#4054](https://github.com/headroomlabs-ai/headroom/issues/4054))
([3f99066](https://github.com/headroomlabs-ai/headroom/commit/3f990663cca5b9dd2ed0ca26343b0619bbab0aa7))
* **router:** bound ML compression per request, not just per block
([#3721](https://github.com/headroomlabs-ai/headroom/issues/3721))
([f37980f](https://github.com/headroomlabs-ai/headroom/commit/f37980f7f7612e7ae58b4f3b5b98f185e216fd91))
* **router:** preserve nested JSON records through compression
([#3680](https://github.com/headroomlabs-ai/headroom/issues/3680))
([fd06703](https://github.com/headroomlabs-ai/headroom/commit/fd067033da185f1abf48ea58e63c6d71d4d11ec1))
* **savings,ccr:** log the ledger and MCP failures that are swallowed
silently
([#4105](https://github.com/headroomlabs-ai/headroom/issues/4105))
([97680e7](https://github.com/headroomlabs-ai/headroom/commit/97680e7782423308b8e35c5560fea5b1d9434e1b))
* **savings:** don't let a thin holdout arm decide the headline number
([#3127](https://github.com/headroomlabs-ai/headroom/issues/3127))
([2a12e03](https://github.com/headroomlabs-ai/headroom/commit/2a12e035a3239bdfbb4fe75e1246923c144aabef))
* **security:** resolve 23 open CodeQL alerts
([#4045](https://github.com/headroomlabs-ai/headroom/issues/4045))
([a88e2d5](https://github.com/headroomlabs-ai/headroom/commit/a88e2d51452f7a2fa1882639585d482e1f05d92f))
* **security:** resolve high-severity CodeQL alerts
([#4005](https://github.com/headroomlabs-ai/headroom/issues/4005))
([dea9092](https://github.com/headroomlabs-ai/headroom/commit/dea9092e19385f286b7f67a64f4d85de2708d756))
* **smart-crusher:** preserve wrapped retrieval results in apply
([#4149](https://github.com/headroomlabs-ai/headroom/issues/4149))
([9762a14](https://github.com/headroomlabs-ai/headroom/commit/9762a14a40bde4d3f58a027c086b6ac75fbd5ed2))
* **subscription:** log a failed OTEL window update instead of passing
silently
([#4131](https://github.com/headroomlabs-ai/headroom/issues/4131))
([7d9dd55](https://github.com/headroomlabs-ai/headroom/commit/7d9dd55e7c4bbd2a95b054de7e5722c4cf20ce50))
* **toin:** make diagnostic pattern identifiers addressable
([#4021](https://github.com/headroomlabs-ai/headroom/issues/4021))
([def6d41](https://github.com/headroomlabs-ai/headroom/commit/def6d41185d3091d4ef42ae379829087deeaf38f))
* **transforms:** log failed transforms with tracebacks
([#3981](https://github.com/headroomlabs-ai/headroom/issues/3981))
([a654558](https://github.com/headroomlabs-ai/headroom/commit/a65455804ce6c16670af6fe253bd9f8f6105bfe3))
* **wrap:** carry the shared proxy's extensions over to a dedicated
Copilot proxy
([#4154](https://github.com/headroomlabs-ai/headroom/issues/4154))
([feea130](https://github.com/headroomlabs-ai/headroom/commit/feea130f81953030bda222ffe88abb61fbb60ee8))
* **wrap:** let `wrap opencode` target a third-party OpenAI-compatible
upstream
([#3125](https://github.com/headroomlabs-ai/headroom/issues/3125))
([0d7d61d](https://github.com/headroomlabs-ai/headroom/commit/0d7d61d5ccaee25d399ae3209e8ce067e8673b30))
* **wrap:** reject saved bob gateway URLs the proxy would not route
([#3975](https://github.com/headroomlabs-ai/headroom/issues/3975))
([944eafc](https://github.com/headroomlabs-ai/headroom/commit/944eafc6d4bcebbe6624cff95681f5af8b257868))
* **wrap:** trim the wrap claude startup banner
([#3900](https://github.com/headroomlabs-ai/headroom/issues/3900))
([aba75cb](https://github.com/headroomlabs-ai/headroom/commit/aba75cbf6d2fe1e4c728e4af258907d9c28028d0))
* **wrap:** warn when reused proxy ignores compression settings
([#4019](https://github.com/headroomlabs-ai/headroom/issues/4019))
([278bbc8](https://github.com/headroomlabs-ai/headroom/commit/278bbc8771938eec18e89df942e1594b6ddf41d4))


### Performance Improvements

* **proxy:** avoid eager dependency imports
([#3546](https://github.com/headroomlabs-ai/headroom/issues/3546))
([59bd482](https://github.com/headroomlabs-ai/headroom/commit/59bd482fa1661293d86834e73fe90f0ee21130c5))


### Code Refactoring

* **backends:** reuse the LiteLLM tool converters in the any-llm backend
([#4076](https://github.com/headroomlabs-ai/headroom/issues/4076))
([03538f2](https://github.com/headroomlabs-ai/headroom/commit/03538f2f2f55cafc0cec4ddf1b22e3189e2a0a24))
* **cli:** one missing-binary error for every wrap command
([#4122](https://github.com/headroomlabs-ai/headroom/issues/4122))
([2c2357a](https://github.com/headroomlabs-ai/headroom/commit/2c2357ad342de69d4576f0e38efc58646f054913))
* **cli:** remove test-only and dead helpers from wrap, proxy and mcp
([#4118](https://github.com/headroomlabs-ai/headroom/issues/4118))
([73f59a3](https://github.com/headroomlabs-ai/headroom/commit/73f59a32ccda8fe9de385031ccd032d1007be650))
* **compression:** deprecate the test-only UniversalCompressor package
([#4095](https://github.com/headroomlabs-ai/headroom/issues/4095))
([fc8ff5a](https://github.com/headroomlabs-ai/headroom/commit/fc8ff5a7619271ffe306ffad50f2ee936d5d2158))
* **core:** remove unreferenced helpers, attributes and a shadowed
module
([#4091](https://github.com/headroomlabs-ai/headroom/issues/4091))
([08fce18](https://github.com/headroomlabs-ai/headroom/commit/08fce1831067005f048cb81f0033abc17a89e9fd))
* **graph:** drop the bespoke codebase-memory-mcp downloader nothing
calls ([#4102](https://github.com/headroomlabs-ai/headroom/issues/4102))
([30d23fb](https://github.com/headroomlabs-ai/headroom/commit/30d23fb799674a5d9a3c531baf09a307d62c2bf2))
* **mcp_registry:** share spec helpers and fold GrokRegistrar onto the
Codex TOML registrar
([#4121](https://github.com/headroomlabs-ai/headroom/issues/4121))
([6e14ee0](https://github.com/headroomlabs-ai/headroom/commit/6e14ee0bc2dde72378b841f708f73cdf79df6e2d))
* **memory,learn,cache:** remove unreferenced classes, methods and
constants
([#4112](https://github.com/headroomlabs-ai/headroom/issues/4112))
([abbf36f](https://github.com/headroomlabs-ai/headroom/commit/abbf36f052fca643a3cd5f7cadd21b5a7d4bf406))
* **memory:** deprecate the never-wired agent memory writers
([#4101](https://github.com/headroomlabs-ai/headroom/issues/4101))
([2e497cb](https://github.com/headroomlabs-ai/headroom/commit/2e497cbec3c26c1d2c83adcc94794164cbab3268))
* **memory:** deprecate the orphaned Mem0SystemAdapter
([#4114](https://github.com/headroomlabs-ai/headroom/issues/4114))
([7387b8c](https://github.com/headroomlabs-ai/headroom/commit/7387b8cc11ecdf4775faa6042e7cc15d114b4942))
* **memory:** drop the unused extraction prompts and tool schemas
([#4100](https://github.com/headroomlabs-ai/headroom/issues/4100))
([6d23895](https://github.com/headroomlabs-ai/headroom/commit/6d23895dc003e865c3c5d4690853551406e7cdc8))
* **memory:** remove the unused memory budget manager
([#4099](https://github.com/headroomlabs-ai/headroom/issues/4099))
([e7ac6ca](https://github.com/headroomlabs-ai/headroom/commit/e7ac6ca6f81834549a66fc0832b1ddb2470da245))
* **proxy:** delete the unused memory_tool_adapter module
([#4071](https://github.com/headroomlabs-ai/headroom/issues/4071))
([7e5d97f](https://github.com/headroomlabs-ai/headroom/commit/7e5d97fe29073af0751cc0abc7bdf6a6d3bd74a2))
* **proxy:** drop the test-only memory ranker and file-backed native
memory ops
([#4072](https://github.com/headroomlabs-ai/headroom/issues/4072))
([fc5ac70](https://github.com/headroomlabs-ai/headroom/commit/fc5ac70b4a1eac8f49d86ad386c76c67bab40372))
* **proxy:** parse HEADROOM_OUTPUT_HOLDOUT in one place
([#4082](https://github.com/headroomlabs-ai/headroom/issues/4082))
([1a4e419](https://github.com/headroomlabs-ai/headroom/commit/1a4e4194a0b26e4f09026c18ac6b8935c6a99c0c))
* **proxy:** remove dead aliases and wrappers from helpers,
body_forwarding, forwarded_headers
([#4080](https://github.com/headroomlabs-ai/headroom/issues/4080))
([63cc9af](https://github.com/headroomlabs-ai/headroom/commit/63cc9afa9d282aeae127e6af20d9a9efa2eebd7e))
* **proxy:** remove dead wiring and unused re-exports from server.py
([#4073](https://github.com/headroomlabs-ai/headroom/issues/4073))
([58387c1](https://github.com/headroomlabs-ai/headroom/commit/58387c1174e6f7f526c3677b72986079da554a8a))
* **proxy:** remove test-only and dead helpers from the handlers
([#4117](https://github.com/headroomlabs-ai/headroom/issues/4117))
([31d378b](https://github.com/headroomlabs-ai/headroom/commit/31d378b0e5337bf8c572ca272e8649762457dc5f))
* **proxy:** remove the unreachable debug branches from the Responses
payload compressor
([#4116](https://github.com/headroomlabs-ai/headroom/issues/4116))
([132cd58](https://github.com/headroomlabs-ai/headroom/commit/132cd583daeb968dd4121f0163677f5b1605f29c))
* **proxy:** remove the unreachable debug branches from the Responses
unit router
([#4115](https://github.com/headroomlabs-ai/headroom/issues/4115))
([25cc2d5](https://github.com/headroomlabs-ai/headroom/commit/25cc2d586316fee5cb67b7a25ef2927198a0ae6b))
* **proxy:** remove unreferenced and test-only helpers
([#4074](https://github.com/headroomlabs-ai/headroom/issues/4074))
([e5cbec5](https://github.com/headroomlabs-ai/headroom/commit/e5cbec5f1a860eb51e4e49507b8eb26742abba22))
* remove test-only compatibility helpers in rollout and agent_savings
([#4089](https://github.com/headroomlabs-ai/headroom/issues/4089))
([310c108](https://github.com/headroomlabs-ai/headroom/commit/310c108c24caef1839a538a28878b6709f8987f9))
* remove write-only and test-only code in subscription and install
([#4123](https://github.com/headroomlabs-ai/headroom/issues/4123))
([c191bee](https://github.com/headroomlabs-ai/headroom/commit/c191beef59cc9bde622cf7db251ac94eb2a20c70))
* **transforms:** deprecate the unused Python AnchorSelector port
([#4104](https://github.com/headroomlabs-ai/headroom/issues/4104))
([9b1971d](https://github.com/headroomlabs-ai/headroom/commit/9b1971dd82c941d683902014b203de4bf617cc61))
* **transforms:** deprecate unused compress_with_stats, extract_batch
and align_for_cache
([#4098](https://github.com/headroomlabs-ai/headroom/issues/4098))
([e4a1ec1](https://github.com/headroomlabs-ai/headroom/commit/e4a1ec19be787a312624fdca52e2184b9a4127b9))
* **transforms:** drop the Python mirror of the Rust log selector
([#4096](https://github.com/headroomlabs-ai/headroom/issues/4096))
([a20c76c](https://github.com/headroomlabs-ai/headroom/commit/a20c76c26b15557a1bf176c4ef84f46121550297))
* **transforms:** drop the Python mirror of the Rust search selector
([#4103](https://github.com/headroomlabs-ai/headroom/issues/4103))
([47f8710](https://github.com/headroomlabs-ai/headroom/commit/47f8710817ddc6612127662714b5fcecf83dc644))
* **transforms:** remove the unused summarize_dropped_items
([#4093](https://github.com/headroomlabs-ai/headroom/issues/4093))
([eaa7308](https://github.com/headroomlabs-ai/headroom/commit/eaa7308a52620ad803b13c7f66300d7196f63212))
* **transforms:** remove unused convenience wrappers and helpers
([#4097](https://github.com/headroomlabs-ai/headroom/issues/4097))
([5c72d82](https://github.com/headroomlabs-ai/headroom/commit/5c72d824f4d1ab0d46a960f8f61a14d000482591))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-10-14 17:45:55 -05:00
f3d240bcae fix(cli): say why the proxy failed to start (#4120)
## Description

Fixes two proxy startup failures that hid their cause from the user.

**1. `headroom proxy` on a port that is already in use.** It printed the
full banner, ending in "Press Ctrl+C to stop.", and then about 10 INFO
lines. The one line that mattered, uvicorn's `[Errno 48] ... address
already in use`, came next. After it came `event=proxy_shutdown
reason=signal` and a 10-line zero-valued session summary.

The command now checks the port before printing the banner and exits
with one clear line:

```
Error: Port 54351 on 127.0.0.1 is already in use by another process (Address already in use). Start this proxy on another port with --port N (env: HEADROOM_PORT).
```

When a Headroom proxy is the process holding the port, the message says
so instead. The check asks the address that is actually busy (IPv6
included), so a Headroom proxy on 127.0.0.1:P is never reported as the
owner of [::1]:P. When that address cannot be probed (a scoped IPv6
address, an unresolvable name), the message is the generic `already in
use (<reason>)`.

**2. `headroom wrap <tool>` when the proxy it starts dies during
startup.** The error quoted the last 500 characters of the proxy stdio
log. That was the wrong part of the log, for two reasons:
- The proxy logs its shutdown summary after the error, so the tail was
the summary box.
- The log is appended to across runs, so the tail could come from an
older run.

The error also never said where the log was. It now reads only this
run's output, at most its first 64 KiB and, when the head has no error,
its last 64 KiB (so a runaway log is never read whole, and an error
after a long burst of startup output is still found), quotes from the
first `ERROR` / `CRITICAL` / `Traceback` line or line-leading Click
`Error: ` (otherwise the end of the first non-blank window, so neither a
blank head nor a blank tail hides useful startup text), and adds `Full
log: <path>`. The timeout error now names the log too.

Refs #4136

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/cli/proxy.py`: new `_tcp_port_in_use` / `_refuse_busy_port`.
They run after the bind-policy check and before the banner, and are
skipped for `--uds`. The probe mirrors uvicorn's own bind, so it never
refuses a bind that uvicorn would accept:
- It sets `SO_REUSEADDR`, as both uvicorn paths do. A port in TIME_WAIT
after a restart is therefore not reported as busy.
- With one worker, it binds every address the host resolves to, with
`IPV6_V6ONLY`, the same way asyncio `create_server` does.
- With `--workers > 1`, it binds one AF_INET or AF_INET6 socket, as
uvicorn's `Config.bind_socket` does.
- On Windows, and for any error other than EADDRINUSE, it does nothing
and leaves the case to uvicorn, exactly as today.
- It returns the busy address. `_probe_host_for` maps it to the address
to ask: wildcards go to loopback of the same family (`0.0.0.0` to
`127.0.0.1`, `::` to `::1`), a hostname is resolved for IPv4, and a
scoped IPv6 address returns None (generic message).
- `headroom/cli/port_discovery.py`: `probe_headroom_proxy` takes an
optional keyword `host` (default `127.0.0.1`, so existing callers are
unchanged) and brackets IPv6 in the URL.
- `headroom/cli/wrap.py`:
  - `_start_proxy` records the stdio log size before spawning the proxy.
- New `_proxy_startup_failure_excerpt` picks the error line from this
run's output, reading at most the first and last 64 KiB written after
the recorded offset.
  - Both startup errors now end with `Full log: <path>`.
- `tests/conftest.py` + `pyproject.toml`: an autouse guard, and its
`proxy_port_preflight` marker, turn the new check off unless a test opts
in. It follows the existing `proxy_dependency_gate` pattern.
- Without it, the 16 test files that invoke `headroom proxy` with a
stubbed `run_server` on the default port 8787 would fail whenever a
developer has their own proxy running.
- Tests:
- New `tests/test_cli/test_proxy_port_preflight.py`, which uses real
sockets:
    - busy port with workers 1 and 2;
    - port held by a Headroom proxy;
    - free port still starts;
- `test_ipv6_conflict_is_identified_on_the_requested_host`: a real
fake-Headroom `/livez` on 127.0.0.1:P and a plain listener on [::1]:P;
`--host ::1` must say "another process";
    - `test_unprobeable_host_gets_the_generic_message`.
  - New `test_startup_excerpt_reads_at_most_64_kib_of_this_run`.
- New
`test_start_proxy_exit_quotes_this_runs_error_not_summary_or_old_runs`.
  - The timeout test now also asserts the log path.
- The existing stdio-tail test now writes its log output from the fake
`Popen`, as the real child process does.
- The new tests fail on the old code (3 preflight tests; the excerpt and
timeout tests) and pass now. The three tests added for the review (IPv6
owner, unprobeable host, 64 KiB bound) fail on the PR's previous commit
03288c05. The late-error test (an error after 256 KiB of output is
quoted, at most 128 KiB read) fails on c9868420. The head-fallback test
(blank tail) fails on 062cf011, and the two Click `Error:` tests fail on
409fee89 (one of them also on 062cf011). The blank-head/useful-tail test
fails on 92b1bd08. The excerpt fixtures write bytes, so their byte
offsets also hold on Windows.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_cli/test_proxy_port_preflight.py tests/test_cli_proxy_env.py tests/test_proxy_bind_policy.py tests/test_proxy_uds.py tests/test_cli/test_wrap_helpers.py tests/test_cli/test_wrap_proxy_detach.py tests/test_cli/test_port_alignment.py tests/test_malloc_tuning.py tests/test_telemetry_warning.py tests/test_cli_extension_seam.py tests/test_agent_savings.py tests/test_no_ccr_disables_response_handling.py tests/test_stateless_no_disk.py tests/test_cli_proxy_embedding_server.py tests/test_proxy_per_provider_kompress.py tests/test_savings_ledger.py
11 failed, 427 passed, 1 warning in 18.04s
# The 11 failures are all in tests/test_proxy_uds.py ("Socket path is 134 bytes, over this platform's 104-byte sun_path limit"). They are pre-existing on this machine: clean origin/main gives "11 failed, 19 passed" for that file.

# Regression tests against the old code:
3 failed, 1 passed   (test_proxy_port_preflight.py with the proxy.py change reverted)
2 failed, 8 passed   (test_cli_proxy_env.py -k "TestCLIWrapProxyTimeout or start_proxy" with the wrap.py change reverted)

# After the review fixes (c9868420):
$ pytest -q -p no:cacheprovider tests/test_cli/test_proxy_port_preflight.py tests/test_cli_proxy_env.py tests/test_cli/test_wrap_helpers.py tests/test_cli/test_wrap_proxy_detach.py tests/test_cli/test_port_alignment.py tests/test_proxy_bind_policy.py
247 passed
$ pytest -q tests/test_cli -k "port or discovery or livez"
126 passed, 989 deselected
# The 3 new review tests against 03288c05: 3 failed

$ uvx ruff@0.16.8 check headroom/cli/proxy.py headroom/cli/wrap.py tests/conftest.py tests/test_cli_proxy_env.py tests/test_cli/test_proxy_port_preflight.py
All checks passed!
$ mypy headroom/cli/proxy.py headroom/cli/wrap.py headroom/cli/port_discovery.py --ignore-missing-imports
Success: no issues found in 3 source files
```

## Real Behavior Proof

- Environment: macOS 25.6 with Python 3.12 (repo `.venv`); Linux checked
in Docker `python:3.12-slim-trixie` with uvicorn 0.40.0.
- Exact command / steps:
1. Bound a socket to 127.0.0.1:N, then ran `python -m headroom.cli proxy
--port N`.
2. Ran a script that compares `_tcp_port_in_use` with uvicorn's real
bind (asyncio `create_server` for one worker,
`uvicorn.Config(...).bind_socket()` for workers=2). It covered free
ports; listeners on 127.0.0.1, 0.0.0.0 and ::1; hosts 127.0.0.1,
0.0.0.0, localhost and ::; a port in TIME_WAIT; and a non-local host.
- Observed result:
1. rc=1, empty stdout, and stderr `Error: Port 54351 on 127.0.0.1 is
already in use by another process (Address already in use). Start this
proxy on another port with --port N (env: HEADROOM_PORT).` The banner
did not print and uvicorn was never reached.
2. On both macOS and Linux, the probe agreed with uvicorn in every case,
including the ones where the two platforms differ (a 127.0.0.1 listener
with host 0.0.0.0 is busy on Linux and free on macOS). TIME_WAIT is not
reported as busy. For a non-local host, the probe returns "not busy" and
leaves the EADDRNOTAVAIL error to uvicorn, unchanged.
- Direct runtime command (this PR's path). A script holds 127.0.0.1:P
with a fake Headroom `/livez` and [::1]:P with a plain listener, then
runs the real CLI, `python -m headroom.cli proxy --host <h> --port P`,
with temp `HOME`, `HEADROOM_WORKSPACE_DIR` and `CODEX_HOME`:

  ```text
  $ headroom proxy --host ::1 --port 64747
  exit=1 stdout=''
stderr: Error: Port 64747 on ::1 is already in use by another process
(Address already in use). Start this proxy on another port with --port N
(env: HEADROOM_PORT).
  $ headroom proxy --host 127.0.0.1 --port 64747
  exit=1 stdout=''
stderr: Error: Port 64747 on 127.0.0.1 is already in use by a running
Headroom proxy (reuse it, or stop it first). Start this proxy on another
port with --port N (env: HEADROOM_PORT).
  # Same script on the previous commit 03288c05, --host ::1:
stderr: Error: Port 64976 on ::1 is already in use by a running Headroom
proxy (reuse it, or stop it first). ...
  ```

- Shared smoke harness (`smoke.sh <worktree>`: a real proxy from this
checkout against a local fake upstream, offline, temp HOME):

  ```text
  branch: cleanup/cli-integrations-proxy-start-errors @ 92b1bd08
  health: 200
  POST /v1/messages        -> HTTP200 smoke-ok
  POST /v1/chat/completions -> HTTP200 smoke-ok
  stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
  proxy.log WARNING/ERROR lines (<tmp>/ws/logs/proxy-49585.log):
2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active —
every connection Headroom initiates is refused (telemetry, update check,
license reporter, model/tokenizer/binary/dataset downloads, remote
Kompress, OTLP/Langfuse export, Copilot auth, subscription polling,
OpenAI embedders, Headroom Cloud compression). Still allowed on purpose:
forwarding your requests to the upstream you configured,
operator-configured local endpoints, loopback health probes.
2 headroom.transforms.kompress_compressor - WARNING - Kompress:
'onnx/kompress-int8-wo.onnx' for chopratejas/kompress-v2-base is not
cached and HEADROOM_OFFLINE forbids fetching it (HEADROOM_OFFLINE is
set: refusing outbound network access for HuggingFace download of
chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to
huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that
needs this connection.). Compression falls back to the non-ML path.
4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact
prefetch found no usable file for chopratejas/kompress-v2-base
4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact
prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is
set): HEADROOM_OFFLINE is set: refusing outbound network access for
HuggingFace download of
chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to
huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that
needs this connection.
  (smoke dir: <tmp>)
  ```

- Not tested: Windows (the check is skipped there by design), and a live
`wrap` session whose proxy crashes. The excerpt logic is covered by the
unit test.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A, not rollout-managed.
- Stable/default behavior changed: Yes, only on failure paths. A busy
port now fails before the banner (exit 1, same as before) with a clear
message; wrap's startup errors quote a different part of the log and add
the path.
- Kill switch / disable path: None needed. The probe only refuses on
EADDRINUSE, in the same cases where uvicorn itself would fail to bind.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

- Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.
- Restart race: the check runs before the heavy app import, a few
seconds earlier than uvicorn's bind used to. A restart whose old process
still holds the listening socket can now fail fast where it used to win
the race narrowly. The restart paths wait for the old process to exit
first (`stop_runtime` polls `pid_alive`; systemd and launchd wait for
exit), and the exit code is 1 either way.
- No docs change: the new behaviour is an error message.
- The audit had also proposed changing wrap's startup `except
RuntimeError` to raise `ClickException` (stderr). I dropped that: every
caller of `_ensure_proxy` wraps it in `except Exception: echo " Error:
..."; SystemExit(1)`, so the output would not change.
- The audit had proposed reusing wrap's `_port_bind_error` for the
probe. I did not, because that helper binds 127.0.0.1 only and without
`SO_REUSEADDR`, so it does not match uvicorn.

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

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4120"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-12 18:59:35 -07:00
Tejas Chopra 08fce18310 refactor(core): remove unreferenced helpers, attributes and a shadowed module (#4091)
## Description

This PR removes code that nothing calls: one shadowed module, five
functions or classes, two attributes that are set but never read, and
two constants. About 140 lines go.

Evidence: for each name I ran a word-boundary search across `headroom`,
`crates`, `plugins`, `sdk`, `examples`, `benchmarks`, `scripts`, `e2e`,
`docs`, `wiki`, `.github`, `pyproject.toml`, `tests` and the org's
consumer repos. Each search found only the definition. None of the names
is in a lazy export map, an entry point or the docs.

`headroom/cli.py` was a January back-compat shim, `from headroom.cli
import main`. The `headroom/cli/` package has the same import name, and
a package directory wins over a module file in the same directory, so
the file can never be imported. I checked this in both install modes:
- In the published `headroom-ai==0.40.0` wheel, which ships both,
`import headroom.cli` resolves to `headroom/cli/__init__.py`.
- In the repo's editable install, it resolves to the same file.

The `headroom` console script points at `headroom.cli:main`, which is
the package.

Refs #4136

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- Delete `headroom/cli.py`, and its entry in `[tool.coverage.run] omit`
in `pyproject.toml`.
- `headroom/client.py`: delete `HeadroomClient._call_openai` and
`_call_anthropic`. Since b17c6d81, `_create` calls
`call_client_transport(api_style, …)` directly.
- `headroom/copilot_auth.py`: delete `copilot_api_url()`, which only
forwarded to `_configured_api_url()`.
- `headroom/perf/analyzer.py`: delete `_litellm_cost()`, and update the
section comment. `_get_list_price` still uses the litellm import.
- `headroom/ccr/batch_processor.py`: delete the `APIClient` Protocol,
and the `Protocol` import it alone used.
- `headroom/ccr/batch_store.py`: delete
`BatchContextStore._cleanup_task`, which is set but never read.
- `headroom/ccr/mcp_server.py`: delete
`HeadroomMCPServer._compressor_initialized`, which is set but never
read.
- `headroom/telemetry/toin.py`: delete `DEFAULT_TOIN_DIR` and
`DEFAULT_TOIN_FILE`. The path comes from `HEADROOM_TOIN_PATH` and
`headroom.paths`.
- `headroom/telemetry/models.py`: delete
`FieldSemantics.is_value_important()`, part of the request-time hint API
that PR-B5 retired.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_provider_registry_extended.py tests/test_copilot_auth.py tests/test_cli_perf_format.py tests/test_perf_per_port_logs.py tests/test_ccr_batch_store.py tests/test_ccr_batch_processor.py tests/test_ccr_mcp_http.py tests/test_ccr_mcp_server.py tests/test_toin.py tests/test_toin_integration.py tests/test_telemetry.py tests/test_package_init_lazy.py
334 passed, 6 skipped in 10.91s
$ pytest -q -p no:cacheprovider tests/test_cache/test_client_integration.py tests/test_canonical_pipeline.py tests/test_models.py
60 passed in 28.63s
$ uvx ruff@0.16.8 check <8 touched .py files>
All checks passed!
$ python -m mypy <8 touched .py files> --ignore-missing-imports
Success: no issues found in 8 source files
$ python -m headroom.cli --help
Usage: python -m headroom.cli [OPTIONS] COMMAND [ARGS]...
# published wheel, unpacked, with the editable path removed from sys.path:
$ python -I -c "import headroom.cli as c; print(c.__file__)"
.../wheel/x/headroom/cli/__init__.py
# editable install, run from outside the repo:
$ python -c "import headroom.cli as c; print(c.__file__)"
/Users/tejas/headroom/headroom/cli/__init__.py
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, this branch checked out in a
worktree, repo .venv; temp HOME and HEADROOM_WORKSPACE_DIR, offline.
- Exact command / steps: (1) The shared smoke harness `smoke.sh
<worktree>`: it starts a real proxy from this checkout against a local
fake upstream and sends one Anthropic and one OpenAI request with a
compressible tool result. (2) A direct command on this PR's own path:
`cd $TMP && PYTHONPATH=<worktree> python -c 'import headroom.cli as c;
print(c.__file__)'; python -m headroom.cli --help | head -3;
GITHUB_COPILOT_API_URL=https://copilot.example.test python -c 'from
headroom import copilot_auth as c; print(c._configured_api_url())'`.
- Observed result: Both requests return 200 and `/stats` shows savings,
with only the expected offline-mode warnings in proxy.log. The direct
command's output is below.
- Not tested: Live proxy traffic through the Copilot and batch CCR
paths; none of the removed code was on them.

```text
$ bash smoke.sh <worktree>
branch: cleanup/core-misc-dead-helpers @ 221984e8
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines ($SMOKE_TMP/ws/logs/proxy-50464.log):
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you configured, operator-configured local endpoints, loopback health probes.
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.
(smoke dir: $SMOKE_TMP)

$ cd $TMP && PYTHONPATH=<worktree> python -c 'import headroom.cli as c; print(c.__file__)'; python -m headroom.cli --help | head -3; GITHUB_COPILOT_API_URL=https://copilot.example.test python -c 'from headroom import copilot_auth as c; print(c._configured_api_url())'
<worktree>/headroom/cli/__init__.py
Usage: python -m headroom.cli [OPTIONS] COMMAND [ARGS]...

  Headroom - The Context Optimization Layer for LLM Applications.
https://copilot.example.test
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; dead-code removal.
- Stable/default behavior changed: No. Nothing called the removed code.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review. This is a pure
deletion. No test referenced any removed name, and no doc mentions one.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-10-10 08:58:09 -07:00
lorenzozaneandJD Davis 51ec6e8ffe fix(deps): support Intel macOS ONNX Runtime resolution (#3823)
## Description

Intel macOS cannot install `headroom-ai[proxy]` or `[all]` when the
extras select ONNX Runtime 1.24+, whose wheels no longer support x86_64
macOS. Retain the available pre-1.24 runtime on Intel Python 3.10–3.13.
On Intel Python 3.14+, omit optional ONNX backends because no compatible
wheel exists, allowing the proxy and core compression to remain usable.

Closes #3818

## Type of Change

- [x] Bug fix
- [ ] New feature
- [ ] Breaking change
- [x] Documentation update

## Changes Made

- Keep ONNX Runtime below 1.24 on Intel macOS through Python 3.13, while
retaining the API-24 floor on supported modern platforms.
- Omit ONNX Runtime and its Magika, FastEmbed, and OCR dependency roots
on Intel Python 3.14+. This also fixes transitive ONNX requirements in
`[all]`.
- Refresh `uv.lock` to match the platform markers; no package names or
versions changed.
- Extend the dependency contract to Python 3.14/3.15 Intel cases and
modern Linux/Apple Silicon controls.
- Align the CLI dependency gate with those platform markers so `headroom
proxy` and `wrap` accept the omitted ONNX packages while retaining every
other required dependency check.
- Document unavailable optional ML features and the Python 3.13
alternative.

## Dependency Justification

No new package or version bump is introduced. The existing ONNX package
and dependent optional backends receive platform/interpreter markers
reflecting their published wheel availability. Installation surface
remains the existing packages on supported combinations; unsupported
Intel Python 3.14+ no longer attempts to install unavailable native
backends. Runtime model downloads and network policies are unchanged.

## Testing

At `7189f19031f77578141f98044eabadad91ea0edf`:

- 184 dependency-contract, CLI, ORT guard, relevance, and image tests
pass (four existing warnings). Marker regressions fail before their fix;
the Python 3.14/3.15 Intel CLI gate regressions also fail before the
startup correction and pass afterward. Other platforms still require the
ONNX packages.
- Ruff lint/format and whitespace pass; Linux-target mypy passes over
566 source files.
- `uv lock --check` passes; frozen `[all]` export succeeds. Lock
package-name/version sets are identical before and after refresh.
- Real wheel-aware `uv pip compile pyproject.toml --extra all
--python-version <version> --python-platform <target>
--only-binary=onnxruntime` succeeds for Intel macOS Python 3.10, 3.11,
3.13, and 3.14; Linux Python 3.10/3.14; and Apple Silicon Python 3.14
with `MACOSX_DEPLOYMENT_TARGET=14.0`.
- Intel 3.10–3.13 resolve ONNX Runtime 1.23.2. Intel 3.14 resolves
without ONNX, Magika, FastEmbed, or OCR backends. Modern Linux and macOS
14 Apple Silicon resolve ONNX Runtime 1.30.0. Individual Intel 3.14
`proxy` and `voice` extras also resolve.

## Real Behavior Proof

- Setup: Windows Python 3.12, an isolated environment installed from
dependency roots selected by Intel macOS Python 3.14 markers. Confirmed
ONNX Runtime, Magika, FastEmbed, RapidOCR, and Torch are absent. Actual
Intel/macOS execution was not available.
- Steps: run `pr3823-resume16-runtime.py` against a real uvicorn proxy
with optimization enabled and subscription polling disabled; send a real
TCP tool-result chat request to a separate loopback HTTP upstream, then
query real `/stats`.
- Observed: content detection uses `FallbackDetector`, relevance uses
BM25, proxy returns HTTP 200, and the upstream receives one request. The
inflation guard preserves the original 8,988-byte request in this case.
No local ML inference or live provider billing is claimed.
- Packaging proof: before correction the Intel Python 3.14 resolver
rejects the ONNX range because its newest Intel wheel has only
cp310–cp313/cp313t ABIs. After correction `[all]`, `proxy`, and `voice`
resolve. Evidence logs: `pr3823-resume16-red-py314.log`,
`pr3823-resume16-green-py314.log`, `pr3823-resume16-runtime.log`, and
`pr3823-resume16-focused.log`.
- Older-runtime control: a second isolated Windows Python 3.12
environment uses the Intel Python 3.13-selected dependency roots and
actual ONNX Runtime 1.23.2. Python Magika detects JSON, the API-24
native detection guard remains false, direct Rust SmartCrusher
compresses 100 JSON records to 724 bytes, and the real
optimization-enabled TCP proxy returns HTTP 200. Evidence:
`pr3823-resume16-ort123-runtime.py/log`. This verifies the older C API
path on Windows; native Intel macOS execution remains untested.
- Direct embedding audit: Python-exposed Rust SmartCrusher constructs
`HybridScorer::default`, whose `EmbeddingScorer::default` is unloaded
and uses BM25. Rust `create_scorer` also uses the unloaded default. The
native `EmbeddingScorer::try_new` call sites found are its definition
and module tests; no production Python embedding initializer is exposed.
Python FastEmbed uses the compatible installed Python ONNX backend on
older Intel interpreters.
- CLI proof: invoke the actual Click `headroom proxy` command in a
subprocess using the isolated no-ORT environment; simulate only the
Intel macOS Python 3.14 platform predicate, leaving dependency imports
and server startup real. The real dependency gate passes and live TCP
`/health` returns HTTP 200 with `ready=true`, Rust core loaded, and
optional Kompress marked degraded. Evidence:
`pr3823-resume16-cli-boot.py`, `pr3823-resume16-cli-runtime.py/log`, and
`pr3823-resume16-cli-server.log`. The owned subprocess is stopped after
verification.

## Runtime Rollout Safety

- Rollout-managed features: none; dependency selection uses package
markers.
- Default behavior: Intel Python 3.10–3.13 can use the older Python ONNX
runtime; Rust ML detection remains guarded because it requires API 24.
Intel Python 3.14+ retains core/proxy and non-ML fallbacks, with
optional ONNX features unavailable.
- Existing Linux and Apple Silicon dependency policies retain their
modern ONNX floor.
- No unsafe override or new network behavior. Rollback: revert the
marker and lockfile commits.

## Review Readiness

- [x] Self-review completed
- [x] Real behavior and packaging evidence supplied
- [x] Regression tests and local checks pass
- [x] Did not edit CHANGELOG.md

Hosted checks and review must qualify this new head before approval. No
PR merge performed.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-08 10:07:57 -05:00
JD Davisandgithub-actions[bot] 855390d611 chore: release 0.40.0 (#3833)
🤖 I have created a release *beep* *boop*
---


##
[0.40.0](https://github.com/headroomlabs-ai/headroom/compare/v0.39.1...v0.40.0)
(2026-10-06)


### ⚠ BREAKING CHANGES

* **proxy:** read HEADROOM_LICENSE and make usage reporting opt-in
([#3857](https://github.com/headroomlabs-ai/headroom/issues/3857))
* drop the crewai extra to remove chromadb from the lockfile
([#3870](https://github.com/headroomlabs-ai/headroom/issues/3870))

### Features

* **compress:** add per-message compression diagnostics
([#3058](https://github.com/headroomlabs-ai/headroom/issues/3058))
([fef99cc](https://github.com/headroomlabs-ai/headroom/commit/fef99cc5b444bb16ac33fe8ec70108f7c0271de1))
* **compress:** live-agent densify mode, lossless and cache-safe
([#1402](https://github.com/headroomlabs-ai/headroom/issues/1402))
([84f0e84](https://github.com/headroomlabs-ai/headroom/commit/84f0e84dccd3736b4a0c6c817bc83da307a5fbb8))
* **dashboard:** add CO₂ Saved card to dashboard and /stats API
([#1369](https://github.com/headroomlabs-ai/headroom/issues/1369))
([2bc9419](https://github.com/headroomlabs-ai/headroom/commit/2bc94194671548c5def53809f736340285e20e76))
* **dashboard:** give savings metrics one canonical home
([#3320](https://github.com/headroomlabs-ai/headroom/issues/3320))
([6af7efe](https://github.com/headroomlabs-ai/headroom/commit/6af7efe0d1fa9786d1fd5e5dc9884b7750c0f569))
* **learn:** add agy (Antigravity CLI) as an analysis backend
([#3939](https://github.com/headroomlabs-ai/headroom/issues/3939))
([4ba231a](https://github.com/headroomlabs-ai/headroom/commit/4ba231ab3d51c409804af24ea03692aed33deb2e))
* **live-zone:** wire the SourceCode and PlainText dispatch arms
([#3227](https://github.com/headroomlabs-ai/headroom/issues/3227))
([49f69be](https://github.com/headroomlabs-ai/headroom/commit/49f69be2836e90cbd210e39d82b36d514404cc76))
* **memory:** persist TrafficLearner pending evidence across restarts +
expose learner stats
([#3104](https://github.com/headroomlabs-ai/headroom/issues/3104))
([4257ed4](https://github.com/headroomlabs-ai/headroom/commit/4257ed4df377a93cd2e0d526ef61d2a32cbc54cf))
* **proxy:** add x-headroom-keep-last-turns header for per-request
context trimming (issue
[#2858](https://github.com/headroomlabs-ai/headroom/issues/2858))
([#3059](https://github.com/headroomlabs-ai/headroom/issues/3059))
([246162d](https://github.com/headroomlabs-ai/headroom/commit/246162d70bbc68cc1b7d44a015ddaf320cd23a3d))
* **proxy:** route Gemini plugin traffic through native transforms
([#2697](https://github.com/headroomlabs-ai/headroom/issues/2697))
([0ad996a](https://github.com/headroomlabs-ai/headroom/commit/0ad996a82eef65183271243fa71bb0f5653be369))
* **proxy:** serve on a Unix domain socket (--uds)
([#3151](https://github.com/headroomlabs-ai/headroom/issues/3151))
([e7b3baf](https://github.com/headroomlabs-ai/headroom/commit/e7b3baf236b832e1d4d086c4425b8d32560d0d7c))
* **wrap:** add headroom wrap bob for IBM Bob CLI
([#3801](https://github.com/headroomlabs-ai/headroom/issues/3801))
([0b7dab4](https://github.com/headroomlabs-ai/headroom/commit/0b7dab47c62a8372c7bf7031d744658d71745679))
* **wrap:** extend reduce-at-source quiet defaults to telemetry/nag
banners
([#2550](https://github.com/headroomlabs-ai/headroom/issues/2550))
([3a3a465](https://github.com/headroomlabs-ai/headroom/commit/3a3a465bb129ad74f6e04f7c50e0fe7489383ba2))


### Bug Fixes

* **anthropic:** preserve failed CCR continuations
([#3843](https://github.com/headroomlabs-ai/headroom/issues/3843))
([94bb055](https://github.com/headroomlabs-ai/headroom/commit/94bb055810dc1258bd248cd0a9d0e7c51df64844))
* **backends/anyllm:** map Anthropic tool_choice none to OpenAI none
([#3963](https://github.com/headroomlabs-ai/headroom/issues/3963))
([d722a64](https://github.com/headroomlabs-ai/headroom/commit/d722a6414c3896ef092a0d8764c64d9681e07410))
* **backends/litellm:** align streaming usage tokens with the
non-streaming path
([#2688](https://github.com/headroomlabs-ai/headroom/issues/2688))
([90a68e0](https://github.com/headroomlabs-ai/headroom/commit/90a68e02910126373f3d3769158925e3a55ce411))
* **backends/litellm:** keep the upstream 4xx status on send_message
errors
([#3944](https://github.com/headroomlabs-ai/headroom/issues/3944))
([e0e41cd](https://github.com/headroomlabs-ai/headroom/commit/e0e41cd2f57a80612ddbf1568e4ad245046a0131))
* **backends/litellm:** map Anthropic tool_choice none to OpenAI none
([#2689](https://github.com/headroomlabs-ai/headroom/issues/2689))
([57a5708](https://github.com/headroomlabs-ai/headroom/commit/57a57088de8920091ecaaac0e3cadf3932698154))
* **backends/litellm:** match the caller-key Bearer scheme
case-insensitively (RFC 7235)
([#3965](https://github.com/headroomlabs-ai/headroom/issues/3965))
([848d7a0](https://github.com/headroomlabs-ai/headroom/commit/848d7a04b489600d3c0de0ba4f7c47cdb8ed5cc2))
* **backends/litellm:** report requested model in OpenAI streaming
chunks
([#2690](https://github.com/headroomlabs-ai/headroom/issues/2690))
([8538a83](https://github.com/headroomlabs-ai/headroom/commit/8538a831531bb277a6083ed2a010312a849c3050))
* **cache:** keep prefix lineage across a replaced system tail
([#3934](https://github.com/headroomlabs-ai/headroom/issues/3934))
([16eaec1](https://github.com/headroomlabs-ai/headroom/commit/16eaec1e95cd39135ef06f6664b309c71b03e3ad))
* **ccr:** answer headroom_retrieve on the direct chat path instead of
forwarding it
([#3816](https://github.com/headroomlabs-ai/headroom/issues/3816))
([126e144](https://github.com/headroomlabs-ai/headroom/commit/126e144876d2bd01246b5066dd5d3379b7a0e2da))
* **ccr:** inject headroom_retrieve before the prefix is warm, not after
([#3810](https://github.com/headroomlabs-ai/headroom/issues/3810))
([bb8c285](https://github.com/headroomlabs-ai/headroom/commit/bb8c285714b19dadf4f96305ba5a74877a0dd103))
* **ccr:** only proactively expand compressions present in the
requesting conversation
([#3924](https://github.com/headroomlabs-ai/headroom/issues/3924))
([9b9a883](https://github.com/headroomlabs-ai/headroom/commit/9b9a883e96ec28e361a3d95e34ec29ecd2ef8abb))
* **ccr:** unwrap Hermes batched tool_call so headroom_retrieve stays
exempt
([#3839](https://github.com/headroomlabs-ai/headroom/issues/3839))
([2f07668](https://github.com/headroomlabs-ai/headroom/commit/2f076687b069f09c69a1ce3e6f3eaaa521b838f7))
* **ci:** clear dependency audit and gate Docker publishing
([#3984](https://github.com/headroomlabs-ai/headroom/issues/3984))
([67ce7d0](https://github.com/headroomlabs-ai/headroom/commit/67ce7d0f3119883a873a53c1fb1e569c80d36d71))
* **ci:** keep hard watchdog out of pytest shards
([#3845](https://github.com/headroomlabs-ai/headroom/issues/3845))
([2527431](https://github.com/headroomlabs-ai/headroom/commit/25274310ca396aaf5761d78d07106de3dfde2951))
* **ci:** tolerate missing Docker cache blobs
([#3945](https://github.com/headroomlabs-ai/headroom/issues/3945))
([540f4da](https://github.com/headroomlabs-ai/headroom/commit/540f4da19995ce9ec60240f991a8091466ee7e51))
* clarify CCR marker content preservation
([#3175](https://github.com/headroomlabs-ai/headroom/issues/3175))
([005a4e1](https://github.com/headroomlabs-ai/headroom/commit/005a4e146f94e2388e8e0e7eaabe5a831676b26b))
* **cli:** honor CODEX_HOME and align wrap/init/doctor with the live
proxy port
([#3855](https://github.com/headroomlabs-ai/headroom/issues/3855))
([5bf6612](https://github.com/headroomlabs-ai/headroom/commit/5bf661232667fe2573caafcd9b48f86c6388b5bd))
* **cli:** strip unmarked headroom_memory TOML table before injecting
([#3490](https://github.com/headroomlabs-ai/headroom/issues/3490))
([08dda4c](https://github.com/headroomlabs-ai/headroom/commit/08dda4cb0b5fe69bff8aa1deeabfb2111738087c))
* **codex:** explain why wrapped Codex runs without the shared server
([#3899](https://github.com/headroomlabs-ai/headroom/issues/3899))
([1982b3a](https://github.com/headroomlabs-ai/headroom/commit/1982b3a773093ff8262887e69ffb12e342ce4ffc))
* **codex:** preserve remote compaction in init config
([#3410](https://github.com/headroomlabs-ai/headroom/issues/3410))
([6df4a96](https://github.com/headroomlabs-ai/headroom/commit/6df4a963ae4cfefa2269b751874e142b02feb726))
* **codex:** resolve per-turn project context
([#2636](https://github.com/headroomlabs-ai/headroom/issues/2636))
([0396ea2](https://github.com/headroomlabs-ai/headroom/commit/0396ea2fc22d72d95d1f3bfa63bfbdd0abd74a80))
* **codex:** strip stale compression framing on the Responses subpath
passthrough
([#3792](https://github.com/headroomlabs-ai/headroom/issues/3792))
([0eba65c](https://github.com/headroomlabs-ai/headroom/commit/0eba65ca4a8f04b55d568fc35829eca053a7cfac))
* **copilot:** defer keychain auth lookup
([#2739](https://github.com/headroomlabs-ai/headroom/issues/2739))
([81a8a28](https://github.com/headroomlabs-ai/headroom/commit/81a8a28da38f1837c6b8dd6217a35a5ebb98bc87))
* **copilot:** read timezone-naive token expiry as UTC, not host local
time ([#3216](https://github.com/headroomlabs-ai/headroom/issues/3216))
([2b2dc1b](https://github.com/headroomlabs-ai/headroom/commit/2b2dc1b2c93c596ad5129dff914978c5679ef126))
* **copilot:** warn when a VS Code profile cannot see the proxy settings
([#3919](https://github.com/headroomlabs-ai/headroom/issues/3919))
([7b68fc2](https://github.com/headroomlabs-ai/headroom/commit/7b68fc263a925f97116e1e648cd3fa22a0f04f1b))
* **deps:** patch brace-expansion in wrap E2E lockfile
([#3873](https://github.com/headroomlabs-ai/headroom/issues/3873))
([5e0435d](https://github.com/headroomlabs-ai/headroom/commit/5e0435d2156229c04951da9fafeafdf74d2abf84))
* **deps:** patch urllib3 and Next.js advisories
([#3896](https://github.com/headroomlabs-ai/headroom/issues/3896))
([573e385](https://github.com/headroomlabs-ai/headroom/commit/573e385f120cfd4f5e4d54c791025f2253abf08a))
* **doctor:** recognize Azure Foundry routing for Claude Code
([#1339](https://github.com/headroomlabs-ai/headroom/issues/1339))
([d5318ac](https://github.com/headroomlabs-ai/headroom/commit/d5318ac235595b9740fccb0910ec7139c42d51a0))
* **grok:** route CLI traffic to api.x.ai on shared proxies
([#2693](https://github.com/headroomlabs-ai/headroom/issues/2693))
([ef1c528](https://github.com/headroomlabs-ai/headroom/commit/ef1c528e92a2b037a170f94ec8adf917322ba630))
* honor configured port in container startup and healthcheck
([#2436](https://github.com/headroomlabs-ai/headroom/issues/2436))
([1b7977c](https://github.com/headroomlabs-ai/headroom/commit/1b7977cecd95e53cccf45f04248097a8e4137b3f))
* **install/apply:** add --no-rate-limit flag, persist in proxy_args
([#1350](https://github.com/headroomlabs-ai/headroom/issues/1350))
([#1365](https://github.com/headroomlabs-ai/headroom/issues/1365))
([31d0344](https://github.com/headroomlabs-ai/headroom/commit/31d03449910fbacbefdde8c04ea2c10299f9bba6))
* **install:** parse Windows Task Scheduler XML output
([#3830](https://github.com/headroomlabs-ai/headroom/issues/3830))
([c32a4f4](https://github.com/headroomlabs-ai/headroom/commit/c32a4f4131934dee48d793156fb8a536a4b2617e))
* **install:** replace the launchd wrapper with the proxy listener
([#3224](https://github.com/headroomlabs-ai/headroom/issues/3224))
([44db755](https://github.com/headroomlabs-ai/headroom/commit/44db755ee6d85d0eb74f1fc79ef737741f87debc))
* **install:** use safe model backends for persistent services
([#3646](https://github.com/headroomlabs-ai/headroom/issues/3646))
([7287589](https://github.com/headroomlabs-ai/headroom/commit/7287589d23b76911b036d97f58c3cc043a9693c8))
* **integrations:** record metric timestamps in UTC, not naive local
time ([#3117](https://github.com/headroomlabs-ai/headroom/issues/3117))
([76ef2c3](https://github.com/headroomlabs-ai/headroom/commit/76ef2c3bc9cc302f4b638fab83467ab53cb192c1))
* **kompress:** degrade when a native dep is installed but unloadable
([#3133](https://github.com/headroomlabs-ai/headroom/issues/3133))
([8f3d677](https://github.com/headroomlabs-ai/headroom/commit/8f3d677354f50df9181cbb3fa002003be4e3c237))
* **kompress:** pin ModernBERT tokenizer and encoder revisions
([#3808](https://github.com/headroomlabs-ai/headroom/issues/3808))
([2de5828](https://github.com/headroomlabs-ai/headroom/commit/2de582875b7dd1ef8754df8a2905ab4d72dab581))
* **learn:** drop the echoed prompt from a failed cli's error
([#3928](https://github.com/headroomlabs-ai/headroom/issues/3928))
([f00d425](https://github.com/headroomlabs-ai/headroom/commit/f00d42561402752e56666ff35962ad8da6f7966c))
* **learn:** keep CLAUDE.local.md out of git via .git/info/exclude
([#3108](https://github.com/headroomlabs-ai/headroom/issues/3108))
([c072251](https://github.com/headroomlabs-ai/headroom/commit/c072251c10a1334265974ed33f655487518d41d0))
* **learn:** keep transcript-derived content inside the managed block
([#3850](https://github.com/headroomlabs-ai/headroom/issues/3850))
([c46e74d](https://github.com/headroomlabs-ai/headroom/commit/c46e74d06b5ffa9643f420f28d2da6686fb7e487))
* **learn:** merge git worktree sessions into the repo's project
([#3854](https://github.com/headroomlabs-ai/headroom/issues/3854))
([3fdf18e](https://github.com/headroomlabs-ai/headroom/commit/3fdf18ededa162e5f46f5a996a164a6ca9de283f))
* **learn:** preserve stable traffic pattern items
([#2293](https://github.com/headroomlabs-ai/headroom/issues/2293))
([1631cde](https://github.com/headroomlabs-ai/headroom/commit/1631cde6865cbc03a60ade5e9baaa28837add4e4))
* **learn:** recognize escaped persisted pattern IDs
([#3951](https://github.com/headroomlabs-ai/headroom/issues/3951))
([2e74f06](https://github.com/headroomlabs-ai/headroom/commit/2e74f06ecec73d365e06de6832b13f7e9fe386b7))
* **learn:** run the claude-cli analysis with hooks disabled
([#3926](https://github.com/headroomlabs-ai/headroom/issues/3926))
([2a4d34c](https://github.com/headroomlabs-ai/headroom/commit/2a4d34c47676080336577bb4b227864258cb2c78))
* **learn:** run the claude-cli analysis with no tools
([#3892](https://github.com/headroomlabs-ai/headroom/issues/3892))
([db90b93](https://github.com/headroomlabs-ai/headroom/commit/db90b93da9f8decb9cac7fa007674de7974a1cdb))
* **log_compressor:** keep and name pytest short-summary failures
([#3828](https://github.com/headroomlabs-ai/headroom/issues/3828))
([d90b320](https://github.com/headroomlabs-ai/headroom/commit/d90b32008dc47f25737d9cef8da942fd8dc1af76))
* make Headroom work behind Zscaler and other TLS-inspecting networks
([#3831](https://github.com/headroomlabs-ai/headroom/issues/3831))
([66258c4](https://github.com/headroomlabs-ai/headroom/commit/66258c40a4589bb2fef934dec6fb69c527ae8b44))
* **mcp:** bound version-detection git subprocess
([#3038](https://github.com/headroomlabs-ai/headroom/issues/3038))
([0712e04](https://github.com/headroomlabs-ai/headroom/commit/0712e048b034e7f15ce10c0fc4e99795cab082ff))
* **mcp:** escape control characters when rendering TOML server blocks
([#3964](https://github.com/headroomlabs-ai/headroom/issues/3964))
([a96154f](https://github.com/headroomlabs-ai/headroom/commit/a96154f03b65179f23496a1ff9682cfc476eaff5))
* **mcp:** keep other apps' tables when replacing the Codex/Grok MCP
span ([#3877](https://github.com/headroomlabs-ai/headroom/issues/3877))
([d0fd56e](https://github.com/headroomlabs-ai/headroom/commit/d0fd56e4910c997a3121aa27ab578b998b260f5a))
* **mcp:** resolve opencode.jsonc for MCP registration
([#2496](https://github.com/headroomlabs-ai/headroom/issues/2496))
([f824a27](https://github.com/headroomlabs-ai/headroom/commit/f824a270f132516443deeef2555076bf4cd40a34))
* **memory:** align project routing with wrap headers
([#3603](https://github.com/headroomlabs-ai/headroom/issues/3603))
([b1b005a](https://github.com/headroomlabs-ai/headroom/commit/b1b005a9a867d75cbc6b459b1f5276c272e7ac50))
* **memory:** avoid injecting tools into tool-free requests
([#3677](https://github.com/headroomlabs-ai/headroom/issues/3677))
([46755b5](https://github.com/headroomlabs-ai/headroom/commit/46755b5f72804c32dc7d6ded5595342a2cac6157))
* **memory:** close SQLite connections in memory/fts5/graph adapters
([#3153](https://github.com/headroomlabs-ai/headroom/issues/3153))
([231a627](https://github.com/headroomlabs-ai/headroom/commit/231a6277024938d28e0ebeda29378dea3822b527))
* **memory:** handle list-shaped system content in inline memory
injection
([#3794](https://github.com/headroomlabs-ai/headroom/issues/3794))
([717527b](https://github.com/headroomlabs-ai/headroom/commit/717527bc8681665326c064ed47e3f5a0284b01a5))
* **memory:** ignore leading cd prefix when pairing Bash error
recoveries
([#3776](https://github.com/headroomlabs-ai/headroom/issues/3776))
([143a38d](https://github.com/headroomlabs-ai/headroom/commit/143a38d56f5bddb96dd486948c3318bd8dc93372))
* **memory:** pin LF on memory writers and guard the learn-writer
newline contract
([#3706](https://github.com/headroomlabs-ai/headroom/issues/3706))
([b10dd8d](https://github.com/headroomlabs-ai/headroom/commit/b10dd8db6e71903e550edd1707ce044f3520f0b4))
* **oauth2:** mint and inject only on requests that go upstream
([#3849](https://github.com/headroomlabs-ai/headroom/issues/3849))
([f977d52](https://github.com/headroomlabs-ai/headroom/commit/f977d525e4cf4ac1cad64dd59cfc6d3e54cd8e36))
* **offline:** make HEADROOM_OFFLINE a real air-gap via one chokepoint
([#3729](https://github.com/headroomlabs-ai/headroom/issues/3729))
([119d1a1](https://github.com/headroomlabs-ai/headroom/commit/119d1a19393697f22140da654f0b6a10c3866d79))
* **opencode:** hide spawned Windows console windows
([#3743](https://github.com/headroomlabs-ai/headroom/issues/3743))
([2157400](https://github.com/headroomlabs-ai/headroom/commit/2157400b005b858fb4ab96dadde022bb22d3d244))
* **opencode:** route only LLM traffic through Headroom
([#3884](https://github.com/headroomlabs-ai/headroom/issues/3884))
([d75eecd](https://github.com/headroomlabs-ai/headroom/commit/d75eecd814d391f51c6b98b1594c0ea180e9103a))
* **output-savings:** seed the holdout key on the whole first user
message
([#3209](https://github.com/headroomlabs-ai/headroom/issues/3209))
([117ff72](https://github.com/headroomlabs-ai/headroom/commit/117ff72ec9aa6385c4e6afb23f06a4a6edb59f8e))
* **parser:** stop counting HTML comments twice in waste signals
([#3942](https://github.com/headroomlabs-ai/headroom/issues/3942))
([d0e9c4c](https://github.com/headroomlabs-ai/headroom/commit/d0e9c4ca4810f36c8bd71cfc567be9e72c8c06d1))
* **parser:** whitespace waste signal always reported zero
([#1102](https://github.com/headroomlabs-ai/headroom/issues/1102))
([f19bc9a](https://github.com/headroomlabs-ai/headroom/commit/f19bc9a9c344e846ef61de09652c55f8db835aa1))
* **plugin:** resolve hook CLI through plugin-root launcher
([#3053](https://github.com/headroomlabs-ai/headroom/issues/3053))
([ef7605f](https://github.com/headroomlabs-ai/headroom/commit/ef7605fdbb82a5c1a75c9192432bc719aa92927d))
* **plugins/openclaw:** return messages the proxy did not change exactly
as they came in
([#3826](https://github.com/headroomlabs-ai/headroom/issues/3826))
([d1ad189](https://github.com/headroomlabs-ai/headroom/commit/d1ad189819d0dd87137267a17233ab2703eb803c))
* prevent HF tokenizer downloads in offline mode
([#3783](https://github.com/headroomlabs-ai/headroom/issues/3783))
([d503c57](https://github.com/headroomlabs-ai/headroom/commit/d503c575eabd6dfed3f390754d391a337340d7d7))
* **pricing:** add Claude Sonnet 5.5 / Opus 5.5 / Fable 5.1, correct
Sonnet 5 rates
([#3841](https://github.com/headroomlabs-ai/headroom/issues/3841))
([0d99c56](https://github.com/headroomlabs-ai/headroom/commit/0d99c56dc519c4684079a0e1107399068342104d))
* protect file reads in chained shell commands
([#2668](https://github.com/headroomlabs-ai/headroom/issues/2668))
([ffc3599](https://github.com/headroomlabs-ai/headroom/commit/ffc359976b09f64388ac9cb8685904c5a5f59708))
* **providers/vertex:** Vertex route multi-region locations
([#3802](https://github.com/headroomlabs-ai/headroom/issues/3802))
([a9c1ac5](https://github.com/headroomlabs-ai/headroom/commit/a9c1ac5368798382b0d7e081e910a6df2a728bb0))
* **proxy/anthropic:** keep tool_result blocks first when neutralizing
headroom_retrieve history
([#3874](https://github.com/headroomlabs-ai/headroom/issues/3874))
([ccd9fff](https://github.com/headroomlabs-ai/headroom/commit/ccd9fffce93cd93d694d78c601ec50eeff0bd256))
* **proxy/batch:** honor x-headroom-bypass on the batch paths
([#2570](https://github.com/headroomlabs-ai/headroom/issues/2570))
([9b26a49](https://github.com/headroomlabs-ai/headroom/commit/9b26a49c14eacd8e14385bf8d28c67b2425b3c5c))
* **proxy:** add same-origin check to /v1/retrieve/tool_call
([#3955](https://github.com/headroomlabs-ai/headroom/issues/3955))
([2297b50](https://github.com/headroomlabs-ai/headroom/commit/2297b5059f27c0018b15f7857a5b3a7026a68bdd))
* **proxy:** bill the whole prompt on the gateway path so savings read
true ([#3632](https://github.com/headroomlabs-ai/headroom/issues/3632))
([befdb52](https://github.com/headroomlabs-ai/headroom/commit/befdb52fd565ff990e4ff1463f0550ba7df588b5))
* **proxy:** carry safeguard_results through SSE resynthesis
([#3958](https://github.com/headroomlabs-ai/headroom/issues/3958))
([f37ef59](https://github.com/headroomlabs-ai/headroom/commit/f37ef591894c6b89bc25ea628b64b40bdd1037fb))
* **proxy:** classify Pi Codex Responses alias
([#2583](https://github.com/headroomlabs-ai/headroom/issues/2583))
([a493f55](https://github.com/headroomlabs-ai/headroom/commit/a493f559a1a85a5462fc3bf3f363d64c3c9444ce))
* **proxy:** do not cache error replies delivered as http 200
([#3930](https://github.com/headroomlabs-ai/headroom/issues/3930))
([1132a54](https://github.com/headroomlabs-ai/headroom/commit/1132a54b21482332f6ffeeebe8c9935a69709afa))
* **proxy:** drop a tool_reference naming the search tool itself
([#3172](https://github.com/headroomlabs-ai/headroom/issues/3172))
([b73adaa](https://github.com/headroomlabs-ai/headroom/commit/b73adaa0ce36a2e65a98f5590c46ea555751b445))
* **proxy:** F3 — per-tenant TOIN learning key
([#404](https://github.com/headroomlabs-ai/headroom/issues/404))
([f90a56b](https://github.com/headroomlabs-ai/headroom/commit/f90a56b0388f3dcb6455425a3405b40b67da6858))
* **proxy:** forward operator-listed guarded upstreams through a proxy
([#3804](https://github.com/headroomlabs-ai/headroom/issues/3804))
([4b7e5d2](https://github.com/headroomlabs-ai/headroom/commit/4b7e5d246e54b856af22cd1a90b47d93b26226cb))
* **proxy:** freeze and replay the forwarded prefix on Gemini paths
([#3394](https://github.com/headroomlabs-ai/headroom/issues/3394))
([#3865](https://github.com/headroomlabs-ai/headroom/issues/3865))
([dd84321](https://github.com/headroomlabs-ai/headroom/commit/dd84321daa0c3c9dca9264098bb396a75d9e52cd))
* **proxy:** gate the raw request body, not just its Content-Length
header
([#3338](https://github.com/headroomlabs-ai/headroom/issues/3338))
([c946b6b](https://github.com/headroomlabs-ai/headroom/commit/c946b6b0b0ae048c576940d1a57071b84cb05fb6))
* **proxy:** hard watchdog that dumps and exits when a native call
seizes the GIL
([#3180](https://github.com/headroomlabs-ai/headroom/issues/3180))
([79daeb5](https://github.com/headroomlabs-ai/headroom/commit/79daeb590f46c8f74483e975647c202d09f01fbb))
* **proxy:** inject memory context past a trailing system message
([#3948](https://github.com/headroomlabs-ai/headroom/issues/3948))
([3948dbe](https://github.com/headroomlabs-ai/headroom/commit/3948dbe409eba48c065a3ecb2af9fa2f51921787))
* **proxy:** keep cache_control outside content blocks where the Chat
Completions client put it
([#3895](https://github.com/headroomlabs-ai/headroom/issues/3895))
([a6d6c14](https://github.com/headroomlabs-ai/headroom/commit/a6d6c14cf781a7725e4e8366e8cd86b1e4e44ba9))
* **proxy:** keep exception text and the proxy token out of client
output
([#3851](https://github.com/headroomlabs-ai/headroom/issues/3851))
([861e94d](https://github.com/headroomlabs-ai/headroom/commit/861e94d8c173bcca1ec4ae4f84a3e7ef477c4a19))
* **proxy:** keep the newest user message verbatim in cache-mode delta
compression
([#3923](https://github.com/headroomlabs-ai/headroom/issues/3923))
([613ae92](https://github.com/headroomlabs-ai/headroom/commit/613ae9215058c1d5cabc67186f3b47089b22eddb))
* **proxy:** key rate limits by peer unless the caller authenticated
([#3860](https://github.com/headroomlabs-ai/headroom/issues/3860))
([6fb7cad](https://github.com/headroomlabs-ai/headroom/commit/6fb7cadfe4c54c2be6b90e9fdea36e91da7b2945))
* **proxy:** kill the image worker a timed-out call abandons
([#3940](https://github.com/headroomlabs-ai/headroom/issues/3940))
([793bb85](https://github.com/headroomlabs-ai/headroom/commit/793bb85659d9aa907115ec16ea3356c5459f6299))
* **proxy:** label plain OpenAI chat traffic openai, not custom
([#3912](https://github.com/headroomlabs-ai/headroom/issues/3912))
([7df8bd8](https://github.com/headroomlabs-ai/headroom/commit/7df8bd87b54725174e1ea88e2dcd428b66cb608f))
* **proxy:** log response_content_length in proxy_inbound_response
([#2701](https://github.com/headroomlabs-ai/headroom/issues/2701))
([cfa479a](https://github.com/headroomlabs-ai/headroom/commit/cfa479af8e551d5d2710debf80adb86fd72b16e5))
* **proxy:** preserve Bedrock body-limit error dialect
([#3871](https://github.com/headroomlabs-ai/headroom/issues/3871))
([ffc6edb](https://github.com/headroomlabs-ai/headroom/commit/ffc6edb4ba7a775d2f6440769b626132a66aa7d3))
* **proxy:** preserve Windows service when Rust core is blocked
([#2989](https://github.com/headroomlabs-ai/headroom/issues/2989))
([eaa16d9](https://github.com/headroomlabs-ai/headroom/commit/eaa16d9f6343f9d5364863c7522734f6b86b1844))
* **proxy:** quarantine compression only once half the pool is stuck
([#3932](https://github.com/headroomlabs-ai/headroom/issues/3932))
([be2b205](https://github.com/headroomlabs-ai/headroom/commit/be2b205c51430236404177bb7d80930a2d299d5a))
* **proxy:** read HEADROOM_LICENSE and make usage reporting opt-in
([#3857](https://github.com/headroomlabs-ai/headroom/issues/3857))
([7460389](https://github.com/headroomlabs-ai/headroom/commit/746038991cf2b4dbb31dd2227d607db7bc273da7))
* **proxy:** reap wrap-spawned proxies once no wrap clients remain
([#3202](https://github.com/headroomlabs-ai/headroom/issues/3202))
([4227bd2](https://github.com/headroomlabs-ai/headroom/commit/4227bd2419e72a922149d5dfaf416808d8e08139))
* **proxy:** redact upstream error detail and add opt-in /metrics
loopback gate
([#2589](https://github.com/headroomlabs-ai/headroom/issues/2589))
([a05717f](https://github.com/headroomlabs-ai/headroom/commit/a05717f6ec2b0514ccaa42b9bd1b3c95d3465730))
* **proxy:** refuse token-less non-loopback binds, gate operator routes
([#3852](https://github.com/headroomlabs-ai/headroom/issues/3852))
([ee731d7](https://github.com/headroomlabs-ai/headroom/commit/ee731d7ea84503ad844eb2759fcb5bbf04a1ae0e))
* **proxy:** reset the cc-switch upstream when Claude Official is
selected
([#3166](https://github.com/headroomlabs-ai/headroom/issues/3166))
([fed7281](https://github.com/headroomlabs-ai/headroom/commit/fed7281120af5b476d3911ca1ebf4dc66d5ca1ea))
* **proxy:** run extension middleware inside the security gate and body
ceiling
([#3847](https://github.com/headroomlabs-ai/headroom/issues/3847))
([1854fd7](https://github.com/headroomlabs-ai/headroom/commit/1854fd7fd3f52bb4cc0b17803de0a04a850eb8f7))
* **proxy:** run injected memory tools server-side on streaming turns
([#3947](https://github.com/headroomlabs-ai/headroom/issues/3947))
([1cf4966](https://github.com/headroomlabs-ai/headroom/commit/1cf496612e781ef8d67ff87ee4f78037492f0bc7))
* **proxy:** share one compression deadline across a Responses request
([#3938](https://github.com/headroomlabs-ai/headroom/issues/3938))
([4d27d02](https://github.com/headroomlabs-ai/headroom/commit/4d27d024b09fe04f6e32b158063538f084d7febb))
* **proxy:** skip pricing lookup for passthrough:* models
([#2585](https://github.com/headroomlabs-ai/headroom/issues/2585))
([f87848c](https://github.com/headroomlabs-ai/headroom/commit/f87848cf78db43dcd4b7e9b6aca3859245348456))
* **proxy:** stop headroom logger from suppressing propagation to
stdout/stderr
([#3096](https://github.com/headroomlabs-ai/headroom/issues/3096))
([f78e66f](https://github.com/headroomlabs-ai/headroom/commit/f78e66f7cc5e00d5db04c493f702ef4ebe7035b0))
* **relevance:** bound segment size by max_chars
([#2518](https://github.com/headroomlabs-ai/headroom/issues/2518))
([0ef7b2a](https://github.com/headroomlabs-ai/headroom/commit/0ef7b2a7fdd7daf4dbb8628c616c28a233ce7910))
* **reporting:** price the savings tile instead of fabricating $0.00
([#3821](https://github.com/headroomlabs-ai/headroom/issues/3821))
([f519fa8](https://github.com/headroomlabs-ai/headroom/commit/f519fa8b97aa9ccef369f5973f1d476af2a65edf))
* **router:** fall back to built-ins when an external compressor passes
through
([#3893](https://github.com/headroomlabs-ai/headroom/issues/3893))
([2c4b20f](https://github.com/headroomlabs-ai/headroom/commit/2c4b20fcba6da0366c1c637a2a3cc61e843012a7))
* **router:** keep ccr_retrieve exemption through orchestrator wrappers
([#3915](https://github.com/headroomlabs-ai/headroom/issues/3915))
([6151ed1](https://github.com/headroomlabs-ai/headroom/commit/6151ed1f52f3d0dd24eb28e0fa666226150a0055))
* **rust-proxy:** forward request paths verbatim and pin the rustls
provider
([#3853](https://github.com/headroomlabs-ai/headroom/issues/3853))
([9d98ea5](https://github.com/headroomlabs-ai/headroom/commit/9d98ea59082ca6b00be2508f00b85ef90c94f744))
* **savings:** record tool-schema dollars disjointly beside the folded
headline
([#3170](https://github.com/headroomlabs-ai/headroom/issues/3170))
([c719d4a](https://github.com/headroomlabs-ai/headroom/commit/c719d4af55ebca177c81c98f74531bfaca831366))
* **savings:** stop scoring unobserved strata against the global mean
([#3128](https://github.com/headroomlabs-ai/headroom/issues/3128))
([f864525](https://github.com/headroomlabs-ai/headroom/commit/f8645257c074b7e5babd949e705d7ca4e8366ae4))
* **sdk:** keep tool names on Vercel tool-result parts through the
OpenAI round trip
([#3883](https://github.com/headroomlabs-ai/headroom/issues/3883))
([b715671](https://github.com/headroomlabs-ai/headroom/commit/b7156714acf1f06cd37f642044455e23e2f89d47))
* **sdk:** preserve Gemini media parts in message conversion instead of
dropping the turn
([#3882](https://github.com/headroomlabs-ai/headroom/issues/3882))
([038c923](https://github.com/headroomlabs-ai/headroom/commit/038c923b4bcd01305f18d993e301b837d668c343))
* **sdk:** stop JSON-wrapping structured tool_result content in the
Anthropic adapter
([#3797](https://github.com/headroomlabs-ai/headroom/issues/3797))
([2e4a60a](https://github.com/headroomlabs-ai/headroom/commit/2e4a60ae3730fc7ea8f5afebbc29961d5fd0af11))
* **search:** stop a context line's body from becoming its line marker
([#3788](https://github.com/headroomlabs-ai/headroom/issues/3788))
([f3f2e00](https://github.com/headroomlabs-ai/headroom/commit/f3f2e0077ae67d492bfc5922e9a49427036e32e0))
* **security:** create memory stores and other state files owner-only
([#3848](https://github.com/headroomlabs-ai/headroom/issues/3848))
([5119b6e](https://github.com/headroomlabs-ai/headroom/commit/5119b6eb545e35b617e2d08b183e968d0104d548))
* **security:** exempt only GET health probes from the proxy token
([#3921](https://github.com/headroomlabs-ai/headroom/issues/3921))
([d99779d](https://github.com/headroomlabs-ai/headroom/commit/d99779dae69d44c934d2115ffd8ee1f1a6cbb898))
* **security:** partition the response cache by credential and principal
([#3862](https://github.com/headroomlabs-ai/headroom/issues/3862))
([ee6cfcc](https://github.com/headroomlabs-ai/headroom/commit/ee6cfcccf6a8944225344c2a468f509783934239))
* **security:** poll usage only with the operator's own credential
([#3863](https://github.com/headroomlabs-ai/headroom/issues/3863))
([65e63c0](https://github.com/headroomlabs-ai/headroom/commit/65e63c08835410149bec4acba8e3737366eb0586))
* **security:** stop forwarding the proxy token to upstream providers
([#3891](https://github.com/headroomlabs-ai/headroom/issues/3891))
([0147cf0](https://github.com/headroomlabs-ai/headroom/commit/0147cf02207fd76be8a14932bcc65a9709bfdb59))
* **settings:** report live proxy configuration
([#3177](https://github.com/headroomlabs-ai/headroom/issues/3177))
([58b1454](https://github.com/headroomlabs-ai/headroom/commit/58b1454282f2b2dee49616c6637fa135ccb885b7))
* **smart-crusher:** recurse at adaptive array limit
([#3770](https://github.com/headroomlabs-ai/headroom/issues/3770))
([7790bde](https://github.com/headroomlabs-ai/headroom/commit/7790bdeebda290b9fdbf899df1cbf9a05e0bc5e9))
* **storage:** page JSONL queries after sorting
([#3872](https://github.com/headroomlabs-ai/headroom/issues/3872))
([91237ca](https://github.com/headroomlabs-ai/headroom/commit/91237cae70771e8e19cbc06ca65d328ac6cb0878))
* **subscription:** match the Bearer scheme case-insensitively for the
Codex usage poll (RFC 7235)
([#3966](https://github.com/headroomlabs-ai/headroom/issues/3966))
([fe88461](https://github.com/headroomlabs-ai/headroom/commit/fe884612c07d2e8a4454615ccc5b6d4feed1d7dd))
* **subscription:** poll with the refreshed credentials-file OAuth token
([#3916](https://github.com/headroomlabs-ai/headroom/issues/3916))
([2dc9fc2](https://github.com/headroomlabs-ai/headroom/commit/2dc9fc22f09ec85d8e73c916e7c1f6f565d271ec))
* surface Codex responses traffic in dashboard
([#399](https://github.com/headroomlabs-ai/headroom/issues/399))
([ecc4967](https://github.com/headroomlabs-ai/headroom/commit/ecc496709b7f2c2657de25d1e3f8de3f226b32e5))
* **telemetry:** label custom-base chat upstreams from a fixed provider
set ([#3759](https://github.com/headroomlabs-ai/headroom/issues/3759))
([f0ec2bb](https://github.com/headroomlabs-ai/headroom/commit/f0ec2bb37697b1addccb416bd626e7bf3c5ea835))
* **thinking:** don't read the model's date suffix as its minor version
([#3791](https://github.com/headroomlabs-ai/headroom/issues/3791))
([afaaaa8](https://github.com/headroomlabs-ai/headroom/commit/afaaaa88049357bac7ec186ea33678f406d02609))
* **transforms/kompress:** preserve line boundaries and tabular output
in Kompress
([#3119](https://github.com/headroomlabs-ai/headroom/issues/3119))
([fe2ed2b](https://github.com/headroomlabs-ai/headroom/commit/fe2ed2b545e4b3c97d21872232d5446cb54aedc2))
* **transforms:** judge a Codex exec envelope read by its output
([#3878](https://github.com/headroomlabs-ai/headroom/issues/3878))
([922924e](https://github.com/headroomlabs-ai/headroom/commit/922924ef44ebd7501ff00923cc0c2007f06cfade))
* **transforms:** judge the code_aware Kompress fallback in tokens
([#3881](https://github.com/headroomlabs-ai/headroom/issues/3881))
([6326965](https://github.com/headroomlabs-ai/headroom/commit/63269650462c1a565c259cfe3fc3bd67ac942f5a))
* **transforms:** keep record-bearing JSON out of Kompress
([#3673](https://github.com/headroomlabs-ai/headroom/issues/3673))
([#3880](https://github.com/headroomlabs-ai/headroom/issues/3880))
([8dbbd1d](https://github.com/headroomlabs-ai/headroom/commit/8dbbd1d8967f719acfaa21e2c1668e9f3193dbe8))
* **wrap:** never reuse a non-Headroom listener on the proxy port
([#3799](https://github.com/headroomlabs-ai/headroom/issues/3799))
([3ffa57e](https://github.com/headroomlabs-ai/headroom/commit/3ffa57ec25a6f05dff073c0ad0b14c90ce264fd8))
* **wrap:** never reuse a proxy with incompatible routing config
([#3201](https://github.com/headroomlabs-ai/headroom/issues/3201))
([f69e246](https://github.com/headroomlabs-ai/headroom/commit/f69e2463a0c29cea7943af5efe4b2a2170a1e863))
* **wrap:** preserve pre-set ANTHROPIC_BASE_URL as proxy upstream
([#1358](https://github.com/headroomlabs-ai/headroom/issues/1358))
([bb1ab6a](https://github.com/headroomlabs-ai/headroom/commit/bb1ab6afd35a5c22b6c11b549aba4075fb7791ec))
* **wrap:** scope Serena's MCP registration to the wrapped project
([#2787](https://github.com/headroomlabs-ai/headroom/issues/2787))
([#2992](https://github.com/headroomlabs-ai/headroom/issues/2992))
([8cfeb69](https://github.com/headroomlabs-ai/headroom/commit/8cfeb692ca0cad9598160020a144c5c671cd2fc3))
* **wrap:** set ANTHROPIC_HOST so `wrap goose` actually proxies
Anthropic
([#2619](https://github.com/headroomlabs-ai/headroom/issues/2619))
([c07fad0](https://github.com/headroomlabs-ai/headroom/commit/c07fad0f37d44b7f6886e6ce774d424463636242))
* **wrap:** strip -dev from running proxy version in restart check
([#3200](https://github.com/headroomlabs-ai/headroom/issues/3200))
([bd0296b](https://github.com/headroomlabs-ai/headroom/commit/bd0296b5e7b62b620df7b37b41ce573d57958e71))


### Performance Improvements

* add savings audit output
([#1211](https://github.com/headroomlabs-ai/headroom/issues/1211))
([9a72bc0](https://github.com/headroomlabs-ai/headroom/commit/9a72bc024263e2470626fae7f20430db682e0042))
* **compression/code:** avoid a UTF-8 copy per code block in
byte-to-char mapping
([#3169](https://github.com/headroomlabs-ai/headroom/issues/3169))
([d5e5534](https://github.com/headroomlabs-ai/headroom/commit/d5e5534b4763b14d7710908153e0d6a89423eea9))
* **image:** OCR and SigLIP each image once, not once per turn
([#3941](https://github.com/headroomlabs-ai/headroom/issues/3941))
([a8561fb](https://github.com/headroomlabs-ai/headroom/commit/a8561fb4be1bdc17bf8bf86ac97c17651e2820b7))
* **memory:** bound traffic-learner _persisted_ids with the dedup window
([#3341](https://github.com/headroomlabs-ai/headroom/issues/3341))
([7e73438](https://github.com/headroomlabs-ai/headroom/commit/7e73438dc5f923c90ad0c1f2f07cb6de221c9f08))
* **metrics:** cap inbound request-path cardinality to bound memory
([#3340](https://github.com/headroomlabs-ai/headroom/issues/3340))
([88a1f4e](https://github.com/headroomlabs-ai/headroom/commit/88a1f4e52ba220b5ddb34d94ac0a201391c16027))
* **proxy:** lighter request path: alias the message snapshot, keep the
token cache on re-counts, decompress off the event loop
([#3909](https://github.com/headroomlabs-ai/headroom/issues/3909))
([c873d13](https://github.com/headroomlabs-ai/headroom/commit/c873d13fe07d09be71d5dcbfd640a78ec5b3f0d7))
* **tokenizer:** memoize OpenAI token counts like the Anthropic counter
([#3168](https://github.com/headroomlabs-ai/headroom/issues/3168))
([0a2c80d](https://github.com/headroomlabs-ai/headroom/commit/0a2c80d5207642a5e58ba9eb65e19cd004018642))


### Dependencies

* bump pyjwt 2.13.0 -&gt; 2.15.1 for CVE-2026-102274
([#3861](https://github.com/headroomlabs-ai/headroom/issues/3861))
([37b9c46](https://github.com/headroomlabs-ai/headroom/commit/37b9c46069f11a2b2a477ae4ef25dd33bf359684))
* Bump source-map-js from 1.2.1 to 1.2.2 in /docs
([#3986](https://github.com/headroomlabs-ai/headroom/issues/3986))
([e06631a](https://github.com/headroomlabs-ai/headroom/commit/e06631a7a78d18432c90cfb44b30e461424cfd30))
* Bump source-map-js from 1.2.1 to 1.2.2 in /plugins/openclaw
([#3988](https://github.com/headroomlabs-ai/headroom/issues/3988))
([4be83b3](https://github.com/headroomlabs-ai/headroom/commit/4be83b35e683df077b11af4c4b37b301c4a65547))
* Bump source-map-js from 1.2.1 to 1.2.2 in /plugins/opencode
([#3987](https://github.com/headroomlabs-ai/headroom/issues/3987))
([478dd9e](https://github.com/headroomlabs-ai/headroom/commit/478dd9e0a34cd592fdc0e313019297bc23b17db3))
* Bump source-map-js from 1.2.1 to 1.2.2 in /sdk/typescript
([#3985](https://github.com/headroomlabs-ai/headroom/issues/3985))
([62cde35](https://github.com/headroomlabs-ai/headroom/commit/62cde35b939d7405735b72d1e50aa7c1407e5892))
* bump the npm-minor-patch group across 2 directories with 11 updates
([#3903](https://github.com/headroomlabs-ai/headroom/issues/3903))
([afe4f4e](https://github.com/headroomlabs-ai/headroom/commit/afe4f4eca58977ae9382dfb2899a8097b46c0909))
* bump the npm-minor-patch group across 3 directories with 11 updates
([#3910](https://github.com/headroomlabs-ai/headroom/issues/3910))
([ff1a0d6](https://github.com/headroomlabs-ai/headroom/commit/ff1a0d69f4a83f7c5583a7af2d2961025587801e))
* bump webpki-roots from 0.26.11 to 1.0.8
([#3905](https://github.com/headroomlabs-ai/headroom/issues/3905))
([fee53b4](https://github.com/headroomlabs-ai/headroom/commit/fee53b4daa3a0ac2b2378a692278f24f0062d584))
* drop the crewai extra to remove chromadb from the lockfile
([#3870](https://github.com/headroomlabs-ai/headroom/issues/3870))
([59b8cef](https://github.com/headroomlabs-ai/headroom/commit/59b8cefc24e48539974787e0677298f335b2720e))


### Code Refactoring

* **ccr:** read the expansion query through extract_user_query
([#2707](https://github.com/headroomlabs-ai/headroom/issues/2707))
([dcec845](https://github.com/headroomlabs-ai/headroom/commit/dcec845851d8202ce3361022a14b3716fdeb59c0))
* **wrap:** generate goose/openhands/openclaude from a WrapTarget
registry
([#3800](https://github.com/headroomlabs-ai/headroom/issues/3800))
([de4cf7e](https://github.com/headroomlabs-ai/headroom/commit/de4cf7e7a1ece51ce6c60d25bc34f46897e972c9))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-10-05 22:06:30 -05:00
Tejas ChopraandClaude Opus 5.5 59b8cefc24 deps!: drop the crewai extra to remove chromadb from the lockfile (#3870)
## Description

Removes the `crewai` extra. Every CrewAI release requires `chromadb`,
which has unpatched advisories in its server, so the extra kept CrewAI,
ChromaDB and about 40 other packages in `uv.lock` and in Headroom's
Dependabot alerts. Headroom never imports ChromaDB or runs a ChromaDB
server, and the extra was never part of `[all]`, `[sandbox]` or any
image.

The extra added nothing to the integration itself: the CrewAI adapter
only wraps CrewAI tools and uses whatever CrewAI the user has installed.
Users install CrewAI alongside Headroom instead.

Closes Dependabot alerts #204, #205, #206 (chromadb) and #412, #413
(oauthlib, which came in only through ChromaDB's Kubernetes client).
Dependabot PR #3890 (oauthlib bump) becomes moot.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `pyproject.toml`: remove the `crewai` extra, with a comment saying why
there is none.
- `uv.lock`: 42 packages removed (crewai, chromadb, kubernetes, lancedb,
oauthlib and their dependencies). Nothing added or upgraded.
- `SECURITY.md`: the CrewAI / ChromaDB section now states the new
boundary: Headroom does not lock CrewAI or ChromaDB, and a user who
installs CrewAI owns that exposure. It still lists the ChromaDB
advisories and server mitigations for those users.
- `.github/dependabot.yml`: drop the ChromaDB ignore range, which now
matches nothing. The Accelerate range stays.
- Installation docs and the integrations docstring now say `pip install
headroom-ai crewai`.

## Migration

`pip install "headroom-ai[crewai]"` still succeeds, but pip warns about
the unknown extra and installs Headroom without CrewAI. Replace it with:

```bash
pip install headroom-ai crewai
```

The CrewAI integration (`headroom.integrations.crewai`) is unchanged.
Without CrewAI installed it raises an `ImportError` that names the same
command.

## Testing

- [ ] Unit tests pass (`pytest`) — no code changed; the CrewAI tests
skip without CrewAI, as before
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`) — no Python code changed
- [ ] New tests added for new functionality — not applicable
- [x] Manual testing performed

### Test Output

```text
$ uv lock --check
Resolved 250 packages
$ grep -c '^name = "crewai"\|^name = "chromadb"\|^name = "oauthlib"' uv.lock
0
$ python -c "import headroom.integrations"   # imports without CrewAI
```

## Real Behavior Proof

- Environment: local, Python 3.14, current main merged in.
- Exact command / steps: `uv lock --check`; checked that crewai,
chromadb and oauthlib are absent from `uv.lock`; imported
`headroom.integrations` without CrewAI installed.
- Observed result: lockfile consistent; the three packages are absent;
import succeeds.
- Not tested: installing CrewAI alongside Headroom in a fresh
environment.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: no runtime change; packaging only.
The `[crewai]` extra no longer installs CrewAI.
- Kill switch / disable path: n/a
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works — not applicable (packaging change)
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

Marked breaking (`deps!:`) so release-please records the removal and the
migration note above. Addresses the review on this PR: breaking-change
classification and migration note, SECURITY.md and Dependabot updated in
the same PR, branch brought current with main.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 11:29:19 -07:00
Tejas ChopraandClaude Opus 5 b10dd8db6e fix(memory): pin LF on memory writers and guard the learn-writer newline contract (#3706)
Closes #3698. Follow-up to #3594, which fixed `headroom/learn/writer.py`
correctly but left three gaps.

## 1. The write half had no regression guard

`test_apply_does_not_accumulate_carriage_returns_on_crlf_file` passes on
`main` with the fix reverted — its assertion (`raw.count(b"\r") ==
raw.count(b"\r\n")`) holds for a CRLF-preserving file too. So the
`newline="\n"` pins, which *are* the fix, were unguarded.

This cannot be caught by asserting on file bytes on POSIX: CPython's C
`TextIOWrapper` picks the newline translation target at compile time
(`#ifdef MS_WINDOWS`), so monkeypatching `os.linesep` does not simulate
Windows.

The new test spies on `Path.write_text` and drives the real writer
`.write()` methods. Stripping the kwargs from all seven sites:

```
tests/test_learn/test_writer.py ................................F
E   AssertionError: learn writers wrote without newline='\n': [
E     .../data/memory/MEMORY.md, .../instructions.md, .../myproject/AGENTS.md,
E     .../myproject/CLAUDE.local.md, .../myproject/CLAUDE.md,
E     .../myproject/GEMINI.md, .../myproject/GROK.md]
=================== 1 failed, 32 passed ===================
```

All seven named — and note the other 32 pass, including the old test,
confirming it was never a guard.

## 2. The same bug was still live in the memory writers

Ten call sites, all nine from the issue plus
**`headroom/memory/sync.py:137`** (`_save_sync_state`), which the issue
missed:

`writers/base.py:168` · `writers/claude_writer.py:119` ·
`writers/cursor_writer.py:130` · `bridge.py:126, 394, 650` ·
`sync.py:137` · `sync_adapters/codex_agent.py:124` ·
`sync_adapters/claude_code.py:196, 239`

These write files that **overlap** with the learn writers
(`~/.claude/CLAUDE.md`, `AGENTS.md`), so on Windows a file flipped
between LF and CRLF depending on which subsystem wrote last.

**No live accumulation bug:** every reader of these files uses
`read_text()`, which normalizes — that is the key difference from
`learn/writer.py`'s `read_bytes().decode()`, which is what let `\r` pile
up. Checked all of them (`bridge.py:114, 222, 617`,
`writers/base.py:193`, `writers/cursor_writer.py:103`,
`sync_adapters/claude_code.py:106, 163, 178, 216`,
`sync_adapters/codex_agent.py:48, 83`, `sync.py:127`).

**But the churn is more than cosmetic**, which the issue did not note:
`claude_code.py:252` and `codex_agent.py:135` read via `read_bytes()`
for `fingerprint()` change-detection hashing. An EOL flip changes the
hash, so a CRLF/LF flip reads as a content change and triggers a
spurious re-sync.

Three new tests cover the writer, bridge and sync-adapter paths; all
three fail with the pins stripped.

## 3. No unit test had ever run on Windows

The sharded `test` job is ubuntu-only, and `build-wheel-windows` builds
without testing — which is how a Windows-only bug shipped twice. Added
`test-windows-newline`: consumes the existing `headroom-wheel-windows`
artifact and runs only tests marked `windows_newline`. Marker registered
in `pyproject.toml`.

**Known limitation, documented in the job comment:** it is gated on the
`packaging` paths-filter (that is what builds the wheel), so a
pure-Python PR skips it. The ubuntu shards still run the same marked
tests — they assert the kwarg, which fails on any platform — so this is
the Windows-side backstop, not the only guard. Making it fire on every
writer change would mean gating the Windows Rust wheel build on `code`,
which is too expensive to do unasked.

## Verification

- 4 guards proven to fail before, pass after.
- `tests/test_learn/ tests/test_memory/ tests/test_memory_sync.py` →
**950 passed, 4 skipped**.
- Adjacent suites → 168 passed. `pytest tests -m windows_newline` → 4
passed, no marker warning.
- `actionlint .github/workflows/*.yml` → exit 0. Action versions match
the file's conventions (`checkout@v7`, `setup-python@v7`,
`download-artifact@v8`).

`CONTRIBUTING.md` states the invariant once under Coding standards:
Headroom writes LF and normalizes on read, on every platform.

## Not in this PR

Issue section 3's release-note line about the one-time EOL churn on
Windows (the first `--apply` rewrites the whole file to LF). Harmless
under `autocrlf=true`, but worth a release note; `CHANGELOG.md` edits
are blocked by `changelog-guard.yml`.

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

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-29 11:18:03 -05:00
66258c40a4 fix: make Headroom work behind Zscaler and other TLS-inspecting networks (#3831)
## Description

Customers behind **Zscaler** (and Netskope, Palo Alto, Cisco Secure
Access, …) report that Headroom "cannot work": every upstream request
fails with `CERTIFICATE_VERIFY_FAILED`, and the agent only sees a bare
502.

These gateways inspect TLS by re-signing every certificate with a
company root. IT installs that root in the **OS certificate store**
(macOS Keychain, Windows cert store), which is why browsers, `curl` and
Claude Code keep working. Headroom never read that store:

- The httpx upstream client trusted certifi only.
- On macOS, the stdlib default reads the static file
`/etc/ssl/cert.pem`, not the Keychain.
- The Rust proxy trusted Mozilla's webpki roots only.

Only 3 of about 40 outbound call sites used the shared CA helper. We had
been patching one path at a time (#741, #998, #1308, #3244, #3344,
#3358, #810, #2029). This PR sets **one trust policy, based on the OS
store, used everywhere.**

Closes #3358

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

**1. Verify upstream TLS through the OS store by default**
(`headroom/proxy/ssl_context.py`)
- New `HEADROOM_CERT_STORE`, default `system,bundled` (same shape as
Claude Code's `CLAUDE_CODE_CERT_STORE`). It uses
[`truststore`](https://truststore.readthedocs.io/), which pip has used
by default since 24.2, plus certifi's public roots.
- The same policy covers the HTTP upstream client, both WebSocket
upstreams, and the `urlopen` paths (Copilot auth).
- **The builders now always return a concrete, verifying `SSLContext`**,
never a `bool`. The legacy default is built explicitly as httpx's
`verify=True` equivalent (certifi).
- OS-store contexts are cached per configuration. They set
`VERIFY_X509_PARTIAL_CHAIN` so an exported intermediate still works as a
trust anchor (matching `create_default_context()` on 3.13). On macOS and
Windows the OS verifies the chain, so the Python 3.13 strict-mode
rejection (#1308) no longer happens.
- `HEADROOM_CA_BUNDLE` and `NODE_EXTRA_CA_CERTS` **add** roots.
`SSL_CERT_FILE` and `REQUESTS_CA_BUNDLE` keep their **replacement**
meaning and turn the OS store off.
- `HEADROOM_CERT_STORE=bundled` restores the old behavior. The aliases
`bundle`, `certifi`, `os` and `native` are also accepted.
- `truststore.inject_into_ssl()` (covers `huggingface_hub`, tiktoken and
OTEL) runs only in processes the Headroom CLI owns. The CLI marks them
with `HEADROOM_PROCESS_TRUST=1`, and proxy workers inherit it.
Applications that embed Headroom keep their own process-wide TLS
behavior.
- `truststore` is added as a core dependency: pure Python, with no
dependencies of its own.

**2. Errors that say what's wrong**
(`headroom/proxy/tls_diagnostics.py`)
- When the certificate check fails, the Anthropic, streaming (SSE) and
OpenAI passthrough errors now name who signed the certificate and give
the fix. For example: *"…The certificate was issued by 'O=Zscaler Inc.,
CN=Zscaler Intermediate Root CA': Zscaler is inspecting this connection.
Fix (pick one): …"*
- The issuer comes from a separate handshake that inspects the
certificate only:
  - It sends no data and requires **TLS ≥ 1.2**.
- It has a 4-second timeout and is cached for 5 minutes per host. A
burst of failures shares a single handshake.
  - It uses the same environment-variable proxies as the real client.
  - It targets the host that actually failed.
- **Security:** on the request path it skips hosts that resolve to
non-public addresses. It also connects to the exact address it checked,
instead of looking the host up again. A per-request upstream therefore
can't be used to read an internal service's certificate or to rebind
DNS.

**3. `headroom doctor`**
- A new **tls trust** row reports the running proxy's policy, read from
`/health`.
- A **proxy env** warning appears when `HTTP(S)_PROXY` is set but
`NO_PROXY` doesn't exempt loopback.
- `--network` (plus a repeatable `--network-url`) probes the provider
and model hosts. For each it shows the certificate issuer, whether
Headroom trusts it, and whether a gateway block page came back. On
failure it prints a paste-ready request for IT.

**4. `headroom wrap`**
- Merges `NO_PROXY` and `no_proxy`, appends `127.0.0.1,localhost,::1`,
and writes the result to both, so a corporate proxy doesn't capture the
agent's traffic to Headroom.
- The notice goes to stderr, because the JSON that `--prepare-only`
prints on stdout is parsed by `install.sh`.

**5. Rust proxy** (`crates/headroom-proxy`)
- reqwest now enables `rustls-tls-native-roots`, and
`HEADROOM_CA_BUNDLE` / `NODE_EXTRA_CA_CERTS` add roots.
- **Fixes a bug already on `main`: `wss://` upstreams panicked.** Both
ring and aws-lc-rs are compiled into this binary, so
`rustls::ClientConfig::builder()`, which
`tokio_tungstenite::connect_async` calls, panics with "no process-level
CryptoProvider available". WebSocket upstreams now use an explicit
config: the ring provider, webpki + OS + additive roots, and ALPN
`http/1.1`.

**6. Docs**
- New page **Corporate Networks**: trust settings, HTTP proxies, a
domain table for IT, and notes on Caution/Isolate, SSE buffering,
process bypass, tenant restrictions and `HF_ENDPOINT` mirrors.
- README section updated, correcting a wrong claim about which trust
store the Rust core uses.

**7. `uv.lock`**
- `main`'s lockfile plus `truststore` only. The diff is 11 lines: the
new package entry and two lines in `headroom-ai`'s dependency lists.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest tests/test_corporate_tls.py tests/test_ssl_context.py tests/test_copilot_auth.py tests/test_cli_doctor.py -q
============================= 278 passed in 2.88s ==============================

$ pytest <117 related files: doctor, wrap, streaming, codex, copilot, ssl, upstream, websocket, passthrough> -q
====== 4 failed, 1876 passed, 25 skipped, 7 warnings in 132.42s (0:02:12) ======
# the 4 failures: tests/test_codex_live.py ordering issue, identical on main (see Additional Notes)

$ cargo test -p headroom-proxy
passed=478 failed=0 suites=37
$ cargo clippy -p headroom-proxy --all-targets -- -D warnings
Finished `dev` profile [unoptimized + debuginfo] target(s)

$ ruff check .                                            -> All checks passed!
$ ruff format --check .                                   -> 1660 files already formatted
$ mypy headroom --ignore-missing-imports                  -> Success: no issues found in 544 source files
$ uv export --frozen --no-dev --no-hashes | grep truststore -> truststore==0.10.4
```

`tests/test_corporate_tls.py` runs a **fake Zscaler** HTTPS server. Its
root is `O=Zscaler Inc.` with **non-critical basicConstraints**, like
the real 2014 root. The tests check that:

- certifi alone rejects it;
- the default policy plus `HEADROOM_CA_BUNDLE` or `NODE_EXTRA_CA_CERTS`
accepts it;
- the probe names Zscaler, and the request path skips private hosts;
- a streaming request surfaces the actionable message in a 502 SSE
error;
- a burst of failures shares one handshake;
- the notices and JSON output from `wrap` go to the right streams;
- process injection is gated as described.

## Real Behavior Proof

- **Environment:**
  - macOS (Darwin 25.6, Apple Silicon), Python 3.12.13 venv
  - Python 3.13.15 via `uv run --python 3.13`
  - Linux `python:3.13-slim` in Docker
  - Rust proxy built from this branch
- **Steps and results:**
1. **Standalone fake-Zscaler script** (same root as above) on Python
3.13:
- old stdlib path, `ssl.create_default_context(cafile=root)` →
`CERTIFICATE_VERIFY_FAILED: Missing Authority Key Identifier`
     - new `truststore` context + root → `200`
     - identical results on macOS and in `python:3.13-slim`.
2. **`headroom doctor --network`** from this branch on an uninspected
network: every endpoint shows `reachable, certificate trusted`
(api.anthropic.com 401, api.openai.com 401, api.githubcopilot.com 400,
huggingface.co 200, openaipublic 404); the tls trust row shows `OS
certificate store + certifi`.
3. **Rust `wss://` connection** (temporary test) to
`wss://echo.websocket.org`:
- `tokio_tungstenite::connect_async` as on `main` → **panic** (no
process-level CryptoProvider)
     - `connect_async_tls_with_config` with the new config → `Ok(())`
- **Not tested:**
  - A real Zscaler, Netskope or Palo Alto tenant.
- Windows. `truststore` supports the Windows cert store, but no Windows
run was done here.
- A root installed into the OS store. That needs admin rights, so the
additive-bundle path stood in for it; it goes through the same OS
verifier.

## Runtime Rollout Safety

- **Rollout-managed feature(s):** none. This is trust-store selection,
not a rollout-gated feature.
- **Minimum rollout channel:** n/a.
- **Stable/default behavior changed:** yes. Upstream TLS now also trusts
the OS certificate store; certifi is still loaded, so public endpoints
behave the same. The Rust `wss://` upstream no longer panics.
- **Kill switch / disable path:** `HEADROOM_CERT_STORE=bundled` restores
certifi-only trust. An explicit `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE`
behaves exactly as before.
- **Unsafe override required:** none. Nothing here disables certificate
verification.
- **Qualification impact:** none expected. Default behavior on
uninspected networks is unchanged.
- **Rollback path:** revert the PR, or set
`HEADROOM_CERT_STORE=bundled`.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

n/a (CLI and proxy behavior).

## Additional Notes

**Review response** (@JerrettDavis):
- **CodeQL:** the 5 alerts that were still open on `efe173c9` had two
causes.
- **Certificate-validation alerts:** CodeQL traced a `None` returned by
the optional-context helpers through the `configured or default`
fallback into `verify=`. All contexts are now built by a single
`_build_context()`, and every branch returns a verifying `SSLContext`.
`build_httpx_verify()` is typed `-> ssl.SSLContext`.
- **TLS-version alerts:** every context the module creates now sets an
explicit `minimum_version = TLSv1_2`. That includes the
certificate-inspection probe, whose no-validation scope stays confined
to that handshake behind the public-address / environment-proxy CONNECT
guard. The test server also requires TLS 1.2, and the host assertion in
the test is a regex.
  - **Verified locally with CodeQL 2.27.1** before pushing:
- the same 5 alerts reproduce on `efe173c9`, and 0 remain on the fix
commit;
- `python-security-extended` over every Python file this PR changes
finds the same 14 pre-existing alerts on `main`'s versions and on the
branch's versions, so the PR adds none.
- **`uv.lock`:** rebuilt as `main`'s lockfile plus `truststore` only (11
lines). Re-locking with current uv also rewrites markers across the
file, because `main`'s lockfile predates the current `pyproject.toml`.
That is left for a separate lock refresh.

**Earlier review:** a high-effort code review of this branch produced 10
findings plus 3 minor notes. Commit `fix: address review findings…`
resolves 9 of the 10 and two of the notes; the third note (lockfile
markers) checked out as a false alarm. The remaining finding is the last
follow-up below.

**Follow-ups (not in this PR):**
- SSE keep-alives and HTTP/1.1 fallback when a gateway buffers a stream.
- A `wrap` pre-flight that steps aside when the upstream is unreachable.
- The Rust core's fastembed/hf-hub embedding download, which hard-codes
WebPki roots (needs an hf-hub patch; BM25 is the fallback, and
`HF_ENDPOINT` is documented).
- A CI job with a fake root installed in the OS store on macOS and
Windows.
- Map certificate failures once, in a shared layer, so batch, Gemini and
the other handlers get the TLS hint too.

**Known unrelated failures:**
- 4 `tests/test_codex_live.py` tests fail when run after other files in
this set, both on `main` and on this branch. They pass when run on their
own.
- After merging the latest `main` (thanks for the refresh),
`tests/test_cli/test_wrap_helpers.py::test_start_proxy_strips_ambient_worker_configuration`
and `::test_start_proxy_timeout_kills_failed_new_process` fail locally
with `TypeError: <lambda>() takes 0 positional arguments but 1 was
given`. They fail the same way on a clean checkout of current `main`.

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

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-09-28 18:06:09 -07:00
JD Davisandgithub-actions[bot] d13e1966f8 chore: release 0.39.1 (#3807)
🤖 I have created a release *beep* *boop*
---


##
[0.39.1](https://github.com/headroomlabs-ai/headroom/compare/v0.39.0...v0.39.1)
(2026-09-26)


### Bug Fixes

* **proxy:** stop the 0.39.0 TPM limiter from refusing large-context
requests forever
([#3806](https://github.com/headroomlabs-ai/headroom/issues/3806))
([7968122](https://github.com/headroomlabs-ai/headroom/commit/7968122658c31c06ef3e5b1fe7911c8cb0a79ade))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-09-26 15:31:25 -05:00
JD Davisandgithub-actions[bot] 66f426171b chore: release 0.39.0 (#3713)
🤖 I have created a release *beep* *boop*
---


##
[0.39.0](https://github.com/headroomlabs-ai/headroom/compare/v0.38.0...v0.39.0)
(2026-09-25)


### Features

* **compression:** describe what CCR compression dropped, not just how
much ([#3635](https://github.com/headroomlabs-ai/headroom/issues/3635))
([62d1cc0](https://github.com/headroomlabs-ai/headroom/commit/62d1cc08b10c3e397875d82a33e500ce9a6b44e7))
* **hooks:** add protect_messages, a hard per-message compression veto
([#3772](https://github.com/headroomlabs-ai/headroom/issues/3772))
([d17ac6a](https://github.com/headroomlabs-ai/headroom/commit/d17ac6a174d9617951ca6eff4646da4c19f83922))
* **opencode:** exclude hosts from transport plugin routing
([#3668](https://github.com/headroomlabs-ai/headroom/issues/3668))
([0024b57](https://github.com/headroomlabs-ai/headroom/commit/0024b57405ee0b9b622c7ef5e18bde1657d4a142))
* **proxy:** let /transformations/feed omit message bodies for
number-only pollers
([#3672](https://github.com/headroomlabs-ai/headroom/issues/3672))
([46ac52d](https://github.com/headroomlabs-ai/headroom/commit/46ac52d39d6d7fc275dc24c7788bca5acfbcde31))
* **savings:** carry exact cache-read cost in history rollups
([#3734](https://github.com/headroomlabs-ai/headroom/issues/3734))
([1cb779e](https://github.com/headroomlabs-ai/headroom/commit/1cb779e1bcaebad4cba113bf2106bcd9825bef40))
* **savings:** show the new-input savings basis beside the whole-wire
figure
([#3485](https://github.com/headroomlabs-ai/headroom/issues/3485))
([e92cccc](https://github.com/headroomlabs-ai/headroom/commit/e92cccca00fa53f27d4a04b5ec244cc105e60caa))
* **savings:** track lifetime output spend so a bill-share rate has a
denominator
([#3520](https://github.com/headroomlabs-ai/headroom/issues/3520))
([c766bdb](https://github.com/headroomlabs-ai/headroom/commit/c766bdb2b36199dedb081963a74a77652e633c98))
* **sdk:** support per-call config override in compress()
([#3370](https://github.com/headroomlabs-ai/headroom/issues/3370))
([c3e8a1e](https://github.com/headroomlabs-ai/headroom/commit/c3e8a1ee63f8a2fec25a2f1b507413dd1f50faf7))
* **wrap:** support 1m context in vscode claude
([#3361](https://github.com/headroomlabs-ai/headroom/issues/3361))
([fc5a09e](https://github.com/headroomlabs-ai/headroom/commit/fc5a09e1b3daa9e434b27f5f3160f8d1d56a4896))


### Bug Fixes

* **anthropic:** reject ping-only SSE from buffered CCR
([#3682](https://github.com/headroomlabs-ai/headroom/issues/3682))
([000fefc](https://github.com/headroomlabs-ai/headroom/commit/000fefceaa26223ee95e8f9deb58bfc1854275ec))
* **anthropic:** stop the spurious compaction warning and drop dead
handler code
([#3678](https://github.com/headroomlabs-ai/headroom/issues/3678))
([6e71267](https://github.com/headroomlabs-ai/headroom/commit/6e712672cb5cc298772c8edd0e4480da53853f99))
* **backends/litellm:** stop dropping image blocks from /v1/messages
requests
([#3753](https://github.com/headroomlabs-ai/headroom/issues/3753))
([577336d](https://github.com/headroomlabs-ai/headroom/commit/577336d2b66ab0d08cd28c408e2244dca15a3bbc))
* **binaries:** fail closed when a download carries no sha256 pin
([#3724](https://github.com/headroomlabs-ai/headroom/issues/3724))
([26a2c49](https://github.com/headroomlabs-ai/headroom/commit/26a2c4939c408bf6a0b7b20f3671378fc5cd61f6))
* **cache/google:** tolerate timezone-aware cache expiry timestamps
([#3210](https://github.com/headroomlabs-ai/headroom/issues/3210))
([7ce2580](https://github.com/headroomlabs-ai/headroom/commit/7ce2580ff95c5943d9e68e2d1d6cd89e1abd9bdc))
* **cache:** default CCR payload previews off; harden the log when they
are on
([#3728](https://github.com/headroomlabs-ai/headroom/issues/3728))
([5cb87bc](https://github.com/headroomlabs-ai/headroom/commit/5cb87bc3516fc7c1a2ba6bde8aa6a0337c6437c9))
* **cache:** never batch-compress already-forwarded small Responses
outputs in cache mode
([#3756](https://github.com/headroomlabs-ai/headroom/issues/3756))
([ab62b9e](https://github.com/headroomlabs-ai/headroom/commit/ab62b9e0ad95494793b91c6317e122ebc8d18709))
* **cache:** preserve cache_control schema properties
([#3348](https://github.com/headroomlabs-ai/headroom/issues/3348))
([b84c4c9](https://github.com/headroomlabs-ai/headroom/commit/b84c4c9f7164fae8e1e74e419af026ad37c2869e))
* **cache:** preserve the forwarded OpenAI chat prefix across turns
([#3757](https://github.com/headroomlabs-ai/headroom/issues/3757))
([deca575](https://github.com/headroomlabs-ai/headroom/commit/deca575c63ec2c09b3e465229c2cd674b29299d9))
* **cache:** stop prefix transforms from busting the provider cache
([#3735](https://github.com/headroomlabs-ai/headroom/issues/3735))
([a2bf5ed](https://github.com/headroomlabs-ai/headroom/commit/a2bf5ed1ba456303173d35611e3844909a2614db))
* **cache:** stop skipping tool compaction on a pinned tools array
([#3750](https://github.com/headroomlabs-ai/headroom/issues/3750))
([a6a9cef](https://github.com/headroomlabs-ai/headroom/commit/a6a9cef9458e2e07c8222d76714e540a7de68ac4))
* **cli:** keep non-ASCII working directory names out of the init
profile slug
([#3718](https://github.com/headroomlabs-ai/headroom/issues/3718))
([f3d95ee](https://github.com/headroomlabs-ai/headroom/commit/f3d95ee275a33631d37f03b16a8c64c87787a064))
* **cli:** report anonymous beacon status accurately in the banner, log,
and /stats
([#3533](https://github.com/headroomlabs-ai/headroom/issues/3533))
([fa9edb3](https://github.com/headroomlabs-ai/headroom/commit/fa9edb3a2989a06323c1471131c8570425e45497))
* **content_detector:** detect CMTrace (SCCM/Intune) logs as
BUILD_OUTPUT
([#3712](https://github.com/headroomlabs-ai/headroom/issues/3712))
([6feb1fb](https://github.com/headroomlabs-ai/headroom/commit/6feb1fb22a3977f173d115285468e9ec1e8af39f))
* **dashboard:** separate rolling cache economics by owner
([#3319](https://github.com/headroomlabs-ai/headroom/issues/3319))
([a29162b](https://github.com/headroomlabs-ai/headroom/commit/a29162baa674f3c210d074c1f0d1a0b589538b7d)),
closes [#960](https://github.com/headroomlabs-ai/headroom/issues/960)
* **docker:** support OpenCode in native wrapper
([#3547](https://github.com/headroomlabs-ai/headroom/issues/3547))
([d90dadf](https://github.com/headroomlabs-ai/headroom/commit/d90dadf2668ac3b4f9706d45aa04b39f9dabac79))
* fall back for non-admin Windows task installs
([#3437](https://github.com/headroomlabs-ai/headroom/issues/3437))
([b958509](https://github.com/headroomlabs-ai/headroom/commit/b95850945270678bd1a1ed555149dc45be8e878e))
* **graph:** fetch and extract the zip codebase-memory-mcp asset on
Windows
([#3730](https://github.com/headroomlabs-ai/headroom/issues/3730))
([b776983](https://github.com/headroomlabs-ai/headroom/commit/b7769831282a5e67ec3a331f26e77d823decdeb6))
* **grok:** preserve xAI model context metadata
([#3312](https://github.com/headroomlabs-ai/headroom/issues/3312))
([#3315](https://github.com/headroomlabs-ai/headroom/issues/3315))
([c81378c](https://github.com/headroomlabs-ai/headroom/commit/c81378c878121d6bcf144c89ba8c07029e86baea))
* **init:** raise the ensure hook's timeout above cold-start latency
([#3438](https://github.com/headroomlabs-ai/headroom/issues/3438))
([9a11109](https://github.com/headroomlabs-ai/headroom/commit/9a1110997a1387394844993a07a3674a8a09f288))
* **install:** apply managed env vars added after a deployment was
installed
([#3740](https://github.com/headroomlabs-ai/headroom/issues/3740))
([a4cb2bc](https://github.com/headroomlabs-ai/headroom/commit/a4cb2bc02144d4bb6d8213c71f66ee039d03ae15))
* **install:** wait for the old process to stop before restarting
([#3670](https://github.com/headroomlabs-ai/headroom/issues/3670))
([11c7320](https://github.com/headroomlabs-ai/headroom/commit/11c7320bbcc45033238a7a804aaf515ea276bfed))
* **kompress:** bound the inference deadline to the request, not each
block ([#3693](https://github.com/headroomlabs-ai/headroom/issues/3693))
([7f2766c](https://github.com/headroomlabs-ai/headroom/commit/7f2766ca4beb9270ce35aa4f18aa01ef7ae3698a))
* **kompress:** keep the boolean connectives that hold a condition
together
([#3687](https://github.com/headroomlabs-ai/headroom/issues/3687))
([bf290ba](https://github.com/headroomlabs-ai/headroom/commit/bf290ba9a9de3a6af62fe3aa4bd8dacc8d9e2b92))
* **learn:** treat an unreadable project memory dir as absent instead of
crashing
([#3710](https://github.com/headroomlabs-ai/headroom/issues/3710))
([ff60d57](https://github.com/headroomlabs-ai/headroom/commit/ff60d5764c6499fe6453a475a6f26647fd87a508))
* **mcp:** accept an empty install ledger instead of failing mutations
as malformed
([#3235](https://github.com/headroomlabs-ai/headroom/issues/3235))
([19ddfe1](https://github.com/headroomlabs-ai/headroom/commit/19ddfe1a56ec7cbd48e595686f650e1d57469e4e))
* **memory/graph:** apply relation_type filter to both sides of a BOTH
subgraph query
([#3236](https://github.com/headroomlabs-ai/headroom/issues/3236))
([1a6f941](https://github.com/headroomlabs-ai/headroom/commit/1a6f941908038c696987a3f1a159f64e3145fae0))
* **memory:** fail closed for unresolved tools
([#3655](https://github.com/headroomlabs-ai/headroom/issues/3655))
([7c3cbc8](https://github.com/headroomlabs-ai/headroom/commit/7c3cbc824c1b584274450a90ea406072faa94f61))
* **memory:** make extract_system_prompt concatenative, not first-match
([#3644](https://github.com/headroomlabs-ai/headroom/issues/3644))
([3f3cf19](https://github.com/headroomlabs-ai/headroom/commit/3f3cf19e1a68313e949a3dd178aed2fafa050ed6))
* **memory:** tolerate None message content in inline memory parser
([#3211](https://github.com/headroomlabs-ai/headroom/issues/3211))
([5ccec67](https://github.com/headroomlabs-ai/headroom/commit/5ccec67f0c3abfe57d52308ccbe1f93cb772eba4))
* **metrics:** split rate-limited by source and label failures by
provider
([#3707](https://github.com/headroomlabs-ai/headroom/issues/3707))
([5ff4ea1](https://github.com/headroomlabs-ai/headroom/commit/5ff4ea1ef948563304c9e8f4b9ccff0e2ae3aedd))
* **openclaw:** declare transcriptSemantics and implement commitTurn
([#3442](https://github.com/headroomlabs-ai/headroom/issues/3442))
([a28dd4e](https://github.com/headroomlabs-ai/headroom/commit/a28dd4eab70a8fd6f72e3752e4cf1e363fca344c))
* **perf:** make budget checks constant-time
([#3368](https://github.com/headroomlabs-ai/headroom/issues/3368))
([ed08069](https://github.com/headroomlabs-ai/headroom/commit/ed08069ba00d5335d39c1726b95b218ef55be919))
* **perf:** make rate limiter bucket checks constant-time
([#3373](https://github.com/headroomlabs-ai/headroom/issues/3373))
([a8bd9be](https://github.com/headroomlabs-ai/headroom/commit/a8bd9becb300ea5fe774a27d89ee8d84033186da))
* preserve null and empty strings in lossless CSV compaction
([#3665](https://github.com/headroomlabs-ai/headroom/issues/3665))
([7ad9f80](https://github.com/headroomlabs-ai/headroom/commit/7ad9f809fa1b4191937dea1c2e1a974eee2eefe8))
* **proxy:** admit container host gateway on compress routes
([#3715](https://github.com/headroomlabs-ai/headroom/issues/3715))
([a8ae0a6](https://github.com/headroomlabs-ai/headroom/commit/a8ae0a6fd5d6274c0eb9fa63ba57f24de05c1080))
* **proxy:** bound request-log message payloads to the feed window; trim
glibc too
([#3717](https://github.com/headroomlabs-ai/headroom/issues/3717))
([994a89f](https://github.com/headroomlabs-ai/headroom/commit/994a89f169d436f369ca97824c5518287669803a))
* **proxy:** count a ceiling-stopped stream exactly instead of
estimating its text
([#3771](https://github.com/headroomlabs-ai/headroom/issues/3771))
([b36e59a](https://github.com/headroomlabs-ai/headroom/commit/b36e59a89370f2ffddcd0cfc4068956da1248626))
* **proxy:** discard partial SSE tails during finalization
([#3411](https://github.com/headroomlabs-ai/headroom/issues/3411))
([6c0e817](https://github.com/headroomlabs-ai/headroom/commit/6c0e817bcc0a83e23a7030c3df6d313280bcb30a))
* **proxy:** enforce configured TPM limits
([#3350](https://github.com/headroomlabs-ai/headroom/issues/3350))
([138736c](https://github.com/headroomlabs-ai/headroom/commit/138736c96f2421dbf40bf0698bc2ae8d9527a80e))
* **proxy:** fall back when forced Kompress is cold
([#3381](https://github.com/headroomlabs-ai/headroom/issues/3381))
([ca54c2a](https://github.com/headroomlabs-ai/headroom/commit/ca54c2aba1809f9b19acfc2ef9a9dd13276f4f19))
* **proxy:** make the output shaper actually reduce output in the
default mode
([#3773](https://github.com/headroomlabs-ai/headroom/issues/3773))
([c029298](https://github.com/headroomlabs-ai/headroom/commit/c02929846cafa4b9bc68c9d2ef47f41a10a6989d))
* **proxy:** partition response cache by upstream
([#3349](https://github.com/headroomlabs-ai/headroom/issues/3349))
([dfdc725](https://github.com/headroomlabs-ai/headroom/commit/dfdc72511ef4dd7c1ddb1e6acf1735f1ba10d2e3))
* **proxy:** pin the validated address so DNS rebinding cannot move an
upstream
([#3731](https://github.com/headroomlabs-ai/headroom/issues/3731))
([a102e05](https://github.com/headroomlabs-ai/headroom/commit/a102e05b511297ba979963a506318ca7459e63e0))
* **proxy:** preserve Claude Code auto-mode protocol
([#3784](https://github.com/headroomlabs-ai/headroom/issues/3784))
([12c1579](https://github.com/headroomlabs-ai/headroom/commit/12c157966f3ec378d66c764757d5d55dfb2a16d1))
* **proxy:** preserve empty transport error context
([#3675](https://github.com/headroomlabs-ai/headroom/issues/3675))
([ca02f28](https://github.com/headroomlabs-ai/headroom/commit/ca02f28c674473e94e3089eda970c046dd6a2426))
* **proxy:** preserve OpenCode Headroom retrieve results
([#3782](https://github.com/headroomlabs-ai/headroom/issues/3782))
([c7ebaed](https://github.com/headroomlabs-ai/headroom/commit/c7ebaedd74b2146f41e1b86e27b46334df477ea2))
* **proxy:** protect Codex exec reads whose argument is a JavaScript
object literal
([#3737](https://github.com/headroomlabs-ai/headroom/issues/3737))
([ecb5e5a](https://github.com/headroomlabs-ai/headroom/commit/ecb5e5afea15493d43aa89db67a4e9e90de6cab1))
* **proxy:** reject Anthropic batch operations on Copilot
([#3318](https://github.com/headroomlabs-ai/headroom/issues/3318))
([871bbde](https://github.com/headroomlabs-ai/headroom/commit/871bbde37ae2bf181917a281efcbc6e6a99fb1e3))
* **proxy:** repair client-side tool_search tool_reference blocks
([#3443](https://github.com/headroomlabs-ai/headroom/issues/3443))
([f12e3fb](https://github.com/headroomlabs-ai/headroom/commit/f12e3fbeed523d2f3f81fc83c8a08b46fdc9111b))
* **proxy:** resolve Codex custom_tool_call names for Responses tool
exclusion
([#3755](https://github.com/headroomlabs-ai/headroom/issues/3755))
([55c78de](https://github.com/headroomlabs-ai/headroom/commit/55c78deaa8171234e705b4315fdde5df0156cbdb))
* **proxy:** restrict urlopen SSL context ALPN to http/1.1
([#3567](https://github.com/headroomlabs-ai/headroom/issues/3567))
([5baa439](https://github.com/headroomlabs-ai/headroom/commit/5baa439ebf4aae37358f7f0a5707912d1007dbbc))
* **proxy:** scope OpenAI rate limits by api-key
([#3365](https://github.com/headroomlabs-ai/headroom/issues/3365))
([b9e8462](https://github.com/headroomlabs-ai/headroom/commit/b9e8462a3a84af7c92fa288fd53bd2e0d46b2dd2))
* **proxy:** stamp x-headroom-* compression metrics on streaming
responses
([#3769](https://github.com/headroomlabs-ai/headroom/issues/3769))
([2c4dc44](https://github.com/headroomlabs-ai/headroom/commit/2c4dc446279ddaf89930e54385a2a27fc3aa20e0))
* remove deprecated Apache license classifier
([#3566](https://github.com/headroomlabs-ai/headroom/issues/3566))
([b2d9275](https://github.com/headroomlabs-ai/headroom/commit/b2d927532895d37721d54039a8a9d02a909cf09a))
* **savings:** report negative savings instead of flooring them at zero
([#3744](https://github.com/headroomlabs-ai/headroom/issues/3744))
([1455f00](https://github.com/headroomlabs-ai/headroom/commit/1455f0022220f9c526e20f9898e4d56d951ec379))
* **sdk:** enforce dormant public type tests
([#3424](https://github.com/headroomlabs-ai/headroom/issues/3424))
([95cbbb8](https://github.com/headroomlabs-ai/headroom/commit/95cbbb8158292cbdf04eb873c9e62f25946f77a2))
* **sdk:** preserve Anthropic image blocks in message conversion instead
of dropping the turn
([#3439](https://github.com/headroomlabs-ai/headroom/issues/3439))
([63676e6](https://github.com/headroomlabs-ai/headroom/commit/63676e6cff020047687af9c526c69ff1e135931d))
* **sdk:** preserve proxy authentication alongside provider credentials
([#3450](https://github.com/headroomlabs-ai/headroom/issues/3450))
([ca4b47a](https://github.com/headroomlabs-ai/headroom/commit/ca4b47a3fc63584bcbc8792da9b099435b430c67))
* **security:** create credential files private instead of narrowing
after write
([#3215](https://github.com/headroomlabs-ai/headroom/issues/3215))
([9b8cae8](https://github.com/headroomlabs-ai/headroom/commit/9b8cae844808ec67d43006e6785daa4c246d5dfb))
* **security:** reject unauthenticated public proxy binds
([#3316](https://github.com/headroomlabs-ai/headroom/issues/3316))
([b0c19a2](https://github.com/headroomlabs-ai/headroom/commit/b0c19a25f0e2adfd23031d5f0a37d842618c3203))
* **smart-crusher:** disclose dropped scalar-array items with a
retrievable ccr sentinel
([#3692](https://github.com/headroomlabs-ai/headroom/issues/3692))
([c1fc84a](https://github.com/headroomlabs-ai/headroom/commit/c1fc84ade6c80486b63d5e8220c08d90cb8938e6))
* **spreadsheet:** stop .xls integer rendering fabricating digits above
2^53 ([#3704](https://github.com/headroomlabs-ai/headroom/issues/3704))
([e8a5109](https://github.com/headroomlabs-ai/headroom/commit/e8a510982a1e9164b6c2c48e92eeade90dc24fcf))
* **spreadsheet:** stop inventing digits for .xls cells above 2**53
([#3700](https://github.com/headroomlabs-ai/headroom/issues/3700))
([1a7c5bb](https://github.com/headroomlabs-ai/headroom/commit/1a7c5bbf52aefb4ce950f6b4c8e7feac0c62315e))
* **tests:** ask litellm for a model it prices instead of naming a
retired one
([#3722](https://github.com/headroomlabs-ai/headroom/issues/3722))
([0ad5e68](https://github.com/headroomlabs-ai/headroom/commit/0ad5e68ca559b3fc2c82a230a577b1b4bfc77792))
* **tool-search:** detect every wire shape of client-side deferral
([#3746](https://github.com/headroomlabs-ai/headroom/issues/3746))
([665b73d](https://github.com/headroomlabs-ai/headroom/commit/665b73df1b256c4eb0c41e44e29c93211e35f5d4))
* **tool-search:** don't orphan deferred tools, and stop overstating the
saving
([#3739](https://github.com/headroomlabs-ai/headroom/issues/3739))
([85f9e01](https://github.com/headroomlabs-ai/headroom/commit/85f9e01d71c712ef071d64a54e3e1c57eb330147))
* **tool-search:** make the core-tools override authoritative and the
warning recurrent
([#3745](https://github.com/headroomlabs-ai/headroom/issues/3745))
([a9757c9](https://github.com/headroomlabs-ai/headroom/commit/a9757c9c7e0e50635c5bc82d59a543cc45cde7b2))
* **transforms:** detect fixed-width command output as tabular and keep
it out of Kompress
([#3786](https://github.com/headroomlabs-ai/headroom/issues/3786))
([6c9aef1](https://github.com/headroomlabs-ai/headroom/commit/6c9aef1dec71e99fa2872737de9842ce9fea284d))
* **transforms:** stop embedded JSON pre-pass short-circuiting HTML
extraction
([#3620](https://github.com/headroomlabs-ai/headroom/issues/3620))
([195910b](https://github.com/headroomlabs-ai/headroom/commit/195910b218da26a053b22101df119f4cb2889813))
* **transforms:** stop routing timestamped log rows as grep matches
([#3748](https://github.com/headroomlabs-ai/headroom/issues/3748))
([d971f7c](https://github.com/headroomlabs-ai/headroom/commit/d971f7c3983b05653ef1eb88539bbbbc3667eb67))
* **wrap:** handle SIGHUP on the shared proxy paths, not just `claude`
([#3331](https://github.com/headroomlabs-ai/headroom/issues/3331))
([c4df2dd](https://github.com/headroomlabs-ai/headroom/commit/c4df2dde62d0c8d527323b4f6985d57469ae594e))
* **wrap:** stop blocking the launch on the Serena pre-index
([#3557](https://github.com/headroomlabs-ai/headroom/issues/3557))
([df8ebdf](https://github.com/headroomlabs-ai/headroom/commit/df8ebdf97da68496ab514f321583a393b74243ea))


### Performance Improvements

* **cache:** drop eager full-backend TTL sweep on every new-key store()
([#3256](https://github.com/headroomlabs-ai/headroom/issues/3256))
([2fed685](https://github.com/headroomlabs-ai/headroom/commit/2fed685e77734efe234cc12da363d185d7922378))
* **cache:** LRU-bound the compression-feedback tool-pattern map
([#3342](https://github.com/headroomlabs-ai/headroom/issues/3342))
([2d10b10](https://github.com/headroomlabs-ai/headroom/commit/2d10b10ae47aa10682d94d7145b7b6204c2a9f70))
* **memory:** reindex FTS5 a page at a time instead of a record at a
time ([#3466](https://github.com/headroomlabs-ai/headroom/issues/3466))
([3e36aef](https://github.com/headroomlabs-ai/headroom/commit/3e36aefb432e69e7ce065c1efe7600f85909e7fc))
* **providers:** cache Google/Cohere token counters across requests
([#3273](https://github.com/headroomlabs-ai/headroom/issues/3273))
([cc6a07c](https://github.com/headroomlabs-ai/headroom/commit/cc6a07cd651abbd7552814414e90096e0c1bcdde))
* **relevance:** order BM25 query terms once, not once per document
([#3468](https://github.com/headroomlabs-ai/headroom/issues/3468))
([6880984](https://github.com/headroomlabs-ai/headroom/commit/6880984b4a96d29fd655354e7633b797c9f511b6))


### Dependencies

* bump dotenv from 17.4.2 to 18.0.1 in /sdk/typescript
([#3765](https://github.com/headroomlabs-ai/headroom/issues/3765))
([56edfbc](https://github.com/headroomlabs-ai/headroom/commit/56edfbc9312b3e16a505c5d82e9ce7d75ffb8a76))
* bump ruff from 0.16.7 to 0.16.8 in the pip-minor-patch group
([#3761](https://github.com/headroomlabs-ai/headroom/issues/3761))
([b9ded1a](https://github.com/headroomlabs-ai/headroom/commit/b9ded1ae5587751cfd10dd2254d73f7205ca58a2))
* bump the cargo-minor-patch group with 3 updates
([#3762](https://github.com/headroomlabs-ai/headroom/issues/3762))
([fbbe8b8](https://github.com/headroomlabs-ai/headroom/commit/fbbe8b8e99635fd9805b7ef7946fa00d615ab0a9))
* bump the npm-minor-patch group across 2 directories with 19 updates
([#3763](https://github.com/headroomlabs-ai/headroom/issues/3763))
([54357ff](https://github.com/headroomlabs-ai/headroom/commit/54357ff660a413dafa01594c54362de6e11ebb9f))
* bump the npm-minor-patch group across 3 directories with 9 updates
([#3764](https://github.com/headroomlabs-ai/headroom/issues/3764))
([6311332](https://github.com/headroomlabs-ai/headroom/commit/63113329cfe96dde5087fe0a2837eb543ed1391b))


### Code Refactoring

* **sdk:** route _fetch through rawFetch instead of duplicating it
([#3473](https://github.com/headroomlabs-ai/headroom/issues/3473))
([b2b5847](https://github.com/headroomlabs-ai/headroom/commit/b2b58474c4a3b43bbcc81cc833c0a8f28dadaa21))
* **smart-crusher:** drop the dead crush_object clone from the object
path ([#3705](https://github.com/headroomlabs-ai/headroom/issues/3705))
([7221724](https://github.com/headroomlabs-ai/headroom/commit/72217242c1cc52e3ed09780b53440abe9ca22478))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-09-25 14:29:40 -05:00
dependabot[bot]andJerrettDavis b9ded1ae55 deps: bump ruff from 0.16.7 to 0.16.8 in the pip-minor-patch group (#3761)
Bumps the pip-minor-patch group with 1 update:
[ruff](https://github.com/astral-sh/ruff).

Updates `ruff` from 0.16.7 to 0.16.8
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/ruff/releases">ruff's
releases</a>.</em></p>
<blockquote>
<h2>0.16.8</h2>
<h2>Release Notes</h2>
<p>Released on 2026-09-16.</p>
<h3>Bug fixes</h3>
<ul>
<li>Visit functional <code>TypedDict</code> keyword arguments correctly
(<a
href="https://redirect.github.com/astral-sh/ruff/pull/28584">#28584</a>)</li>
<li>[<code>flake8-simplify</code>] Detect nested <code>async with</code>
under sync parent (<code>SIM117</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27821">#27821</a>)</li>
<li>[<code>flake8-simplify</code>] Preserve operand order in
<code>SIM109</code> fix (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27824">#27824</a>)</li>
<li>[<code>pyupgrade</code>] Preserve required parentheses in multiline
<code>UP040</code> fixes (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28164">#28164</a>)</li>
<li>[<code>pyupgrade</code>] Skip <code>TypeVarTuple</code> and
<code>ParamSpec</code> conversions with bounds or constraints
(<code>UP040</code>, <code>UP046</code>, <code>UP047</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28505">#28505</a>)</li>
</ul>
<h3>Rule changes</h3>
<ul>
<li>Add support for <code>__lazy_modules__</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28459">#28459</a>)</li>
<li>Recognize PEP-728 <code>TypedDict</code> class keywords (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28533">#28533</a>)</li>
<li>Recognize quoted types in <code>typing.TypeForm</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28507">#28507</a>)</li>
<li>Support conditional assignment to <code>__lazy_modules__</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28491">#28491</a>)</li>
<li>[<code>flake8-type-checking</code>] Prefer lazy imports over
<code>TYPE_CHECKING</code> on Python 3.15 and later (<code>TC001</code>,
<code>TC002</code>, <code>TC003</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28541">#28541</a>)</li>
<li>[<code>pyupgrade</code>] Make the fix for <code>UP040</code> always
unsafe (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28526">#28526</a>)</li>
<li>[<code>pyupgrade</code>] Stop recommending deprecated
<code>ByteString</code> aliases (<code>UP035</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28498">#28498</a>)</li>
<li>[<code>ruff</code>, <code>flake8-use-pathlib</code>] Recognize the
<code>parent_mode</code> argument (<code>RUF064</code>,
<code>PTH103</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28528">#28528</a>)</li>
<li>[<code>ruff</code>] Detect <code>\Z</code> in
<code>pytest.raises()</code> match patterns (<code>RUF043</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28598">#28598</a>)</li>
</ul>
<h3>CLI</h3>
<ul>
<li>Use rule name and code in formatter incompatibility warnings (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28571">#28571</a>)</li>
</ul>
<h3>Configuration</h3>
<ul>
<li>[<code>flake8-tidy-imports</code>] Add
<code>extend-banned-api</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28644">#28644</a>)</li>
</ul>
<h3>Contributors</h3>
<ul>
<li><a
href="https://github.com/VedantMadane"><code>@​VedantMadane</code></a></li>
<li><a href="https://github.com/alzeph"><code>@​alzeph</code></a></li>
<li><a
href="https://github.com/charliermarsh"><code>@​charliermarsh</code></a></li>
<li><a
href="https://github.com/fredrikblau"><code>@​fredrikblau</code></a></li>
<li><a href="https://github.com/ntBre"><code>@​ntBre</code></a></li>
<li><a href="https://github.com/zsol"><code>@​zsol</code></a></li>
<li><a
href="https://github.com/Aniket-a14"><code>@​Aniket-a14</code></a></li>
<li><a href="https://github.com/r-b-1"><code>@​r-b-1</code></a></li>
</ul>
<h2>Install ruff 0.16.8</h2>
<h3>Install prebuilt binaries via shell script</h3>
<pre lang="sh"><code>curl --proto '=https' --tlsv1.2 -LsSf
https://releases.astral.sh/github/ruff/releases/download/0.16.8/ruff-installer.sh
| sh
&lt;/tr&gt;&lt;/table&gt; 
</code></pre>
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md">ruff's
changelog</a>.</em></p>
<blockquote>
<h2>0.16.8</h2>
<p>Released on 2026-09-16.</p>
<h3>Bug fixes</h3>
<ul>
<li>Visit functional <code>TypedDict</code> keyword arguments correctly
(<a
href="https://redirect.github.com/astral-sh/ruff/pull/28584">#28584</a>)</li>
<li>[<code>flake8-simplify</code>] Detect nested <code>async with</code>
under sync parent (<code>SIM117</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27821">#27821</a>)</li>
<li>[<code>flake8-simplify</code>] Preserve operand order in
<code>SIM109</code> fix (<a
href="https://redirect.github.com/astral-sh/ruff/pull/27824">#27824</a>)</li>
<li>[<code>pyupgrade</code>] Preserve required parentheses in multiline
<code>UP040</code> fixes (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28164">#28164</a>)</li>
<li>[<code>pyupgrade</code>] Skip <code>TypeVarTuple</code> and
<code>ParamSpec</code> conversions with bounds or constraints
(<code>UP040</code>, <code>UP046</code>, <code>UP047</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28505">#28505</a>)</li>
</ul>
<h3>Rule changes</h3>
<ul>
<li>Add support for <code>__lazy_modules__</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28459">#28459</a>)</li>
<li>Recognize PEP-728 <code>TypedDict</code> class keywords (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28533">#28533</a>)</li>
<li>Recognize quoted types in <code>typing.TypeForm</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28507">#28507</a>)</li>
<li>Support conditional assignment to <code>__lazy_modules__</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28491">#28491</a>)</li>
<li>[<code>flake8-type-checking</code>] Prefer lazy imports over
<code>TYPE_CHECKING</code> on Python 3.15 and later (<code>TC001</code>,
<code>TC002</code>, <code>TC003</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28541">#28541</a>)</li>
<li>[<code>pyupgrade</code>] Make the fix for <code>UP040</code> always
unsafe (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28526">#28526</a>)</li>
<li>[<code>pyupgrade</code>] Stop recommending deprecated
<code>ByteString</code> aliases (<code>UP035</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28498">#28498</a>)</li>
<li>[<code>ruff</code>, <code>flake8-use-pathlib</code>] Recognize the
<code>parent_mode</code> argument (<code>RUF064</code>,
<code>PTH103</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28528">#28528</a>)</li>
<li>[<code>ruff</code>] Detect <code>\Z</code> in
<code>pytest.raises()</code> match patterns (<code>RUF043</code>) (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28598">#28598</a>)</li>
</ul>
<h3>CLI</h3>
<ul>
<li>Use rule name and code in formatter incompatibility warnings (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28571">#28571</a>)</li>
</ul>
<h3>Configuration</h3>
<ul>
<li>[<code>flake8-tidy-imports</code>] Add
<code>extend-banned-api</code> (<a
href="https://redirect.github.com/astral-sh/ruff/pull/28644">#28644</a>)</li>
</ul>
<h3>Contributors</h3>
<ul>
<li><a
href="https://github.com/VedantMadane"><code>@​VedantMadane</code></a></li>
<li><a href="https://github.com/alzeph"><code>@​alzeph</code></a></li>
<li><a
href="https://github.com/charliermarsh"><code>@​charliermarsh</code></a></li>
<li><a
href="https://github.com/fredrikblau"><code>@​fredrikblau</code></a></li>
<li><a href="https://github.com/ntBre"><code>@​ntBre</code></a></li>
<li><a href="https://github.com/zsol"><code>@​zsol</code></a></li>
<li><a
href="https://github.com/Aniket-a14"><code>@​Aniket-a14</code></a></li>
<li><a href="https://github.com/r-b-1"><code>@​r-b-1</code></a></li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/astral-sh/ruff/commit/62914c4b9b79a9e5004374a9c482ad2ed69290e1"><code>62914c4</code></a>
Bump version to 0.16.8 (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28648">#28648</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/c47e0cdc665f56536ce7f7a8ac40fa0ff3f79482"><code>c47e0cd</code></a>
[ty] Bound aliased intersection expansion during inference (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28546">#28546</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/ff4747b509ab4fffbe5689fcae39caa7503d1dcf"><code>ff4747b</code></a>
renovate: update uv hashes correctly with setup-uv (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28621">#28621</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/94efeaa28630d80b2a74adf3c3963de99ed4ee29"><code>94efeaa</code></a>
[ty] Compact reachable binding and declaration histories (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28349">#28349</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/50020fb1e8aa83b0826fa6f5f33a1e93c10cc60e"><code>50020fb</code></a>
[ty] Avoid storing constraint nodes twice (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28375">#28375</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/446bb68da50014bb75f5ce1504a80c5883e3b0b2"><code>446bb68</code></a>
[ty] Compare bound-method receivers before signatures (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28384">#28384</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/304ab86be5de6507e276ab09f5b43f44aeb92469"><code>304ab86</code></a>
[<code>flake8-type-checking</code>] Prefer lazy imports over
<code>TYPE_CHECKING</code> on 3.15+ (`...</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/d940b244f7512427b0d87c7953e88c60e69f9bdf"><code>d940b24</code></a>
[ty] Watch script dependencies in CLI watch mode (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28125">#28125</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/fe9f065a504127b11da72c2ff6d7813ddf3ce8ac"><code>fe9f065</code></a>
[flake8-tidy-imports] Add <code>extend-banned-api</code> (<a
href="https://redirect.github.com/astral-sh/ruff/issues/28644">#28644</a>)</li>
<li><a
href="https://github.com/astral-sh/ruff/commit/31131db44f057cce68fa6b95552b7db54167b0b3"><code>31131db</code></a>
[ty] Support <code>type[A &amp; B]</code> (<a
href="https://redirect.github.com/astral-sh/ruff/issues/27124">#27124</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/astral-sh/ruff/compare/0.16.7...0.16.8">compare
view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=ruff&package-manager=pip&previous-version=0.16.7&new-version=0.16.8)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions


</details>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-09-24 22:00:44 -05:00
Tejas ChopraandClaude Opus 5 a102e05b51 fix(proxy): pin the validated address so DNS rebinding cannot move an upstream (#3731)
Security-remediation item **A-4** (P-2). The agent that wrote this was
killed mid-run by a machine sleep, so I reviewed the diff, re-ran the
evidence and opened this myself.

## The defect

`upstream_guard.is_safe_upstream_url` resolves a caller-supplied
hostname, checks every returned address is global, and then hands the
**hostname** to httpx — which resolves it *again* when it opens the
socket. Two resolutions are two chances to answer, and an attacker who
controls the name's authoritative DNS takes both: a public address for
the check, `169.254.169.254` or an RFC1918 host for the connection.

The verdict was never wrong. It just never reached the socket.

## The fix

Two halves:

- **`upstream_guard.py`** now records the addresses each accepted
destination was *judged on* (60 s TTL, bounded at 512 entries,
LRU-evicted).
- **`upstream_pinning.py`** (new) wraps the httpcore connection pool's
network backend and substitutes a validated address for the hostname at
`connect_tcp` time — **and only there**.

Substituting at the socket rather than rewriting the URL to an IP
literal is the whole design, because the URL still carries the hostname:

- httpx still sends `Host: <hostname>`, so gateways and multi-tenant
providers still route correctly;
- httpcore still passes the hostname as `server_hostname` to
`start_tls`, so **SNI and certificate hostname verification are
untouched**;
- two hostnames sharing an address do not collapse into one pooled
origin, so a connection whose certificate was checked for one host can
never serve the other.

All addresses from the accepted answer are pinned, in resolver order, so
an AAAA record on a host with no IPv6 route still falls back the way the
OS resolver would have — at no cost in safety, since every address in
the set passed the same check.

## Scope — why this cannot regress other harnesses

The guard only ever sees **client-supplied** upstreams
(`x-headroom-base-url`). Every configured provider upstream — Anthropic,
OpenAI, Gemini, Bedrock, Copilot, LiteLLM, a Kong gateway — is
operator-configured, never passes through the guard, has no pin, and
resolves exactly as before. Redirects and retries re-enter the same
path. With an HTTP/SOCKS proxy configured the pool dials the *proxy's*
host, which is never pinned, so proxied deployments are unchanged.

Allowlist mode pins nothing on purpose: it admits a host by name without
resolving it, precisely so split-horizon and on-prem endpoints keep
working.

`install_upstream_pinning` raises if httpx/httpcore stops exposing the
pool it hooks. That is fail-closed by design — the alternative is a
proxy that starts happily with the hole quietly reopened. Versions are
locked in `uv.lock`, so it can only fire on a deliberate dependency
bump, which is exactly when someone should look.

## Verification

Scoped to the pinning tests, reverting the source and keeping the tests:

```
BEFORE:  6 failed, 1 passed
AFTER:   7 passed
```

The one test passing in both is
`test_pinning_does_not_disable_certificate_hostname_verification` — cert
verification was already on, and the test exists to prove this change
does not weaken it.

Full file: **45 passed**. The tests include a stub resolver that returns
a different address on successive calls and asserts the connection
targets the validated one, plus coverage of pin expiry, store bounding,
and the allowlist-pins-nothing rule.

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-24 17:14:56 -05:00
Waqas Ahmed b2d9275328 fix: remove deprecated Apache license classifier (#3566)
## Description

`pyproject.toml` already declares the modern SPDX license expression
(`license = "Apache-2.0"`), but the `classifiers` list still carried the
legacy trove classifier `License :: OSI Approved :: Apache Software
License`. Per PEP 639, that classifier is deprecated once a license
expression is declared, and shipping both is exactly what #3508 reports
after inspecting the built wheel's METADATA.

Closes #3508

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Removed the single deprecated `License :: OSI Approved :: Apache
Software License` line from `classifiers` in `pyproject.toml`. Nothing
else changed.

## Testing

- [x] Manual testing performed (no unit test needed -- one-line metadata
removal, verified by building the package and inspecting its metadata)

### Test Output

```text
$ uv build --sdist
Built dist/headroom_ai-0.37.0.tar.gz

$ tar xzOf dist/headroom_ai-0.37.0.tar.gz --wildcards "*/PKG-INFO" | grep -i "license\|classifier"
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
...
License-File: LICENSE
License-File: NOTICE
License-Expression: Apache-2.0
```

The deprecated `License :: OSI Approved :: Apache Software License`
classifier is gone; `License-Expression: Apache-2.0` is present and
unaffected.

## Real Behavior Proof

- Environment: this repo's `main`, `uv build --sdist`.
- Exact command / steps: shown above.
- Observed result: metadata is now PEP 639-compliant -- no deprecated
classifier, license expression intact.
- Not tested: wheel build (requires the Rust toolchain, not available in
this sandbox); sdist metadata is generated from the same
`pyproject.toml` fields and was verified directly.

## Runtime Rollout Safety

- N/A -- build metadata only, no runtime behavior change.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] My changes generate no new warnings
- [x] I did **not** edit `CHANGELOG.md`
2026-09-23 20:55:21 -05:00
JD Davis 94206e2652 chore: release 0.38.0
Release Headroom 0.38.0.
2026-09-21 18:47:42 -05:00
LukasandJD Davis 261796f9be fix(spreadsheet): render an .xls cell the way the .xlsx loader renders it (#3616)
## Description

`_load_xls` reads a legacy workbook with `sheet.row_values(i)`, which
hands back xlrd's **raw storage** rather than the value. The `.xlsx`
loader goes through openpyxl and hands back the value. So the two
loaders disagree about the same workbook.

Measured on `main` (35b1156), the same three cells written to both
formats:

| cell | `.xls` today | `.xlsx` |
|---|---|---|
| `2024-01-01` | `45292.0` | `2024-01-01 00:00:00` |
| `TRUE` | `1` | `True` |
| `12` | `12.0` | `12` |

The date is the one that matters: a serial number is not recoverable
from the compressed text, so whatever reads the table downstream sees
`45292.0` and has no way to know it was a date. The boolean and the
whole number are the same class of drift — `1` and `12.0` are not what
the sheet says.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/transforms/spreadsheet_ingest.py`: new `_xls_cell(cell,
datemode)` converts each cell by its xlrd type, matching what openpyxl
already delivers — `XL_CELL_DATE` → `datetime` via `xldate_as_tuple`
with the workbook's `datemode` (the 1900/1904 epoch matters and only the
book knows which it is); `XL_CELL_BOOLEAN` → `bool`; a whole
`XL_CELL_NUMBER` → `int`, since xlrd stores every number as a double;
`XL_CELL_ERROR` → the text Excel shows (`#DIV/0!`), which is what
openpyxl with `data_only=True` gives.
- A cell whose `xldate_as_tuple` has no date part — a time such as
`12:00` is `(0, 0, 0, 12, 0, 0)` — becomes a `datetime.time`, again
matching openpyxl. Building a `datetime` from it raises `ValueError:
year 0 is out of range`.
- A float that is not whole, a string, and an empty cell are untouched:
`1.5` stays `1.5`, and a blank still renders as an empty field through
`_rows_to_csv`.
- `sheet.row_values(i)` becomes `sheet.row(i)`, because the conversion
needs the cell type that `row_values` throws away.
- The `# pragma: no cover - legacy .xls; needs optional xlrd + binary
fixture` comes off `_load_xls`: it is covered now.
- `pyproject.toml`: `xlrd>=2.0.1` (the `spreadsheet` floor) and
`xlwt>=1.3.0` join the dev extra beside `openpyxl`, with the same style
of comment. The CI test job installs only `[dev]`, and every new test
`importorskip`s both: `xlwt` is the only way to write a legacy `.xls`
fixture, and `xlrd` is what `_load_xls` reads it with. `uv.lock` is
regenerated to match (13 added lines, nothing else moves).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

Three cases in `tests/test_transforms_tabular.py`, each building a real
`.xls` with `xlwt`:

- the row renders as `2024-01-01 00:00:00,True,12,1.5,ok` — it was
`45292.0,1,12.0,1.5,ok`;
- `load_spreadsheet` of the `.xls` and of the equivalent `.xlsx` return
**equal** dictionaries, which is the property the first test is really
about;
- a time-only cell renders as `12:00:00` in both formats, where it
rendered as `0.5` (and raised with only the first commit applied).

`mypy` is unchecked because it was not run locally; CI's lint job runs
it.

### Test Output

```text
$ ruff check headroom/transforms/spreadsheet_ingest.py tests/test_transforms_tabular.py
All checks passed!

$ ruff format --check headroom/transforms/spreadsheet_ingest.py tests/test_transforms_tabular.py
2 files already formatted

$ python -m pytest tests/test_transforms_tabular.py -rs
43 passed in 4.03s
```

Before `xlrd` joined the dev extra, the same command in the CI test
environment gave 40 passed, 3 skipped (`could not import 'xlrd'`).

## Real Behavior Proof

- Environment: macOS 26.6 (arm64), CPython 3.12.11, `xlrd 2.0.2`,
`openpyxl`, `xlwt 1.3.0`; the wheel built with `maturin build --profile
ci` (Rust 1.98.1) and installed as `"${WHEEL}[dev]"`, as the CI test job
does.
- Exact command / steps: build a one-cell `.xls` with `xlwt` and the
equivalent `.xlsx` with `openpyxl`, then call
`headroom.transforms.spreadsheet_ingest.load_spreadsheet` on each. That
module imports cleanly on its own; only the test file's other imports
pull in `headroom._core`.
- Observed result: on `main` the `.xls` row reads
`45292.0,1,12.0,1.5,ok` and a time-only cell reads `0.5`; with this PR
both match the `.xlsx` output:

```text
# before (main)
xls  -> ['Starts', '0.5']                           # the time-only cell
xls  -> ['When,Active,Units,Rate,Text',
         '45292.0,1,12.0,1.5,ok']                   # the value cells

# after
xls  -> ['Starts', '12:00:00']
xlsx -> ['Starts', '12:00:00']
xls  -> ['When,Active,Units,Rate,Text',
         '2024-01-01 00:00:00,True,12,1.5,ok']
```

- Not tested: `mypy headroom` locally (CI's lint job runs `mypy headroom
--ignore-missing-imports`; green at 466683c). Note on CI: its test job
installs only `"${WHEEL}[dev]"`, and `xlrd` was only in the
`spreadsheet` extra, so the three new cases were skipped there (shard 4:
`s`/`ss`) until `xlrd` joined `dev` in this PR.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. `spreadsheet_ingest` is not behind a
rollout channel.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: yes, for `.xls` input only — a date,
a boolean, a whole number and an error cell now render as their value
instead of as xlrd's storage, which is what the `.xlsx` path has always
done. `.xlsx`, `.csv` and every other input are byte-identical.
- Kill switch / disable path: none needed; revert the commit.
- Unsafe override required: no.
- Qualification impact: any golden output that pinned `45292.0`, `1` or
`12.0` for a `.xls` would change. There is none in the repo —
`_load_xls` was `# pragma: no cover` before this PR.
- Rollback path: `git revert`; the change is confined to `_xls_cell` /
`_load_xls`, two dev-extra lines and their `uv.lock` entries.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation (no
documented behaviour changes: the `.xls` path now matches the `.xlsx`
path the docs already describe)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes (full
suite locally: 12550 passed, 599 skipped, 1 failed; the failure,
`tests/test_cli/test_mcp_reconcile.py::test_ordinary_install_does_not_adopt_serena`,
needs the venv's `bin` on `PATH` and passes with it)
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

The time-only case was found after the first commit: `xldate_as_tuple`
returns `(0, 0, 0, 12, 0, 0)` for `0.5`, and `datetime(0, 0, 0, 12, 0,
0)` raises, so the whole workbook failed to load. Commit 466683c fixes
it and adds the third test.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-09-21 10:06:01 -07:00