## Description
The committed `server.json` pinned version `0.27.0` while
`pyproject.toml` is at `0.32.0`.
`tests/test_mcp_registry/test_server_json.py::test_root_server_json_matches_builder`
asserts the committed artifact equals `render_server_json()`, so it
fails on `main`. This regenerates `server.json` from the current
metadata.
Found while getting the security PR (#2207) CI green. The two other
pre-existing failures it was grouped with were **already fixed on
`main`** by recent commits — `test_cold_start_fast_pass`
(`record_compression_failed` added to the metrics double) and
`test_cli/test_wrap_zcode` (watcher mock now passes the port) — so this
PR only needs the `server.json` regen.
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
## Changes Made
- Regenerated `server.json` from `render_server_json()` so the committed
artifact matches the current package version (`0.32.0`).
## Testing
- [x] Unit tests pass (`pytest`) — the previously-failing tests
- [x] Linting passes (`ruff check`)
### Test Output
```text
$ pytest tests/test_mcp_registry/test_server_json.py::test_root_server_json_matches_builder \
tests/test_cold_start_fast_pass.py::test_fast_pass_failure_falls_back_to_full_deferral \
tests/test_cli/test_wrap_zcode.py::test_wrap_prints_proxy_urls -q
3 passed
```
## Real Behavior Proof
- Environment: branch off current `main` (`ea3d5a86`), Python 3.12,
project `.venv`.
- Steps: `python -c "from headroom.mcp_registry import
render_server_json;
open('server.json','w').write(render_server_json())"`, then ran the MCP
registry test.
- Observed: `server.json` `version` → `0.32.0`;
`test_root_server_json_matches_builder` passes.
- Not tested: full suite (single generated-artifact change).
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] Documentation changes (N/A)
- [x] My changes generate no new warnings
- [ ] Tests added (N/A — regenerates an artifact an existing test
already guards)
- [x] New and existing unit tests pass locally
- [ ] CHANGELOG (N/A)
## Additional Notes
`server.json` is a generated artifact
(`headroom/mcp_registry/server_json.py`) — regenerate with
`render_server_json()` after any version bump.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Description
`headroom proxy` can wedge when code-aware compression enters the
tree-sitter Perl external scanner and the native scan keeps the GIL
indefinitely. Current main still has two routes into that scanner:
explicit `perl` or `pl` hints flow through `CodeAwareCompressor`, and
`detect_language()` can nominate Perl on non-Perl code because its
prefilter matches generic sigils such as decorators, JSDoc tags, and
shell variables before phase 2 parses every surviving candidate grammar.
This change quarantines Perl at the code-aware compression funnel
without widening scope. Perl remains recognized at the input boundary,
but live proxy compression no longer requests a Perl parser. Non-Perl
code keeps its existing code-aware behavior. Real Perl falls back
through the existing safe Kompress or passthrough contract instead of
entering tree-sitter. The diff stays inside
`headroom/transforms/code_compressor.py` plus focused parser-safety
regressions.
Refs #2185
## 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 Perl quarantine list in
`headroom/transforms/code_compressor.py` and used it to stop Perl
candidate parsing during language detection.
- Added a hard `_get_parser()` guard so no live code-aware path can
construct a Perl parser.
- Routed resolved explicit Perl hints through the existing safe fallback
or passthrough contract before AST compression.
- Added focused parser-safety regressions for non-Perl candidate bleed,
explicit `perl` and `pl`, inferred real Perl, mixed fenced Perl content,
fallback-disabled passthrough, and non-Perl negative space.
## Testing
- [x] Unit tests pass (`uv run pytest tests/test_perl_scanner_safety.py
-q`)
- [x] Linting passes (`uv run ruff check
headroom/transforms/code_compressor.py
tests/test_perl_scanner_safety.py`)
- [ ] Type checking passes (`uv run mypy headroom`)
- [x] New tests added for new functionality when applicable
- [ ] Manual testing performed
### Test Output
```text
uv run pytest tests/test_perl_scanner_safety.py -q
8 passed in 1.93s
uv run ruff check headroom/transforms/code_compressor.py tests/test_perl_scanner_safety.py
All checks passed!
uv run ruff format headroom/transforms/code_compressor.py tests/test_perl_scanner_safety.py --check
2 files already formatted
```
## Real Behavior Proof
- Environment: Windows, Python from the synced `uv` environment, `dev`
and `code` extras installed, no provider call
- Exact command / steps: Run `uv run pytest
tests/test_perl_scanner_safety.py -q`.
- Observed result: `8 passed in 1.93s`; the suite proves explicit `perl`
and `pl`, inferred real Perl, mixed fenced Perl, and non-Perl
negative-space routes all avoid Perl parser entry.
- Not tested: the reporter's macOS payload and long-running concurrent
workload
## 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
- [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
- Use `Refs #2185`, not `Closes #2185`. The wedge surface is this PR's
scope, but #2185 also carries a separate orphaned `headroom mcp serve`
report that this slice does not address.
- This is a reachability fix. It does not repair the upstream Perl
scanner and it does not harden other grammars against the same class of
native wedge.
- `CHANGELOG.md` remains unchanged because Headroom generates release
notes from conventional commits.
- Merged PR https://github.com/headroomlabs-ai/headroom/pull/2114
addresses a different cooperative compression stall and stays separate
from this native parser-entry slice.
---------
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
## Description
Headroom can launch its MCP server, but did not publish a canonical
`server.json` that registries and MCP hosts can consume directly. This
PR adds a shared descriptor builder, commits a root `server.json`,
parity-tests that artifact against the builder and existing runtime
spec, and updates docs so registry authors do not need to reconstruct
`headroom mcp serve` from prose.
Closes#929.
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- Added a shared `server_json.py` descriptor builder for Headroom MCP
publication metadata.
- Published a canonical root `server.json` and parity-tested it against
the builder.
- Encoded the publishable uvx contract as `headroom-ai[mcp]` plus
`headroom mcp serve`.
- Updated README and MCP docs to point registry authors at the canonical
descriptor.
- Added the README ownership marker used by MCP Registry verification.
- Kept existing registrars and `headroom mcp install` behavior
unchanged.
## Testing
- [x] Unit tests pass
- [x] Linting passes
- [x] Type checking passes
- [x] New tests added for new functionality when applicable
- [x] Manual testing performed
### Test Output
```text
Focused registry/server-json tests and reviewer approval were completed on this PR before the governance body cleanup. The current body update is documentation-only metadata for PR governance.
```
## Real Behavior Proof
- Environment: Headroom development checkout with MCP test dependencies.
- Exact command / steps: Inspected the generated `server.json` contract
and parity coverage against the descriptor builder and runtime MCP spec.
- Observed result: The committed descriptor matches the builder/runtime
contract and advertises the intended `headroom-ai[mcp]` / `headroom mcp
serve` launch path.
- Not tested: live publication to third-party registries
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Additional Notes
This body was normalized by a maintainer after approval so the
governance parser reflects the already-reviewed PR state.
Tejas Chopra