Commit Graph
32 Commits
Author SHA1 Message Date
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
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
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
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
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
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
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 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
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
JerrettDavis 2d418335a1 ci: preserve merge labels while state is unknown 2026-07-09 19:51:41 -05:00
JerrettDavis 595b709a5b ci: keep ready label off changes-requested PRs 2026-07-09 19:49:55 -05:00
Sepuri Sai Krishna 772adc93b2 fix(scripts): rename .releaseetadata to .releasemetadata (#1246)
## Description
  
Fixes a typo in the release metadata filename written by
`scripts/version-sync.py`.
The file was being created as `.releaseetadata` (double `e`) instead of
`.releasemetadata`.
Any downstream tooling or developer looking for the artifact by its
correct name would not find it.

  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/version-sync.py`: corrected the filename in
`write_release_metadata()` — both the docstring and the `metadata_path`
assignment.
- `scripts/tests/test_version_sync.py`: updated 3 test assertions to
reference `.releasemetadata`.

  ## 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   
  $ uv run python -m pytest scripts/tests/test_version_sync.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 6 items
  
scripts/tests/test_version_sync.py ...... [100%]

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

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

  $ 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: grep -r "releaseetadata" scripts/ before the
fix returns hits; after the fix returns nothing. Confirmed
.releasemetadata is written correctly by
  test_release_metadata_written.
- Observed result: all 6 test_version_sync.py tests pass with the
corrected filename.
- Not tested: full repository pytest, ruff, and mypy — this is a
one-line spelling fix with no logic changes.

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

- The typo was consistent across implementation and tests, so all tests
passed before this fix with the wrong name. The fix corrects both the
code and the test expectations together.
- No production behaviour changes the file is written but not yet
consumed by any workflow step.
2026-07-09 17:29:17 -05:00
JD Davis adb793bee1 ci: harden PR governance and model cache checks (#1401)
## Description

Hardens two routine PR-review pain points from the recent open-PR sweep:

- PR Governance reruns could keep validating the stale
`pull_request_target` event body even after the live PR description had
been fixed.
- Main CI model-cache misses could surface as dozens of unrelated
memory-test failures instead of one clear cache-preflight failure.

This intentionally avoids PyPI/package-bloat and release/nightly
workflow changes so the PR stays scoped to review and CI stabilization.

## Type of Change

- [x] Bug fix
- [ ] New feature
- [ ] Documentation
- [x] Refactor
- [x] Tests only

## Changes Made

- Added `--body-file` support to `scripts/pr-governance.py` so workflows
can validate the current PR body rather than stale rerun payloads.
- Updated PR Governance to fetch the live PR body via the GitHub API
before validating template fields.
- Added a CI preflight script that loads the default
sentence-transformer model in offline mode and verifies the expected
embedding dimension.
- Wired that preflight into the sharded CI job before pytest starts,
turning missing/corrupt Hugging Face caches into one early, actionable
failure.
- Added workflow/script regression tests for the live-body override and
model-cache preflight placement.

## Testing

- [x] Unit tests
- [x] Lint/static checks
- [ ] Integration tests
- [ ] Manual testing

### Test Output

```text
uv run --with pytest --with pytest-asyncio python -m pytest scripts/tests/test_pr_governance.py scripts/tests/test_pr_health_workflow.py scripts/tests/test_ci_workflow.py -q
9 passed in 0.04s

uv run ruff check scripts/pr-governance.py scripts/ci/verify_hf_model_cache.py scripts/tests/test_pr_governance.py scripts/tests/test_pr_health_workflow.py scripts/tests/test_ci_workflow.py
All checks passed!

python -m py_compile scripts\ci\verify_hf_model_cache.py scripts\pr-governance.py
# passed
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.13.3, isolated worktree
`C:\git\headroom\.worktrees\stabilization-hardening`.
- Exact command / steps: Ran the focused governance/workflow tests, ruff
on touched Python files, and `py_compile` for the executable scripts.
- Observed result: Governance tests prove a stale event body can be
overridden by the live PR body; workflow tests prove CI validates live
PR body and runs the Hugging Face offline-cache preflight before pytest
shards.
- Not tested: Full GitHub CI before PR creation; that will run on this
PR. The new Hugging Face preflight itself is intentionally not run
locally because it depends on the CI-warmed offline model cache.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review
2026-06-26 21:34:34 -07:00
ParideboyandJerrettDavis 5194388b66 fix(ci): normalize Windows CRLF line endings in PR governance script (#1012)
## Description

The `CODE_BLOCK_RE` regex in `scripts/pr-governance.py` expects LF after
the opening fenced code block. PR bodies authored on Windows can arrive
with CRLF line endings, which leaves a `\r` before the `\n` and prevents
`has_test_output()` from detecting a valid Test Output block.

This normalizes CRLF to LF once when loading the pull request body,
before section extraction and code-block matching. A regression test now
verifies that a valid PR body with CRLF line endings still passes
governance.

## Type of Change

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

## Changes Made

- Normalize Windows CRLF line endings in `scripts/pr-governance.py`
before regex-based validation runs.
- Added `test_validate_pull_request_accepts_crlf_test_output_code_block`
to prevent regressions.

## Testing

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

### Test Output

```text
python -m pytest scripts/tests/test_pr_governance.py scripts/tests/test_pr_health_labels.py scripts/tests/test_pr_health_workflow.py -q
8 passed in 0.06s

ruff check scripts/pr-governance.py scripts/tests/test_pr_governance.py scripts/tests/test_pr_health_labels.py scripts/tests/test_pr_health_workflow.py
All checks passed!

ruff format --check scripts/pr-governance.py scripts/tests/test_pr_governance.py scripts/tests/test_pr_health_labels.py scripts/tests/test_pr_health_workflow.py
4 files already formatted
```

## Real Behavior Proof

- Environment: local Windows 11 checkout, Python 3.13.13.
- Exact command / steps: Converted the known-valid governance test body
to CRLF line endings and passed it through `validate_pull_request` in
the new regression test.
- Observed result: The report is valid with no problems, proving the
fenced Test Output block is recognized after normalization.
- Not tested: GitHub-hosted Windows PR authoring path end to end; the
unit test covers the exact CRLF body shape consumed by the validator.

## Review Readiness

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

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-06-22 18:45:12 -05:00
JD Davis 74dff94fb8 fix(ci): make PR governance advisory (#1047)
## Description

Make the PR Governance workflow advisory for incomplete pull request
bodies. The workflow still validates the template, writes the run
summary, comments on the PR, and syncs governance labels, but it no
longer marks the check red for expected author follow-up.

## Type of Change

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

## Changes Made

- Replaced the failing incomplete-template step with a reporting step
that exits successfully.
- Added a regression test that guards against reintroducing the hard
failure path.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Manual testing performed

### Test Output

```text
pytest scripts/tests/test_pr_governance.py scripts/tests/test_pr_health_labels.py scripts/tests/test_pr_health_workflow.py -q
# 7 passed

act pull_request_target -W .github/workflows/pr-health.yml -e .github/act/pr-governance-invalid.json -n
# Job succeeded

act pull_request_target -W .github/workflows/pr-health.yml -e .github/act/pr-governance-valid.json -n
# Job succeeded
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.13.13, act 0.2.87, Docker Desktop
via npipe.
- Exact command / steps: Ran the focused governance/label tests and
`act` dry-runs for the valid and invalid PR governance payloads.
- Observed result: Tests passed, the invalid payload's reporting step
completed successfully, and both PR Governance dry-runs ended with job
success.
- Not tested: Full non-dry-run `act` execution against GitHub API
side-effect steps, to avoid mutating real labels/comments from a local
run.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review
2026-06-16 12:36:39 -05:00
RAPHAEL LUGO 99c874d423 fix(codex): PR health label check state (#986)
## Description

Fix the PR health label job so `status: ci failing` reflects the latest
check attempt for each check, not historical failed or cancelled
attempts that still appear in `statusCheckRollup`.

This showed up on #984: the current checks were green, but the label job
kept `status: ci failing` because older failed template runs were still
present in the rollup payload.

## Type of Change

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

## Changes Made

- Added a small `.github/scripts/pr-health-labels.py` helper that groups
check-rollup entries by logical check name and evaluates only the newest
entry for each check.
- Updated the PR health workflow label job to call the helper instead of
treating any historical failing rollup entry as current failure.
- Added regression tests for historical failures followed by latest
passing attempts, plus current latest failure behavior.

## Testing

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

### Test Output

```text
PYTEST_ADDOPTS='-p no:cacheprovider' pytest scripts/tests -q
47 passed, 1 warning in 0.39s

python .github/scripts/pr-health-labels.py --state-json '<payload with old FAILURE and latest SUCCESS>'
passing

data=$(gh pr view 984 --repo chopratejas/headroom --json statusCheckRollup)
python .github/scripts/pr-health-labels.py --state-json "$data"
passing
```

## Real Behavior Proof

- Environment: macOS local checkout, Python 3.11.7, live GitHub PR #984
check-rollup payload fetched with `gh pr view`.
- Exact command / steps: Added regression coverage for historical
failed/cancelled check runs followed by latest successful runs, ran the
scripts test suite, and evaluated live PR #984's `statusCheckRollup`
with the new helper.
- Observed result: The helper returns `passing` for #984's live payload
even though older failed/cancelled check runs are still present, while
still returning `failing` when the latest attempt for a check failed.
- Not tested: A full GitHub Actions run of the updated workflow on
upstream before merge; this PR should exercise the workflow on itself.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review
2026-06-15 16:52:26 -05:00
96a7d7cbbe Fix CI lint failure by formatting PR governance scripts (#933)
`CI / lint (pull_request)` failed because `ruff format --check` detected
formatting drift in the new PR governance script and its tests. This PR
aligns those files with repository formatting rules so the lint job can
pass.

- **Root cause**
  - `ruff format --check .` reported two files as non-canonical:
    - `scripts/pr-governance.py`
    - `scripts/tests/test_pr_governance.py`

- **Change set**
  - Applied `ruff` formatting to only the two flagged files.
- No behavioral or logic changes; edits are line-wrap/format
normalization only.

- **Representative update**
  ```python
  parser.add_argument(
"--event", type=Path, required=True, help="Path to the GitHub event
payload JSON."
  )
  ```

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
2026-06-12 17:11:39 -05:00
chopratejas 80f403db4a test(scripts): cover branch-aware _should_sync in sync-plugin-versions
PR #484 added branch-awareness to ``scripts/sync-plugin-versions.py``
(no-op on feature branches unless ``HEADROOM_SYNC_VERSIONS=1``). The
existing ``test_main_runs_plugin_only_version_sync`` test broke
because it didn't account for the new ``_should_sync`` gate — on a
feature branch the main() function early-returns and the subprocess
mock was never invoked, but actually the test broke earlier because
``_current_branch`` calls ``subprocess.run(..., capture_output=True,
text=True, check=False)`` and the test's lambda only accepted
``(command, cwd, check)``.

Fix: force ``_should_sync`` True in the existing test so it locks
the run-path, then add 4 new tests covering the branch-aware logic
itself (env override, main vs feature, git-unavailable defensive
no-op).
2026-05-19 12:49:21 -05:00
Tejas Chopra ea1f608e79 fix: make proxy upgrades version-aware
Derive source-tree versions from release history so headroom --version no longer reports stale project metadata.

Restart stale idle proxies after an upgrade, but leave active sessions running to avoid interrupting ongoing conversations.

Remove _version.py from version-sync ownership and make version verification catch package/plugin manifest drift.
2026-05-09 15:58:27 -07:00
GarmandClaude Opus 4.7 efd2ac1ca4 chore: renormalize line endings to LF
`.gitattributes` declares `*.py text eol=lf` and `*.sh text eol=lf`, but
74 files (73 .py, 1 .sh) are stored in the index with CRLF line endings,
violating that contract. Every macOS/Linux clone reports these files as
"modified" on fresh checkout because git's diff engine sees the stored
bytes don't match the attribute contract, even though the working tree
and index match byte-for-byte.

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

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

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-24 15:33:30 +02:00
JerrettDavisandCopilot b852460af9 chore: normalize line endings in init diffs
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-21 20:17:14 -05:00
JerrettDavisandCopilot a278a7b0ba test: cover init install flows end to end
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-21 20:15:11 -05:00
JerrettDavisandCopilot c5d795c2af build: sync agent hook manifests to repo semver
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-21 20:03:14 -05:00
JerrettDavisandCopilot c24b1fa46f fix: harden release notes and semver
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-16 18:50:36 -05:00
JerrettDavisandClaude Opus 4.6 6299644b6d feat: add changelog generator from conventional commits
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-15 19:34:50 -05:00
JerrettDavis 93af60ac31 feat: add version synchronization script for multi-package releases 2026-04-15 19:29:15 -05:00