Commit Graph
106 Commits
Author SHA1 Message Date
JD DavisandJerrett Davis b235bc2d27 fix(ci): verify installer provenance in build workflows (#4677)
## Current maintainer status (2026-11-10, current-main refresh)

Published head: `db4bdd71e7ddc1a72316445ef0d16a7d90b62951`, containing
upstream main `a385ea8e60a14c1511d82b21d518421af35deab2` through a clean
mechanical merge. All 13 remediation files are byte-identical to
reviewed head `81ff3ed384afbd404c48fd79d6bed41e8d647a99`; no installer,
action metadata, or checksum selection changed.

Fresh focused Windows checks: 61 passed and 23 platform skips. Fresh WSL
offline bootstrap/hook fixtures: 23 passed, with one pytest
configuration warning. These local checks use fixtures and do not claim
live vendor, provider, or native GUI execution.

Exact-head CI, including Docker-native, and the Init, Wrap, Rust,
governance, changelog, and merge-conflict workflows succeeded. Security
remains FAILURE: the OpenCode npm audit reports two moderate findings
through Effect advisory GHSA-chp3-j5qr-2vfr. The security workflow and
affected OpenCode package manifest/lock are byte-identical to current
main, establishing an inherited dependency finding. This is not an
all-green result or a fresh audit of main. No workflow rerun, dependency
downgrade, or advisory override was performed on this branch.

Independent human review and integration remain required. No
self-approval or merge was performed. Other branch publication and
execution holds remain active. All older qualification below belongs to
its recorded historical heads.

---



## Description

Build validation jobs fetched mutable installer scripts, and the pinned
commitlint action still declared a mutable Docker image tag. This pins
that image digest, verifies workflow-tool archives and cached binaries,
and replaces the Docker bootstrap scripts with pinned, verified sources.


## Type of Change

- [x] Bug fix



## Changes Made

- Preserve Rust 1.95.0, minimal/rustfmt/clippy options, Node 24, npm
12.2.1, and OpenCode 1.17.8.
- Preserve Debian userland architecture detection, Rustup ARM fallback,
and OpenCode x64 AVX2/baseline selection.
- Use an official Node image pinned by manifest digest; retain
npm/corepack trees and explicit runtime libraries.
- Add offline bootstrap tests for failed downloads, corrupt bytes,
unsupported targets, symlinks, and option forwarding.


## Testing

- [x] Offline bootstrap tests pass (stdlib unittest, 16 cases).

- [x] Ruff lint/format pass for the two new test files; shell syntax and
whitespace checks pass.
- [x] Exact-head hosted CI passed, including platform tests and
Docker-native, Init, and Wrap build/container checks.


### Test Output

```text

python3 -m unittest discover -s tests/test_install -p 'test_*bootstrap.py'

................

Ran 16 tests in 0.770s

OK

```



## Real Behavior Proof

- Environment: Ubuntu 24.04 under WSL, exact candidate
4ee38e8619.
- Exact command / steps: Run the unittest discovery command above.
Separately stream the recorded release archives and official Node image
layer through SHA-256 and inspect their tar headers.
- Observed result: Invalid bytes stop before extraction/execution;
fixture platform and CPU cases select the intended archives. Actual
workflow-tool/OpenCode archives and the Node layer match published
digests. The Rustup x64 binary matches its vendor checksum; all nine
embedded target checksums match vendor records.
- Not tested: No live model/provider behavior or unexercised
architecture is claimed. Local bootstrap fixtures use mocks; the hosted
Docker/build checks below exercised the actual pinned installation
paths.


## Runtime Rollout Safety

- Rollout-managed feature(s): None; CI/build bootstrap only.

- Minimum rollout channel: Not applicable.

- Stable/default behavior changed: Build inputs become pinned; proxy
defaults, Rust 1.95.0/components, npm 12.2.1 and OpenCode 1.17.8 stay
unchanged. Node remains on the 24 LTS line with a fixed image digest.
- Kill switch / disable path: Revert the maintenance change through
review; do not bypass checksum failures.
- Unsafe override required: None for this exact reviewed candidate.

- Qualification impact: The exact-head hosted checks below passed.
Existing PR heads retain their separate security/qualification holds
until main is remediated and their own gates are refreshed.
- Rollback path: Revert this maintenance PR if build compatibility
regresses.


## Review Readiness

- [x] I performed a self-review.

- [x] This PR is ready for human review.



## Checklist

- [x] New security regression tests are included.

- [x] CHANGELOG.md is unchanged.



## Additional Notes

Static independent code review found no defects. No merge or
self-approval is requested. Completed historical CI evidence is retained
within its original scope; this change qualifies future installer
execution separately.


Initial hosted validation of b2592de8d stopped at rustup filename
dispatch. Follow-up 4ee38e861 retains the required rustup-init basename
in a private directory and adds the reproducing regression test. All
nine latest applicable hosted workflows passed on the corrected head.


### Hosted validation on 4ee38e861

- [CI: platform tests and Docker-native
build/install/compose/wrap/init](https://github.com/headroomlabs-ai/headroom/actions/runs/42352878789):
success.
- [Wrap
E2E](https://github.com/headroomlabs-ai/headroom/actions/runs/42352878762),
[Init
E2E](https://github.com/headroomlabs-ai/headroom/actions/runs/42352878760),
[Init Native
E2E](https://github.com/headroomlabs-ai/headroom/actions/runs/42352878767),
and
[Security](https://github.com/headroomlabs-ai/headroom/actions/runs/42352878768):
success.
- Governance, changelog, Rust and merge-conflict checks also passed. The
older cancelled governance duplicate was superseded by a successful run.


Independent human review is required. No self-approval or merge has been
performed.




### Local-action metadata coverage follow-up



`38337d8be` adds `.github/actions/**` to both code and workflow filters.
The normal pytest suite now checks the vendored commitlint metadata
structure and immutable Docker digest; this is separate from actionlint
workflow parsing. Six focused CI regression tests pass, including a
filter regression that failed before the fix. Independent delta review
found no issues. `38337d8be` now has successful latest applicable CI,
Wrap E2E, Init E2E, Init Native E2E, Security, Rust, Changelog Guard,
Merge Conflicts, and PR Governance runs. The successful runs above
remain historical evidence for `4ee38e861`.




Current-head
[CI](https://github.com/headroomlabs-ai/headroom/actions/runs/42360858297),
[Wrap](https://github.com/headroomlabs-ai/headroom/actions/runs/42360858271),
[Init](https://github.com/headroomlabs-ai/headroom/actions/runs/42360858296),
[Init
Native](https://github.com/headroomlabs-ai/headroom/actions/runs/42360858178),
and
[Security](https://github.com/headroomlabs-ai/headroom/actions/runs/42360858352)
passed. Independent human review remains required; no self-approval or
merge.


<!-- maintainer-current-main-qualification -->

## Current-main qualification



Published head `9381378ffb07e466acef6a57eb39322aa84d4582` includes
upstream main `bb8d18a56abb07ca7e811235c86ea6b626eb1f8b` and is
mergeable. All nine exact-head workflows succeeded; all 53 jobs are
terminal success or explicit skips, including CI Docker-native,
wrap/init and native-init validation. Local metadata/release checks: 61
passed; 16 Linux-only bootstrap tests skipped on Windows. Remediation
installer/action sources are unchanged by the clean main integration.


Independent human review and merge are required. No self-approval or
merge performed. This PR does not lift the inherited
execution-provenance hold on main or other branches before human
integration.
<!-- /maintainer-current-main-qualification -->



### Maintainer current-main refresh (a2bcbd101)

Published `a20f072a238a1f8de422adf6a25d3f9d664151e4` incorporates
upstream main `a2bcbd101b1391debfd218ec8c63cb72d2bc240a` through a clean
merge. All 13 previously screened CI provenance remediation files are
byte-identical to prior published head
`9381378ffb07e466acef6a57eb39322aa84d4582`; no
installer/action/remediation logic was rewritten. Fresh focused checks:
61 passed, 23 platform-specific shell cases skipped on Windows. No
vendor installer, Docker image or downloaded binary was executed
locally. Earlier Linux bootstrap and hosted evidence retain their
original scope.

Fresh exact-head hosted validation completed successfully: all 10
observed workflow runs succeeded; all 56 checks are terminal successful
or explicitly skipped. Ready for independent human review on this
head/current main. This remediation branch alone is permitted to run its
screened checks; inherited execution/publication holds on main and other
PRs remain until independent human integration. Independent review is
required; no self-approval, merge or release publication.

---------

Co-authored-by: Jerrett Davis <JerrettDavis@users.noreply.github.com>
2026-11-10 21:02:42 -06:00
Kenneth WongandKenneth Wong cbcf8d8d9b fix(scripts): skip ci-precheck in the pre-push hook when a push only deletes refs (#4702)
## Description

The pre-push hook that `make install-git-hooks` writes runs the full
`make ci-precheck` (cargo fmt, clippy and the workspace tests, plus the
Python suite) even when a push only deletes branches. Its loop over the
refs on stdin skips deleted refs with `continue`, but the precheck runs
after the loop regardless, so `git push origin --delete <branch>` waits
several minutes for checks on code it doesn't send.

This PR tracks whether any ref in the push is an update, and exits 0
when none is.

No tracking 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

- `scripts/install-git-hooks.sh` (the generated pre-push hook): set
`has_update=1` for every non-delete ref and `exit 0` after the loop when
no ref was an update. A push that mixes a delete with an update still
runs the precheck.
- The delete check now matches an all-zero sha of any length (`^0+$`),
so SHA-256 repositories (64-zero null id) are also recognised. The old
check compared against exactly 40 zeros.
- Removed the hook comment about gating only "main tracking branches";
the hook has no such pattern.
- `tests/test_install_git_hooks_script.py`: three end-to-end tests that
install the hooks into a temp repo and push to a bare remote with `make`
stubbed to log its calls. A branch update runs `make ci-precheck`; a
delete-only push does not (and the remote branch is gone); a push that
mixes a delete and an update runs it once.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`) (not run: no `headroom/`
code changed; the pre-commit mypy hook passed on the changed test file)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q tests/test_install_git_hooks_script.py            # this branch
.......                                                         [100%]
7 passed in 3.97s

$ pytest -q tests/test_install_git_hooks_script.py            # same tests, origin/main's script
E   AssertionError: assert ['ci-precheck'] == []
FAILED tests/test_install_git_hooks_script.py::test_pre_push_skips_ci_precheck_for_a_delete_only_push
1 failed, 6 passed in 3.40s

$ ruff check tests/test_install_git_hooks_script.py
All checks passed!
$ ruff format --check tests/test_install_git_hooks_script.py
1 file already formatted
$ shellcheck -s bash scripts/install-git-hooks.sh
(no output)
$ npx commitlint --from origin/main --to HEAD
(exit 0)
```

pre-commit (ruff, ruff format, mypy, commitlint) passed on the commit.

## Real Behavior Proof

- Environment: macOS 27.2 arm64, git 2.x, bash 5; hooks installed by
each version of `scripts/install-git-hooks.sh` into a throwaway repo
with a bare remote; `make` stubbed to print instead of running the
precheck.
- Exact command / steps: install the hooks, push a `feature` branch with
`--no-verify`, then run `git push origin --delete feature` and `git push
origin HEAD:refs/heads/feature`, once with origin/main's script
(bb8d18a56) and once with this branch's.
- Observed result: origin/main runs `make ci-precheck` for the delete;
this branch skips it and still runs it for the branch push:

```text
== origin/main bb8d18a56
$ git push origin --delete feature
  [make ci-precheck] would run the full Rust + Python precheck
$ git push origin HEAD:refs/heads/feature
── pre-push: running 'make ci-precheck' before pushing HEAD → refs/heads/feature
  [make ci-precheck] would run the full Rust + Python precheck
== this branch
$ git push origin --delete feature
$ git push origin HEAD:refs/heads/feature
── pre-push: running 'make ci-precheck' before pushing HEAD → refs/heads/feature
  [make ci-precheck] would run the full Rust + Python precheck
```

- Not tested: a SHA-256 repository end to end (the regex change is
covered by reading only); Windows (the hook test module skips without
bash and git, as before); the full `make ci-precheck` itself (pushed
with `--no-verify`, since this PR changes only the hook script and its
test, and the precheck's `pip install -e .` would overwrite the local
venv used for the tests above).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; contributor git hook only.
- Minimum rollout channel: N/A (not shipped in the package).
- Stable/default behavior changed: only for delete-only pushes, which no
longer run `make ci-precheck`. Every push that sends commits behaves as
before.
- Kill switch / disable path: N/A; contributors re-run `make
install-git-hooks` to pick up the change.
- Unsafe override required: no.
- Qualification impact: none; CI does not use this hook.
- Rollback path: revert this commit and re-run `make install-git-hooks`.

## 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

Documentation: N/A. `CONTRIBUTING.md` says the pre-push hook runs
ci-precheck "on every push"; a push that only deletes branches sends no
code, so I left that wording alone. Happy to add a note if you prefer.

The three existing shellcheck SC2034 warnings in the hook body
(`remote`, `url`, `remote_sha` unused) are unchanged by this PR.

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4702"
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: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
2026-11-09 12:24:49 -06:00
2973ca593d ci: pin every GitHub Action to a commit SHA (#4671)
## Description

Every third-party action in `.github/` ran from a version tag like
`actions/checkout@v7`. A tag can be moved to other code at any time.
That is how `tj-actions/changed-files` leaked CI secrets from ~23,000
repos in March 2025.

Here a moved tag would run with the release job's PyPI OIDC token
(`id-token: write`) and the Docker job's `packages: write` token.
Pinning to a commit SHA closes that, and a new test keeps it closed.

Closes #

## 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

- All 195 third-party `uses:` refs in 25 files now name the commit their
tag points to today, with the version as a comment:
`actions/checkout@3d3c42e5... # v7.0.1`. No action version changes.
- Dependabot's existing `github-actions` config updates SHA pins and
their version comments, so the pins stay current.
- Pin dtolnay/rust-toolchain stable and 1.95.0 branches to their
existing commit heads. The stable action retains its runtime toolchain
input/default; the 1.95.0 action embeds toolchain: 1.95.0. This
preserves each call site's existing toolchain selection.
- New `test_every_action_is_pinned_to_a_commit_sha` in
`scripts/tests/test_ci_workflow.py` fails on any tag-pinned action and
lists each one.
- Three tests in `tests/test_release_workflows.py` matched the old tag
text (`setup-buildx-action@v4`, `gh-action-pypi-publish@vX.Y.Z`,
`release-please-action@v4/v5`). They now match the SHA pin and its
version comment.

## 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
$ uv run --frozen --extra dev pytest -q scripts/tests/test_ci_workflow.py scripts/tests/test_pr_health_workflow.py scripts/tests/test_normalize_release_pr_bodies.py tests/test_release_workflows.py
87 passed in 0.87s

$ uv run --frozen --extra dev pytest -q scripts/tests/test_pr_health_labels.py scripts/tests/test_version_sync.py tests/test_cli/test_wrap_copilot.py tests/test_learn/test_subagent_scanning.py tests/test_plugin_manifests.py tests/test_pr208_changes.py
114 passed in 1.32s

$ uvx ruff check scripts/tests/test_ci_workflow.py tests/test_release_workflows.py && uvx ruff format --check <same>
All checks passed!
```

## Real Behavior Proof

- Environment: macOS, Python 3.12 via `uv run --frozen --extra dev`,
branch cut from `main` at c01cf07d.
- Exact command / steps: resolved each tag with `git ls-remote --tags
--heads https://github.com/<owner>/<repo>` (peeled for annotated tags),
rewrote only the `uses:` lines, then ran the test files above and a
`yaml.safe_load` over every file in `.github/`.
- Observed result: 195 lines changed, 195 removed, no other line touched
(mixed LF/CRLF in `pr-health.yml` kept). All 201 tests pass. On `main`
the new test fails and lists the unpinned refs.
- Not tested: `scripts/validate-workflows.sh` (actionlint plus act dry
runs) was not run locally. The `workflow-validation` job runs it on this
PR.

## Runtime Rollout Safety

- Rollout-managed feature(s): None. CI workflow files and their tests
only.
- Minimum rollout channel: N/A, no runtime code changes.
- Stable/default behavior changed: No. Each SHA is the commit its tag
points to today.
- Kill switch / disable path: N/A, revert the commit.
- 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
- [ ] 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, no UI change.

## Additional Notes

- mypy and docs are N/A: no `headroom/` code or documented behavior
changes.
- Dependabot does not bump branch pins, so the two
`dtolnay/rust-toolchain` pins stay on today's branch head until someone
moves them. That action rarely changes.

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

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4671"
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 `57b7edd8d05b6dc5e3bc4eac1dff55f21519afe8`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Reviewed the27-file delta and existing discussion/Devin no-issues result
against current upstream main c01cf07d94,
already included in the contributor head. Independent full-workflow
comparison proves only uses refs/comments change across the25
workflow/action files. All195 replaced refs resolve exactly to their
original upstream tag/branch commits (29 unique pins across26
repositories), with annotated tags peeled; no mismatches. Pinned dtolnay
action source independently confirms stable runtime default versus
embedded1.95.0 branch behavior, preserving toolchain selection.87
workflow/release tests and113 adjacent tests pass,1skip; changed Python
lint/format passes. Maintainer fix only removes CRLF endings on two
edited pr-health lines to clear whitespace; provenance reverified
afterward. No contributor workflow logic altered. Description is
corrected to explain embedded1.95.0 semantics. No publish/release
workflow execution claimed; full hosted qualification must run on this
new mechanical-fix head. 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.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-06 09:16:15 -06:00
JD Davis 917edc6223 fix(release): normalize damaged release PR envelopes before detection (#4664)
## Description

Merging release PR #4643 did not create `v0.43.0` because its body
contained repeated carriage returns (`CRCRLF`). Release Please removes
one CRLF layer and then looks for exact `---` delimiter lines; the
leftover CR prevents release detection. The merge-triggered
[run](https://github.com/headroomlabs-ai/headroom/actions/runs/42065983322)
succeeded while logging `Pull request body did not match` and `could not
parse pull request body as a release PR`, leaving #4643 labeled
`autorelease: pending` and opening #4661 from the old release baseline.

Normalize only the damaged envelope before Release Please reads pending
merged releases. Eligibility requires a merged bot PR, a main base, a
release-please main branch in this repository, the pending label, and
repeated-CR damage. Ordinary CRLF, open PRs, human PRs, forks and
unrelated historical bodies are untouched. The normalized body must
still have a valid release-note envelope. JSON is sent through stdin,
avoiding another Windows text-file conversion.

The malformed body came from Windows text-mode maintainer tooling, not
contributor runtime code. That local writer has separately been
corrected to preserve LF.

## Type of Change

- [x] Bug fix (release automation)

## Changes Made

- Add a narrow, default-read-only body normalizer and tests.
- Run it with the workflow's existing release credential before release
detection.
- Allowlist the checked-in helper in `.gitignore`.

## Testing

- `pytest scripts/tests/test_normalize_release_pr_bodies.py
tests/test_release_workflows.py -q`: **75 passed**.
- Ruff 0.17.3 check/format and `git diff --check`: pass.
- `actionlint .github/workflows/release-please.yml`: pass.
- Regression tests demonstrate the old exact-delimiter parser fails on
CRCRLF, then verify repaired delimiters, eligibility exclusions, dry-run
no writes, JSON-stdin transport and workflow ordering.

## Real Behavior Proof

- Environment: Windows, Python 3.12.13, gh CLI; current main
`8d3e9e5ca`.
- Exact command: `python scripts/normalize_release_pr_bodies.py --repo
headroomlabs-ai/headroom` (default read-only).
- Observed result: `Would normalize release PR #4643`, exit 0. Other
historical pending PR formats were not edited. Current GitHub has no
`v0.43.0` tag/release; the exact merge-triggered log identifies the
failed body parse above.
- Not tested: deliberately did not run `--apply`, repair the live body,
create a tag/release, dispatch a release workflow, or publish packages.
No hosted release recovery is claimed.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; trusted main release automation
only.
- Stable/default behavior changed: on the next normal main push after
this fix merges, the workflow can normalize #4643's damaged body and let
Release Please create its pending release. This is the intended
recovery; review this effect before merging.
- Disable/rollback: revert the normalization step. The helper defaults
to read-only when invoked manually without `--apply`.
- No package versions, notes, labels, tags or releases are directly
changed by the helper; Release Please retains those responsibilities.

## Review Readiness

- [ ] This PR is ready for human merge review (draft pending independent
review/hosted checks).

## Additional Notes

Do not manually remove repeated generated entries from #4661. Once
0.43.0 is recovered, release notes should be regenerated from that
proper baseline. This PR does not perform that recovery or change
generated `CHANGELOG.md` itself.
2026-11-05 12:36:23 -06:00
66e1467682 feat(plugins): headroom skill for Claude Code, Codex, Copilot and skills.sh (#4533)
## Description

In the unbranded sandbox run the agent never searched and wrote a
300-line trimmer by hand; nothing in its environment said Headroom
exists. An Agent Skill is the one artifact that fires on the job words
(cut input tokens, trim tool outputs, fit a context window) with zero
fetches. Four unofficial "headroom" skills already exist on skills.sh;
there is no official one.

Depends on #4529 for the `/docs/fastapi` link in the skill body.

## Type of Change

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

## Changes Made

- `skills/headroom/SKILL.md`: job-language description; body is the
no-key `compress()` path, the zero-network check, `model_limit` /
`protect_recent`, the TypeScript proxy caveat, the coding-agent path,
and a short do-not list (no savings claims, no `CompressionMiddleware`
for apps that call a provider, no `[all]` unless asked).
- `plugins/headroom-skill/`: the same SKILL.md under `skills/`,
`.claude-plugin/plugin.json` and `.github/plugin/plugin.json`
(identical), README with install lines for Claude Code, Copilot CLI and
`npx skills add`.
- Both marketplace manifests: `headroom-skill` entry, inserted after the
hooks plugin so `plugins[0]` stays as the existing tests expect.
- `scripts/version-sync.py` and `scripts/verify-versions.py`: the two
new manifests, so the next release PR passes the version gate.
`scripts/tests/test_version_sync.py` fixture and assertion extended;
`tests/test_release_workflows.py` gate list extended.
- `tests/test_plugin_manifests.py`: the two SKILL.md copies must be
byte-identical (the repo has no symlinks, for Windows checkouts),
frontmatter has `name: headroom`; the skill plugin's two manifests match
each other and the marketplace entry.

## Testing

- [x] Unit tests pass: `tests/test_plugin_manifests.py
scripts/tests/test_version_sync.py tests/test_release_workflows.py -k
"manifest or version or skill or sync"`: 30 passed
- [x] `ruff check` / `ruff format --check` on the touched Python
- [x] `python scripts/verify-versions.py`: "All versions aligned at
0.42.0"
- [x] Manual testing performed

### Test Output

```text
pytest tests/test_plugin_manifests.py scripts/tests/test_version_sync.py tests/test_release_workflows.py -k "manifest or version or skill or sync": 30 passed
python scripts/verify-versions.py: All versions aligned at 0.42.0
claude plugin validate .: ✔ Validation passed
```

## Real Behavior Proof

- Environment: macOS arm64, Claude Code CLI.
- Exact command / steps: `claude plugin validate .` at the repo root of
this branch.
- Observed result: `✔ Validation passed`. The only warning is
pre-existing and about `plugins/headroom-agent-hooks/README.md` lacking
a marketplace install line.
- Not tested: installing the plugin from the marketplace into a fresh
Claude Code or Copilot CLI session and triggering the skill on a real
task; skills.sh indexing (happens on their side once this is on `main`).

## 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:43:21 -06:00
0f4275f8b3 fix(scripts): resolve hooks dir via git so install-git-hooks works in linked worktrees (#4176)
## Description

`make install-git-hooks` fails in a linked Git worktree because
`scripts/install-git-hooks.sh` checks for a literal `.git/hooks`
directory. In a worktree `.git` is a file and the hooks live in the
shared common dir, so the script exits before installing anything. The
script now asks Git for the effective hooks directory (`git rev-parse
--git-path hooks`) and writes the pre-push hook there. `pre-commit
install` already handles worktrees.

Closes #4161

## Type of Change

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

## Changes Made

- Resolve `HOOKS_DIR` with `git rev-parse --git-path hooks` instead of
assuming `.git/hooks`; fail clearly when not in a git checkout.
- Write `pre-push` to `$HOOKS_DIR` and print the real installed paths.
- Ordinary checkouts are unchanged (still `.git/hooks`, same output).

## Testing

- [x] Manual testing performed
- [ ] Unit tests / ruff / mypy: N/A, shell-only change with no Python
touched

### Test Output

```text
# linked worktree, before
$ ./scripts/install-git-hooks.sh
error: .git/hooks/ not found — run from a git checkout root

# linked worktree, after
✅ installed: /…/co/.git/hooks/pre-push
pre-commit installed at /…/co/.git/hooks/pre-commit
pre-commit installed at /…/co/.git/hooks/commit-msg

# ordinary checkout, after (unchanged)
✅ installed: .git/hooks/pre-push
✅ installed: .git/hooks/pre-commit (repo pre-commit checks via pre-commit)

# outside a git checkout
error: not inside a git checkout — run from a Headroom git checkout
```

## Real Behavior Proof

- Environment: Linux x86_64, git 2.43.0, pre-commit from a venv
- Exact command / steps: `git worktree add <dir> HEAD`, then
`./scripts/install-git-hooks.sh` from the worktree; repeated in the main
checkout and outside any repo
- Observed result: hooks install into the shared common dir; a commit
made in the worktree runs the pre-commit hooks (ruff/mypy hooks ran)
- Not tested: macOS; a repo with `core.hooksPath` set (pre-commit
refuses that config regardless)

## Runtime Rollout Safety

- Rollout-managed feature(s): None. Developer tooling only
(`scripts/install-git-hooks.sh`); no runtime code changes.
- Minimum rollout channel: Stable.
- Stable/default behavior changed: No. Proxy, library, and CLI behavior
are untouched; ordinary checkouts install hooks to the same `.git/hooks`
paths as before.
- Kill switch / disable path: Not applicable.
- 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] I have performed a self-review of my code
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

No hook bypass: the same pre-commit, commit-msg and pre-push hooks are
installed.
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4176"
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: JD Davis <mxjerrett@gmail.com>
2026-11-03 21:43:33 -06:00
dependabot[bot]andJerrettDavis 65bcc4c313 deps: qualify latest Anthropic SDK 1.4.0 in docs (#4556)
Qualify the docs development dependency `@anthropic-ai/sdk` against the
latest stable 1.4.0 client under the user-requested newest secure
compatible dependency scope. This supersedes the original 1.3.0 target.
npm registry `version` returned 1.4.0 during qualification. The SDK
remains unused by the docs application itself; this is explicitly
required compatibility qualification, not a claim of a site runtime bug
or newly required vendor endpoint.

## Dependency assessment

Anthropic maintains the official SDK:
https://github.com/anthropics/anthropic-sdk-typescript/releases/tag/sdk-v1.4.0.
It remains a development dependency; published Headroom runtime behavior
is unchanged. The package declares standardwebhooks, json-schema-to-ts
and @opentelemetry/api dependencies, unchanged from the prior 1.3.0
candidate; there is no new install lifecycle hook or exporter. Existing
OpenTelemetry tracing can use an application-registered provider; this
proof does not qualify tracing/export behavior. npm audit reports zero
vulnerabilities, not a guarantee of upstream security history.

Compared with the prior candidate, only the root Anthropic version range
and SDK tarball version/integrity change. Unrelated platform/libc
metadata is preserved. Registry downloads and the docs existing Fumadocs
generation/build lifecycle remain install surfaces. The SDK makes
provider requests only when invoked; the new qualification uses explicit
fake credentials and an owned loopback server.

## Real behavior proof

Windows, Node 22.22.0, npm 10.9.4; main `038af599e` merged cleanly. From
`docs/`:

```sh
npm ci --ignore-scripts=false --no-audit --no-fund
npm run types:check
npm run build
npm audit --json
```

All passed, audit zero vulnerabilities. From repository root:

```sh
node scripts/verify_docs_anthropic_sdk.mjs
```

Actual installed Anthropic 1.4.0 client makes one real HTTP request to
the ephemeral loopback server. PASS: `/v1/messages`, default
`anthropic-version: 2026-10-21`, Bearer authentication, exact
thinking/cache/tool/system/metadata serialization, parsed thinking/text
response. Initial older fixture expectations for the old
API-version/API-key headers failed during earlier 1.3.0 qualification;
the fixture was corrected to assert the actual new SDK defaults, which
also pass on 1.4.0. The real client is used with fake credentials; no
external provider request is made.

Built Next.js production server returned HTTP 200 for
`/docs/anthropic-sdk`, 239099 bytes with expected Anthropic content;
owned server terminated afterward. `git diff --check` passes. Logs
retained locally as
`.codex/dep4556-latest-{ci,types,build,audit,route}.*`.

Untested: live vendor inference/authentication, streaming, real
signed-thinking validation, new SDK APIs, browser/other operating
systems, tracing export, and Headroom middleware transport (this is a
direct docs dependency proof). Hosted CI must qualify the final remote
head. No push, approval, merge or release performed by this
qualification.


Supply-chain metadata: SDK 1.4.0 declares Apache-2.0; the base lockfile
declared MIT.

---------

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-03 17:07:21 -06:00
dependabot[bot]andJerrettDavis 038af599e1 deps: Bump lru from 0.18.5 to 0.19.0 (#4382)
## Why this version

Upgrade the native proxy's bounded session caches from lru 0.18.5 to
0.19.0 to retain the upstream iterator soundness correction. The
official 0.19.0 changelog says "Require Sync for sendable shared
iterators." In source, `Send for Iter<'a, K, V>` now requires `K: Sync,
V: Sync`, replacing `K: Send, V: Send`: the iterator yields shared
references, which may cross threads only when their referents are Sync.

Headroom uses this crate for the shared `BetaStickyState` session
beta-token union and `DriftState` structural-hash history. Both live in
`Arc<Mutex<LruCache<...>>>` and are cloned into concurrent request
handlers. They use String / Vec<String> / StructuralHash values; they do
not transfer shared iterators across threads. Thus this updates a
concurrency-sensitive dependency to its corrected upstream contract; it
does not claim that current Headroom calls demonstrate an exploit or
require a new API.

The patch preserves the 0.19 target and adds the dependency rationale
beside its declaration, removes an obsolete lru 0.12 documentation
reference, and mechanically merges current main so the current security
workflows and fixes are included.

## Compatibility and installation

This is a pre-1.0 minor bump, so compatibility was checked rather than
assumed. The only dependency introduced by lru remains hashbrown 0.17.1.
The crate's MSRV is 1.85.0 in both 0.18.5 and 0.19.0; this bump does not
raise it. Headroom's workspace rust-version=1.80 already understates
that dependency floor; its pinned toolchain is 1.95.0, used for this
validation. Correcting the workspace-wide MSRV declaration is outside
this dependency patch.

Native installation already builds the ONNX/image/AWS dependency stack
and may fetch build dependencies and ONNX Runtime artifacts; lru adds no
build script or model download. This was a fresh isolated native target
build using the existing registry/artifact caches, not a clean
offline-install certification. Runtime validation disables model
downloads with HEADROOM_OFFLINE/HF_HUB_OFFLINE and uses only local fake
upstreams, with no cloud inference or credentials.

## Validation

- `cargo test -p headroom-proxy --lib cache_stabilization --locked`: 105
passed, including concurrent_unions_lose_no_tokens (8 threads, 50
updates each), LRU eviction and recency checks.
- `cargo fmt --all -- --check`: passed.
- `git diff --check`: passed.
- `cargo test -p headroom-proxy --test integration_cache_drift --test
integration_cache_control --test integration_e3_anthropic_cache_control
--test integration_e4_openai_cache_key --locked`: 20 passed across four
binaries (1/8/5/6).
- `cargo build -p headroom-proxy --locked`: passed with Rust 1.95.0 on
Windows MSVC.
- `python scripts/verify_native_session_caches.py --proxy
target/debug/headroom-proxy`: passed. A separately spawned native binary
forwarded 12 requests to an ephemeral loopback fake Anthropic upstream
without credentials. Sequential requests retained beta-a,beta-b; eight
concurrent same-session requests retained all token-0 through token-7 in
the next request. Logs recorded both first-seen and changed-system drift
events. Both proxy and fake upstream were cleaned up. Compression
interception was enabled with compression-mode off; this exercises the
actual session caches and byte passthrough, not model compression or
cloud behavior.
- The standard-library runtime proof is committed as
`scripts/verify_native_session_caches.py`; no private artifacts are
required. Security/CI approval and remote branch update remain separate
gates; this local proof does not certify hosted checks.

Official upstream references:
https://github.com/jeromefroe/lru-rs/blob/0.19.0/CHANGELOG.md and
https://github.com/jeromefroe/lru-rs/blob/0.19.0/src/lib.rs .

## Reproduce the native loopback proof

From the repository root, with its pinned Rust toolchain and Python 3:

```sh
cargo build -p headroom-proxy --locked
python scripts/verify_native_session_caches.py --proxy target/debug/headroom-proxy
```

On Windows use `--proxy target/debug/headroom-proxy.exe`. If
`CARGO_TARGET_DIR` is set, pass the binary under that directory instead.
Optional `--log /path/to/proxy.log` preserves logs; otherwise logs and
the child working directory are temporary. The script uses only Python's
standard library, strips provider/Headroom configuration environment
variables, disables model egress, bypasses caller HTTP proxy settings,
disables stats persistence, and starts only its own loopback fake
upstream and native child. It returns nonzero on readiness, forwarding,
sticky-union, or drift-event failures and cleans up its processes.

This proof was rerun after making the harness portable: all 12 upstream
requests passed. Current main was fetched again and remains
`74277d47ecfbca349ddb99f81094c4dd30539d43`, already included in this
candidate.

---------

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-03 08:45:55 -06:00
dependabot[bot]andJerrettDavis 99e223c0e2 deps: Bump tsup from 8.5.1 to 9.0.0 in /plugins/opencode (#4385)
Build the OpenCode plugin with the patched esbuild line inside tsup's
supported range. Headroom's existing esbuild 0.28 security override is
outside tsup 8.5.1's ^0.27.0 declaration. Tsup 9 declares ^0.28.2, so
retain the major upgrade and raise the override floor from ^0.28.1 to
^0.28.2. The original tsup 9 lock still selected 0.28.1; this follow-up
corrects that mismatch and documents the source-build requirements.

## Dependency assessment

- **Version reason:** use an upstream-supported build combination for
the existing dependency-security mitigation, rather than forcing the
selected esbuild release outside the old bundler's range. This does not
claim a new advisory in 0.28.1 or that the old built plugin was
demonstrated broken. Tsup remains the existing builder;
[v9](https://github.com/egoist/tsup/releases/tag/v9.0.0) also changes
debug/obug, watchers and related toolchain packages.
- **Maintenance/security:** reviewed the published release/manifest and
resolved graph. Fresh audit reports zero vulnerabilities; this does not
imply every upstream project has a spotless history. Platform-selector
metadata outside the esbuild refresh is preserved instead of accepting
unrelated npm-version normalization.
- **Node/build boundary:** tsup requires `^22.18.0 || ^24.11.0 ||
>=26.0.0`; the current graph's ini 7 also requires `^22.22.2 || ^24.15.0
|| >=26.0.0`. The README documents both and the verified Node 24.22.2
choice. Published plugin/host runtime declarations are unchanged. An
earlier Node 22.22.0 pass emitted the existing ini warning; acceptance
uses the supported Node 24 install.
- **Native/install/network:** existing esbuild/Rollup platform code and
lifecycle scripts remain build inputs. Rollup's optional GNU Linux-x64
LZMA and Android-x64 bindings are present; the LZMA entry is a real
optional dependency, not an orphan. Windows x64 installation/build was
tested; these non-Windows paths were not. No new install-script flag is
introduced. Existing plugin runtime dependencies are unchanged; tsup
remains a development dependency. npm and host support-dependency
installation use the registry. No plugin is published and no
inference/provider message is requested.

The branch is synchronized with main's merged security and SDK updates.

## Real behavior proof

Windows x64 / Node 24.22.2 / npm 10.9.4, fresh isolated checkout. From
`plugins/opencode`, under that Node:

```bash
npm ci --ignore-scripts=false --no-audit --no-fund
npm test
npm run typecheck
npm run build
npm run build:standalone
npm audit --json
node ../../scripts/verify_opencode_bundle.mjs .
```

The install has no engine warning; **61 tests pass**, typecheck and both
builds succeed, audit reports zero vulnerabilities. The committed
portable proof imports actual `dist/index.js` and
`dist-standalone/index.js`, invokes the built server entry and performs
real chat/retrieve HTTP requests against an ephemeral loopback fixture.
It asserts original upstream/path, project/session headers, response and
retrieval content; output reports PASS. The plugin routes the synthetic
OpenAI URL to the fixture. Hooks/sockets/processes are disposed. This is
built-artifact wire behavior, not a claim that the fixture is the Python
service.

**Actual host loading:** installed official `opencode-ai@1.19.4`,
matching the installed 1.x plugin SDK, into a task-only prefix/cache.
Its native Windows `opencode.cmd debug config --print-logs` ran from an
isolated task workspace with the built main entry
`file:///G:/git/headroom-dep4385/plugins/opencode/dist/index.js`
configured directly. No wrapper was used for this check. It exited 0
with successful bootstrap/configuration/disposal and no loader error. A
separate instrumentation probe preserved the exported object shape and
delegated its actual `server` function; it recorded `id=headroom`,
retrieval-tool registration and the shell-environment hook. It did not
adapt the object into a legacy function.

The host's XDG config/data/state/cache point at task-only directories.
Enabled providers are empty; auto-update, remote model fetching and
default plugins are disabled. Credential environment names are removed
in the child shell only; user home/config/auth files are not repurposed.
The CLI installed support dependencies in the isolated config, so
registry traffic occurred. No inference command or provider action was
requested.

Node syntax and whitespace checks pass. Independent technical review
found no code or dependency-policy blocker in the corrected build
range/source-runtime boundaries.

Untested: actual OpenCode 2.x, registry-tarball plugin installation, the
Python compression proxy in this smoke, streaming, live providers,
hook-shim spawning, non-Windows native installation, or production
publishing. Current-head hosted CI must pass before approval.

---------

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-03 08:45:19 -06:00
dependabot[bot]andJerrettDavis e666fd8e35 deps: Bump tsup from 8.5.1 to 9.0.0 in /sdk/typescript (#4386)
Build the SDK with Headroom's patched esbuild release inside the
bundler's supported dependency range. Headroom already overrides esbuild
to the 0.28 series as part of dependency-CVE remediation
([#1509](https://github.com/headroomlabs-ai/headroom/pull/1509)); tsup
8.5.1 declares ^0.27.0, so that combination relies on an out-of-range
override. Tsup 9 declares ^0.28.2. Upgrade the bundler and raise the
override floor from ^0.28.1 to ^0.28.2 so the selected secure-build
inputs agree with the upstream-supported range.

The original tsup 9 lock still selected esbuild 0.28.1 through the
override. This maintainer follow-up corrects that mismatch, regenerates
the lock and documents the actual source-build Node requirement. It does
not claim that 0.28.1 introduces a new advisory or that the old
bundler's emitted SDK was demonstrated broken.

## Dependency assessment

- **Why tsup/version:** existing ESM/CJS/declaration builder; version 9
provides the upstream-supported esbuild 0.28 build combination needed by
the existing security override. This avoids introducing a new bundler or
relying indefinitely on tsup 8's incompatible declared dependency range.
[Official v9
changes](https://github.com/egoist/tsup/releases/tag/v9.0.0).
- **Maintenance/security:** tsup's published 9.0.0 release/source and
installed manifest were reviewed, including esbuild/chokidar upgrades,
the debug-to-obug change, and the Node floor. Security expectations are
evaluated on the resolved dependency tree, not inferred from the major
number. Fresh Windows and Linux audits report zero vulnerabilities; this
does not assert a clean history for every upstream project.
- **Build/runtime boundary:** tsup 9 requires `^22.18.0 || ^24.11.0 ||
>=26.0.0`. The source-build README now recommends Node 24 LTS >=24.11
and documents the alternatives. The published SDK's Node >=18 engines
field and optional peer requirements are unchanged. Built ESM/CJS
entrypoints load and construct the SDK client on Node 18.20.8; current
Vercel peers have their own higher runtime floor, qualified separately
on Node 22.
- **Transitive/native/install surface:** the lock adds Rollup's optional
Linux-x64 GNU LZMA binding and Android-x64 parser binding. It removes
debug, ms, source-map and a nested tinyexec entry while updating the
bundler's declared toolchain. No new install-script flag is introduced.
Existing esbuild/Rollup platform-native components and installation
scripts remain development inputs. The Linux LZMA package is a
legitimate Rollup optional dependency, not an unreferenced lock entry.
It was installed and resolvable in the Linux qualification; its
compression functions and Android bindings were not independently
exercised. Fresh installs with scripts enabled and actual builds were
run on Windows x64 and Linux x64 GNU. No build tooling/native binary is
added to the SDK's published runtime dependency list.
- **Network surface:** npm registry/package downloads and any existing
build-tool setup behavior remain install-time network surfaces. Normal
SDK/provider HTTP behavior is unchanged; the proof uses an isolated
local proxy/provider fixture and no real vendor credential. No release
or production rollout is performed.

## Real behavior proof

Windows/Node 22.22.0 and Linux/Debian bookworm/Node 24.22.2, with the
resolved tsup 9.0.0 and esbuild 0.28.2. The Linux run copies the SDK
source into an ephemeral container, keeping its install/build separate
from the Windows tree.

From `sdk/typescript`, on each environment:

```bash
npm ci --ignore-scripts=false --no-audit --no-fund
npm run typecheck
npm test -- --reporter=dot
npm run build
npm audit --audit-level=low
```

Both report **406 tests passed, 33 skipped**, no type errors, successful
ESM/CJS/declaration builds, and zero audit findings. Linux resolves
`@napi-rs/lzma-linux-x64-gnu` and loads Rollup 4.67.2. These are fresh
installs with scripts enabled, rather than relying only on a
scripts-disabled install.

Against the Windows-built artifacts, `python
scripts/verify_sdk_provider_peers.py` runs the real Headroom HTTP
compression path (isolated temporary state, stateless mode, no
subscription tracking/upstream discovery) and actual provider/native SDK
clients with loopback provider responses. It verifies final JSON text
preservation, per-request async credential resolution, and native chat
completion through the generated adapters. Observed exit 0 with four
`/v1/compress` responses of 200. The local run reused an existing
Headroom native extension and does not claim a fresh local Rust build or
live model inference.

From `sdk/typescript`, `npm exec --yes --package=node@18.20.8 -- node
../../scripts/verify_sdk_dist_compat.mjs .` reports that the built ESM
and CJS SDK entrypoints load and construct the client. This tests the
core entrypoint boundary, not all optional provider peers or every SDK
call on Node 18.

`git diff --check` and the new Node proof's syntax check pass. The
branch is synchronized with main, including the already-qualified
dependency/security updates.

After main gained the native Anthropic 1.3 update, the SDK lock was
combined again without dropping that update or any of the six
provider-group targets. The final tree retains tsup 9.0.0, esbuild
0.28.2 and native Anthropic 1.3.0, preserving unrelated platform
metadata. Fresh scripts-enabled install, 406 tests/33 skips,
types/build/audit and Node 18 entrypoint loading pass again on Windows.
Both `verify_sdk_provider_peers.py` (four compression HTTP calls) and
`verify_anthropic_peer.py` (native thinking/cache/tool/system/metadata
preservation) also pass against these newly built artifacts. The earlier
Linux qualification used the same bundler/esbuild graph before that
native-peer merge; final-head hosted platform CI supplies the
combined-tree platform coverage.

Untested: other operating systems/architectures, Android or musl native
bindings, LZMA compression behavior, watch-mode filesystem events, live
vendor models/credentials, streaming, production publishing, and the 33
skipped tests. Hosted CI must qualify the current head.

---------

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-03 08:45:00 -06:00
dependabot[bot]andJerrettDavis b9049d703a deps: Bump the cargo-minor-patch group across 1 directory with 12 updates (#4553)
## Purpose

Retain the complete selected 12-version Cargo group and qualify its
compatibility with Headroom. The AWS release moves its config,
credential, Smithy runtime/schema and SDK dependencies together to a new
coordinated compatibility line; upstream explicitly warns against
upgrading only part of that line. Existing proxy credential resolution
and SigV4 signing must continue to work with that coherent set.

This is a compatibility-qualified grouped update. Companion updates are
not individually claimed to fix a Headroom bug where upstream only added
unused APIs.

## Selected versions and project relevance

| Package | Selected update | Relevance and qualification |
| --- | --- | --- |
| tokio | 1.53.3 → 1.54.1 | Proxy HTTP/SSE/WebSocket execution and
timers; includes upstream timer-handle regression revert. Local native
proxy/SSE/WSS tests exercise runtime. |
| aws-config | 1.12.0 → 1.13.0 | Required companion for new AWS
schema/runtime compatibility line; production environment credential
chain exercised with explicit fake credentials. |
| aws-credential-types | 1.3.0 → 1.3.1 | Same coordinated AWS line,
production credential conversion and SigV4 signing exercised. |
| aws-smithy-runtime-api | 1.19.0 → 1.19.2 | Same coordinated AWS line;
timeout finalizer behavior changed upstream. Local signing/wire tests do
not establish SSO/STS timeout behavior. |
| sha2 | 0.11.0 → 0.11.1 | Existing cache/SigV4-related payload hashing;
upstream unsafe-op lint fix. Local signed payload SHA256 verified; no
claimed cryptographic vulnerability fixed. |
| redis | 1.7.1 → 1.8.0 | Optional multiworker CCR backend; upstream TLS
error/secret redaction and subscription correctness fixes. Production
backend roundtrip exercised against local RESP fixture; cluster/pubsub
are not Headroom backend usage. |
| tree-sitter | 0.27.0 → 0.27.1 | Code compressor parser/error recovery
fixes. Reconstructed 9 samples × 8 pinned languages compare old/new node
kinds, complete row/column spans, ERROR/MISSING: 72/72 identical. |
| uuid | 1.28.0 → 1.29.0 | Full-group companion target; new NonNilUuid
constructors are unused. Existing request-ID generation exercised
through real proxy calls and both response x-request-id values parsed as
UUIDv4; no invented bug/security rationale. |
| crc32fast | 1.5.2 → 1.5.3 | Full-group companion target; upstream
total-length API is unused. Existing Bedrock EventStream
checksum/framing path exercised by streaming integration suite. |
| rustls-native-certs | 0.8.4 → 0.8.5 | Native trust-store handling;
avoids duplicate Unix certificate-file reads. Windows build and WSS
fail-closed behavior exercised; Unix store traversal not locally
exercised. |
| webpki-roots | 1.0.10 → 1.0.11 | Updated bundled CA trust set (CCADB
CA removals); WSS verification tests exercise existing explicit TLS
configuration. No public CA endpoint contacted. |
| cc | 1.8.0 → 1.10.0 | Native C/C++ dependency builds; upstream fixes
MSVC archive object paths and cl.exe wrapper handling. Actual clean
Windows MSVC native dependency compilation performed. |

## Maintenance and install surface

The packages remain maintained by their existing upstream projects:
Tokio, AWS/Smithy, RustCrypto, redis-rs, tree-sitter, uuid-rs,
srijs/rust-crc32fast, rustls and rust-lang/cc-rs. Release/compare links
in the original Dependabot body identify the reviewed releases; AWS
authoritative release notes:
https://github.com/awslabs/aws-sdk-rust/blob/main/CHANGELOG.md (October
20–30, 2026). UUID comparison confirms its change only adds NonNilUuid
constructors; it is not presented as a security fix.

No new package source/registry is introduced. Cargo resolves registry
downloads at build time; cc executes the native compiler for existing
C/C++ dependencies (tree-sitter grammars and other existing native
crates). The lock update changes the transitive AWS SDK/schema/runtime
family together. Existing ONNX runtime loading/model behavior is not
altered by this PR. Redis is feature gated and adds runtime network only
when explicitly configured. AWS credentials can normally resolve through
environment, profiles, SSO/STS or metadata; qualification uses only
explicit fake environment credentials, NUL config files and disabled
IMDS. Normal configured proxy upstream traffic and native trust-store
reads remain existing runtime surfaces.

Pinned qualification compiler: Rust 1.95.0 on Windows/MSVC. Resolved
proxy AWS floor is 1.94.1; core/Python/parity graph includes
tree-sitter-language floor 1.90. Both already existed in the base lock,
so no global rust-version change is made; inherited workspace
rust-version=1.80 is not a valid full-workspace source-build promise.
Fresh base/head Windows-filtered metadata comparison confirms unchanged
floors: core/Python/parity1.90,proxy1.94.1,simulators1.86(ICU). These
are dependency-declared effective floors, not measured lower-toolchain
builds. No lower-toolchain build was attempted.

## Real behavior proof

Windows, Rust1.95.0 x86_64-pc-windows-msvc, isolated worktree, dedicated
CARGO_TARGET_DIR, CARGO_BUILD_JOBS=2. No actual AWS/provider
credentials, profiles, cloud inference or model downloads used.

- `cargo test --locked -p headroom-core -p headroom-proxy` with explicit
existing x64 ONNX Runtime DLL (`ORT_DYLIB_PATH`) and
`HEADROOM_OFFLINE=1`, `HF_HUB_OFFLINE=1`, `TRANSFORMERS_OFFLINE=1`:
**1,659 passed, 0 failed, 3 ignored; exit 0**, across 61 test/doc-test
executables. Initial run without the Windows loader path was diagnosed
loader-blocked and terminated; its separate failed log is retained.
- `cargo test --locked -p headroom-proxy --test
integration_bedrock_invoke --test integration_bedrock_streaming --test
integration_ws_tls --test integration_sse`: 23passed,0failed
(8invoke,11streaming,2SSE,2WSS).
- `python G:/git/headroom/.codex/dep4553-runtime.py`: built
headroom-proxy.exe on ephemeral ports with compression disabled;
passthrough and native Bedrock routes each return local200, both bodies
byte equal; AWS environment provider loaded fake credentials and SigV4
Credential prefix/payload SHA256 checked; both generated response
x-request-id headers validated UUIDv4. Synthetic wire fixture, not real
AWS service emulation.
- `python G:/git/headroom/.codex/dep4553-redis-wire.py`: temporary
integration test calls production RedisCcrStore using redis1.8.0; local
RESP fixture validates PING,miss,UTF8 payload write/read,TTL refresh and
replacement; 1passed. Synthetic protocol server; supplemented by `python
G:/git/headroom/.codex/dep4553-redis-real.py`: real Redis7Alpine
ephemeral loopback Docker service with persistence disabled; production
backend2testsPASS,including real TTLrefresh andexpiry. Owned
--rmcontainer stopped automatically. TLS/cluster/failover/pubsub not
tested.
- Standalone canary under `.codex/dep4553-canary`: exact engine
versions0.27.0 and0.27.1, same eight pinned grammars,72/72 AST snapshots
identical. Historical canary source was absent; reconstructed inputs are
recorded, including second distinct valid fixture per language (explicit
Cfunctionpointer sample), CRLF,truncated,error,concatenated andUnicode
cases.
- Isolated Python3.12 env: recorder regression9tests passed; Ruff
checks/format passed. Original official fixture generator reproduced
KeyError(bash). Minimal3line helper fix raises ValueError, matching
existing detector unsupported-language contract; all8pinned grammars
remain covered. Official generator then recorded30fixtures.
- Generator revealed12preexisting Python-reference fixture differences.
Exact main74277d47 source extracted independently, same Python
environment +same helper fix:30/30 regenerated semantic fixture objects
match PR source, excluding recorded_at only. Preserve original repo
fixture bytes; do not mask unrelated Python-reference drift by replacing
goldens. Baseline/regenerated files and comparisons retained as
artifacts.

## Remaining gates / limitations

Initial broad Cargo suite was loader-blocked: source live_zone.rs
documents indefinite Windows initialization without ORT_DYLIB_PATH.
Controlled termination of exact owned testPID717412 produced
authoritative exit1 for original session37711. Distinct corrected
configuration uses existing verified x64ORT1.26.0 DLL(API24), explicit
ORT_DYLIB_PATH and offline guards; corrected full core+proxy
qualification completed exit0,1659passed,0failed,3ignored. This is an
environment diagnosis, not a demonstrated dependency regression. Hosted
checks must be rerun on the exact final remote SHA; prior shard4 red is
not claimed fixed. Canonical fixture rerecord was executed and its
baseline-identical semantic drift documented, not silently normalized
away. No Linux/macOS build, lower MSRV build, real AWS SSO/STS/IMDS,
public CA endpoint, Redis TLS/cluster/failover, production provider
inference or model download was tested. No remote push, PR edit/review
or merge performed by this qualification task.

## Public reproduction

The committed standard-library harness reproduces the full 72-case
parser comparison and launches the actual native proxy against
credentialless loopback fixtures. It stores both complete AST snapshots
and inputs when `--artifacts-dir` is provided. No private `.codex`
artifacts are needed.

Windows, from a clean checkout with Rust 1.95/MSVC and Python 3.11+:

```powershell
cargo build --locked -p headroom-proxy --target-dir target/qualification
python scripts/qualify_cargo_dependencies.py all --binary target/qualification/debug/headroom-proxy.exe --artifacts-dir target/qualification-proof --canary-target-dir target/qualification-canary
```

Linux/macOS use the same commands with the binary path
`target/qualification/debug/headroom-proxy` (omit `.exe`). Those
platforms are reproduction instructions, not platforms locally qualified
here. The canary compiles standalone exact engine versions0.27.0/0.27.1
against all eight production grammar pins, so Cargo registry
downloads/native compilers may be needed. Runtime checks use fake AWS
credentials, platform null config files, disabled IMDS, offline model
guards, compression off, and local HTTP endpoints only.

The source-comment-required Python fixture rerecord is independently
reproducible:

```text
python -m pip install tree-sitter==0.25.2 tree-sitter-python==0.25.0 tree-sitter-javascript==0.25.0 tree-sitter-typescript==0.23.2 tree-sitter-go==0.25.0 tree-sitter-rust==0.24.2 tree-sitter-java==0.23.5 tree-sitter-c==0.24.2 tree-sitter-cpp==0.23.4
python scripts/record_code_compressor_fixtures.py
```

Use an isolated development Python environment with the project
development dependencies installed. The recorder helper fix in this PR
preserves its existing eight-grammar scope; unsupported detector
candidates are skipped through the existing ValueError contract.
Regeneration currently exposes baseline Python-reference drift as
documented above; inspect semantic differences rather than replacing
goldens blindly.

---------

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-03 08:43:53 -06:00
dependabot[bot]andJerrettDavis 74277d47ec deps: Bump @anthropic-ai/sdk from 0.133.0 to 1.3.0 in /sdk/typescript (#4554)
Qualify the TypeScript SDK's native Anthropic adapter against
Anthropic's stable 1.3.0 client, rather than testing only the old
0.133.0 development peer. Current-peer compatibility is a required
qualification target for this SDK maintenance work, including the native
Anthropic client admitted by the existing `@anthropic-ai/sdk >=0.30.0`
range. The README installs Headroom only; Anthropic is an optional,
separately installed peer, not an automatically installed dependency.
This PR makes the selected 1.3.0 qualification concrete with actual HTTP
transport and Headroom compression, including the native blocks that
must survive unchanged.

## Dependency assessment

- **Why package/version:** retain Anthropic's official client as an
optional integration peer instead of duplicating its authentication,
request serialization, retries and response API. Version 1.3.0 is the
selected stable peer qualification target for the native adapter under
the required current-client compatibility scope. The broad peer range
permits 1.x but is not itself evidence that it was tested, nor a
requirement for users to install it. This is deliberate compatibility
qualification, not a claim that Enterprise Claude Tag endpoints are used
by Headroom or that an unrelated upstream feature fixes compression.
[Official
release](https://github.com/anthropics/anthropic-sdk-typescript/releases/tag/sdk-v1.3.0).
- **Maintenance/security:** maintained by Anthropic, with the reviewed
release/source history covering the stable client and request-layer
changes. Fresh SDK audit reports zero vulnerabilities; this is not a
guarantee about all past/future upstream security issues. Actual
transport, build and test results support acceptance rather than the
major version number alone.
- **Install surface:** the only added lock package is
`@opentelemetry/api` 1.9.0 (SDK requirement ^1.4.1). Existing
standardwebhooks and json-schema-to-ts dependencies remain. No new
install-script flag, native package or exporter is introduced. The
Anthropic SDK remains a development/test dependency here; published
optional peer ranges are unchanged. A registry install and the client's
existing provider HTTP requests remain network surfaces. Node 22.22.0
was tested; the distribution has no engines field, so this result is not
a claim of qualification on every Node version.
- **Tracing/privacy:** the new client can emit API-call spans when the
application has registered an OpenTelemetry tracer provider. Defaults
use metadata-only content mode and permit trace-context propagation;
prompt/response content capture requires content mode selection.
`openTelemetry: false` or the documented ANTHROPIC_OPEN_TELEMETRY
environment setting disables spans. The API package supplies no exporter
itself, but an application's existing tracer/exporter can receive the
new spans. This behavior and configuration are part of the upgrade's
surface, not assumed absent because the dependency is JavaScript-only.
Exporter/propagation behavior was inspected but not exercised by the
transport proof.

The branch is synchronized with main, including the merged #4599
glob/minimatch audit remediation and its existing exact bundled
exceptions/November 15 expiry. The SDK lock conflict with merged #4621
is resolved by retaining all six of that group's updates and applying
the Anthropic 1.3.0 change to that combined lock. A parsed comparison
with main confirms the only package-version difference is Anthropic and
the only added package is the telemetry API.

## Real behavior proof

Windows, Node 22.22.0, Python 3.12.13, the actual 1.3.0 client from the
PR lock, and Headroom's built native Anthropic adapter. The local proxy
used an existing native Headroom extension, isolated temporary
workspace/config storage, stateless operation, disabled subscription
tracking, and skipped upstream discovery. A loopback provider fixture
sends a valid SDK response. No cloud credential, real model inference,
or genuine thinking signature was used.

```powershell
cd sdk/typescript
npm ci --ignore-scripts --no-audit --no-fund
npm run build
cd ../..
python scripts/verify_anthropic_peer.py
```

Observed, exit 0:

```text
PASS: actual Anthropic SDK client + Headroom adapter preserve thinking, cache markers, tool pairs, system and metadata on the wire
Real Headroom /v1/compress response: [200]
```

The actual 1.3.0 `client.messages.create()` passes through
`withHeadroom`, makes a real compression HTTP request with fallback
disabled, then sends a real HTTP request to `/v1/messages`. The fixture
asserts the complete message array (opaque thinking/signature, paired
tool use/result and cache markers), separate system blocks and metadata;
the returned SDK text is also asserted. No SDK/client/compression
function is replaced. The short payload does not trigger token
reduction, so this proves native transport/payload preservation rather
than a long-input compression ratio or vendor acceptance of the
synthetic signature.

SDK tests: **406 passed, 33 skipped**. Typecheck, ESM/CJS/declaration
build and zero-finding audit pass. Python lint/format, Node syntax and
whitespace checks pass.

After the main/SDK-group synchronization, the native proof and all these
checks passed again. The committed `python
scripts/verify_sdk_provider_peers.py` also passes on the combined tree:
the actual Vercel Anthropic provider retains final JSON text, the OpenAI
provider resolves two async credentials separately, and the native
OpenAI client completes its request, with four real `/v1/compress`
responses of 200. Thus the conflict resolution preserves the
already-qualified peer matrix alongside the new native Anthropic client.

Untested: live Anthropic credentials/models, streaming/beta/new
Enterprise APIs, signed-thinking validation by Anthropic, tracing
export/propagation, browser behavior, active compression of long inputs,
other Node/platform combinations, and the 33 skipped tests. Current-head
hosted CI remains required.

---------

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-02 22:44:52 -06:00
5c785e6938 chore(deps): bump the uv group across 1 directory with 2 updates (#4537)
Mem0's recent-conversation cache can mix distinct Headroom tenant
identities when an agent/user ID contains `&` or `=`. In the published
mem0ai 2.0.5 code, `(agent_id="alpha&user_id=beta", user_id="gamma")`
and `(agent_id="alpha", user_id="beta&user_id=gamma")` produce the same
cache key. Writing the first tenant's messages to Mem0's actual SQLite
conversation store makes them retrievable through the second tenant's
key. Mem0 2.0.18 escapes those delimiters and prevents that collision.

Upgrade the dependency and adapt Headroom to its stricter identity API:
save agent_id as an identity argument, search/list with identity
filters, use get_all's top_k argument, and restore promoted response
identities with a fallback for older metadata layouts. Otherwise the
upgraded library strips scope metadata, rejects search arguments, and
silently breaks the adapter's listing/query paths. Explicit search
user_id retains precedence over the filter's user_id.

## Dependency assessment

- **mem0ai 2.0.5 -> 2.0.18:** fixes the demonstrated tenant-buffer
isolation bug in a path used by the optional conversational-memory
backend. Headroom accepts these identifier strings; assuming they never
contain reserved characters would not be a safe substitute. The two old
Python source files were compared byte-for-byte with the SHA256-verified
public 2.0.5 wheel before reproducing the leak. [Release notes and fix
#6892](https://github.com/mem0ai/mem0/releases/tag/v2.0.18) describe
delimiter escaping and the one-time reset of recent buffers for IDs
containing `%`, `&`, or `=`. Persisted memory records are unaffected.
The independent 2.0.5 reproduction is the reason for this update; it
does not rely on interpreting the narrower version range in the upstream
security advisory as covering 2.0.5.
- **langgraph-sdk 0.4.4 -> 0.4.6:** fixes thread/assistant IDs being
interpreted as URL paths, query strings, or fragments in the stream
state's REST helpers. [Upstream fix
#9213](https://github.com/langchain-ai/langgraph/pull/9213)
percent-encodes these identifiers. A real loopback HTTP test with
`tenant/../other?query#fragment` reproduced wrong paths on 0.4.4 and
verified one encoded path segment on 0.4.6. This is an optional
graph-client dependency; the proof exercises its real transport helpers
directly, not a claim that Headroom's local LangGraph hook calls a cloud
API.
- **posthog 5.4.0 -> 7.79.0:** a required transitive major update, since
the new Mem0 distribution declares `posthog>=7.14.0`. Keep the locked
compatible 7.79.0 resolution rather than retaining a version outside
that requirement. The real 7.79.0 client passes capture/shutdown against
a loopback endpoint, and Mem0's actual opt-out creates no telemetry
client/event. This is not an independent new analytics feature for
Headroom.
- **Maintenance/security:** Mem0 is maintained by mem0ai (2.0.18
released August 11), the graph SDK by LangChain (0.4.6 released October
6), and PostHog's client by PostHog (7.79.0 uploaded October 28). Public
release/source history and Mem0's published security advisory were
reviewed. PyPI's current 0.4.6/7.79.0 responses list no vulnerability
entries; this is not a guarantee about all upstream security history.
Current branch hosted dependency audits passed before the proof-only
follow-up commit; current-head qualification remains required.
- **Install/runtime surface:** these updated distributions have
Python-only wheels; the lock package set is unchanged and these three
are the only Python package-version changes. Existing
embedding/vector/LLM dependencies still have native components, model
downloads and provider/storage network access. LangGraph SDK uses the
existing HTTP/serialization dependencies. PostHog's mandatory runtime
dependencies are requests, backoff, distro and typing-extensions;
optional async, zstd, OpenTelemetry and development/test extras are not
enabled by this update. Mem0 telemetry remains opt-out and can send
metadata/feature-flag requests to PostHog when enabled.
Exception/code-variable autocapture is not enabled by Headroom or this
change. The proof's telemetry opt-outs are test settings, not a
production-default change or a claim of blocked production egress.

The branch also carries the reviewed glob/minimatch remediation from
#4599 (now merged upstream). Its eight exact bundled advisory/path
exceptions and November 15 expiry remain unchanged.

## Real behavior proof

Windows / Python 3.12.13 with mem0ai 2.0.18, langgraph-sdk 0.4.6 and
posthog 7.79.0 explicitly installed. Actual storage proof uses
sentence-transformers/all-MiniLM-L6-v2 embeddings and temporary local
Qdrant/history storage. The existing locally installed project/embedding
dependencies were reused; this is not a claim of a fresh frozen
installation of every optional package. Model files were downloaded from
Hugging Face. No cloud credential or LLM inference request was used.

From the checkout with those exact versions and the project dependencies
installed:

```powershell
$env:PYTHONPATH='.'
python scripts/verify_mem0_tenant_scope.py
python scripts/verify_mem0_dependency_boundaries.py
python scripts/verify_mem0_agent_scope.py
```

Observed, all exit 0:

- Tenant cache: distinct identity tuples share scope key=False; other
tenant retrieved messages=0. The same storage exercise on
source-verified 2.0.5 reports True/1 and fails the isolation assertion.
Plain identifiers retain their existing keys.
- LangGraph 0.4.6 keeps the assistant/thread identifiers in encoded path
segments. Version 0.4.4 sends `/assistants/other` and
`/threads/other?query` instead and fails the path assertions.
- `MEM0_TELEMETRY=false`: no client/event created. PostHog 7.79.0
capture/shutdown sends exactly one deliberately synthetic event to the
loopback server; no event is sent to PostHog's service.
- Each of two agents retrieves exactly its own persisted memory, with
the user/agent identity and original Headroom ID restored. User listing
and filtered queries see the persisted records, while another user sees
none. `infer=False` disables LLM fact inference but retains actual
embedding, add, search, query and listing operations.

`python -m pytest tests/test_memory/test_mem0_agent_scope.py
tests/test_memory/test_direct_mem0.py
tests/test_memory/test_factory_external.py -q --no-cov -o addopts=''`:
**34 passed**, including nine red/green scope regressions. The real
storage proof was repeated with all three updated packages pinned to the
lock versions. `uv lock --check`, changed-file Ruff lint/format and
whitespace checks pass. Independent review previously found the listing
API defect, then verified its fix and reran all nine scope regressions
successfully.

The carried npm fix was separately qualified with 61 OpenCode tests,
typecheck/build, zero OpenCode audit findings, three E2E dependency
regressions on Node 24, and the exact workflow checker accepting only
eight preexisting bundled exceptions.

Untested: Mem0 cloud API, LLM fact extraction, Neo4j or hosted vector
storage, a live LangGraph deployment or event stream, PostHog
production/feature-flag delivery, sampling under load, other Python/OS
combinations, or a production rollout. The loopback tests establish the
stated identifier and transport boundaries without claiming those
external integrations were exercised.

---------

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 22:09:52 -06:00
dependabot[bot]andJerrettDavis 5e4827de12 deps: Bump the npm-minor-patch group across 1 directory with 6 updates (#4621)
Update the TypeScript SDK's development peer matrix to versions that
preserve Anthropic JSON final answers and support async OpenAI
credential callbacks through Headroom's existing adapters. With the old
locked Anthropic provider, a model in JSON-tool mode that returns final
text without calling the tool produces an empty SDK answer. With the old
OpenAI provider, an async API-key callback is rejected as a non-string.
Both behaviors were reproduced with the actual old packages, the real
Headroom middleware and compression HTTP endpoint, and a loopback
provider response.

## Dependency assessment

- **@ai-sdk/anthropic 4.0.87 -> 4.0.94:** includes the final-text
preservation fix
[e10aebb](https://github.com/vercel/ai/commit/e10aebbad661c641a5463c645272168d03a5c2f2).
Headroom must preserve assistant output rather than allowing the peer
provider to discard it in JSON mode/manual thinking. The new proof fails
on the old locked provider with `actual ''` versus `expected
'{"name":"Ada"}'`, and passes with this version. It also includes schema
handling fixes for newer Claude models; those additional models are not
claimed tested here.
- **@ai-sdk/openai 4.0.101 -> 4.0.106:** includes per-request resolution
of async credential settings
([v4.0.106](https://github.com/vercel/ai/releases/tag/%40ai-sdk%2Fopenai%404.0.106)).
The new proof calls the wrapped provider twice and observes a different
resolved bearer value each time, after passing through Headroom. The old
locked provider fails with `AI_LoadAPIKeyError: OpenAI API key must be a
string.` This qualifies the new credential functionality for the
existing middleware without adding an authentication mechanism to
Headroom.
- **@ai-sdk/provider 4.0.33 -> 4.0.35** is the shared contract used by
the updated providers. **ai 7.0.152 -> 7.0.159** is the actual
wrapLanguageModel peer used by Headroom's convenience wrapper. Qualify
that provider/AI combination together instead of treating compilation of
isolated provider packages as compatibility evidence.
- **openai 7.43.0 -> 7.46.0** and **@types/node 26.6.5 -> 26.6.6** are
retained as required current-peer compatibility coverage for Headroom,
alongside the provider fixes. The real native OpenAI chat client has a
transport check through the native Headroom adapter; the Node
declarations are checked by the SDK typecheck. These are deliberate
qualification targets for the supported peer matrix, rather than claims
that either package fixes the Vercel defects. The native client's
independent new API surfaces and Node 26 runtime behavior are not
covered by the chat/typecheck proof.
- **Maintenance/security:** Vercel maintains ai and the provider
packages, OpenAI maintains the native client, and DefinitelyTyped
maintains @types/node. The linked provider releases/source fixes and
OpenAI's 7.46.0 release were reviewed; active upstream release history
does not imply a spotless security record. Fresh SDK audit reports zero
vulnerabilities.
- **Install/runtime surface:** all six are development dependencies,
used to build/test optional peer integrations. This PR does not change
published runtime dependency or peer ranges, so consumers do not
automatically receive the provider fixes merely by installing a new
Headroom package. Compared with the prior lock, no package paths are
added/removed, no new install-script flags appear, and all resolved
tarballs remain on registry.npmjs.org. Existing esbuild/native build
tooling remains part of SDK development. The existing Vercel peer
toolchain already requires Node 22; these patches do not newly establish
that floor. Node type declarations are not shipped runtime code. OpenAI
widens the optional google-auth-library peer upper bound, but this
install does not add that optional peer. Registry installs and provider
API traffic remain network surfaces; the proof uses no real credential
and contacts no cloud model.

## Real behavior proof

Windows, Node 22.22.0, Python 3.12.13, the actual PR's package-lock
install, and the real Headroom proxy source. The local run reused an
existing native Headroom extension; it does not claim a fresh local Rust
build. The proof runs the proxy with isolated temporary workspace/config
paths, stateless storage, subscription tracking disabled, and upstream
discovery skipped. A loopback HTTP provider fixture deliberately
supplies valid API responses; it is not a live model.

```powershell
cd sdk/typescript
npm ci --ignore-scripts --no-audit --no-fund
npm run build
cd ../..
python scripts/verify_sdk_provider_peers.py
```

Observed, exit 0:

```text
PASS: real provider + Headroom middleware + real compression HTTP path preserve final JSON text without a tool call
PASS: real OpenAI provider resolves async credentials separately for both wrapped requests
PASS: native OpenAI SDK chat client completes a real HTTP request through the Headroom adapter
Real Headroom /v1/compress response: [200, 200, 200, 200]
```

The same Anthropic case on main's old lock drops the final JSON text.
Running the proof with `openai-only` against a separate old-lock
checkout reproduces the old async-credential error. No
client/model/compress function is replaced; the actual SDKs make the
HTTP requests, and all four calls pass through Headroom's real
/v1/compress endpoint with fallback disabled. The short prompts do not
trigger token reduction, so this is transport/response preservation
proof, not a compression-ratio benchmark.

Additional validation: SDK tests **406 passed, 33 skipped**; typecheck
and ESM/CJS/declaration build pass; `npm audit --json` reports zero
vulnerabilities. The Python proof passes Ruff lint/format, the Node
proof passes `node --check`, and whitespace checks pass.

Untested: live vendor credentials/models, streaming responses, async
credential failures/refresh races, actual token reduction on long
inputs, browser environments, other platforms, new native OpenAI
agent/image/organization APIs, and the 33 skipped tests. Current-head
hosted CI remains required.

---------

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-02 22:07:30 -06:00
08ed419515 ci: Bump the actions-minor-patch group with 2 updates (#4557)
The PyPI publishing workflows use `pypa/gh-action-pypi-publish` v1.14.2,
which is affected by the critical Trusted Publishing / Sigstore CA
advisory
[GHSA-5xjx-3w67-w9x9](https://github.com/pypa/gh-action-pypi-publish/security/advisories/GHSA-5xjx-3w67-w9x9).
Upgrade both publish paths to v1.14.3 so the action's certificate
bundles exclude the compromised emSign root. Also update setup-uv in
both dependency-audit paths to v10.3.2, which includes corrected
cache-error classification and newer known tool checksums. The
synchronized branch carries the reviewed glob/minimatch remediation from
#4599.

## Dependency assessment

- **PyPI publish action:** existing PyPA-maintained release tool. The
advisory lists <=1.14.2 as affected and >=1.14.3 as patched; upstream
[fix #427](https://github.com/pypa/gh-action-pypi-publish/pull/427)
updates both Certifi and Sigstore, which also bundles certificate data.
[Release
v1.14.3](https://github.com/pypa/gh-action-pypi-publish/releases/tag/v1.14.3)
also adds hash-checked runtime dependency installation. This is a
security fix for Headroom's actual artifact-upload/attestation path.
- **setup-uv:** existing Astral-maintained installer.
[v10.3.1](https://github.com/astral-sh/setup-uv/releases/tag/v10.3.1),
included in v10.3.2, fixes duplicate-cache-save warnings caused by lost
error class names; the two security audit jobs share a lock-based tool
cache and can finish concurrently. V10.3.2 includes known checksums
through uv 0.13.5. The observed hosted installation selected newer uv
0.13.6; this proof does not claim it used a prebundled 0.13.6 checksum.
- **Execution/install surface:** PyPI publishing continues to execute
PyPA's Docker-based action, with Python/native TLS support, downloaded
hash-checked Python dependencies, and network access for package upload
and Trusted Publishing/attestations. The existing release
OIDC/credential boundary is unchanged; no permission or new secret was
added. Setup-uv runs its bundled Node action, downloads the uv native
binary, and reads/writes the existing Actions cache. These are
CI/release tools, not additions to the shipped Headroom application. The
upstream security advisory is explicitly considered; no claim is made
that these projects have never had vulnerabilities.
- **Carried audit remediation:** exact #4599 glob/minimatch fix;
existing bundled npm advisory exceptions remain exact-path/version and
expire November 15.

## Real behavior proof

On Windows with Linux Docker, clone PyPA's official v1.14.3 tag and
build its Dockerfile with `docker build --tag
headroom-qualification-pypi143 .`. No upload command, publishing
credential, or OIDC token is supplied.

Run the committed `scripts/verify_pypi_action_trust.py` inside that
image using a read-only bind mount and Python as the entrypoint. It
downloads the **data** in the old Certifi 2026.7.22 wheel, verifies its
PyPI SHA-256 digest, and compares its CA roots with the action's
installed Certifi trust store. It does not install or execute the old
wheel. Observed, exit 0:

```text
installed certifi=2026.10.19
roots: old=121, new=120
removed: emSign ECC Root CA - G3, serial 3CF607A968700EDA8B84
PASS: removed emSign root certificates are absent from the action trust store
```

This validates the concrete trust-store change in the built action.
Other healthy emSign roots remain; absence of every certificate whose
name contains emSign is not the acceptance criterion.

On branch head `078a77f2c6c938dc07033a14a5c124cabbaf9b4e`, the real
setup-uv v10.3.2 dependency-audit path ran on GitHub Ubuntu 24.04 /
Python 3.12.15, installed uv 0.13.6, restored the lock-keyed cache,
exported the project dependencies and passed pip-audit:
https://github.com/headroomlabs-ai/headroom/actions/runs/41568399206/job/125695327377
. The companion package-metadata dependency audit also passed. The
subsequent local proof-script commit does not alter those
workflow/action inputs; current-head hosted qualification is still
required.

`actionlint -shellcheck= -pyflakes= .github/workflows/publish.yml
.github/workflows/release.yml .github/workflows/security.yml`,
proof-script Ruff checks and `git diff --check` pass. The carried npm
inputs match the validated #4599 fix: 61 OpenCode tests, types/build,
zero OpenCode audit findings, three E2E regressions on Node 24, and only
eight preexisting bundled advisory/path entries accepted by the exact
workflow checker.

Untested: actual PyPI/TestPyPI upload, OIDC token exchange, PEP 740
attestation issuance, production signing identity, an injected
duplicate-cache race, or other runner platforms. No release was
published. The image/trust-store proof does not substitute for a
production release or claim that its credentials were exercised.

---------

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:46:35 -06:00
Eren ŞahinandJD Davis 3d8dcf476c fix(client): close upstream responses when wrapped streams are closed (#4482)
## Description

Closing a streaming `HeadroomClient` response can leave its upstream
HTTP response open. Repeatedly closing unread streams retains
connections even after garbage collection and eventually exhausts the
connection pool.

`yield from stream` closes the generator returned by OpenAI's
`Stream.__iter__()`, rather than the original stream. Closing the
wrapper before its first iteration also skips its cleanup entirely.
Replace it with an owning iterator that closes the upstream stream and
saves metrics once on close, exhaustion, or error.

## Type of Change

- [x] Bug fix

## Changes Made

- Close the upstream source and its active iterator when distinct;
handle their cleanup independently and save metrics once.
- Add a runnable loopback reproducer for the connection and memory
measurements.

## Testing

- [x] 71 lifecycle, client, pipeline, and provider tests passed,
including 15 lifecycle tests. The OpenAI response-close tests fail
against the original implementation; two additional iterator-cleanup
tests fail against the first PR revision.
- [x] The Python pre-push suite passed: 177 passed, 4 skipped.
- [x] Ruff lint/format and `git diff --check` passed. `mypy --platform
linux headroom` passed for all 578 source files.

### Test Output

```text
71 passed in 10.81s
177 passed, 4 skipped, 1 warning in 27.62s
Success: no issues found in 578 source files
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12.12, OpenAI SDK 2.41.0, HTTPX
0.28.1.
- Exact command / steps: From this PR's checkout, run the commands
below. The
[reproducer](https://github.com/ernsahin/headroom/blob/codex/close-sdk-streams/scripts/repro_client_stream_close.py)
starts a separate loopback SSE server and fresh client processes. It
compares the original `_wrap_stream` from commit `3fef15d` with the
patched method, using the same installed dependencies and normal GC.
- Observed result: All three runs released every connection after the
fix; memory results below.
- Not tested: Live model endpoints.

```sh
uv sync --extra dev
uv run python scripts/repro_client_stream_close.py --cycles 500 --repeats 3
uv run python scripts/repro_client_stream_close.py --cycles 1001 --repeats 1
uv run python scripts/repro_client_stream_close.py --cycles 500 --repeats 3 --started --no-trace --timeout 20
```

If the checkout is shallow, first fetch the baseline with `git fetch
origin 3fef15d376d9899f77a28464e2e91f8b99514930`. Each run prints JSON
with completed requests, connection counts, RSS, and Python heap
samples. RSS is measured in the client process, excluding the server.
Exact memory figures vary by environment.

Across three fresh-process runs of 500 unread streams:

| Result | Before | After |
| --- | ---: | ---: |
| Open connections after explicit GC | 500 | 0 |
| Median client RSS increase | 7.03 MiB | 0.93 MiB |
| Median Python heap retained after GC | 3.35 MiB | 0.10 MiB |

With a 1,000-connection pool, request 1,001 failed with `PoolTimeout`
before the fix; all 1,001 completed afterward.

Closing after the first chunk also reproduced a GC cleanup deadlock
inside the HTTPcore pool lock in 3/3 runs with memory tracing disabled.
Each original-code run was stopped after 20 seconds; the fixed code
completed 500/500 cycles in every run. GC timing depends on allocations.

## Runtime Rollout Safety

- Rollout-managed feature(s): N/A; Python SDK resource cleanup.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: Closing a wrapped stream releases its
upstream response.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: No rollout-channel changes.
- Rollback path: Revert this commit.

## Review Readiness

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

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-28 23:36:10 -05:00
danieldutuandJerrettDavis 3a38d0b93b docs: drop effort-routing text that #3377 removed (#4449)
## Description

<!-- Briefly explain the change and why it is needed. -->

`python scripts/eval_output_shaper.py B` raised `AssertionError: []` at
`scripts/eval_output_shaper.py:201`. Scenario B asserted
`body["output_config"]["effort"] == "low"` after `shape_request`, and
`shape_request` returned no labels.

Root cause: #3377 (`1390d897`) deleted `output_effort_policy.py` and the
`effort_router` config, so the shaper no longer changes
`output_config.effort`, `reasoning.effort` or `thinking.budget_tokens`.
The text around it was not updated. 17 lines mentioning effort routing
remained in 9 files: `README.md:186-192`,
`headroom/proxy/output_shaper.py:12-22,103-104,196`,
`headroom/proxy/thinking_tokens.py:4`,
`headroom/proxy/outcome.py:127,253`,
`headroom/proxy/handlers/anthropic.py:124,3651`,
`headroom/proxy/handlers/openai.py:834`,
`headroom/agent_savings.py:176`, `headroom/proxy/server.py:6511` and the
eval script. @HetCreep reported the stale text in #4421 and listed most
of these locations. I started from that list and found
`agent_savings.py:176`, `server.py:6511` and `anthropic.py:124` by grep.

Fix: I removed the effort-routing bullet and the `reasoning_effort` /
`output_config.effort` paragraph from the README, and docstring item 2
plus the `output_config.effort` safety rule from `output_shaper.py`. I
deleted two cache-mode sentences that said effort routing stays on in
cache mode, and reworded the other comments. I dropped Scenario B from
the eval script (66 lines).

Boundary: no runtime code changed and `CHANGELOG.md` is untouched. I did
not re-implement effort routing; #3377 removed it on purpose and the
issue asks for docs only. I deleted Scenario B instead of rewriting it
to assert that effort stays `xhigh`, because
`tests/test_output_shaper.py:185` already asserts that. Question for
maintainers: do you want that assertion kept in the script as well? I
will split the script change into its own PR if you prefer.

Closes #4421

## 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)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `README.md`: removed the effort-routing bullet and the
`reasoning_effort` / `output_config.effort` paragraph.
- `headroom/proxy/output_shaper.py`: removed docstring item 2, the
`output_config.effort` safety rule and two cache-mode comments.
- `headroom/proxy/thinking_tokens.py`, `outcome.py`,
`handlers/anthropic.py`, `handlers/openai.py`, `agent_savings.py`,
`server.py`: comment and docstring wording only.
- `scripts/eval_output_shaper.py`: removed Scenario B.

## Testing

<!-- Check what you actually ran, then paste the real command output
below. -->

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`) — not run
- [ ] New tests added for new functionality — none added, no behavior
change
- [x] Manual testing performed

### Test Output

```text
$ uv run pytest -q tests/test_output_shaper.py tests/test_thinking_tokens.py tests/test_outcome_token_scale.py tests/test_output_shaper_responses.py tests/test_openai_responses_output_shaper.py
117 passed, 1 warning in 21.78s
$ uv run ruff check .
All checks passed!
$ uv run ruff format --check .
1812 files already formatted
$ ANTHROPIC_API_KEY=dummy uv run python scripts/eval_output_shaper.py B
exit=0
```

The pytest run covers the five test files that touch the output shaper.
I did not run the full suite. The one warning is a Starlette `httpx`
deprecation from `fastapi/testclient.py` in site-packages.

## Real Behavior Proof

- Environment: macOS 27.0.1, Python 3.12.13, `uv sync --extra dev
--extra proxy`, `ANTHROPIC_API_KEY=dummy` (no network call)
- Exact command / steps: before the patch (`e995eb9f`)
`ANTHROPIC_API_KEY=dummy python scripts/eval_output_shaper.py B` in a
venv with `anthropic`; after the patch `ANTHROPIC_API_KEY=dummy uv run
python scripts/eval_output_shaper.py B`; after the patch `grep -rniE
"effort.rout|effort router|effort-router" README.md headroom scripts`
- Observed result: before, `AssertionError: []` at
`scripts/eval_output_shaper.py:201`, exit 1; after, exit 0 with the
header `model=claude-opus-4-8 trials=2` and an empty table, because `B`
now matches no scenario and the script makes no API call; the grep
returned 0 lines after the patch and 17 lines at `e995eb9f`
- Not tested: a live Anthropic run of Scenario A (no API key), the full
pytest suite, `mypy headroom`, Windows and Linux

## Runtime Rollout Safety

- Rollout-managed feature(s): none, no runtime code changed
- Minimum rollout channel: n/a, no runtime change
- Stable/default behavior changed: no, comments, docstrings, README and
one eval script only
- Kill switch / disable path: n/a, no behavior added
- Unsafe override required: no
- Qualification impact: none, docs and comments only
- Rollback path: `git revert` of the single commit

## Review Readiness

- [x] I have performed a self-review
- [ ] 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
— no code added
- [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 — none added, no behavior change
- [ ] New and existing unit tests pass locally with my changes — 5 test
files ran, full suite not 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)

None. No UI change.

## Additional Notes

The README now states that the shaper applies verbosity steering to
`/v1/messages`, `/v1/chat/completions` and `/v1/responses` with the same
`output_shaper:*` labels. I kept that sentence from the removed
paragraph because it still holds.

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-24 08:44:57 -07:00
7b6cb77905 fix(install): keep the HuggingFace cache on a writable mount in Docker presets (#4207) (#4209)
## Description

With the `persistent-docker` preset, Kompress never loads. The container
runs as the host user (`--user 501:20`) with `HOME=/tmp/headroom-home`,
but the image never creates that directory. Docker creates it as
`root:root 0755` to hold the bind mounts, so the proxy cannot create
`~/.cache` and the HuggingFace download of the Kompress model fails with
`Permission denied (os error 13)`. The log never shows that error: it
reports a missing dependency instead (`Kompress requires onnxruntime or
torch`), pointing the operator at reinstalling extras that are already
present.

Fix: point `HF_HOME` and `XDG_CACHE_HOME` at the bind-mounted,
host-owned `.headroom` workspace so the cache is writable regardless of
who Docker made the container's `$HOME`; and keep the underlying
`OSError` in both `kompress_compressor.py` log sites instead of masking
it.

Closes #4207

## 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/install/runtime.py`: `build_runtime_command()` now emits
`HF_HOME` and `XDG_CACHE_HOME` as real `--env` flags pointing under the
bind-mounted `.headroom` workspace (`<container_home>/.headroom/cache`),
and applies them to the persistent-container args path, not only the
dev/foreground path.
- `headroom/install/runtime.py`: added `_append_cache_env()` and wired
it through both command builders.
- `scripts/install.sh` and `docker/docker-compose.native.yml`: set
`HF_HOME`/`XDG_CACHE_HOME` under the writable `.headroom` mount for the
same preset.
- `headroom/transforms/kompress_compressor.py`: `_create_onnx_session()`
appends the underlying cause to its `No loadable ONNX artifact` message;
`_load_kompress()` re-raises the real ONNX failure (chained) instead of
reporting a missing dependency when onnxruntime is present but loading
failed.

## Testing

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

### Test Output

```text
$ .venv/bin/python -m pytest tests/test_install/ tests/test_kompress_failsafe.py -q
278 passed, 11 skipped, 1 failed

The single failure is tests/test_install/test_runtime.py::test_build_runtime_command_lets_the_host_dashboard_read_its_data
which fails with ImportError: FastAPI required in this environment. It fails identically on unmodified main here,
so it is a local environment gap, not this change.

New regression tests, all passing:
- test_build_runtime_command_keeps_hf_cache_on_the_writable_mount
- test_build_runtime_command_persistent_path_keeps_hf_cache_on_the_writable_mount
- test_no_loadable_artifact_message_carries_the_underlying_error
- test_onnx_failure_while_onnxruntime_available_reports_the_real_error
- test_missing_dependency_still_reports_install_hint

$ bash -n scripts/install.sh          # clean
$ python -c "import yaml,sys;yaml.safe_load(open('docker/docker-compose.native.yml'))"   # clean
```

## Real Behavior Proof

- Environment: Linux, Python venv at `.venv`, repo at this branch. No
Docker daemon available on this machine.
- Exact command / steps: `pytest tests/test_install/
tests/test_kompress_failsafe.py -q`; asserted the generated `docker run`
argv from both `build_runtime_command()` and
`build_persistent_container_args()` contains `--env HF_HOME` / `--env
XDG_CACHE_HOME` pointing under the `.headroom` mount.
- Observed result: all new tests pass; both argv builders now emit the
cache env pointing at the writable host-owned mount.
- Not tested: the end-to-end container run from the issue's reproduction
steps — no Docker daemon here. The fix is verified at the level of the
generated `docker run` argv and the unit tests above.

## Runtime Rollout Safety

- Rollout-managed feature(s): Kompress proxy model loading under the
`persistent-docker` preset.
- Minimum rollout channel: all channels that use the persistent-docker
preset; the change only affects env vars for cache directories.
- Stable/default behavior changed: no. Default (non-persistent) paths
are unchanged; persistent paths gain two `--env` flags pointing at an
existing writable mount.
- Kill switch / disable path: unset/override `HF_HOME`/`XDG_CACHE_HOME`,
or run without the persistent-docker preset.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert this commit; the preset returns to the previous
(broken) cache behavior.

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

## Additional Notes

- Docs untouched: no user-facing docs describe
`HF_HOME`/`XDG_CACHE_HOME` for this preset, so no documentation change
was needed (hence the unchecked box).
- No lint/type-check run: `ruff`/`mypy` are not installed in this
environment.
- No Docker daemon available, so the container-level e2e reproduction
was not executed — flagged under "Not tested" above.

---------

Co-authored-by: Shivam Maurya <shivam@programmingwithmaurya.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
Co-authored-by: JerrettDavis <jerrett@headroomlabs.ai>
2026-10-24 08:38:28 -07:00
5698e91b2a chore(security): beacon rate limit, dev environment, weekly CodeQL triage (#4008)
SOC 2 follow-ups from the 2026-10-06 firewall review (R3, R4) and
incident INC-2026-001.

## Beacon rate limit (R3)
`deploy/beacon/wrangler.toml` said a WAF rule limited `/v1/logs` to 60
req/min/IP. That rule could not exist: headroomlabs.ai is not a
Cloudflare zone, so the Worker is only on `workers.dev`. This adds a
[Workers rate-limit
binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/)
checked in `fetch()` **before** the body is read.

- Keyed on one constant, not the IP: the Worker still never reads
`cf-connecting-ip` (privacy promise in the file header). Trade-off: a
flood also sheds real events for that minute.
- 3000 req/min **per Cloudflare location** (~10x today's ~300/min
total).
- Returns 429, which the client does **not** treat as a gzip refusal
(`_GZIP_REFUSED_STATUSES` is 400/415), so rate-limited clients keep
compressing.
- Fails open if the binding is absent **or the limiter itself errors**
(review fix): a rate-limit service outage lets beacons through rather
than dropping all of them. `node deploy/beacon/test-rollup.mjs` covers
429 over the limit, fail-open on outage and when unbound, and the single
shared key.

## Dev environment (R4)
`[env.dev]` deploys `headroom-beacon-dev` bound to the new
`headroom-telemetry-dev` bucket (600/min limit). Already deployed and
tested: a sample event returns 204, and a 2,500-request burst got 384 ×
429.

## Weekly CodeQL triage
`.github/workflows/codeql-triage.yml` opens an issue every Monday,
assigned to @chopratejas (tejas@headroomlabs.ai), listing open
critical/high alerts with checkboxes. Alert #63 sat unowned for five
months; this gives alerts an owner and leaves an audit trail.

**One issue per week, however often it runs (review fix).** The logic is
in `scripts/codeql_triage.sh`:
- It keys the issue on the ISO week, using a hidden marker in the body.
- It finds the existing issue by listing security-labelled issues,
closed ones included. It uses a listing, not search, so an issue created
seconds earlier is not missed.
- It reuses that issue and never edits, reopens or retitles it, so
ticked boxes and closure stand. Alerts opened since then are added once,
as a comment.
- The jq programs live in quoted heredocs, which clears ShellCheck
SC2016 without any shell expansion.
- `tests/test_codeql_triage_script.py` runs the real script against a
fake `gh`. It covers same-day re-runs, a Friday dispatch on a closed
issue with ticked boxes, the next week, and the ISO year boundary
(2027-01-01 is in 2026-W53).

### Test output

```text
$ pytest -q tests/test_codeql_triage_script.py
6 passed
$ node deploy/beacon/test-rollup.mjs
rate limit: 429 over, fail-open on outage and when unbound
ok
$ shellcheck scripts/codeql_triage.sh && actionlint .github/workflows/codeql-triage.yml
(clean)
```

## ⚠️ Before deploying production
The live `headroom-beacon` Worker predates #3253 (gzip inflate, schema
v2 allowlist). `wrangler deploy` from main will ship that too, not just
this change.

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4008"
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 11:18:47 -07:00
Tejas ChopraandClaude Opus 5.5 a88e2d5145 fix(security): resolve 23 open CodeQL alerts (#4045)
## Description

CodeQL had 43 open alerts on `headroom` (19 high, 24 medium). We need 0
for SOC 2 (risk R-10: developers introduce vulnerabilities). This PR
fixes the 23 that are real problems in code we ship or run. The 16 in
`tests/` are handled by #4047. 11 were dismissed in GitHub with written
reasons: 7 stale alerts from the retired default-setup scan, and 4 false
positives (#21, #105, #109, #135).

**In plain words:**
1. **Error replies no longer include internal error text.** When a
request body couldn't be read, the proxy sent back Python's raw error
message. It now sends a fixed message that still says what kind of
problem it was.
2. **A benchmark no longer logs a possible API key.** `--model_args` is
shown as `<redacted>` in the log, but `lm_eval` still receives the real
value.
3. **A test no longer prints part of the Gemini API key.**
4. **Five workflows declare read-only permissions**, and CodeQL scans
GitHub Actions workflows again.
5. **The npm release scripts no longer pass arguments through Windows
`cmd.exe`**, which reinterprets `&` and `|` inside arguments, file paths
included.

Closes CodeQL alerts #20, #23, #24, #25, #26, #27, #28, #29, #31, #33,
#193 (stack-trace exposure), #177, #51, #145, #146, #147. The
workflow-permission fixes correspond to the dismissed #2, #7, #67, #85,
#86, #87, #125.

## 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/proxy/helpers.py`:
- New `invalid_request_body_message(exc)` returns a fixed string per
error type and logs the type:
    - `…: malformed JSON`
    - `…: not valid UTF-8 (possibly compressed?)`
    - `…: must be a JSON object`
    - `…: too large`
    - plain `Invalid request body` for anything else
- New `RequestBodyNotObject(ValueError)` replaces a bare `ValueError`,
so every existing `except ValueError` still catches it.
- `headroom/proxy/handlers/{anthropic,openai,gemini,batch}.py`:
  - All 10 `f"Invalid request body: {e!s}"` replies now use the helper.
- The Google batch forwarder's 500 reply drops the exception text; it
was already logged on the line above.
- `headroom/evals/comprehensive_benchmark.py`: `--model_args` is
appended after the command is logged, and the log line shows it as
`<redacted>`.
- `tests/test_google_multimodal_e2e.py`: stops printing the first 10
characters of the API key.
-
`.github/workflows/{devcontainers,eval,init-e2e,init-native-e2e,wrap-e2e}.yml`:
top-level `permissions: contents: read`. None of these jobs write to the
repo; caching and artifact upload don't use the repo token.
- `.github/workflows/security.yml`: CodeQL matrix adds `actions`.
- `scripts/{build,verify}_npm_release_assets.mjs`:
- On Windows, npm runs as `node <npm-cli.js> …` instead of `cmd.exe /c
npm.cmd …`.
- `npm-cli.js` is found via `npm_execpath`, then next to node, then
beside each `npm.cmd` on PATH. This handles node and npm in different
directories, per Devin's review.
  - If none is found, it fails listing every path searched.
- New tests:
  - `tests/test_invalid_request_body_message.py`
- `tests/test_evals/test_comprehensive_benchmark_log_redaction.py`, per
Devanshi's review.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`): one error remains, the
same one `main` has, in an untouched file. See notes.
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q tests/test_release_workflows.py tests/test_invalid_request_body_message.py \
    tests/test_evals/test_comprehensive_benchmark_log_redaction.py
============================== 62 passed in 3.10s ==============================

# The redaction test against the pre-fix comprehensive_benchmark.py (origin/main):
========================= 1 failed, 1 passed in 0.50s ==========================
# With the fix:
============================== 2 passed in 0.57s ===============================

$ pytest -q (proxy/handler/batch/eval/request-body files, run one file at a time)
187 files: 182 OK; the 5 below fail or hang identically on unchanged origin/main:
  tests/test_proxy_uds.py                          11 failed  (macOS 104-byte sun_path limit)
  tests/test_anthropic_buffered_ccr_usage.py        6 failed
  tests/test_proxy_copilot_auth_hooks.py            2 failed
  tests/gateway/test_parity_proxy_vs_gateway.py     2 failed
  tests/test_cli_proxy_improvements.py             hangs >300s

$ ruff check . -q                      -> clean
$ ruff format --check headroom tests   -> clean
$ mypy headroom
headroom/integrations/langchain/chat_model.py:394: error: Function "RunnableBinding" could always be true in boolean context  [truthy-function]
Found 1 error in 1 file (checked 566 source files)   # identical on origin/main

$ node --check scripts/build_npm_release_assets.mjs && node --check scripts/verify_npm_release_assets.mjs  -> ok
```

CI: the `test (3)` failures (`tests/test_onnx_dependency_contract.py`, 5
tests) and `test (4)` failures (`tests/test_xai_cache_economics.py`, 5
tests) also fail on `main`'s latest CI run (run 37806990929), so they're
unrelated to this PR.

## Real Behavior Proof

- Environment: macOS 26 (arm64), Python 3.12.13, Node 24, npm 11.19.0.
Worktree of `origin/main` at 87e05b68 plus this branch.
- Exact command / steps: the three checks below.
1. **Error replies:** `invalid_request_body_message` was exercised with
each exception type, including a `JSONDecodeError` whose document is
`"secret-doc"`. Each case asserts the reply names the category and
contains neither the exception text nor the document.
2. **Benchmark:**
`run_lm_eval(model_args="model=gpt-4o-mini,api_key=sk-test-FAKE-…")` was
called with the subprocess call mocked. The log shows `--model_args
<redacted>` and not the fake key, while the mocked call received
`model=gpt-4o-mini,api_key=sk-test-FAKE-…,base_url=http://localhost:8787/v1`.
3. **Windows npm lookup:** `findNpmCli()` was extracted from each script
and run against a temporary layout reproducing Devin's case: node shim
in `dev/bin`, `npm.cmd` plus `node_modules/npm/bin/npm-cli.js` in
`Program Files/nodejs`, both on PATH.
- Observed result: all three Windows npm lookup cases pass in both
scripts (output below); checks 1 and 2 pass as shown in Test Output.
  ```text
  == scripts/build_npm_release_assets.mjs
  separate node/npm dirs -> found npm-cli.js beside npm.cmd on PATH
  npm_execpath set       -> uses npm_execpath
  missing npm            -> clear error: true
  == scripts/verify_npm_release_assets.mjs
  separate node/npm dirs -> found npm-cli.js beside npm.cmd on PATH
  npm_execpath set       -> uses npm_execpath
  missing npm            -> clear error: true
  ```
- Not tested: the two items below.
- A real Windows run of the release scripts. No Windows machine was
available, and CI runs these scripts on Ubuntu, where the code path is
unchanged (`npm` spawned directly, no shell).
- The new CodeQL `actions` scan. It runs on this PR's CI and on `main`
after merge.

### Maintainer verification at `128f271f` (2026-10-08)

- Environment: actual Windows 11, Python 3.12.13, Node 22.22.0, npm
10.9.4. Contributor logic unchanged; this head contains current `main`.
- Commands: the focused `test_invalid_request_body_message.py`,
`test_comprehensive_benchmark_log_redaction.py`, and
`test_release_workflows.py` suites; the existing Windows npm lookup
probe against both checked-in scripts; and a two-process-boundary
loopback uvicorn/httpx malformed-body probe against this head.
- Observed: **62 focused tests passed**. Both npm scripts invoked the
real npm CLI under Node with `shell:false`, including Node copied into a
separate `G:/tmp/headroom-review/resume49-node shim & literal` directory
while npm remained under `C:/Program Files/nodejs`; `npm_execpath` was
unset, so PATH lookup found the separate npm installation. npm reported
10.9.4 and a cache argument containing spaces and `&` was preserved
literally. **36 actual TCP requests** (four malformed-body categories
across nine endpoints) returned the expected fixed 400 messages, with no
private marker disclosed and no upstream requests. Only outbound
provider requests were replaced with a fail-if-called boundary; HTTP
parsing and proxy handlers were real.
- Hosted qualification at this exact head: **67 passed, 11 skipped**,
including all three CodeQL languages. Evidence is retained in the
maintainer review artifacts. The earlier simulated Windows-layout proof
remains below as historical author evidence.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: yes, the text of 400 replies for
unreadable request bodies. It was `Invalid request body: <python
exception text>` and is now a fixed category message. Status codes,
error `type`/`code` fields and response shape are unchanged. Clients
that parse the free-text message, rather than the status and type, would
see different text.
- Kill switch / disable path: none needed; this is message text only.
- 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
- [ ] I have made corresponding changes to the documentation (none
needed)
- [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`

## Additional Notes

- Review feedback addressed in 921de19b: 
- Devin: Windows npm lookup when node and npm are in different
directories.
  - Devanshi: benchmark redaction test.
- **#21 (`security_block` reply in `anthropic.py`) is left as is.** It
returns the security plugin's deliberate, user-facing reason for
blocking a request. It was dismissed as a false positive with that
reason.
- The `mypy` error is pre-existing: the same `truthy-function` error
appears on `origin/main`, in a file this PR doesn't touch.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 22:40:04 -05:00
JD Davis 3f990663cc fix(release): synchronize editable uv lock version (#4054)
## Description

Full version synchronization changes pyproject.toml but previously left
the editable root package version in uv.lock unchanged. Locked uv
installs then reject regenerated release branches. #4002 demonstrated
this again when release-please regenerated from main and discarded its
manual lock repair and automation commit.

Move the durable automation repair into main through this dedicated PR.
Release-please can inherit it after merge rather than repeatedly
dropping a change made only on its generated branch. Current commit:
f61cd097d (comment punctuation follow-up; functional code unchanged).

## Type of Change

- [x] Bug fix (release lock synchronization)

## Changes Made

- Update exactly the editable source="." root package's version during
full version synchronization.
- Preserve all third-party lock entries without resolving dependencies.
- Keep plugin-only synchronization from touching Python/lock metadata.
- Add a byte-preservation regression with a third-party package sharing
the old version.

## Testing

- [x] 81 focused version-sync/release-version/release-workflow tests
passed on current main 17abee272.
- [x] Scoped Ruff lint, format and whitespace checks passed.
- [x] Actual full-sync CLI and uv locked-check replay passed.

```text
81 passed in 5.42s
All checks passed!
2 files already formatted
```

The regression's original red/green evidence is retained from #4002:
full sync left the editable root at 0.5.25 before repair and correctly
updated it to 0.7.0 after repair while same-version third-party bytes
remained unchanged. Plugin-only control passes.

## Real Behavior Proof

- Environment: Windows, current-main checkout with the actual uv.lock,
uv and the real scripts/version-sync.py command. No dependency resolver
substitution.
- Exact command / steps: Run python
G:/git/headroom/.remember/tmp/resume36-lock-sync-runtime.py.
Independently replace only the editable headroom-ai root version with
0.0.0 while project metadata stays 0.40.0; run uv lock --check; run
python scripts/version-sync.py; rerun uv lock --check and compare the
full lock bytes to the original.
- Observed result: The stale root was rejected; full CLI synchronization
repaired it; the locked check passed and every lock byte matched the
original. Existing generated Windows manifest newline noise was restored
before publication; only script/tests change.
- Not tested: Full locked environment installation, release/tag
creation, npm/PyPI publication or external rollout. Exact-head hosted
checks are terminal: 52 successes, 16 intended skips, and 46
duplicate-run cancellations; successful matching workflow runs are
verified below. The repair takes effect for release-please regeneration
only after this PR reaches main.

```text
PASS red: actual uv lock --check rejects stale editable root
Version synchronized to 0.40.0
PASS green: full CLI sync repairs root; uv lock --check passes; complete lock bytes match original
```

## Runtime Rollout Safety

- Rollout-managed feature(s): Release metadata only; no runtime feature.
- Minimum rollout channel: No new channel requirement.
- Stable/default behavior changed: Full version-sync now aligns the
editable uv.lock root; dependencies and plugin-only synchronization
retain their existing behavior.
- Kill switch / disable path: Do not invoke version synchronization; no
runtime toggle applies.
- Unsafe override required: No.
- Qualification impact: Local metadata checks cover the two-file repair.
Release packaging/publication remains separately gated.
- Rollback path: Revert this script/test change, restoring the known
stale-lock limitation.

## Review Readiness

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

Independent review is required. No merge, release, publication or
self-approval performed.


Exact-head qualification for f61cd097d7:
all checks are terminal, with 52 successes and 16 intended skips. The
remaining 46 cancelled checks belong to duplicate runs of the same SHA;
corresponding complete successful workflow runs exist. Verified
successful runs: CI 37838252441, Security 37838252409, rust 37838252460,
Release 37838252963, Merge Conflicts 37838252937, Changelog Guard
37838252468 and PR Governance 37838907358. No failed or live checks
remain. The sole review thread is resolved.

The local full-sync/uv locked-check and byte-preservation proof remains
applicable; the last commit only repairs comment punctuation. This
provides the durable main-branch repair that #4002's generated release
branch still lacks. Release-please cannot inherit it until this PR
merges; future regeneration may discard #4002's manual repair before
then. Independent review is still required. No merge, self-approval,
release or publication performed.
2026-10-08 22:37:38 -05:00
17abee2721 feat(plugins): add headroom-snip Claude Code mod that animates compression (#3980)
## Description

Adds `headroom-snip`, a Claude Code plugin that shows what Headroom does
to each request while you work. Headroom's savings are mostly invisible
from inside Claude Code; this puts them right above the prompt.

- **Band above the prompt:** for each new request through the proxy, a
scissors animation cuts a bar the size of the original prompt down to
what was sent (`21k → 4.1k tok −81%`). It names the compressors that did
the cutting (JSON crush, code AST, Kompress text, log squash, cache
align, …) and the running total since the session started. When a
request goes through unchanged it says why (for example `kept: user
message, recent code`).
- **`/headroom`:** opens a pane with the per-request log since the
session started: bar, what was cut and what was kept, compression
latency, biggest snip, all-time total. `/headroom hide` and `/headroom
show` toggle the band.
- **Status line** running total, and toasts at savings milestones.
- If the proxy isn't reachable, the band says so and suggests `headroom
wrap claude`.

It reads the proxy's existing loopback `GET /stats?cached=1`
(`recent_requests`), polling once a second only while a turn runs and
for a few seconds after. Requests stamped before the session started are
not counted. Under `headroom wrap claude` (which sends
`X-Headroom-Project`), only requests the proxy tagged with this
session's project count, and the totals are labelled as that project's
traffic since the session started (the tag is the launch directory's
basename, so other sessions in the same project are included); otherwise
they are labelled proxy-wide. There is no per-session request identity
at the proxy, so nothing is labelled as a per-session total. No proxy
changes; nothing leaves the machine. Proxy URL: `HEADROOM_PROXY_URL`,
else `ANTHROPIC_BASE_URL`, else `http://127.0.0.1:8787`. Each candidate
must be a loopback URL (http or https on exactly `localhost`,
`127.0.0.1` or `[::1]`, no userinfo); anything else is skipped, so the
plugin never polls a remote host.

## Spec

**API surface:** a Claude Code plugin (`headroom-snip` in
`.claude-plugin/marketplace.json`). The `/headroom` command, with `hide`
and `show`. Reads the `HEADROOM_PROXY_URL`, `ANTHROPIC_BASE_URL` and
`ANTHROPIC_CUSTOM_HEADERS` environment variables. No proxy, CLI or
library changes.

**Changes to existing behavior:** none. The `headroom` plugin and the
Copilot marketplace are untouched.

**User stories:**
- *Golden path.* Given Claude Code launched with `headroom wrap claude`
and the plugin installed, when a turn sends a request the proxy
compresses, then within about a second the band animates that request's
original → sent tokens and names the compressors, and `/headroom` lists
it newest first.
- *Edge case: proxy not running.* Given the plugin is installed but
nothing answers at the proxy URL, when a turn runs, then the band says
Headroom isn't in the loop and suggests `headroom wrap claude`, and
nothing else changes.
- *Edge case: shared proxy.* Given two clients on one proxy, when the
other client sends a request, then a wrapped session leaves it out
(different project tag), and an unwrapped session counts it but labels
its totals "proxy".
- *Edge case: two sessions in one project.* Given two wrapped Claude
Code sessions launched from directories with the same name, when either
sends a request, then both sessions count it, and the band says
"project" and the pane and toasts name the project, never "session".

**Failure modes:** proxy down or slow (the band shows the not-running
message, and requests are recovered when it comes up); a malformed
`/stats` body (ignored); a non-loopback proxy URL (skipped, falls back
to the default); a request without a timestamp (counted only if it
appears after the first successful poll).

**Recovery / resilience:** no state outside Claude Code; running totals
live in plugin state and survive a plugin reload. Disable with `claude
plugin disable headroom-snip@headroom-marketplace`.

**Security considerations:** see Additional Notes.

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which 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

- `plugins/headroom-snip/`: the plugin (`hooks/register.tsx` for hooks
and drawing, `hooks/snip.ts` for parsing, the loopback URL policy,
transform labels and animation frames), its state types, tests and
README.
- `.claude-plugin/marketplace.json`: lists `headroom-snip`, installable
with `claude plugin install headroom-snip@headroom-marketplace`. It is
**not** added to `.github/plugin/marketplace.json`, because Copilot CLI
can't load Claude Code function hooks.
- `tests/test_plugin_manifests.py`: the two marketplaces must still
match apart from Claude-Code-only plugins. A new test checks each such
plugin's manifest name, version and `hooks/hooks.json`.
- `scripts/version-sync.py`, `scripts/verify-versions.py`: the new
`plugin.json` version is synced and verified with the rest (0.39.1).
- `scripts/tests/test_version_sync.py`: fixture and assertion for the
new manifest.

## Testing

- [x] Unit tests pass (`pytest`): the manifest and version-sync tests
touched here
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`): N/A, no changes under
`headroom/`
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q tests/test_plugin_manifests.py scripts/tests/test_version_sync.py
16 passed, 1 warning in 0.60s

$ ruff check tests/test_plugin_manifests.py scripts/
All checks passed!
$ ruff format --check tests/test_plugin_manifests.py scripts/
27 files already formatted

$ python scripts/verify-versions.py
All versions aligned at 0.39.1

$ claude plugin validate plugins/headroom-snip
✔ Validation passed

$ claude plugin test plugins/headroom-snip
(pass) proxy url follows the wrapped base url only when it is local
(pass) valid loopback urls keep their origin
(pass) hosts that only look local are never polled
(pass) userinfo, other schemes and junk are refused even on loopback
(pass) a remote override falls back to the local base url, not the remote host
(pass) transforms read as plain words
(pass) the finished bar keeps the sent share and dusts the rest
(pass) rows come back oldest first, with their project tags
(pass) the session project is read from the wrapped custom headers
(pass) a request is this session's by its stamp and project
(pass) every milestone a step crosses is announced, lowest first
(pass) a request made during a turn is snipped in the band
(pass) two new requests in one poll show the newest in the band and newest first in the pane
(pass) a proxy that comes up after the session started still counts the session's requests
(pass) with a project header, other clients on the proxy are left out
(pass) two sessions in one project share a count, and every label says project, not session
(pass) one big snip announces each milestone it crosses
(pass) polling picks up a request that lands just after the turn, then stops
 18 pass
 0 fail
```

The plugin tests are a bun-style suite run by `claude plugin test`. They
fake the proxy's `/stats` response (newest first, as the proxy sends it)
and check what the band and the `/headroom` pane draw: original → sent
figures, percentages, compressor labels, totals and their project/proxy
label (including two sessions sharing one project tag), newest-first
ordering when one poll brings several requests, a proxy that comes up
mid-session, filtering by project tag, a toast for each milestone
crossed, polling that continues briefly after a turn and then stops, the
hide button and the no-proxy message. Each of the four review fixes was
checked by restoring the old behaviour: its tests fail. The plugin also
type-checks clean under `tsc` against Claude Code's plugin API types
(strict, `noUncheckedIndexedAccess`).

## Real Behavior Proof

- Environment: macOS, iTerm2, Claude Code 2.1.289, local Headroom proxy
- Exact command / steps: `headroom wrap claude --plugin-dir
plugins/headroom-snip`, then ran prompts that read large tool output
(`ls -la /usr/lib`, `cat package-lock.json`), then ran `/headroom`
- Observed result: the band animated the snip for each compressed
request with original → sent tokens and compressor labels; `/headroom`
listed the requests since the session started
- Not tested: Claude desktop app and VS Code surfaces against a live
proxy (covered only by the `desktop` surface in the plugin tests);
terminals other than iTerm2

## Runtime Rollout Safety

- Rollout-managed feature(s): none. This is an opt-in Claude Code
plugin; nothing in the proxy or `headroom` package changes.
- Minimum rollout channel: N/A. It reaches only users who run `claude
plugin install headroom-snip@headroom-marketplace`.
- Stable/default behavior changed: no. Existing installs, the `headroom`
plugin and the Copilot marketplace are unchanged.
- Kill switch / disable path: `claude plugin disable
headroom-snip@headroom-marketplace` (or `uninstall`); `/headroom hide`
hides the band.
- Unsafe override required: no.
- Qualification impact: none on proxy compression or latency. The plugin
makes one cached loopback `GET /stats?cached=1` per second while a turn
runs.
- Rollback path: revert this PR, which removes the plugin and its
marketplace entry; installed copies can be uninstalled as above.

## Review Readiness

- [x] I 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 own 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
- [ ] I have updated the CHANGELOG.md if applicable: N/A, release-please
generates it from the PR title

## Additional Notes

- **Security considerations:** read-only. The plugin only sends `GET`
requests to the proxy's existing loopback `/stats` endpoint, which
already returns per-request metadata only to loopback callers. Proxy
URLs are parsed and must name exactly `localhost`, `127.0.0.1` or
`[::1]` over http(s) with no userinfo; look-alike hosts
(`localhost.example.com`, `127.0.0.1.example.com`,
`localhost@example.com`) and remote overrides are refused, with
regression tests. It sends no data elsewhere and changes nothing in the
proxy.
- Follow-up idea, not in this PR: a pixel-art mascot, and showing when
Claude retrieves stashed originals (CCR, `/v1/retrieve/stats`) as
visible proof that nothing cut is lost.

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-08 14:22:21 -05:00
c195a1220f fix(install): keep an explicitly empty dashboard allowlist on Windows PowerShell 5.1 (#4012)
## Description

On Windows PowerShell 5.1, the persistent Docker install ignores an
explicitly empty `HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` and
trusts the Docker bridge gateway anyway.

`Add-DashboardGatewayEnv` is meant to skip its gateway default whenever
the variable is set, including set to an empty string. That empty case
is the documented way to opt out, and
`test_powershell_native_installer_supports_persistent_docker_lifecycle`
asserts it. The function checks with `Test-Path Env:...`. But
`Get-PassthroughEnvArgs` enumerates `Env:` first, and once that has
happened Windows PowerShell 5.1 reports an empty variable as **unset**
through both `Test-Path` and `[Environment]::GetEnvironmentVariable`.
The enumeration itself still lists it. The result is that `docker run`
gets both arguments:

```
--env HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS                 # passthrough of the empty value
--env HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32   # gateway default, wins
```

Standalone repro in Windows PowerShell 5.1, with a variable inherited as
empty from the parent process:

```
first, in function     Test-Path=True  GetEnvVar!=null=True  Contains=True
after Get-ChildItem    Test-Path=False GetEnvVar!=null=False Contains=True
```

CI's `windows-native-wrapper` job doesn't catch this because
`_powershell_executable()` prefers `pwsh`, which is unaffected. Windows
PowerShell 5.1 is still what a stock Windows install runs as
`powershell`.

The bash installer already gets this right
(`${HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS+x}`).

## 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

- `scripts/install.ps1`: `Add-DashboardGatewayEnv` now finds the
variable through the same `Get-ChildItem Env:` enumeration that
`Get-PassthroughEnvArgs` uses, so the gateway default is skipped exactly
when the passthrough forwards the caller's value.
- `tests/test_install/test_native_installers.py`: new
`test_powershell_dashboard_gateway_default_respects_explicit_allowlist`.
It AST-extracts both functions from the wrapper template, the same
approach as the existing `Ensure-PathEntry` harness, and runs them in
installer order with `docker` stubbed. It's parametrized over
`powershell` and `pwsh` × unset / configured / explicitly empty, so CI's
Windows runner now covers 5.1 as well.

## Testing

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

### Test Output

Before the fix (Windows PowerShell 5.1):

```text
test_powershell_dashboard_gateway_default_respects_explicit_allowlist[unset-windows-powershell] PASSED
test_powershell_dashboard_gateway_default_respects_explicit_allowlist[configured-windows-powershell] PASSED
test_powershell_dashboard_gateway_default_respects_explicit_allowlist[explicitly-empty-windows-powershell] FAILED
E   assert ('HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32' in [...]) is False
```

The existing end-to-end test fails on `main` under 5.1 for the same
reason:

```text
FAILED tests/test_install/test_native_installers.py::test_powershell_native_installer_supports_persistent_docker_lifecycle
    assert not any(arg.startswith(f"{trusted_cidrs}=") for arg in install_call)
    # offending args: ['HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS', 'HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32']
```

After the fix:

```text
$ python -m pytest tests/test_install/test_native_installers.py -q
10 passed, 5 skipped in 73.90s

$ ruff check tests/test_install/test_native_installers.py
All checks passed!
```

## Real Behavior Proof

- Environment: Windows 11 (10.0.26200), Windows PowerShell
5.1.26100.9444 (no pwsh installed), Python 3.12.3, headroom `main` @
dea9092e.
- Exact command / steps: `python -m pytest
tests/test_install/test_native_installers.py -q`. This includes
`test_powershell_native_installer_supports_persistent_docker_lifecycle`,
which runs the real `scripts/install.ps1` and then the generated
`headroom.ps1 install apply` against the repo's fake Docker shim, with
the variable set to `""`.
- Observed result: before the fix, the persistent container's `docker
run` carried
`HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32` despite
the empty opt-out. After the fix, only the name-only passthrough is
sent, and the container env holds `""`.
- Not tested: a real Docker daemon (only the fake Docker shim was used);
`pwsh` 7 locally, since it isn't installed here, though CI's Windows
runner has it and the new test covers it there; macOS/Linux, where the
bash installer is unaffected.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only for Windows PowerShell 5.1 users
who set the allowlist to an empty string. They now get the opt-out they
asked for. Unset and non-empty values behave as before.
- 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
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation: no doc
change needed
- [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`

## Additional Notes

Unrelated and not fixed here:
`tests/test_install/test_planner.py::test_build_manifest_for_persistent_service_uses_safe_model_backends`
also fails on a Windows host. `build_manifest` rewrites
`persistent-service` to `persistent-task` on Windows (#2552), so the
service-only CPU/ONNX defaults from #3646 aren't applied, and the test
doesn't pin `sys.platform`. CI never runs `test_planner.py` on Windows.
Happy to send a separate PR if you'd like the test pinned, or the
defaults keyed off the requested preset.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-08 10:09:05 -05:00
2de582875b fix(kompress): pin ModernBERT tokenizer and encoder revisions (#3808)
## Description

The Kompress ONNX artifacts are pinned to a commit SHA in
`_PINNED_REVISIONS`, but the tokenizer they were exported against
(`answerdotai/ModernBERT-base`) was loaded from the floating default
ref, and so was the torch-path encoder base. The export script that
produces those artifacts also loaded both the Kompress checkpoint and
the tokenizer from floating refs. An upstream change could shift token
ids under the shipped weights, or produce an artifact production never
loads, with no code change on our side.

Revised 2026-10-05 after review: the ONNX export script now loads the
checkpoint, encoder and tokenizer only at immutable commits defaulting
to the production pins, and cache-only PyTorch loads no longer fetch the
encoder.

## 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 `answerdotai/ModernBERT-base @
8949b909ec900327062f0ebf497f51aef5e6f0c8` (the snapshot the export cache
holds; upstream `main` at the time) to `_PINNED_REVISIONS`.
- `_load_modernbert_tokenizer` resolves the pin via `_resolve_revision`
and passes `revision=` on both the cache-only and download paths.
`HEADROOM_HF_PIN=off` floats it exactly as it floats the weights.
- `HeadroomCompressorModel` takes `revision=` and `allow_download=`; it
passes the resolved revision and `local_files_only=not allow_download`
to `AutoModel.from_pretrained`. `_load_kompress_pytorch` forwards
`allow_download` and turns a missing encoder snapshot into
`KompressModelNotCached` in cache-only mode (Devin finding).
- `scripts/export_kompress_v2_onnx.py`: new `--revision` (checkpoint)
and `--base-revision` (ModernBERT encoder + tokenizer). Both default to
the production pins in `_PINNED_REVISIONS` (not affected by
`HEADROOM_HF_PIN`); anything other than a 40-hex commit, or an unpinned
`--model-id` with no `--revision`, is rejected. Every Hub/Transformers
load (`hf_hub_download`, encoder, `AutoTokenizer`) passes them. A model
upgrade is now a reviewed pin bump plus a regenerated artifact.

No behaviour change for a warm cache at the same snapshot; a cache
populated from a different revision now downloads the pinned one (when
downloads are allowed) instead of using whatever is present.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`) — on touched files, plus `ruff
format --check`
- [x] Type checking passes (`mypy headroom`) — `mypy
headroom/transforms/kompress_compressor.py`
- [x] New tests added for new functionality
- [ ] Manual testing performed

New tests (all fail on the pre-fix code, pass now; no network):
- `tests/test_scripts/test_export_kompress_v2_onnx_pins.py`: AST check
that every `from_pretrained` / `hf_hub_download` / `snapshot_download` /
model-class load in the export script passes `revision=`; defaults are
the 40-hex production pins even with `HEADROOM_HF_PIN=off`; `main`, a
tag, or an unpinned repo are rejected; `_build_core` threads both
revisions.
- `tests/test_hf_revision_pinning.py`: tokenizer pin present /
cache-only path / download path / bypass, and
`test_cache_only_pytorch_load_does_not_fetch_encoder`.

### Test Output

```text
$ LITELLM_LOCAL_MODEL_COST_MAP=True uv run --frozen --extra dev --extra proxy pytest -q tests/test_hf_revision_pinning.py tests/test_scripts/test_export_kompress_v2_onnx_pins.py tests/test_kompress_preload_deferral.py tests/test_transforms/test_kompress_compressor.py
78 passed in 62.67s
# With the source changes reverted: 7 failed, 15 passed (all 7 new tests fail)
```

## Real Behavior Proof

- Environment: macOS, Python 3.14, `uv run --frozen --extra dev --extra
proxy`.
- Exact command / steps: the pytest command above; tests drive the real
loader and export entry points with Hub/torch boundaries faked.
- Observed result: every Hub load in the export path receives a 40-hex
revision; cache-only PyTorch load raises `KompressModelNotCached`
without attempting a download.
- Not tested: a real ONNX export / upload against the Hub (needs torch +
HF write auth); no artifact is regenerated by this PR.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: the ModernBERT tokenizer/encoder load
at the pinned commit instead of the floating ref; cache-only PyTorch
loads defer instead of downloading the encoder.
- Kill switch / disable path: `HEADROOM_HF_PIN=off` floats the runtime
loads, as for every other pinned repo.
- Unsafe override required: no.
- Qualification impact: none expected; the pin equals the snapshot the
artifacts were exported against.
- 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)

## Additional Notes

Uploading a newly exported artifact creates a new commit in the model
repo; production picks it up only after the
`chopratejas/kompress-v2-base` pin is bumped in a reviewed PR.

🤖 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-10-05 08:29:20 -05:00
ee731d7ea8 fix(proxy): refuse token-less non-loopback binds, gate operator routes (#3852)
## Why

Four related gaps in the proxy's network gate (findings 01-F1, 01-F2,
01-F5, 01-F9):

- **Open bind.** A non-loopback bind with no `HEADROOM_PROXY_TOKEN` only
logged a warning, then served the `/v1/*` relay, with the operator's
upstream credentials, to every peer that could reach the port.
- **Missing peer address.** `is_loopback_host(None)` returned `True`. A
Unix-domain socket, an ASGI adapter that leaves `scope["client"]` unset,
or a hand-built request therefore turned off the token gate, the
`/admin` and `/debug` guards and the WebSocket gate.
- **Operator data routes.** `/stats-history` (including CSV export),
`/quota`, `/subscription-window` and `/metrics` were served to any
network caller.
- **WebSocket loopback exemption** checked only the peer IP, not the
`Host` header, so it had no DNS-rebinding defence.

## What changes

- New `headroom/proxy/bind_policy.py`. A non-loopback bind (`0.0.0.0`,
`::`, a LAN address or a hostname) with no token is refused at three
places: `create_app` (embedders and the multi-worker factory),
`run_server` (one exit with code 2 before uvicorn forks) and the
`headroom proxy` CLI (a clear error before the banner, exit code 1). An
absent host means uvicorn's default `127.0.0.1`.
- `HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1` acknowledges an open bind when
the runtime already restricts reachability, such as a container
published on `127.0.0.1`. The `proxy_open_bind` warning is still logged
on that path, and the banner says the bind is open.
- `is_loopback_host(None)` now returns `False` (fail closed), matching
`identity.py`.
- `/stats-history`, `/quota` and `/subscription-window` answer only: a
non-loopback caller that passed the token gate, a loopback caller (peer
and `Host` header both loopback), a trusted dashboard client, or, under
an acknowledged token-less bind, the container's own default-gateway TCP
peer with a loopback `Host` (the host browser reaching a
`127.0.0.1`-published container). Everyone else gets 404, as with
`/admin`. Settings writes keep their stricter rule with no token
short-cut.
- `/metrics` answers a non-loopback caller that passed the token gate, a
loopback caller, a connecting peer in
`HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS` (whatever it forwards), or a
resolved client in the dashboard CIDRs. For CIDR peers a hostname `Host`
is fine, so Prometheus scrapers work; a cross-origin browser request is
still refused.
- The token short-cut applies only to non-loopback requests. The gate
exempts loopback peers without checking `Host`, so a loopback request
has not proven it holds the token and must pass the loopback `Host`
check. This blocks a DNS-rebound browser on the operator's machine.
- The `/dashboard` shell stays ungated. It is a static template, like
the already public `/dashboard/static` assets. Gating it would break the
dashboard for containers published on host loopback, where the peer is
the bridge gateway and `Host` is `localhost`. The data routes behind it
are gated.
- The WebSocket loopback exemption requires a loopback peer and a
loopback `Host` header. A loopback peer with a foreign `Host` can still
connect with the token.
- Launchers that always publish on `127.0.0.1` set the acknowledgement
themselves: `headroom install` (docker preset), `scripts/install.sh` and
`scripts/install.ps1` (through one helper that adds the acknowledgement
only together with the `127.0.0.1` publication), and
`docker/docker-compose.native.yml`.
- Docs: `proxy.mdx` documents the new variable and which routes the
token also gates; `docker-install` (docs and wiki) and the
`docker-compose.yml` comment show the acknowledgement in the
loopback-published example. `e2e/docker-bind-security.sh` sets it and
checks that the same launch without it refuses to start.

## Behaviour change (breaking)

- `headroom proxy --host 0.0.0.0`, or `HEADROOM_HOST` set to any
non-loopback address, without `HEADROOM_PROXY_TOKEN` now refuses to
start. The error names both remedies. Set a token, bind loopback, or set
`HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1` when the port is already
confined. Anyone running the image by hand with `--host 0.0.0.0` and no
token must add one of these.
- Without a token, `/stats-history`, `/quota`, `/subscription-window`
and `/metrics` return 404 to non-loopback callers outside a trusted
CIDR. Prometheus scrapers on another host must be in
`HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS` or send the token.
- Code that relied on a request with no peer address being treated as
loopback now gets the non-loopback path.
- The default loopback run is unchanged.

## Tests

- `tests/test_proxy_bind_policy.py`: the refuse/allow matrix
(non-loopback, loopback, unset host, token, acknowledgement values), the
warning on the acknowledged path, `create_app`, the `run_server` exit
before uvicorn, and the CLI (refusal, `HEADROOM_HOST` from env,
acknowledged start, offline banner, start with a token).
- `tests/test_proxy_loopback_gating.py`: each data route against
non-loopback, loopback, trusted-CIDR and token callers; the dashboard
shell stays reachable; the host of an acknowledged, loopback-published
container reads the data routes while another bridge peer, a forwarded
gateway address and a foreign `Host` do not; CSV export is not served to
network callers; `/metrics` across loopback, both CIDR lists,
out-of-range peers, cross-origin browsers and token callers, including a
trusted gateway relaying a scraper outside its own range. A regression
test shows that a token on the proxy does not exempt a loopback peer
from the `Host` check; it fails without the fix.
- `tests/test_proxy_hardening.py`: the HTTP gate with no peer address,
WebSocket `Host` cases, `require_loopback` and `/debug` with no peer.
- Installer tests: `headroom install` adds the acknowledgement, and the
shell and PowerShell wrappers add it only together with the loopback
publication. Launcher-level tests start the proxy with the environment
and `--host` that `build_runtime_command()` and
`docker-compose.native.yml` produce and check that the host browser
(bridge-gateway peer) gets `/stats-history` and another container does
not.
- Tests that bound `0.0.0.0` for unrelated reasons now set a token or
the acknowledgement. Tests that read operator routes use an explicit
loopback peer.

On `main`, 14 of the gating and hardening tests fail and the bind-policy
module does not exist. Manual runs: token-less `--host 0.0.0.0` exits
with the refusal from both the CLI and `run_server`; with the
acknowledgement, the data routes are 404 to a LAN peer and to a loopback
peer with a foreign `Host`; with a token, a LAN peer gets 401 without it
and 200 with it; the default loopback bind starts as before.

Not tested: a real Unix-domain-socket deployment and a real Prometheus
scrape (both covered by tests only).

## Merge order

Part of a set. Suggested order: #3852 → #3891 → #3849 → #3860 → #3862 →
#3863. This PR goes first: it is the gate the others assume, and it is
the release-note event.

## Not in this PR

- Enforcing the token for loopback callers when one is configured.

Revised 2026-10-02 after review: `/metrics` matches gateway CIDRs
against the TCP peer, and the operator data routes serve the host of a
loopback-published container (bridge-gateway peer under the launchers'
bind acknowledgement) so the default Docker dashboard works.

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

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3852"
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 Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-05 08:27:35 -05:00
be2a298ed0 ci: upload shard coverage even when a test in the shard fails (#3876)
## Description

The Codecov upload step in the sharded `test` job has no `if:`, so a
single failing test in a shard skips it. Every line that only that shard
covers then drops out of `codecov/patch`. Because of this, a PR can show
0% patch coverage when its own tests passed but an unrelated test in the
same shard failed. pytest-cov still writes `coverage-N.xml` when tests
fail, so the report exists and only the upload is skipped.

## Type of Change

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

## Changes Made

- `.github/workflows/ci.yml`: add `if: ${{ !cancelled() }}` to `Upload
coverage shard N to Codecov`.
- `scripts/tests/test_ci_workflow.py`: extend the existing upload-step
contract test to require that condition.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] New tests added for new functionality

### Test Output

```text
$ uv run --frozen --extra dev pytest scripts/tests/test_ci_workflow.py -q
3 passed
# with the ci.yml change reverted: 1 failed, 2 passed
```

## Real Behavior Proof

- Environment: GitHub Actions `ci.yml` sharded test job, as observed on
PR #3874 (run 36671680550).
- Exact command / steps: Compared the failing shards' step lists against
the Codecov status on the PR.
- Observed result: Shard 3 failed on an unrelated test, and its `Upload
coverage` step was skipped although pytest had written `coverage-3.xml`.
With this change the step runs after a test failure and is still skipped
on cancellation.
- Not tested: A live Codecov upload from this branch; this PR's own CI
run exercises it.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Stable.
- Stable/default behavior changed: No.
- Kill switch / disable path: Not applicable.
- 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)

## Additional Notes

This does not recover coverage from a shard that is killed outright. A
hard-exited process never writes its XML, so there is nothing to upload;
that case is fixed separately in fix/pytest-hard-watchdog.

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

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-09-30 11:04:01 -05:00
55ce93f3e8 ci(pr-health): check out the commit the workflow runs from (#3887)
## Description

The `PR Governance / label` job fails with `pr-health-labels.py: error:
unrecognized arguments: --field drift --behind-by ... --base-files ...`
on any pull request whose recorded base commit predates #3229.

`pull_request_target` always runs this workflow file from the default
branch, so the job invokes `.github/scripts/pr-health-labels.py` with
the flags #3229 added. But both jobs check out
`github.event.pull_request.base.sha`, which is the base commit recorded
when the PR was last synced, not the commit the workflow came from. On
an older PR that checkout carries the pre-#3229 script, which does not
know those flags. Editing the description of any such PR (an `edited`
event) produces a red run and a failure email, even though nothing about
the PR changed. Today this hit #2626, #2627, #2942 and #3127, whose base
SHAs are all older than c22cd1f1; #3617 and #3108, synced today, pass.

This checks out `github.sha` instead. For `pull_request_target` that is
the last commit on the base branch, the same commit the workflow file is
read from, so the workflow and its helper scripts always match. It is
still trusted base-branch code: the PR head is never checked out, so the
`pull_request_target` safety property is unchanged.

## 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

- `.github/workflows/pr-health.yml`: both `actions/checkout` steps
(governance and label jobs) use `ref: ${{ github.sha }}` instead of
`ref: ${{ github.event.pull_request.base.sha }}`.
- `scripts/tests/test_pr_health_workflow.py`: a contract test that no
checkout uses `pull_request.base.sha` and every checkout pins
`github.sha`.

## Testing

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

### Test Output

```text
$ uv run --frozen --extra dev pytest scripts/tests/test_pr_health_workflow.py scripts/tests/test_pr_health_labels.py -q
21 passed in 0.08s

# new test against main's pr-health.yml (before this change)
$ uv run --frozen --extra dev pytest scripts/tests/test_pr_health_workflow.py -q -k checkouts_use
1 failed, 7 deselected in 0.04s

$ uvx ruff check scripts/tests/test_pr_health_workflow.py && uvx ruff format --check scripts/tests/test_pr_health_workflow.py
All checks passed!
1 file already formatted
```

## Real Behavior Proof

- Environment: GitHub Actions on headroomlabs-ai/headroom, PR Governance
runs 36719570172, 36719565247, 36719562482 and 36719559715 (2026-09-30,
`pull_request_target` `edited` events).
- Exact command / steps: edited the PR body of #2626, #2627, #2942 and
#3127 (all with `base.sha` older than c22cd1f1), then read the failed
`label` job logs and compared each PR's `base.sha` against c22cd1f1 with
`git merge-base --is-ancestor`.
- Observed result: all four `label` jobs failed with
`pr-health-labels.py: error: unrecognized arguments: --field drift
--behind-by 150 --base-files [...]`; all four base SHAs lack c22cd1f1,
while #3617 and #3108 (base ffc6edb4, which contains it) ran green the
same day.
- Not tested: a live run of the patched workflow. `pull_request_target`
always runs the default branch's copy, so this change takes effect only
after merge; the first `edited` event on an older PR after that is the
live check.

## Runtime Rollout Safety

- Rollout-managed feature(s): None. CI workflow only; nothing in the
shipped package changes.
- Minimum rollout channel: N/A
- Stable/default behavior changed: No runtime behavior changes. In CI,
the governance and label jobs run the default branch's scripts instead
of each PR's stale base copy.
- Kill switch / disable path: N/A (CI only). Revert the PR.
- Unsafe override required: No
- Qualification impact: One contract test added; no existing test
changed or relaxed.
- 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 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

Documentation: N/A, no user-facing behavior changes.

🤖 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-30 10:45:46 -05:00
JD Davis 25274310ca fix(ci): keep hard watchdog out of pytest shards (#3845)
## Summary

- disable the production hard watchdog only in the sharded pytest job
- keep the existing 30-minute job timeout responsible for reporting CI
stalls
- add a workflow-contract regression test so the opt-out cannot
disappear silently

## Root cause

After the hard watchdog merged, `main` CI shard 1 began terminating with
exit code 1 during `tests/test_compress_session_mode.py`, without a
pytest failure or summary. A matching Ubuntu 24.04 / Python 3.12 shard
reproduced the abrupt termination locally. The same shard can complete
when `HEADROOM_HARD_WATCHDOG_SECS=0`.

The watchdog deliberately uses `faulthandler.dump_traceback_later(...,
exit=True)` to terminate a production process when native code holds the
GIL. That behavior is appropriate under a service supervisor, but inside
pytest it destroys the diagnostic process before pytest or the job
timeout can identify the stalled test. Production defaults and the
dedicated subprocess watchdog tests remain unchanged.

The contemporaneous Docker failures were separate: Docker Hub reset the
OAuth connection, then the manifest job could not download the missing
amd64 digest artifact.

## Verification

- `uv run --frozen --extra dev pytest scripts/tests/test_ci_workflow.py
tests/test_hard_watchdog.py -q` — 6 passed
- `uv run --frozen --extra dev ruff check
scripts/tests/test_ci_workflow.py` — passed
- `uv run --frozen --extra dev ruff format --check
scripts/tests/test_ci_workflow.py` — passed
- `git diff --check` — passed
- Ubuntu 24.04 / Python 3.12 exact shard command with the CI opt-out —
completed successfully

No production runtime behavior is changed.
2026-09-29 10:57:20 -05:00
c22cd1f1b6 ci(pr-health): flag stale PR branches by ref comparison (#3229)
## Description

The `status: needs rebase` label in `.github/workflows/pr-health.yml` is
driven by `mergeStateStatus == BEHIND`. GitHub only reports `BEHIND`
when the base branch requires branches to be up to date, and `main` does
not (`required_status_checks.strict = false`, per #3066). The label has
therefore never been applied since it was added in #933, so stale-base
risk is invisible on the PR.

This computes the drift directly with a ref comparison instead, so the
label works regardless of the branch-protection setting. It does not
replace the settings decision in #3066 (only a repo admin can enable
strict checks or a merge queue) — it makes the risk visible while that
is pending.

Refs #3066

## 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

- `.github/workflows/pr-health.yml`: the `label` job now asks `gh pr
view` for `baseRefName`, `headRefOid` and `files`, calls
`repos/{repo}/compare/{base}...{head}` for `behind_by` plus the merge
base, and — only when the branch is behind — calls
`compare/{merge_base}...{base}` for the files the base branch changed in
the meantime. That second call has no `[]` fallback: `base_files` is set
to an empty-string sentinel first and reset to it when the call fails,
so partial output from a call that died midway is discarded and a
missing merge base takes the same path.
- `.github/scripts/pr-health-labels.py`: added `drift_state()`,
`parse_behind_by()` and `parse_base_files()`, plus a `--field
checks|drift` switch with `--behind-by` / `--base-files`. A PR is
`stale` when it is behind **and** the base moved on files the PR also
changes, `current` otherwise, and `unknown` when either comparison call
failed. `parse_base_files()` maps the sentinel, invalid JSON and any
non-list payload to `None`, which is what makes a failed base-file
comparison `unknown` rather than an empty set of moved files; a
successful comparison that returns zero files still classifies as
`current`. `unknown` leaves the label untouched, mirroring the existing
`mergeStateStatus == UNKNOWN` guard, so a transient API error never
clears a real label. An explicit `mergeStateStatus == BEHIND` is still
honoured, so nothing regresses if strict checks are enabled later.
- The same `stale` verdict now holds back `status: ready for review`,
replacing the old `BEHIND` condition.
- File overlap is the deliberate narrowing: plain "behind by at least
one commit" matches 18 of 20 open PRs on a base branch this busy, which
would make the label noise. Overlap targets the case that hides a
semantic merge conflict from per-PR checks, which is what #3066
describes.
- Cost is 1-2 extra API calls per PR, so at most ~200 per scheduled run
at the existing 100-PR cap.
- Added unit tests for the new logic and workflow-contract assertions,
including a regression that runs the extracted `base_files` shell block
under `bash` with `gh` stubbed to print partial output and exit 1,
asserts the sentinel survives, feeds it to the script for an `unknown`
verdict, and asserts the drift dispatch has no `else` so `unknown`
neither adds nor removes the label.

## 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
$ python -m pytest scripts/tests/test_pr_health_labels.py scripts/tests/test_pr_health_workflow.py -q
scripts\tests\test_pr_health_labels.py .............                     [ 65%]
scripts\tests\test_pr_health_workflow.py .......                         [100%]
============================= 20 passed in 0.10s ==============================

$ ruff check .github/scripts/pr-health-labels.py scripts/tests/
All checks passed!

$ ruff format --check .github/scripts/pr-health-labels.py scripts/tests/test_pr_health_labels.py scripts/tests/test_pr_health_workflow.py
3 files already formatted
```

## Real Behavior Proof

- Environment: local checkout of the branch at 738f984d, Windows 11,
Python 3.13, `gh` 2.x authenticated against `headroomlabs-ai/headroom`
- Exact command / steps: replayed the new workflow steps against the 25
most recent open PRs — for each one, `gh pr view --json
baseRefName,files,headRefOid,isDraft,labels,mergeStateStatus,reviewDecision,statusCheckRollup`,
then `gh api repos/headroomlabs-ai/headroom/compare/{base}...{head}` and
`compare/{merge_base}...{base}`, feeding the results to `python
.github/scripts/pr-health-labels.py --state-json ... --field drift
--behind-by ... --base-files ...`
- Observed result: review follow-up on 2026-08-27, replayed #3192,
#3180, #3177 and this PR with a successful base-file comparison and
again with a failed one. The successful verdicts are unchanged (`stale`,
`stale`, `stale`, `current`); the failed comparison now returns
`unknown` on all four, where the pre-fix script returned `current` and
the label step would have removed `status: needs rebase`. Reverting the
workflow block to the old `|| echo '[]'` fallback fails both new
workflow tests (`assert 'partia[]' == ''`). Original sweep: 3 of 25 PRs
classified `stale` — #3192, #3180 and #3177, each 13 commits behind
`main` and each touching `headroom/proxy/server.py`, which `main` also
changed in that window. The other 22 came back `current`, including PRs
that are behind by 1 to 13 commits on unrelated files. Before this
change none of the 25 reported `mergeStateStatus == BEHIND` and none
carried `status: needs rebase`. Workflow YAML still parses via
`yaml.safe_load`.
- Not tested: no run of the workflow on GitHub Actions
(`pull_request_target` and the cron schedule can only fire from the
default branch after merge), and no `actionlint`/`act` run locally as
neither tool is installed on this machine — CI covers both.

## Runtime Rollout Safety

- Rollout-managed feature(s): none, this is CI-only automation and
touches no runtime code path
- Minimum rollout channel: not applicable
- Stable/default behavior changed: no product behavior changes; the only
observable change is which PRs receive the `status: needs rebase` label
- Kill switch / disable path: revert this commit, or delete the label —
the `label` job keeps working, and every `gh pr edit` failure is already
tolerated
- Unsafe override required: no
- Qualification impact: none
- Rollback path: `git revert` of this commit restores the previous
`mergeStateStatus == BEHIND` condition

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

## Additional Notes

- Documentation checkbox is unchecked because the label semantics are
described in the label description itself (updated by this PR) and no
docs page covers the PR-health labels.
- `mypy headroom` is unchecked because nothing under `headroom/`
changed; the touched script lives in `.github/scripts/`.
- The overlap comparison uses the files `gh pr view --json files`
returns, so a PR with an unusually large file list could under-report
overlap. That fails safe (no label) rather than mislabelling.
- This PR intentionally does not close #3066: the acceptance criteria
there are strict status checks or a merge queue on `main`, which need
admin rights on the repo.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-09-25 10:34:18 -05:00
Rod BoevandJerrettDavis b0c19a25f0 fix(security): reject unauthenticated public proxy binds (#3316)
## Description

Headroom's published image and maintained Docker launchers could expose
the
proxy on every host interface without a proxy token. This change moves
the
security boundary to the deployment artifacts: published images default
to a
container-loopback listener, supported local launchers publish only on
host
loopback, and deliberate public deployments retain explicit token
protection.
The application factory remains transport-neutral.

Closes #3283

## Type of Change

- [x] Bug fix (non-breaking change which 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

- Set both published image stages to a container-loopback default while
keeping explicit host overrides available.
- Changed native Compose and the maintained Bash and PowerShell
launchers to use an internal `0.0.0.0` listener with host-loopback
publication.
- Preserved the top-level Compose token requirement and the existing
HTTP and WebSocket credential behavior for deliberate public binds.
- Scoped differential-capture token injection to the internal
`headroom-proxy` destination and kept sensitive headers redacted in
captured records.
- Added focused launch-contract, native-core, capture, and Docker
publication checks, plus a base/head harness that tolerates a base
already containing the fix.
- Updated Docker, installer, capture, and mirrored documentation,
including an unauthenticated local loopback quickstart and an
authenticated deliberate-public example.

## Testing

- [x] Focused unit and integration tests pass
- [x] Linting and formatting checks pass
- [ ] Type checking passes
- [x] New tests added for the changed deployment and capture behavior
- [ ] Manual testing performed

### Test Output

```text
uv run python -m pytest tests/test_proxy_hardening.py tests/test_install/test_native_installers.py tests/test_docker_compose_persistence.py tests/test_network_diff_capture.py tests/test_rust_core_smoke.py -q
76 passed, 1 skipped, 1 warning in 23.45s

uv run ruff check tests/test_install/test_native_installers.py tests/test_install/test_runtime.py
All checks passed!

bash -n e2e/docker-bind-security.sh
passed

bash e2e/docker-bind-security.sh --base-image headroom-t3283-base --head-image headroom-t3283-head --fixture tests/fixtures/docker-bind-exposure.json --base-ref origin/main
base_ref=origin/main ... runtime_slim_config=loopback rust_core=loaded local_completion=200 attacker_loopback=000 ws_status=403
docker bind security: fixture forwarding, loopback isolation, built-image health, slim-image loopback config, and token controls passed
```

## Real Behavior Proof

- Environment: Windows, Docker Desktop 29.6.2, current `origin/main`
base, head image, and a real Docker bridge peer.
- Exact command / steps: run the focused security/runtime tests, Compose
configuration checks, then `bash e2e/docker-bind-security.sh` against
the current base and head image definitions.
- Observed result: `76 passed, 1 skipped`; the built-image harness
passed base/head health, local completion, non-loopback isolation,
authenticated public HTTP/WebSocket controls, loopback runtime-slim
configuration, and direct Rust-core loading.
- Not tested: runtime-slim proxy service health on this host, because
its unrelated ONNXRuntime import path exits with code 139; the full
hosted matrix and a future published GHCR image remain CI-owned.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Unsafe override required: no
- Minimum rollout channel: next release containing the Docker and
launcher changes
- Stable/default behavior changed: published images and maintained local
Docker launchers now use loopback-safe publication defaults
- Kill switch / disable path: revert the deployment-artifact changes
before release; deliberate public deployments remain explicitly
operator-controlled
- Qualification impact: Docker users relying on all-interface default
publication must opt into public publication and configure the existing
proxy token
- Deliberate public deployment: use an explicit public host publication,
set `HEADROOM_PROXY_TOKEN`, and send the matching bearer or
`X-Headroom-Proxy-Token` credential
- Local deployment: use the maintained loopback publication and no
mandatory token
- Rollback path: revert the deployment-artifact and documentation
changes together

## 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 the behavior is effective
- [x] Focused tests pass locally with these changes
- [x] I did **not** edit `CHANGELOG.md`; release-please generates
release notes from the conventional PR title

## Additional Notes

The issue fixture remains provenance for the unauthenticated
publication. Native
`headroom proxy` defaults and the application-level authentication
owners are
unchanged.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-09-24 23:58:46 -05:00
AxelRay d90dadf266 fix(docker): support OpenCode in native wrapper (#3547)
## Description

The Docker-native wrapper accepts `opencode` but cannot complete a
normal launch: it does not mount the host config directory, its cleanup
trap can expand an out-of-scope variable, and the prepared config is not
forwarded to the host process. This fix keeps OpenCode configuration on
the shared mount, launches the host binary with the prepared JSON, and
preserves proxy cleanup.

Closes #3534

## 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

- Create and mount the host `.config` directory for Docker-native
OpenCode preparation.
- Launch the host OpenCode binary with the prepared config file content
and preserve proxy cleanup after the wrapper exits.
- Add a fake-Docker regression test covering the config mount, host
arguments, config handoff, and cleanup.

## Testing

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

### Test Output

```text
$ .venv-3534/bin/python -m pytest tests/test_install/test_native_installers.py -q
=================== 2 passed, 4 skipped, 1 warning in 9.13s ====================
$ .venv-3534/bin/ruff format --check tests/test_install/test_native_installers.py
1 file already formatted
$ .venv-3534/bin/ruff check tests/test_install/test_native_installers.py
All checks passed!
$ bash -n scripts/install.sh
(exit code 0)
```

## Real Behavior Proof

- Environment: Linux x86_64, Python 3.11.16, Bash 5, checkout at the
current PR head `23a97458`
- Exact command / steps: `.venv-3534/bin/python -m pytest
tests/test_install/test_native_installers.py -q`; the test generated the
installer wrapper with fake Docker and OpenCode shims, then ran
`headroom wrap opencode --port <ephemeral-port> -- --help`
- Observed result: The wrapper mounted `.config`, passed the prepared
JSON through `OPENCODE_CONFIG_CONTENT`, forwarded `--help` to OpenCode,
and removed the fake proxy container on exit.
- Not tested: A real Docker daemon or image, the actual OpenCode binary,
live provider traffic, Windows, and macOS runtime behavior.

## Runtime Rollout Safety

- Rollout-managed feature(s): N/A
- Minimum rollout channel: N/A
- Stable/default behavior changed: Docker-native `wrap opencode` now
launches OpenCode after preparation.
- Kill switch / disable path: Use `--no-proxy` or the Python-native
wrapper.
- Unsafe override required: N/A
- Qualification impact: N/A
- 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
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] 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
- [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
2026-09-23 20:54:33 -05:00
宇宙的山峰 a490bba83f fix: attach stdin for docker-native MCP stdio (#3447)
## Description

Docker-native PowerShell MCP stdio clients pipe stdin. `Add-TtyArgs`
previously omitted Docker's `-i` flag for redirected input, so the
container saw EOF before answering `initialize` and MCP clients reported
`CONNECTION_CLOSED`.

Closes #3393

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Changes Made

- `Add-TtyArgs` always passes Docker's `-i` flag.
- Pseudo-TTY allocation remains conditional on both host streams being
interactive, so `-t` is only added for fully interactive consoles.
- Added a Windows regression that installs the generated PowerShell
wrapper, pipes an MCP initialize request, and verifies the fake Docker
invocation includes `-i` but not `-t`.

## Testing

- [x] Targeted Windows regression passed (`1 passed, 5 deselected`).
- [x] Ruff check passed for the changed test file.
- [x] Ruff format check passed for the changed test file.
- [x] `git diff --check` passed.
- [x] Full native-installer file: 4 passed, 1 skipped.

### Test Output

```text
python -m pytest tests/test_install/test_native_installers.py -k 'mcp_wrapper_keeps' -q
1 passed, 5 deselected

ruff check tests/test_install/test_native_installers.py
Passed

ruff format --check tests/test_install/test_native_installers.py
Passed

git diff --check
Passed
```

## Real Behavior Proof

- Environment: Windows 10, Windows PowerShell 5.1, Python 3.11.9,
repository checkout at the PR head.
- Exact command / steps: install the generated wrapper, pipe an MCP
initialize request through it, and use a fake Docker executable that
records its exact arguments.
- Observed result: the piped invocation completed successfully; the
recorded `docker run --rm` arguments included `-i` and excluded `-t`.
- Not tested: a live pull of the published Headroom image or an
end-to-end Claude Code session with Docker Desktop.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Existing Docker-native wrapper path.
- Stable/default behavior changed: Redirected stdin is now attached to
the container; interactive TTY behavior is unchanged.
- Kill switch / disable path: Not applicable.
- 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
(not needed for this small change)
- [ ] I have made corresponding changes to the documentation (not
applicable)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective
- [x] New and existing targeted tests pass locally
- [x] I did **not** edit `CHANGELOG.md`

## Screenshots (if applicable)

Not applicable.

## Additional Notes

The full native-installer file has one unrelated persistent lifecycle
test blocked by a pre-existing PowerShell output-encoding failure. The
PR's GitHub `docker-wrap-e2e` check later failed while installing the
unrelated OpenClaw plugin with npm (`Cannot read properties of null
(reading 'edgesOut')`; no code in this PR is involved). The run cannot
be rerun with the current token because GitHub requires repository admin
rights.
2026-09-11 16:05:34 -05:00
Sepuri Sai KrishnaandJerrettDavis 4e1f7769d7 fix(changelog-gen): raise on git failure and remove unreachable fallback regex (#1247)
## Description

Fixes two silent-failure bugs in scripts/changelog-gen.py that could let
the release
pipeline produce an empty changelog with exit code 0.

1. run_git_log() never checked subprocess.returncode, so a failed git
log
(e.g. a non-existent --since ref) silently returned empty output and
wrote a blank
.changelog.md, allowing the pipeline to continue as if nothing went
wrong.
2. iter_commit_entries() had a dead fallback branch using
COMMIT_ENTRY_PATTERN — a
regex that expected | as a field separator, but the actual git log
format uses
\x1f/\x1e. The fallback could never match real output and would silently
return
zero commits if the primary parse path was skipped.

Closes #

## 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

- scripts/changelog-gen.py: run_git_log() now raises RuntimeError on
non-zero git exit, with the stderr included in the message.
- scripts/changelog-gen.py: removed the unused COMMIT_ENTRY_PATTERN
constant; replaced the dead fallback in iter_commit_entries() with an
explicit ValueError so format mismatches
surface immediately instead of returning empty results.

## Testing

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

### Test Output

 ```
$ uv run python -m pytest scripts/tests/test_changelog_gen.py -q
============================= test session starts
==============================
platform linux -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0
rootdir: /home/sepurisaikrishna/Documents/calude-here/headroom
configfile: pyproject.toml
collected 28 items

scripts/tests/test_changelog_gen.py ............................ [100%]

=============================== warnings summary
===============================
PytestConfigWarning: Unknown config option: asyncio_mode

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
======================== 28 passed, 1 warning in 0.03s
=========================

$ git diff --check origin/main..HEAD
# no output; command exited 0
 ```

## Real Behavior Proof

- Environment: Linux, Python 3.14.0, uv-managed .venv, branch based on
current origin/main.
- Exact command / steps: invoke python scripts/changelog-gen.py
--version 0.1.0 --since v99.99.99 (non-existent tag); before the fix the
script exits 0 with an empty .changelog.md;
after the fix it raises RuntimeError: git log failed and exits non-zero.
- Observed result: all 28 test_changelog_gen.py tests pass; script now
fails loudly on bad git input.
- Not tested: full repository pytest, ruff, and mypy; live CI run
against a real release tag.

## 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
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

N/A.

## Additional Notes

- Both bugs share the same failure mode (silent empty output instead of
a clear error) and are in the same file, so they are fixed together in
one PR.
- The COMMIT_ENTRY_PATTERN constant is removed as it is now
unreferenced.
- No production behaviour changes — these scripts are only invoked
during the release pipeline.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-09-09 23:18:51 -05:00
Tejas ChopraandClaude Opus 5 96dfc7005f chore: finish the org and docs-domain migration (#3389)
Two stale identities left over from moves that were only half applied.

## GitHub org

`install/state.py` already migrated Docker images to
`ghcr.io/headroomlabs-ai/headroom` and carries a
`_DEPRECATED_IMAGE_REPO` constant that rewrites the old path on load —
so this move was decided long ago. Everything else still said
`chopratejas/headroom`.

Rewritten across packaging (`pyproject.toml`, `Cargo.toml`), both plugin
marketplaces, the agent-hooks manifests, install scripts, CI templates,
crate docs and tests.

**Two deliberate exclusions:**
- **`ghcr.io/chopratejas/headroom` is untouched everywhere.** It is the
*input* to `_migrate_deprecated_image()` and to the tests covering it.
Rewriting it would silently disable the migration.
- **`CHANGELOG.md` keeps its 238 historical references.** GitHub's
rename redirect resolves them, and rewriting would bury this diff in
noise.

**HuggingFace model ids are NOT affected and were never in scope.**
`chopratejas/kompress-base`, `kompress-v2-base`, `kompress-finance`,
`technique-router`, `technique-router-onnx` and
`siglip-image-encoder-onnx` are account-scoped identifiers on a
different service. All six were validated against the HF API before this
change:

| Model | HTTP |
|---|---|
| `kompress-base` | 200 |
| `kompress-v2-base` | 200 |
| `technique-router` | 200 |
| `technique-router-onnx` | 200 |
| `siglip-image-encoder-onnx` | 200 |
| `kompress-finance` | **401 (private)** |

The 401 is unrelated to this migration, but worth knowing:
`kompress_compressor.py:1255` references it, so that path is not
reachable by an OSS user without access.

**One functional fix, not cosmetic:** `_marketplace_source()`
(`headroom/cli/init.py`) returned the old org as its fallback, so plugin
installs were pointed at the retired repo.

## Docs domain

The site moved to `docs.headroomlabs.ai`, but eleven references still
named the vercel.app host — including **`llms.txt` (27 links)**, which
is served at `docs.headroomlabs.ai/llms.txt` and read by LLM crawlers,
the **dashboard's own Documentation link**, and a `headroom wrap` help
message. The docs app's canonical-URL fallbacks were fixed separately in
#3388.

## Also folded in

`RUST_DEV.md` corrections found while verifying the above:
- `make build-wheel` points at `Cargo.toml`, not `pyproject.toml`
- the Rust toolchain is pinned, not tracking `stable`
- `headroom-simulators` was missing from the workspace listing
- the Python `CompressionStore` defaults to **SQLite**, not in-memory,
when `HEADROOM_CCR_BACKEND` is unset (verified by execution) — this one
matters for multi-worker reasoning

And the install scripts pointed at `docs/docker-install.md`, a path that
no longer exists; they now point at the live docs page.

## Verification

297 tests pass, including the plugin-manifest, install-state and
release-workflow suites that assert on these exact strings. `ruff check`
clean. Unrelated lockfile churn (`uv.lock`, both `package-lock.json`) is
deliberately excluded.

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

https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 15:53:35 +05:30
Tejas Chopra 1f96dabc19 fix(security): address u9up assessment findings (WEB-01–07) (#2207)
Hardens client-selected upstreams, memory identity resolution, downloaded binary integrity, telemetry import, Docker defaults, Neo4j credentials, and archive extraction. Refreshes the branch against current main and preserves newer same-origin and loopback protections.
2026-08-20 09:02:44 -05:00
Tejas ChopraandTejas Chopra cbb950a441 ci(governance): require a Conventional Commit PR title (#3063)
## Description

The repo squash-merges, so the PR title — not the commits inside the PR
— becomes the commit subject on `main`. Nothing validated it.

`commitlint` (`ci.yml:429`) lints a PR's *commits* and therefore cannot
catch this by construction: a PR with clean conventional commits and a
prose title passes CI and then lands a prose subject on `main`.

That is how `31452426` landed:

```
Unify savings attribution across stats, perf, metrics, and dashboard (#2976)
```

release-please cannot parse it — `unexpected token ' ' at 1:6`, because
`Unify` is five characters and position six is a space where the parser
needs `(`, `!` or `:`. The change is silently dropped from the
changelog.

## 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

## Changes Made

- Added `COMMIT_TYPES` and `TITLE_RE` to `scripts/pr-governance.py`,
matching `.commitlintrc.json`'s `type-enum`.
- Added a title check to `validate_pull_request`, reported through the
existing governance comment.
- Added a test asserting `COMMIT_TYPES` equals `.commitlintrc.json`'s
`type-enum`, so the two gates cannot drift apart.
- Gave the `_event` test helper the `title` field a real `pull_request`
payload always carries.

## Testing

- [x] Unit tests pass
- [x] Linting passes (ruff check + format)
- [ ] Type checking passes — N/A (script + test only)
- [x] New tests added for new functionality

### Test Output

```text
$ .venv/bin/python -m pytest scripts/tests/test_pr_governance.py -q
12 passed in 0.02s
```

Against the parent commit:

```text
FAILED test_validate_pull_request_rejects_non_conventional_title
FAILED test_validate_pull_request_rejects_empty_and_typeless_titles
FAILED test_commit_types_match_commitlint_config
3 failed, 9 passed
```

## Real Behavior Proof

- Environment: macOS 15 (darwin 25.4.0), Python 3.12.13,
`scripts/pr-governance.py` loaded directly.
- Exact command / steps: ran `TITLE_RE` against the titles of **all 117
pull requests opened in this repository between 2026-08-10 and
2026-08-16**, pulled with `gh pr list --json title`.
- Observed result: exactly one title is flagged — `#2976`, `Unify
savings attribution across stats, perf, metrics, and dashboard`, the one
that jammed the release. Zero false positives across the other 116,
including every Dependabot `deps: bump ...` title, `chore: release
main`, and scoped forms like `fix(proxy/anthropic): ...`.
- Not tested: the check running inside a live `pull_request_target`
event on a GitHub runner.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: yes — a PR with a non-conventional
title now gets the `status: needs author action` label and a governance
comment.
- Kill switch / disable path: revert; the check is not independently
configurable.
- Unsafe override required: none.
- 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
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective
- [x] New and existing unit tests pass locally with my changes

## Additional Notes

The check lives in `pr-governance.py` rather than `ci.yml` for two
reasons:

1. `ci.yml`'s `pull_request` trigger has no `edited` type, so a
corrected title would never be re-checked.
2. Its `paths-ignore` skips docs-only PRs, which still squash-merge a
subject onto `main`.

`pr-health.yml` already triggers on `edited` and reports through the
same governance comment the author is reading anyway.

Bot PRs keep their existing exemption — Dependabot and release-please
titles are already conventional, and the early return for `is_bot_pr` is
untouched.

Co-authored-by: Tejas Chopra <tejas@Tejass-MacBook-Pro.local>
2026-08-16 19:05:36 -07:00
Abhay SinghandJD Davis ddd9f76729 fix(install): stop the PowerShell installer leaking temp dirs into the real user PATH (#2985)
## Description

`scripts/install.ps1` persists the install directory to the user's PATH
through `Ensure-PathEntry`, which calls
`[Environment]::SetEnvironmentVariable('Path', ..., 'User')`. That value
lives in the `HKCU\Environment` registry key, so it is **not** scoped by
a `HOME` / `USERPROFILE` override.


`tests/test_install/test_native_installers.py::test_powershell_native_installer_supports_persistent_docker_lifecycle`
runs that real installer against a `tmp_path` fake home. Every run
therefore prepended the test's throwaway shim directory to the
developer's actual, persistent user PATH -- and it stayed there after
the test finished. The entries accumulate one per run, ahead of the real
install dir; and since the installer also drops
`headroom.ps1`/`headroom.cmd` into that dir, `headroom` in a fresh shell
could then resolve to a leftover wrapper from a deleted temp directory
(#2970).

## Fix

Make the persistence scope configurable via
`HEADROOM_INSTALL_PATH_SCOPE`, defaulting to `'User'` so production
behavior is unchanged:

```powershell
$scope = if ($env:HEADROOM_INSTALL_PATH_SCOPE) { $env:HEADROOM_INSTALL_PATH_SCOPE } else { 'User' }
$currentPath = [Environment]::GetEnvironmentVariable('Path', $scope)
...
[Environment]::SetEnvironmentVariable('Path', ($newPath -join ';'), $scope)
```

The installer tests (`_build_env`) set
`HEADROOM_INSTALL_PATH_SCOPE=Process`, so the PATH update stays in the
spawned PowerShell process (discarded when it exits) instead of writing
to the registry.

Fixes #2970

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `scripts/install.ps1` (`Ensure-PathEntry`): read/write the PATH via
`$env:HEADROOM_INSTALL_PATH_SCOPE` (default `'User'`).
- `tests/test_install/test_native_installers.py`: `_build_env` sets
`HEADROOM_INSTALL_PATH_SCOPE=Process` for every installer invocation;
add a Windows-only
`test_powershell_installer_does_not_leak_into_user_path` asserting the
real User PATH entry count is unchanged across an installer run.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [x] New test added

### Test Output

```text
tests/test_install/test_native_installers.py -k does_not_leak_into_user_path  1 passed
# uvx ruff@0.15.22 check tests/test_install/test_native_installers.py -> All checks passed!
```

## Real Behavior Proof

- Environment: Windows 11, Windows PowerShell 5.1, Python 3.12.11,
project venv, pytest 9.1.1, ruff 0.15.22 via uvx.
- Exact command / steps: recorded the real user PATH entry count
(`([Environment]::GetEnvironmentVariable('Path','User') -split
';').Count` = 27), ran the PowerShell installer test with the fix, then
re-read the count: still 27 -- no leak. The new
`test_powershell_installer_does_not_leak_into_user_path` formalizes this
(before == after).
- Observed result: running the installer test suite no longer mutates
the developer's persistent user PATH; production installs still persist
to `'User'` as before.
- Not tested: the sibling
`test_powershell_native_installer_supports_persistent_docker_lifecycle`
fails on my Windows host on an unrelated `trusted_cidrs`
dashboard-gateway assertion (it fails identically on `main` without this
change, and the whole PowerShell suite is skipped on the Linux CI
runners). This PR does not touch that path.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. This is the native PowerShell
installer script, not a rollout-channel-gated runtime feature.
- Minimum rollout channel: N/A (no rollout-managed behavior).
- Stable/default behavior changed: no. Production installs still persist
PATH to the `User` scope exactly as before; the new
`HEADROOM_INSTALL_PATH_SCOPE` override defaults to `User` and is used
only by the test suite to avoid mutating the developer's persistent
PATH.
- Kill switch / disable path: leave `HEADROOM_INSTALL_PATH_SCOPE` unset
(the default) for the normal `User` behavior.
- Unsafe override required: no.
- Qualification impact: none. Installer-only; no proxy runtime path is
touched.
- Rollback path: revert this PR; the installer returns to writing the
`User` PATH unconditionally.

## 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
- [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

## Additional Notes

The scope override defaults to `'User'`, so nothing changes for real
installs. It doubles as an escape hatch for any environment (CI images,
ephemeral containers) that must not touch the persistent user PATH.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-08-16 15:05:04 -07:00
3077ac81e8 feat: add deterministic runtime rollout controls (#1490)
## Description

Establish one centrally resolved, observable, deterministic, versioned
runtime rollout-control mechanism for Headroom. Runtime rollout controls
which behaviors an already-built artifact may expose; it does not select
or qualify a Headroom release/version.

## Type of Change

- [x] New feature (non-breaking change that adds functionality)
- [x] Bug fix (non-breaking change that fixes rollout enforcement
regressions)
- [x] Documentation update
- [x] Code refactoring (no functional changes)

## Changes Made

- Added `RolloutChannel`, `HEADROOM_ROLLOUT_CHANNEL`,
`--rollout-channel`, and a versioned immutable `RolloutSnapshot` shared
by Python configuration boundaries.
- Added schema/policy versions, canonical registry and snapshot SHA-256
identities, per-feature decision reasons, disable precedence, unsafe
qualification poisoning, strict CLI validation, and fail-closed
environment handling.
- Added `headroom rollout status --json`, Python `/stats.rollout`, and
Rust `/rollout/status` runtime provenance.
- Added equivalent Rust snapshot semantics and shared Python/Rust policy
vectors while retaining language-specific feature registries.
- Enforced rollout policy at alternate Python server composition roots
so `HEADROOM_READ_MATURATION=1` cannot bypass its beta gate.
- Preserved typed rollout snapshots across multi-worker serialization
with schema, policy, registry, snapshot-digest, type, and feature-name
validation.
- Made loopback runtime output-shaper updates replace the immutable
snapshot atomically for request readers, retain explicit request/disable
provenance, preserve channel and kill-switch precedence, invalidate
cached stats, and return the effective rollout decision.
- Made `headroom learn --verbosity --apply` report a channel-blocked
update instead of claiming the shaper is live.
- Made explicit CLI feature flags fail loudly when their current channel
blocks them.
- Made persistent interceptor installation select canary automatically,
or reject an explicitly insufficient channel unless the break-glass
override is set.
- Updated architecture, proxy, rollout, learn, and output-shaper
documentation with required channels and hot-reload semantics.

## Testing

- [x] Unit tests pass
- [x] Linting passes (`ruff check .` and `ruff format --check .`)
- [x] Type checking passes (`mypy headroom --ignore-missing-imports`)
- [x] New regression tests added for every corrected behavior
- [x] Rust tests and production-target Clippy pass
- [x] Documentation build passes

### Test Output

```text
Focused rollout coverage suite
57 passed; headroom.rollout + rollout CLI: 98% coverage

Affected proxy/rollout/transform/governance suites
222 passed; 0 failed

Final changed regression suites
100 passed; 0 failed

Cross-module hot-reload isolation regression
6 passed; 0 failed

cargo test -p headroom-core -p headroom-proxy --quiet
headroom-core: 924 passed; 1 ignored
headroom-proxy and integration suites: all passed

cargo clippy -p headroom-core -p headroom-proxy --lib --bins -- -D warnings
cargo fmt --all -- --check
ruff check .
ruff format --check .
mypy headroom --ignore-missing-imports
git diff --check
All passed

cd docs && npm run build
Compiled successfully; 164 static pages generated
```

The unsharded Windows-only CI selection exposed unrelated baseline
failures, principally the existing `sqlite:///C:\\...` URL parser
producing an invalid `\\C:\\...` path. At commit `8e793a80`, all 52
completed GitHub checks passed; the only other conclusions are expected
skips and superseded governance jobs.

## Real Behavior Proof

- **Environment:** Windows checkout on Python 3.13.3 and the current
Rust workspace, based on upstream `main` at `93f2d7a2`.
- **Exact command / steps:** Exercised canary and beta feature requests
through CLI status, Python `/stats.rollout`, Rust `/rollout/status`,
multi-worker payload round trips, loopback `/admin/runtime-env`, real
proxy request shaping before/after hot reload, installer manifest
generation, and shared Python/Rust policy vectors.
- **Observed result:** Stable blocks unstable requests; disable wins
over explicit/default/legacy/unsafe paths; unsafe state reports
`qualification_eligible=false`; worker handoff rejects tampering;
running output shaping changes only when the effective beta policy
permits it; explicit blocked flags fail with actionable diagnostics.
- **Not tested:** Live production traffic requiring provider
credentials, or future artifact qualification/promotion automation
(intentionally out of scope).

## Runtime Rollout Safety

- **Rollout-managed features:** Python `tool_result_interceptors`,
`proxy_output_shaper`, `read_maturation`; Rust `native_bedrock`,
`openai_responses_streaming`, `canary_probe`.
- **Minimum rollout channel:** Registry-defined per feature; process
default is `stable`.
- **Stable/default behavior changed:** No unstable feature becomes
enabled by default. Explicit blocked CLI flags now fail instead of
silently doing nothing.
- **Kill switch / disable path:**
`HEADROOM_DISABLE_FEATURES=<comma-separated feature names>`; explicit
disable has highest precedence, including over the unsafe override.
- **Unsafe override required:** No.
`HEADROOM_UNSAFE_ALLOW_UNSTABLE_FEATURES=1` is break-glass only and
makes qualification evidence ineligible.
- **Qualification impact:** Adds machine-readable policy/snapshot
identities and eligibility; does not implement qualification itself.
- **Rollback path:** Set the named disable list for operational
rollback, lower the channel, or revert this PR.

## Review Readiness

- [x] I have performed a full diff 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 hard-to-understand areas
- [x] I have made corresponding documentation changes
- [x] My changes generate no new warnings
- [x] I added tests that reproduce and prevent every regression fixed
during review
- [x] New and existing affected tests pass locally
- [x] I did **not** edit `CHANGELOG.md`; release-please generates it
from the Conventional Commit PR title

## Additional Notes

Out of scope: artifact candidates, benchmark orchestration,
qualification manifests/gates, promotion automation, release branches,
publication guards, and release-risk classification. Those workflows can
consume the rollout registry digest, runtime snapshot digest, decision
reasons, and qualification eligibility through supported black-box
interfaces.

---------

Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net>
Co-authored-by: JD Davis <jd@JDH-AIR-00.local>
2026-08-12 23:16:54 -05:00
Abhay Singh fc5c4e239c fix(install): don't crash the PowerShell installer when $PROFILE is unset (#2469)
## Description

The PowerShell installer (`scripts/install.ps1`) crashes at the very end
on any machine where PowerShell cannot resolve the current user's
profile path.

`Ensure-ProfileBlock` locates the profile with:

```powershell
$profileDir = Split-Path -Parent $PROFILE
```

`$PROFILE` is an empty string when PowerShell cannot compute the profile
path for the current user, which happens for a fresh account with no
Documents folder yet, a service or CI context, or a redirected profile.
`Split-Path -Parent ''` then throws:

```
Split-Path : Cannot bind argument to parameter 'Path' because it is an empty string.
```

Because the script runs under `$ErrorActionPreference = 'Stop'`, that
terminates the whole installer with a non-zero exit, even though it
happens after the `headroom` wrapper and the persistent User PATH entry
were already written. The user sees a scary Split-Path error and assumes
the install failed.

## Fix

Skip the profile convenience block when `$PROFILE` is empty and log why.
`Ensure-PathEntry` already persists the User PATH for new sessions, so
the only thing skipped is auto-refreshing PATH inside the current
profile file, which does not exist in that environment anyway.
Well-behaved environments with a real `$PROFILE` are unchanged.

## 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

- `scripts/install.ps1`: early-return from `Ensure-ProfileBlock` with an
informational message when `$PROFILE` is null or empty, before the
`Split-Path` call.

## Testing

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

### Test Output

```text
$ python -m pytest tests/test_install/test_native_installers.py -q
1 passed, 1 skipped

# The PowerShell lifecycle test was failing on main before this change and now passes:
$ python -m pytest "tests/test_install/test_native_installers.py::test_powershell_native_installer_supports_persistent_docker_lifecycle" -q
1 passed
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12, Windows PowerShell 5.1, project
venv (`uv sync --extra proxy`), pytest in the venv.
- Exact command / steps: ran `install.ps1` under a temp `USERPROFILE`
with no Documents folder (the same setup the installer test uses).
Confirmed `$PROFILE` resolves to an empty string in that context and
that `Split-Path -Parent $PROFILE` throws there, then re-ran the
installer test with the fix.
- Observed result: before the fix the installer aborted with `Split-Path
: Cannot bind argument to parameter 'Path' because it is an empty
string` and exit code 1 (and the test failed); after the fix the
installer completes, writes the wrapper and PATH entry, logs that it
skipped the profile update, and the test passes. Ran against the actual
script.
- Not tested: a real end-user account whose Documents folder is
redirected to a network share.

## 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
- [ ] I have updated the CHANGELOG.md if applicable
2026-08-12 00:12:30 -05:00
Rod BoevandJD Davis 78591545ce fix: publish headroom-opencode in release workflow (#2372)
## Description

`headroom-opencode` is documented as an npm package, but the release
workflow never published it, so installs failed with a registry 404 even
though the plugin source already lived under `plugins/opencode`. This
wires the existing package into the npm release path, keeps its version
synced with root releases, and adds release guards for the new package.
Closes #76.

## 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

- added `headroom-opencode` to the npm release workflow, including
release-version stamping and `headroom-ai` dependency rewrite before
publish
- added `plugins/opencode/package.json` to release-please and local
version-sync guards
- synced the source opencode package version to the current release line
and documented the new npm package in the release docs
- added focused release workflow and version-sync tests for the opencode
package
- aligned the two failing dashboard Playwright tests with the current
Session/Lifetime split and `/stats-lifetime` fixture contract

## Testing

- [x] Unit tests pass (`uv run pytest scripts/tests/test_version_sync.py
-q`, `uv run pytest tests/test_release_workflows.py -q -k
'publish_npm_rewrites_opencode_dependency_after_version_and_before_publish
or opencode_source_dependency_matches_lockfile_registry_range or
release_please_manifest_config_consistency'`)
- [x] Unit tests pass (`uv run pytest
tests/test_dashboard_cache_lifetime_playwright.py
tests/test_dashboard_cache_ttl_playwright.py -q`)
- [x] Linting passes (`uv run ruff check scripts/verify-versions.py
scripts/version-sync.py scripts/tests/test_version_sync.py
tests/test_release_workflows.py`)
- [ ] Type checking passes (`uv run mypy headroom`)
- [x] New tests added for new functionality when applicable
- [x] Manual testing performed

### Test Output

```text
$ uv run pytest scripts/tests/test_version_sync.py -q
8 passed, 1 warning in 0.51s

$ uv run pytest tests/test_release_workflows.py -q -k 'publish_npm_rewrites_opencode_dependency_after_version_and_before_publish or opencode_source_dependency_matches_lockfile_registry_range or release_please_manifest_config_consistency'
2 passed, 38 deselected, 1 warning in 0.07s

$ uv run pytest tests/test_dashboard_cache_lifetime_playwright.py tests/test_dashboard_cache_ttl_playwright.py -q
4 passed, 1 warning in 4.04s

$ uv run ruff check scripts/verify-versions.py scripts/version-sync.py scripts/tests/test_version_sync.py tests/test_release_workflows.py
All checks passed!

$ npm ci && npm run build  (plugins/opencode)
Build success; dist/index.js, dist/entry.opencode.js, and DTS outputs emitted
```

## Real Behavior Proof

- Environment: Windows, Python 3.11.15, Node v24.15.0, npm 11.16.0
- Exact command / steps: inspected `.github/workflows/release.yml`,
updated the npm publish path for `plugins/opencode`, aligned the two
failing dashboard Playwright tests with the current Session/Lifetime
split, then ran the focused pytest commands above plus `npm ci && npm
run build` in `plugins/opencode`
- Observed result: the release workflow now versions and publishes
`headroom-opencode`, release-please and version-sync track
`plugins/opencode/package.json`, the dashboard tests now fetch durable
cache and setup-url data from the Lifetime view, and the opencode
package still builds locally from source
- Not tested: GitHub Package Registry publish

## 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 have updated the CHANGELOG.md if applicable

## Additional Notes

`CHANGELOG.md` is unchanged because release-please owns changelog
generation here.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-08-11 23:56:40 -05:00
Suliman AbdulrazzaqandTejas Chopra e044139001 fix(install): trust Docker bridge for dashboard metadata
## Summary

Closes #2909.

The `persistent-docker` installer now discovers Docker's default bridge
gateway and passes the exact `/32` gateway CIDR to the proxy's dashboard
metadata allowlist when no explicit
`HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` value is configured.
This keeps the existing metadata gate intact while allowing the
first-party loopback-published container to see its own Recent Requests
and Per-Project Savings data. Explicit user configuration continues to
take precedence.

Both native wrappers (POSIX and PowerShell) use the same behavior, and
installer integration coverage verifies the generated Docker command.

## Validation

- `python -m pytest tests/test_install/test_native_installers.py -q -k
bash` (1 skipped on Windows because Bash is unavailable)
- PowerShell wrapper smoke test with the repository fake Docker shim:
verified `docker network inspect bridge` is called and
`HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32` is passed
to `docker run`
- Explicit allowlist smoke test: verified an existing
`HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` is preserved without
adding a discovered default
- `git diff --check`

## Real behavior proof

Setup tested: Windows 11 host, PowerShell wrapper, repository fake
Docker shim (Docker CLI is not installed in this environment).

Exact command: `headroom.ps1 install apply --profile smoke --port 18999
--image fake/headroom:test`.

Observed result: the generated Docker invocation included `docker
network inspect bridge --format ...` and `--env
HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS=172.17.0.1/32`, and the
installer completed successfully.

Not tested: a live Docker daemon/dashboard request on this host.

---------

Co-authored-by: Tejas Chopra <tejas@Tejass-MacBook-Pro.local>
2026-08-11 14:25:29 -07:00
Raúl 3f2ca99fe1 fix(ci): restrict Codecov shard uploads (#2745)
## Description

Closes #2744

Restrict each Codecov Action v5 matrix upload to its declared
`coverage-${{ matrix.shard }}.xml` report. This prevents automatic
discovery
from uploading the unsharded `coverage.xml` alongside every shard.

## Type of Change

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

## Changes Made

- Set Codecov Action `disable_search: true` for Python shard uploads.
- Add a CI workflow contract test that protects the explicit-report-only
setup.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy headroom`) (not applicable:
workflow/test-only change)
- [x] New tests added new functionality
- [x] Manual testing performed (not applicable: GitHub Actions will
execute the workflow)

### Test Output

```text
$ uv run --with ruff ruff format --check scripts/tests/test_ci_workflow.py
1 file already formatted

$ uv run --with ruff ruff check scripts/tests/test_ci_workflow.py
All checks passed!

$ uv run --with pytest pytest scripts/tests/test_ci_workflow.py -q
2 passed
```

## Real Behavior Proof

- Environment: GitHub Actions Ubuntu runner using Python 3.12.13;
Codecov Action v5.
- Exact command / steps: Run the CI Python test matrix, which writes
`coverage-${{ matrix.shard }}.xml`, then runs the Codecov Action upload
step. Inspect the uploader's discovered/uploaded report list.
- Observed result: Before this change, raw CI logs showed the Action
explicitly uploading `coverage-2.xml` and additionally
discovering/uploading `coverage.xml`. This PR configures
`disable_search: true`; the workflow contract test confirms the explicit
report setting and search disablement. Runtime upload evidence will be
added from this draft PR's CI run.
- Not tested: Codecov's final cross-shard patch calculation; that
depends on Codecov processing the reports after CI completes.

## Review Readiness

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

## Checklist

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

## Additional Notes

This is intentionally limited to the Codecov upload configuration and
its
workflow contract test. It does not include the unrelated Copilot
Keychain fix.
2026-08-03 14:20:17 -07:00
Tejas Chopra e0ce4b1d48 fix: remove rtk and lean-ctx CLI context tools (#2677)
## Description

Removes both third-party CLI context tools — **rtk** and **lean-ctx** —
and with them the context-tool selector itself. Headroom no longer
downloads, installs or configures either one, and there is no
replacement.

The previous pass (#2344) gated only three entry points inside
`headroom/cli/wrap.py`. That left the feature reachable in practice:

| Gap | Effect |
|---|---|
| `scripts/install.sh:1544`, `install.ps1:1681` | Ran `rtk init --global
--auto-patch` from bash/PowerShell, **bypassing the Python gate
entirely** — `curl \| sh` still wrote a Claude Code `PreToolUse` hook
regardless of `HEADROOM_RTK` |
| `wrap.py` `_setup_context_tool_for_agent` | **`wrap openhands` was
broken by default**: `rtk_required=True` met a gate returning `None` →
`SystemExit(1)`. Invisible because all 8 openhands tests patched
`_ensure_rtk_binary` to a fake path |
| `proxy/helpers.py`, `subscription/tracker.py` | Proxy shelled out to
`rtk gain` from `/stats`, the dashboard and `headroom perf`; the tracker
polled it per contribution (`_RTK_WIRING_DEFAULT = "enabled"`) |
| No cleanup path | Nothing removed artifacts an earlier default had
installed, so a machine that once ran the old default kept rtk in the
loop forever (#1669, #1955) |

Also worth noting: the rtk binary download had **no SHA or signature
verification** — only `rtk --version` as a smoke test.

## Type of Change

- [x] 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
- [x] Code refactoring (no functional changes)

## Changes Made

**Removed** — `headroom/rtk/` and `headroom/lean_ctx/` packages,
`headroom/cli/wrap_rtk_metrics.py`, `_selected_context_tool` /
`_setup_context_tool_for_agent` / `_VALID_CONTEXT_TOOLS`, the `--rtk` /
`--no-rtk` / `--no-project-rtk` / `--keep-rtk` flags across all 18 wrap
subcommands, `HEADROOM_RTK*`, the proxy-side `rtk gain` polling, the
dashboard CLI-filtering panel (rows + all 8 `cliFiltering*` Alpine
getters), `paths.rtk_path()` / `lean_ctx_path()`, the SDK path helpers,
`benchmarks/rtk_loop_learn_eval.py`, and the `headroom/rtk/**` CI path
filters.

**Fails loudly, not silently** — `--context-tool` / `--no-context-tool`
/ `HEADROOM_CONTEXT_TOOL` are kept solely to error out. They live in
shell profiles, aliases and CI jobs, and accepting them as a no-op would
read as Headroom having quietly stopped working. The installers reject
them too, which matters more than it looks: their arg parsers forward
the first unknown flag **and everything after it** to the wrapped tool,
so a leftover `--no-rtk` would have silently swallowed a following
`--port` and then been ignored downstream.

**New `headroom/context_tool_cleanup.py`** — deleting the code cannot
help a machine that already ran the old default, since the hooks,
binaries and injected guidance are durable on disk.
`purge_context_tool_artifacts()` runs once per `wrap`/`unwrap` and
removes the registered hook entries, the generated hook scripts, the
Headroom-managed `~/.local/bin` symlinks, the vendored
`~/.headroom/bin/{rtk,lean-ctx}` binaries, the `lean-ctx` MCP server
entry and the marker-fenced instruction blocks. Deliberately
conservative: idempotent, **skips** a malformed config rather than
overwriting it, and only unlinks a symlink resolving inside Headroom's
own bin dir so a user's own build is untouched. It reports on
**stderr**, because `wrap/unwrap openclaw --prepare-only` emit
machine-readable JSON on stdout as their entire contract. Skipped for
`wrap selfheal` (runs from a SessionStart hook; must not race Claude
Code's writer for `~/.claude.json`) and for `--help`, which must stay
read-only.

**Client-config hardening** (discovered while investigating a "corrupted
Serena settings file" report) — `wrap.py` reset a settings file to `{}`
when an existing file would not parse, then wrote that back. One
hand-edited typo or a transient `EACCES`/`EINTR` on a valid file
destroyed the user's `permissions`, `env` and `hooks`, on **every
`headroom wrap claude`**. It now refuses to write. Separately,
`fsutil.write_text` is now atomic (temp file + `fsync` + `os.replace`),
fixing all 14 non-atomic client-config writes at once; it follows
symlinks rather than replacing them (dotfile managers) and preserves an
existing file's mode.

**Deliberately kept** — `rtk` stays in the wrapper-peel list in
`transforms/content_router.py`. It sits beside `sudo`/`env`/`timeout` as
shell-command grammar, so `rtk cat f` is still classified as a file read
for anyone running their own rtk install, which the purge intentionally
leaves alone.

## 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
$ ruff check headroom/ tests/ e2e/ --exclude headroom/dashboard/templates
All checks passed!

$ ruff format --check headroom/ tests/ e2e/ --exclude headroom/dashboard/templates
1255 files already formatted

$ mypy headroom/
Success: no issues found in 508 source files

$ pytest tests/test_context_tool_cleanup.py -q
11 passed

$ pytest tests/test_fsutil.py -q
12 passed

$ pytest tests/test_cli/test_wrap_codex.py -q            # 89 tests
89 passed in 431.68s
$ pytest tests/test_cli/test_wrap_opencode.py -q
39 passed in 257.46s
$ pytest tests/test_cli/test_wrap_helpers.py -q
45 passed
$ pytest tests/test_paths.py -q
75 passed
$ pytest tests/test_cli/test_unwrap_claude.py -q
14 passed
$ pytest tests/test_proxy_savings_history.py -q
39 passed
$ pytest tests/test_cli/test_wrap_copilot.py -q
27 passed
$ pytest tests/test_cli/test_wrap_zcode.py -q
20 passed
$ pytest tests/test_subscription_tracker.py -q
9 passed
$ pytest tests/test_proxy_dashboard_stats_cache.py -q
5 passed, 1 skipped
```

Repo-wide grep for 14 removed symbols (`headroom.rtk`,
`headroom.lean_ctx`, `_ensure_rtk_binary`, `_selected_context_tool`,
`_get_context_tool_stats`, `rtk_path`, `lean_ctx_path`,
`wrap_rtk_metrics`, `HEADROOM_RTK`, `cli_tokens_avoided`,
`tokens_saved_rtk`, …) across `*.py`, `*.ts`, `*.sh`, `*.ps1`, `*.yml`,
`*.html`: **zero hits**.

Notable test changes: `test_wrap_openhands.py` no longer patches
`_ensure_rtk_binary` and asserts `wrap openhands --prepare-only` exits 0
unpatched — the regression that was previously masked.
`test_wrap_continue.py` and `test_wrap_hintfile_agents.py` were removed
(every test drove RTK instruction injection). A new
`test_subscription_tracker.py::test_load_state_written_before_cli_context_tools_were_removed`
proves a pre-removal `subscription_state.json` still loads.

## Real Behavior Proof

- **Environment:** macOS 15.4 (darwin 25.4.0), Python 3.12.6, Headroom @
this branch, real `~/.headroom` and `~/.claude` on the dev machine.
- **Exact command / steps and observed result:**

```text
# 1. Retired flag fails loudly instead of silently no-op'ing
$ headroom wrap codex --prepare-only --context-tool rtk
Error: CLI context tools (rtk, lean-ctx) have been removed from Headroom: they
rewrote shell commands through a third-party binary Headroom no longer manages.
Drop --context-tool / --no-context-tool and unset HEADROOM_CONTEXT_TOOL;
`headroom wrap` uninstalls what they left behind on first run.

$ HEADROOM_CONTEXT_TOOL=lean-ctx headroom wrap codex --prepare-only
Error: CLI context tools (rtk, lean-ctx) have been removed from Headroom: ...

# 2. install.sh rejects the retired flags (extracted parse_wrap_args harness)
['--no-rtk', '--port', '9999']   rc=1  ERROR: CLI context tools ... Drop --no-rtk
['--context-tool=rtk']           rc=1  ERROR: CLI context tools ... Drop --context-tool
$ bash -n scripts/install.sh   # syntax OK

# 3. Purge ran against the real machine, which had all the orphaned artifacts
$ python -c "from headroom.context_tool_cleanup import purge_context_tool_artifacts; ..."
  removed ~/.headroom/bin/lean-ctx        (51 MB)
  removed ~/.headroom/bin/rtk             (7.7 MB)
  removed ~/.local/bin/rtk                (symlink into ~/.headroom/bin)
  removed ~/.claude/hooks/rtk-rewrite.sh
  removed 8 lean-ctx-* hook scripts
# ~/.claude.json afterwards: 90 top-level keys, 19 projects, mcpServers unchanged
# → ~59 MB reclaimed, no unrelated key touched

# 4. stdout stays machine-readable while the purge reports (planted a fake artifact)
$ headroom wrap openclaw --prepare-only --gateway-provider-id codex >out 2>err
$ cat out
{"enabled":true,"config":{"proxyPort":8787,...}}     # parses as JSON
$ cat err
Retired CLI context tool cleanup: removed /Users/tcms/.headroom/bin/rtk

# 5. --help is inert (planted artifact survives), a real run purges
$ headroom wrap codex --help   → artifact survived: CORRECT
$ headroom wrap openclaw --prepare-only → purged: CORRECT

# 6. MCP purge dry-run against a copy of the real 82 KB ~/.claude.json
top-level keys 90 -> 90;  projects 19 -> 19;  LOST keys: none
all content outside mcpServers byte-identical: True
```

Dashboard rendered via the Playwright test after the panel removal:
"Token Savings" shows only `Proxy 0 (0.0%)` / `Of total wire: 36.86%`,
and "Token Usage" reads Before Compression → Proxy Removed → After
Compression with no "Filtered (this session)" row. Nothing below the
removed panel broke.

- **Not tested:** Windows and Linux (macOS only) — `install.ps1` is
verified by brace-balance and inspection, not executed, since no `pwsh`
is available locally. The wrap e2e suite (`e2e/wrap/run.py`) was updated
but not run; it needs the Docker e2e image. `serena project index`
interaction is exercised in the stacked base 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)

## Additional Notes

**Stacked on #2676** (`tejas/serena-config-bootstrap`) — please merge
that first; this PR's base should then be retargeted to `main`, or it
will read as containing that fix too.

**Breaking-change migration for users:**
- Drop `--rtk`, `--no-rtk`, `--no-project-rtk`, `--keep-rtk`,
`--context-tool`, `--no-context-tool` from any alias, script or CI job,
and unset `HEADROOM_RTK*` / `HEADROOM_CONTEXT_TOOL`. They now error
rather than being ignored, so the failure is immediate and
self-explaining.
- Previously-installed artifacts are purged automatically on the next
`wrap`/`unwrap`; no manual cleanup needed.
- `headroom perf --json` no longer carries a `cli_filtering` key, and
`/stats` no longer returns a `context_tool` section.

**Docs:** `docs/rtk-architecture.md` deleted; RTK/lean-ctx removed from
`README.md`,
`docs/content/docs/{configuration,opencode,grok-build,docker-install,filesystem-contract}.mdx`,
`docs/observability.md` and the matching `wiki/` pages.
`REALIGNMENT/09-phase-G-rtk-observability.md` is marked SUPERSEDED
rather than deleted, to keep the planning record.

**Follow-ups not in scope:** `_emit_wrap_interrupted` was deleted as
dead code — its only caller was the `except KeyboardInterrupt` guarding
the binary download, so with no download there is nothing slow left to
interrupt.
2026-07-30 22:59:41 -07:00
Tejas Chopra 5383c6bf2f fix(release): sync generated version metadata on the release branch (#2659)
## Description

The 0.33.0 release PR (#2339) has sat in `changes-requested` since
2026-07-17. Root cause: **release-please only rewrites `pyproject.toml`
and its configured `extra-files`**, but other tracked files also carry
the version — and `server.json` is asserted byte-for-byte against
`render_server_json()`, which derives its version from `pyproject.toml`.
So the bump alone fails
`tests/test_mcp_registry/test_server_json.py::test_root_server_json_matches_builder`
(the `test (2)` shard) on every regenerated release PR.

Nothing in the repo regenerated `server.json` at all, so it fell behind
every release.

Unblocks #2339.

### Why the release *build* passes but the release PR does not

`release.yml` already runs `scripts/version-sync.py` immediately before
its own `verify-versions.py` gate (lines 145 and 278). That is why
`build` and `build-wheels` are green on #2339 despite the drift — it
syncs in the workspace, uncommitted. The regular CI test job does
**not** sync, so the fix has to be committed to the branch.

This also explains why reviewers kept seeing `verify-versions.py` fail
locally while CI's build jobs passed: the verifier is never run
un-synced inside `release.yml`.

## 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

- **`scripts/version-sync.py`**: also write `server.json`. It was the
one version-carrying file with no writer anywhere. Values are rewritten
in place so key order and formatting keep matching the builder's
byte-for-byte output (verified: the file is pure ASCII and round-trips
exactly through `json.dumps(..., indent=2) + "\n"`).
- **`.github/workflows/release-metadata-sync.yml`** (new): on a push to
`release-please--branches--**`, run version-sync → gate on
verify-versions → commit if changed.
- **Keyed off the branch push** because release-please force-regenerates
that branch on every merge to main. That is precisely what wiped the
hand-pushed metadata fixes on #2339 (`2a86c8ff`, `d5ea4dc5`) — a push
trigger re-heals after every regeneration instead of being lost.
- **Uses the same PAT as `release-please.yml`**: a `GITHUB_TOKEN` push
does not trigger workflows, so the release PR's checks would never
re-run against the synced commit and would stay red.
- **Idempotent**: the self-triggered rerun finds no diff and exits
before pushing, so the loop terminates after one no-op run.
- **Corrected pre-existing drift on `main`**: the agent-hooks plugin
manifests, both marketplace manifests, and `.releasemetadata` were
stranded at **0.31.0** — never bumped for 0.32.0 either.
`verify-versions.py` now passes on `main`.

### Why not more `extra-files` entries

That would need ~13 jsonpath entries restating what `version-sync.py`
already knows, and a jsonpath that fails to match **fails silently** —
the same class of failure this PR removes, discoverable only after a
real release PR regenerates. There is also no precedent for nested
jsonpath (`$.packages[0].version`, `$.metadata.version`) in the config
today; both existing entries are plain `$.version`. Running the script
keeps one source of truth, and files added to it later are covered with
no change here.

## Testing

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

### Test Output

```text
$ python -m pytest scripts/tests/ tests/test_release_workflows.py tests/test_mcp_registry/ -q
207 passed in 2.69s

$ ruff check scripts/version-sync.py scripts/tests/test_version_sync.py tests/test_release_workflows.py
All checks passed!
$ ruff format --check <same>
3 files already formatted

$ actionlint .github/workflows/release-metadata-sync.yml
(clean)
```

New tests:
- `test_server_json_version_is_synchronized` — version-sync moves both
`server.json` version fields and preserves the other keys.
- `test_release_metadata_sync_runs_on_release_please_branch` — asserts
the trigger, the sync→verify→commit ordering, the no-op guard, and the
PAT.
- `test_version_sync_covers_every_file_the_verifier_gates` — guards
`version-sync.py` and `verify-versions.py` against drifting apart again,
which is the root cause here.

## Real Behavior Proof

- **Environment:** macOS (Darwin arm64), Python 3.12, repo venv.
- **Exact command / steps:** reproduced the CI failure locally by
simulating release-please's partial bump, then applying the fix.

**Reproducing the exact `test (2)` failure** — set `pyproject` to 0.33.0
while `server.json` stays at 0.32.0, as release-please leaves it:

```text
$ python -m pytest tests/test_mcp_registry/test_server_json.py -q
FAILED tests/test_mcp_registry/test_server_json.py::test_root_server_json_matches_builder
1 failed, 3 passed
```

**After `version-sync.py`:**

```text
$ python scripts/version-sync.py && python -m pytest tests/test_mcp_registry/test_server_json.py -q
4 passed
```

**Both gates green on a simulated 0.33.0 bump:**

```text
$ python scripts/version-sync.py --version 0.33.0
Version synchronized to 0.33.0
$ python scripts/verify-versions.py
All versions aligned at 0.33.0
$ python -m pytest tests/test_mcp_registry/test_server_json.py -q
4 passed
```

**Idempotency** (the property the workflow's loop-termination relies
on): re-running against an already-synced tree leaves `pyproject.toml`,
`server.json`, `openclaw`, and `sdk/typescript` untouched.

- **Not tested:** the workflow has not executed on a real release-please
branch regeneration — that can only be exercised once this is on `main`
and release-please next updates #2339. The PAT push path and the
self-trigger no-op are reasoned from `release-please.yml`'s existing
token comment and from local idempotency, not observed in CI.

## 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`

## Additional Notes

**Context on the v0.32.0 release failure, since it is easy to misread as
"images never build".** Every artifact built for v0.32.0 — all 5 wheel
platforms including Windows, all 16 Docker builds + 8 manifests +
`promote-latest`, npm, and GitHub Packages. Only `publish-pypi` failed
(PyPI attestations, already fixed by `f9cbdd6e` / #2405), and
`create-release` was skipped because it depends on it. That is why the
release looked like it produced nothing.

**Separate, approaching blocker — not addressed here.** PyPI is at
**9.69 GB of its 10 GB project cap (96.9%)**, leaving ~305 MB against
~68 MB per release, so roughly 4 more releases fit. The `0.21.x` series
alone holds **6.58 GB across 31 releases**, from the old
every-push-is-a-release era; pruning it would reclaim two thirds of the
quota. Worth a separate issue.

**`.releasemetadata` is written but never read** by anything outside
`version-sync.py` and its test. It is kept in sync here for internal
consistency, but it may be a deletion candidate.
2026-07-29 15:12:04 -07:00
Ruben A. e530de5ad2 feat(rust): port CodeCompressor AST compressor to Rust (parity-only) (#1154)
Adds crates/headroom-core/src/transforms/code_compressor.rs (1,882 lines): the
AST-aware CodeCompressor ported to Rust on tree-sitter, with grammars for
Python, JavaScript, TypeScript, Go, Rust, Java, C and C++.

Parity-only, like #1153. Nothing calls it: the only references outside the
module are the pub mod / pub use declarations in transforms/mod.rs, and
live_zone.rs still routes SourceCode to a no-op. The pyo3 bridge is untouched
and no Python source changes, so the engine is unreachable from the shipped
package. #1155 wires it into live-zone dispatch.

Every grammar is pinned with '=' to the exact version of the corresponding
Python tree-sitter-<lang> PyPI wheel. Same version on crates.io and PyPI means
the same grammar.js, hence the same generated parser.c, hence node-for-node
identical ASTs — the precondition for byte-parity. A canary over 9 samples x 8
languages confirmed identical node-type and line-span trees at these pins;
bumping any pin requires re-running it and re-recording the fixtures.

Ships 30 recorded parity fixtures, a CodeCompressorComparator in
headroom-parity, and scripts/record_code_compressor_fixtures.py.

Verified byte-identical to the recorded Python output:

  [code_aware_compressor] total=30 matched=30 skipped=0 diffed=0

Full harness on the merge result: 227 fixtures, 182 matched, 45 skipped
(cache_aligner + ccr stubs), 0 diffed, exit 0 — with kompress at 21/21 under
ONNX Runtime 1.24.4 (see #2591).

Also verified cargo check -p headroom-core --no-default-features passes, so the
static-musl path stays intact.
2026-07-27 09:21:57 -07:00
Ruben A. 83e27e5036 feat(rust): port Kompress ML prose compressor to Rust (parity-only) (#1153)
Adds crates/headroom-core/src/transforms/kompress.rs (672 lines): the Kompress
ML prose compressor ported to Rust, running the ModernBERT tokenizer plus the
kompress-v2-base ONNX model through ort with a cache-only loader that never
touches the network.

Parity-only. Nothing calls it: the only references outside the module are the
pub mod / pub use declarations in transforms/mod.rs. live_zone.rs still carries
TODO(PR-B4), so PlainText dispatch remains a no-op and Python continues to serve
prose compression. The pyo3 bridge is untouched and no Python source changes, so
the new engine is unreachable from the shipped package. #1155 wires it up.

Ships 21 recorded parity fixtures, a KompressComparator in headroom-parity, and
scripts/record_kompress_fixtures.py.

Verified byte-identical to the recorded Python output:

  [kompress] total=21 matched=21 skipped=0 diffed=0

That required ONNX Runtime >= 1.24 (see #2591) — below it ort deadlocks instead
of erroring, which is why these fixtures had never been run. In CI the model is
absent from the HF cache, so the comparator errors and the fixtures report
Skipped rather than hanging.

Also gates the module behind the ml feature, matching magika_detector: kompress.rs
uses ort, which is optional = true, so an unconditional pub mod broke
cargo check --no-default-features (the static-musl path). CI does not catch that
class of break because cargo test --workspace only builds default features.
2026-07-27 08:17:53 -07:00
Floze 2bb14d1ab2 fix(ci): align Ruff tooling versions (#2406)
## Description

Ruff currently has three independent versions: `uv.lock` resolves
`0.14.14`, pre-commit runs `0.9.4`, and CI installs `0.15.17`.
Contributors can therefore pass one formatter path and fail another.

Make the exact Ruff pin in `pyproject.toml` the source of truth, align
the lockfile and pre-commit hook to it, and make CI read that pin
through a deterministic consistency verifier instead of carrying another
hardcoded version.

Closes #2398

## 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 causes existing functionality
to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Pin the existing `[dev]` Ruff dependency to `0.15.17`, the formatter
baseline already used by CI.
- Refresh only Ruff in `uv.lock` with `uv 0.11.29`.
- Align `ruff-pre-commit` to `v0.15.17`.
- Add `scripts/verify-ruff-version.py` and run it from pre-commit and
CI.
- Make CI install the verified version read from `pyproject.toml` rather
than a separate literal.

## Testing

- [ ] Unit tests pass (`pytest`) — not run; no runtime source or test
behavior changed.
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New deterministic guard proves the configuration fix
- [x] Manual testing performed

### Test Output

```text
# Before: run the verifier with the patched pyproject pin but base-branch
# uv.lock, pre-commit config, and workflow.
Ruff version mismatch detected:
  uv.lock uses Ruff 0.14.14, expected 0.15.17
  .pre-commit-config.yaml uses Ruff 0.9.4, expected 0.15.17
  ci.yml does not run 'python scripts/verify-ruff-version.py --print-version'
  ci.yml does not install Ruff from 'steps.ruff-version.outputs.version'

$ python3 scripts/verify-ruff-version.py
Ruff versions aligned at 0.15.17

$ uvx uv@0.11.29 lock --check
Resolved 269 packages

$ uvx uv@0.11.29 tree --locked --package ruff
ruff v0.15.17

$ uvx ruff@0.15.17 check .
All checks passed!

$ uvx ruff@0.15.17 format --check .
1322 files already formatted

$ uvx mypy@1.20.2 headroom --ignore-missing-imports
Success: no issues found in 505 source files

$ uvx --with tomli mypy@1.20.2 scripts/verify-ruff-version.py --ignore-missing-imports
Success: no issues found in 1 source file

$ uvx pre-commit run ruff --all-files
Passed
$ uvx pre-commit run ruff-format --all-files
Passed
$ uvx pre-commit run verify-ruff-version --all-files
Passed
```

## Real Behavior Proof

- Environment: macOS 26.5, Python 3.14.6 locally; Python 3.10 fallback
also exercised; `uv 0.11.29`, Ruff `0.15.17`, mypy `1.20.2`.
- Exact command / steps: reproduced the mismatch using the base branch's
real `uv.lock`, `.pre-commit-config.yaml`, and
`.github/workflows/ci.yml`; then ran the verifier, locked Ruff tree,
full Ruff check/format, mypy, and actual pre-commit hooks after the
patch.
- Observed result: the base state fails with all four drift points
listed; the patched state reports one aligned Ruff version (`0.15.17`)
and every formatter path passes.
- Not tested: runtime proxy behavior and the pytest suite, because the
change is limited to development-tool configuration, lock metadata,
pre-commit, and CI wiring.

## Dependency / Supply-Chain Justification

- Ruff is an existing development-only formatter maintained by Astral;
this PR adds no new package.
- `0.15.17` is required to fix local/CI reproducibility and has already
been the repository's CI formatter baseline since #1295.
- Install surface is limited to the `[dev]` extra, lint CI job, and
pre-commit environment. Production/runtime dependencies are unchanged.
- The `uv.lock` refresh updates only Ruff; no unrelated dependency
upgrades are included.

## 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 the non-obvious consistency checks
- [x] Documentation changes are N/A; contributor commands are unchanged
- [x] My changes generate no new warnings
- [x] The guard fails on the real base-state mismatch and passes after
the fix
- [ ] New and existing unit tests pass locally — not run; no runtime
code changed
- [x] I did not edit `CHANGELOG.md`; release-please will use the
conventional PR title

## Additional Notes

No formatter-driven source changes are included. AI assistance was used
to inspect configuration, implement the verifier, and run validation.
2026-07-18 20:55:20 -07:00
5709291914 chore(release): harden local artifact smokes (#1824)
## Description

Harden the release artifact workflow so maintainers can reproduce npm
and Python release checks locally and so OpenClaw packaging does not
depend on a not-yet-published SDK version. This follow-up also keeps the
OpenClaw loader export contract explicit and updates the PR after the
branch was merged with current `headroomlabs/main`.

## Type of Change

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

## Changes Made

- Added reusable local release smoke scripts for npm assets, Python
wheel/sdist artifacts, and the combined release gate.
- Switched the release workflow npm asset build to the reusable npm
builder.
- Made OpenClaw release asset building install against the just-built
local SDK tarball before rewriting packed metadata to the release
dependency range.
- Kept the OpenClaw source dependency registry-installable at
`headroom-ai@^0.22.3` while the packed artifact still ships
`^<release-version>`.
- Added `registerHeadroomPlugin` as a named export while preserving the
default `{ register }` OpenClaw loader contract.
- Added Windows development bootstrap docs/script and regression tests
for version sync, npm asset ordering, OpenClaw source installability,
and Python wheel smoke import isolation.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
uv run --with pytest python -m pytest tests/test_release_workflows.py scripts/tests/test_version_sync.py -q
44 passed, 1 warning

node --check scripts/build_npm_release_assets.mjs
node --check scripts/verify_npm_release_assets.mjs

python -m py_compile scripts/build_python_release_smoke.py scripts/release_smoke_all.py scripts/version-sync.py
python scripts/verify-versions.py
All versions aligned at 0.31.0

npm ci (plugins/openclaw)
added 88 packages, audited 89 packages, found 0 vulnerabilities

python scripts/release_smoke_all.py --out release-assets-local/all-pr1824-postmerge-fixed-20260710-104739
Verified npm release assets for 0.31.0
wheel metadata OK: headroom_ai-0.31.0-cp310-abi3-win_amd64.whl contains headroom/_core.pyd
sdist License-File metadata OK: ['LICENSE', 'NOTICE']
smoke-import OK: version=0.31.0 hello=headroom-core
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.14.3, Node v24.14.0, npm 11.9.0, uv
0.11.15, Rust/Cargo already installed in the local development
environment.
- Exact command / steps: Ran `python scripts/release_smoke_all.py --out
release-assets-local/all-pr1824-postmerge-fixed-20260710-104739` after
syncing this branch with current `headroomlabs/main`.
- Observed result: The command built `headroom-ai-0.31.0.tgz`,
`headroom-openclaw-0.31.0.tgz`,
`headroom_ai-0.31.0-cp310-abi3-win_amd64.whl`, and
`headroom_ai-0.31.0.tar.gz`; npm verifier passed; the wheel installed
into a fresh venv and imported `headroom._core`.
- Not tested: Full GitHub Actions release matrix and publish jobs with
real PyPI/npm/GitHub Packages credentials.

## 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
- [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
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

N/A.

## Additional Notes

The post-merge full smoke initially failed because the OpenClaw source
package depended on `headroom-ai@^0.31.0`, which is not available on
public npm yet. The builder now installs OpenClaw against the just-built
local SDK tarball before build/pack, and then rewrites packed metadata
to `^0.31.0`.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
2026-07-14 16:07:34 -04:00
c3db8e47f8 fix(install): default docker image to headroomlabs-ai GHCR registry (#1867) (#2039)
## Description

The GitHub repository was transferred from `chopratejas/headroom` to
`headroomlabs-ai/headroom`. GitHub 301-redirects transferred repos for
web and git operations, but **GitHub Container Registry (GHCR) does
not** — the old package `ghcr.io/chopratejas/headroom` is now orphaned
and frozen (its `latest` tag stopped advancing at `0.27.0`), while CI
publishes new images to `ghcr.io/headroomlabs-ai/headroom` (the workflow
derives the path from `${{ github.repository }}`).

Headroom's install tooling still defaulted to the dead path, so
`headroom install apply --preset persistent-docker`, `headroom init`,
and the standalone install scripts all pulled a stale `0.27.0` image
instead of the current release.

This changes every docker-image **default** to
`ghcr.io/headroomlabs-ai/headroom:latest`.

Closes #1867

## 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/install/models.py` — `InstallManifest.image` default.
- `headroom/cli/install.py` — `--image` Click option default.
- `headroom/cli/init.py` — two `InstallManifest(...)` image args.
- `scripts/install.sh` / `scripts/install.ps1` — `IMAGE_DEFAULT` /
`$ImageDefault` plus the `--image` help-text default.
- `docker/docker-compose.native.yml` — image default in both services.
- `tests/test_install/test_planner.py` (4) and
`tests/test_install/test_runtime.py` (5) — updated the assertions that
pinned the old image (including `assert "<image>" in command`), so they
now verify the corrected registry threads through the planner and docker
runtime command.

Scope note: `github.com/chopratejas/...` links and the plugin
marketplace slug are intentionally **not** changed — GitHub redirects
those, so they still work. Only the genuinely-dead GHCR image references
are touched. No new dependency, no new abstraction.

## 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
$ uv run pytest tests/test_install/ -q
99 passed, 1 skipped in 48.34s

$ uv run ruff check headroom/install/models.py headroom/cli/install.py headroom/cli/init.py
All checks passed!

$ grep -rn "ghcr.io/chopratejas/headroom" headroom/ scripts/ docker/ tests/
# (no source matches — every default now points at headroomlabs-ai)
```

The install-test assertions pinned the old image, so they fail against
the old defaults and pass after the fix — they are the regression guard.

## Real Behavior Proof

- **Environment:** Windows 11, Python 3.13.5, headroom installed from
this branch (editable, via `uv`).
- **Exact command / steps:** The dead-registry claim is verifiable at
the registry level, independent of a release:
  ```text
docker pull ghcr.io/chopratejas/headroom:latest # old default → 0.27.0
(frozen / orphaned)
docker pull ghcr.io/headroomlabs-ai/headroom:latest # new default →
current release
  ```
And the install pipeline now emits the correct image (covered by
`tests/test_install/test_runtime.py`, which asserts the resolved docker
command contains `ghcr.io/headroomlabs-ai/headroom:latest`).
- **Observed result:** `grep` confirms no `ghcr.io/chopratejas/headroom`
default remains in code, scripts, compose, or tests;
`tests/test_install/` is green (99 passed) with the corrected image
asserted end-to-end through planner → runtime command.
- **Not tested:** A live `docker pull` of both tags on this specific
machine (no local Docker daemon guaranteed) — the registry difference is
reproducible by anyone running the two `docker pull` commands above; and
an end-to-end `headroom install apply --preset persistent-docker`
against a real Docker host.

## 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 have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

N/A

## Additional Notes

- Documentation checklist item is N/A — no user-facing docs surface
beyond the CHANGELOG entry.
- `mypy` left unchecked — not run as part of this verification; the
change is a string-default swap with no type-level surface.
- The `--image` help text and `docker-compose.native.yml` were included
so every user-facing default is consistent; only the dead GHCR image
string was changed.

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
2026-07-13 14:01:28 -04:00
JerrettDavis 2d418335a1 ci: preserve merge labels while state is unknown 2026-07-09 19:51:41 -05:00