Commit Graph
259 Commits
Author SHA1 Message Date
0d203db6b8 fix(copilot): keep new VS Code chats on the Local harness so they reach the proxy (#4899)
## Description

VS Code can run a Copilot chat on its "Copilot harness" (Agent Host, the
bundled Copilot SDK runtime) instead of the Local harness. That runtime
ignores `github.copilot.advanced.debug.overrideCapiUrl` /
`overrideProxyUrl`, so the chat goes straight to GitHub. Copilot's small
background calls (title, intent) still reach the proxy, so the proxy
looks connected while the main conversation never arrives. The harness
default (`chat.defaultToCopilotHarness`,
`chat.editor.preferCopilotHarness`) is tagged `experiment: startup` in
VS Code, so it can be flipped per user by rollout.

`headroom wrap vscode` now pins new chats to the Local harness.

## Type of Change

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

## Changes Made

- `headroom/providers/copilot/vscode.py`: the managed block also writes
`"chat.defaultToCopilotHarness": false` and
`"chat.editor.preferCopilotHarness": false`. Because they sit inside the
marker block, `headroom unwrap vscode` removes them. A harness setting
the user already set outside the block is left alone (no duplicate key).
New helper `copilot_harness_settings_enabled(path)` reports a user value
of `true`.
- `headroom/cli/wrap.py`: one line saying new chats stay on the Local
harness and existing chats keep their engine; a warning instead when the
user's own setting is `true`. `--no-configure` prints the two extra
settings.
- `docs/content/docs/vscode-copilot.mdx`: documents the harness settings
and the troubleshooting case.
- Blocks written by older versions (including ones with
`overrideAuthType`) are replaced by marker as before.

## 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
tests/test_provider_copilot_vscode_config.py + tests/test_cli/test_wrap_vscode.py: 32 passed.
Against origin/main source: 7 of those fail (block contents, old-block upgrade, user-set key [True]/[False], wrap output, --no-configure output).
ruff 0.17.4 check + format --check on the 5 changed Python files: clean.
mypy on the changed source files: 8 errors, all in headroom/cache/prefix_tracker.py and headroom/ccr/mcp_server.py, identical on origin/main; none in changed files.
```

## Real Behavior Proof

- Environment: macOS 27.2.1, Python 3.12.13, VS Code 1.145.2 with GitHub
Copilot signed in, core run from this branch, real GitHub Copilot
upstream. Real user `settings.json` (backed up and restored afterwards).
- Exact command / steps:
  1. `headroom wrap vscode -p 8795` from this branch.
2. `code chat -n -m agent "Reply with the single word OK and nothing
else."` (opens a new VS Code window and sends one Agent-mode chat).
3. Read the proxy's `/stats`, VS Code's `agenthost.log`, then `headroom
unwrap vscode`.
- Observed result:
  ```text
VS Code Copilot proxy settings updated: ~/Library/Application
Support/Code/User/settings.json
Keep using Copilot's normal model picker; the selected model is
preserved.
New chats stay on VS Code's Local harness; a chat keeps the engine it
started with, so start a new chat.

  settings.json after wrap:
  {
  	// --- Headroom Copilot proxy ---
"github.copilot.advanced.debug.overrideProxyUrl":
"http://127.0.0.1:8795/p/win-local",
"github.copilot.advanced.debug.overrideCapiUrl":
"http://127.0.0.1:8795/p/win-local",
  	"chat.defaultToCopilotHarness": false,
  	"chat.editor.preferCopilotHarness": false
  	// --- end Headroom Copilot proxy ---
  }

  proxy requests before chat: 0 {}
proxy requests after one Agent-mode chat in a new VS Code window: 4
{'gpt-4o-mini-2024-07-18': 3, 'claude-opus-5.5': 1}
  agent host turns during the chat: 0

Removed Headroom Copilot proxy settings from ~/Library/Application
Support/Code/User/settings.json
  settings.json after unwrap:
  {
  }
  ```
Separately, on the same machine with the settings edited by hand (same
VS Code, same proxy, new window each time):
`"chat.defaultToCopilotHarness": true` -> the Agent-mode chat ran in the
Agent Host (provider `copilotcli`) and 0 requests reached the proxy;
`"chat.defaultToCopilotHarness": false` +
`"chat.editor.preferCopilotHarness": false` -> Local harness, 4 requests
reached the proxy including the main `/v1/messages` call.
`"chat.temporaryDefaultToLocalHarness": true` as a user setting had no
effect, so it is not written.
- Not tested: a VS Code where Microsoft's rollout has flipped the
default (the explicit user value is expected to win, but that could not
be reproduced); an organization that enforces managed sandbox settings,
where VS Code can require the Copilot harness regardless; VS Code
profiles, workspace-level settings, Insiders/VSCodium; Windows and
Linux; the persistent `headroom start --persistent --vscode` path in the
Enterprise client.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: `headroom wrap vscode` writes two
more VS Code user settings inside its managed block. No proxy behaviour
changes.
- Kill switch / disable path: `headroom unwrap vscode` removes them; a
user who sets either key themselves keeps their value.
- Unsafe override required: no.
- Qualification impact: none expected.
- Rollback path: revert this commit; `unwrap` removes blocks of either
format.

## Review Readiness

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

## Checklist

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

## Additional Notes

- This keeps users off the Copilot harness; it does not route that
harness through Headroom. Supporting it is separate work.
- Only the configured settings file is checked for a user value. A
`true` in workspace settings, another profile, or policy is not
detected.
- After `unwrap` the keys return to VS Code's default, which a rollout
may move to the Copilot harness.
- Existing chats keep the harness they started with; the wrap output
says to start a new chat.
- `e2e/copilot_live.py` and `e2e/wrap/run.py` were not run.

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

---

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

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-16 23:19:43 -06:00
66e0086952 feat(opencode): add repeatable --extra-model flag for custom wrap-time models (#2364)
## Description

`headroom wrap opencode` injects a hardcoded model list
(`HEADROOM_OPENCODE_MODELS`) into the `headroom` provider block of
`opencode.json`. There's no way to add custom models (for example a
free-tier DeepSeek) at wrap time. Hand-patching `opencode.json` is the
only workaround, and the next wrap overwrites it.

This PR adds a repeatable `--extra-model` flag and a
`HEADROOM_OPENCODE_EXTRA_MODELS` env var. Both take
`id[=name[=context_window[=output_limit]]]` specs. Extra models are
merged into the injected provider block alongside the built-ins, and
flag specs win over env specs on id collision. `name` defaults to the
id, `context_window` to 200000, and `output_limit` to `min(16384,
context_window)`.

Fields are separated by `=` rather than `:` because model ids routinely
contain `:`. Ollama ids are `name:tag` (`qwen2.5-coder:7b`), and
OpenRouter free-tier ids end in `:free`. With a `:` separator those were
silently cut down to a different id (Devin review, 2026-10-03).

The PR also fixes the wrap/unwrap lifecycle the flag depends on. A wrap
that starts without an `opencode.json` used to write the file with no
backup and no record of what Headroom put in it, so `headroom unwrap
opencode` left the injected models and the proxy base URL behind while
reporting that OpenCode was no longer routed through Headroom, and a
re-wrap under `--openai-api-url` kept an extra model Headroom had
injected but no longer advertised. Wrap now records what it owns in
`opencode.json.headroom-managed.json`, and unwrap uses that record: it
removes the model ids and the base URL Headroom wrote, keeps everything
else in the file, drops an extra model that is no longer requested, and
deletes the config file when Headroom created it and nothing else is
left in it.

Closes #2359

## Type of Change

- [x] 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 not work as expected)
- [x] Documentation update
- [ ] Refactoring (no functional changes)

## Changes Made

- `headroom/providers/opencode/config.py`:
- New `parse_extra_model_spec()`, which splits on `=` with an optional
fourth `output_limit` field and raises `ValueError` on an empty id or a
non-integer / non-positive limit.
- New `extra_models_from_env()`, which reads comma-separated specs from
`HEADROOM_OPENCODE_EXTRA_MODELS`.
- An `extra_models` parameter threaded through
`headroom_provider_entry()`, `_render_provider_block()` and
`inject_opencode_provider_config()`.
- With `keep_user_entries` (#3125's `--openai-api-url` gate),
`--extra-model` entries win over a kept user entry with the same id.
- New managed-state sidecar (`opencode.json.headroom-managed.json`)
recording the model ids and base URL Headroom injected and whether
Headroom created the config file. `inject_opencode_provider_config()`
writes it on every injection; `record_opencode_config_origin()` marks a
config that Headroom creates because none existed.
- `remove_managed_opencode_provider()` drops the recorded model ids, the
recorded base URL, and the provider block once nothing else is left in
it. Entries the user added or edited are preserved.
- `_drop_stale_managed_models()` prunes an extra model Headroom injected
but no longer advertises, including an extra that overrode a built-in id
and is dropped again, so a re-wrap without the flag restores the
built-in defaults rather than keeping the old override.
- `snapshot_opencode_config_if_unwrapped()` no longer snapshots a config
Headroom wrote itself as pre-wrap content.
- `headroom/providers/opencode/runtime.py`: extras also reach the
launch-time `OPENCODE_CONFIG_CONTENT`.
- `headroom/cli/wrap.py`:
- A repeatable `--extra-model` option on `wrap opencode`. Env and flag
specs are parsed up front, and a malformed spec raises
`click.BadParameter`. The merged dict goes to both
`inject_opencode_provider_config` call sites (prepare-only and launch)
and to the launch env. Also adds a help text and docstring example.
- `wrap opencode` records the config origin before the first config
mutation.
- `unwrap opencode` undoes the recorded provider entries when there is
no pre-wrap backup, keeps the rest of the file, and removes a config
Headroom created once nothing Headroom-owned is left in it.
- `docs/content/docs/opencode.mdx`: new "Adding models" subsection
(format, defaults, Ollama/OpenRouter example, built-in id override, the
env var's no-comma limitation) and an env-var table row. The subsection
and the "How It Works Under The Hood" unwrap step now describe the
managed-state record and the automatic cleanup it enables.
- Tests:
- Spec parsing: full spec with output, defaults, the output cap at small
contexts, colon-bearing ids (`qwen2.5-coder:7b`,
`deepseek/deepseek-chat:free`, a name containing `:`), and invalid specs
including a bad output limit.
- Env parsing, provider-entry merge, and end-to-end inject. Also
@JerrettDavis's collision test across both `keep_user_entries` values.
- CLI: the flag reaches `opencode.json`, the env var persists, both
reach `OPENCODE_CONFIG_CONTENT` on launch, the flag wins over a kept
user entry under `--openai-api-url`, and a malformed spec exits with a
usage error.
- Managed state: the sidecar records the injected ids and base URL, a
config the user already had is not marked as Headroom-created, a re-wrap
does not snapshot Headroom's own config, a dropped extra model is pruned
(including an override of a built-in id, which returns to the built-in
defaults), a user model and a user-edited model survive, and the
provider removal keeps unrelated user entries.
- Lifecycle: a fresh wrap followed by an unwrap removes the config file
again (with and without the MCP entry), user content added after a fresh
wrap survives the unwrap, a re-wrap without the extra model drops the
stale one, and a directly injected provider entry is undone by the
unwrap callback as well.
- A user setting that is false, zero or an empty string is content, not
an empty section: such a setting survives the unwrap instead of costing
the user the whole file.

## Testing

- [x] Unit tests pass locally
- [x] Lint/format/type checks pass locally
- [x] New tests added for new functionality

The new parsing tests fail against the previous `:`-based parser:

```text
FAILED tests/test_providers_opencode_config.py::test_parse_extra_model_spec_keeps_colons_in_ids[qwen2.5-coder:7b-...]
FAILED tests/test_providers_opencode_config.py::test_parse_extra_model_spec_keeps_colons_in_ids[deepseek/deepseek-chat:free=DeepSeek Free-...]
FAILED tests/test_providers_opencode_config.py::test_parse_extra_model_spec_full
...
================ 21 failed, 2 passed, 103 deselected in 0.86s =================
```

With this branch (head 6be848942):

```text
$ pytest tests/test_providers_opencode_config.py tests/test_cli/test_wrap_opencode.py -q
179 passed, 2 skipped in 3.31s

$ pytest tests -q -k "opencode"
322 passed, 26 skipped

$ ruff check headroom/providers/opencode/config.py headroom/cli/wrap.py tests/test_providers_opencode_config.py tests/test_cli/test_wrap_opencode.py
All checks passed!
$ ruff format --check (same files)
4 files already formatted
$ mypy headroom --ignore-missing-imports --no-site-packages
headroom\fileperms.py:92: error: Module has no attribute "fchmod"; maybe "chmod"?  [attr-defined]
headroom\proxy\interceptors\astgrep.py:220: error: Module has no attribute "O_DIRECTORY"  [attr-defined]
...
Found 7 errors in 2 files (checked 561 source files)
```

The mypy errors are the Windows-only `os.fchmod` / `os.O_DIRECTORY`
false positives in files this PR does not touch. The same Windows
path-escaping failures that `test_build_launch_env_with_project` used to
hit (`tests/test_cli/test_unwrap_claude.py`,
`tests/test_wrap_code_memory.py`, `tests/test_install/test_planner.py`,
`tests/test_cli/test_wrap_stale_marker.py`) reproduce on unchanged
`main` and are unrelated to this change. `Dependency audit (pip-audit)`
passes on this head; only `Rust advisories (cargo audit)` fails, on
advisories published after upstream `main`'s last green run (2026-11-13
04:47) — `quinn-udp` `RUSTSEC-2026-0538` and `rustix`
`RUSTSEC-2026-0486`. `Cargo.lock` on this branch is byte-identical to
upstream `main` (`81818d49`), so the PR does not introduce them.

## Real Behavior Proof

- Environment: Windows 11, Python 3.13, this branch vs. the previous
`:`-based parser and vs. the previous unwrap lifecycle,
`HOME`/`USERPROFILE` pointed at a temp dir.
- Exact command / steps: `headroom wrap opencode --prepare-only
--no-serena --extra-model "qwen2.5-coder:7b" --extra-model
"deepseek/deepseek-chat:free=DeepSeek Free=65536"`, then read
`provider.headroom.models` from `~/.config/opencode/opencode.json`; then
`headroom unwrap opencode --no-stop-proxy` against a config that did not
exist before the wrap.
- Observed result: with the old parser the entries were `qwen2.5-coder`
(name `7b`) and `deepseek/deepseek-chat` (name `free=DeepSeek
Free=65536`, context 200000): wrong ids, and the paid DeepSeek model
instead of the free one. With this branch they're `qwen2.5-coder:7b`
(name defaults to the id, context 200000, output 16384) and
`deepseek/deepseek-chat:free` (name `DeepSeek Free`, context 65536,
output 16384), next to the built-in `gpt-4o` / `gpt-4.1`. After the
unwrap of a fresh wrap, `opencode.json` and its managed-state sidecar
are both gone and no `provider.headroom` block is left. After the unwrap
of a fresh wrap the user had added to, the file keeps the user's own
model id, key and `theme`, and only the injected ids and the
`http://127.0.0.1:8787/v1` base URL are gone.
- Not tested: a full (non-prepare-only) wrap launching the real OpenCode
binary against a live upstream; the OpenCode TS plugin side (extras are
user-supplied and intentionally not synced into
`plugins/opencode/src/provider.ts` `DEFAULT_MODELS`).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; CLI-only opt-in flag and env var on
`headroom wrap opencode`, plus a `opencode.json.headroom-managed.json`
sidecar next to the OpenCode config
- Minimum rollout channel: stable
- Stable/default behavior changed: no. Without `--extra-model` or
`HEADROOM_OPENCODE_EXTRA_MODELS` the injected provider block is
unchanged. `unwrap opencode` now also removes the provider entries
Headroom recorded, which is what it already reported doing
- Kill switch / disable path: drop the flag and unset
`HEADROOM_OPENCODE_EXTRA_MODELS`, then re-wrap; delete the sidecar to
stop Headroom from tracking the config
- Unsafe override required: no
- Qualification impact: none; no proxy, compression or request-path code
changed
- Rollback path: revert the PR; `headroom unwrap opencode` restores the
pre-wrap `opencode.json` when a backup exists

## Review Readiness

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

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

---

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-17 02:38:10 +05:30
aa2093b4a0 fix(wrap): route Claude Code's Bedrock mode through Headroom (#4316)
## Why
`headroom wrap claude` silently bypassed Headroom for every Claude Code
user on Bedrock.

With `CLAUDE_CODE_USE_BEDROCK=1`, Claude Code ignores
`ANTHROPIC_BASE_URL` and calls AWS itself. wrap only sets
`ANTHROPIC_BASE_URL`, so it started a proxy that saw no traffic: no
error, no savings.

The flag usually lives in `~/.claude/settings.json`, which Claude Code
obeys over the shell, so exporting `CLAUDE_CODE_USE_BEDROCK=0` didn't
help either. A customer hit exactly this and needed a call to find it.

## What
When Bedrock mode is on, wrap routes it through Headroom using the path
that already works with the proxy's Bedrock backend:
- **Read the flag the way Claude Code does:** shell → user → project →
project-local settings → managed settings.
- **Proxy:** started with `--backend bedrock`, in the region Claude Code
would use, with the AWS settings it would read. Settings-file values are
copied in, and keys a settings file clears are cleared.
- **Claude Code:** launched in Anthropic mode against the proxy, with
`--settings '{"env":{"CLAUDE_CODE_USE_BEDROCK":"0"}}'`, which outranks
the settings files. A placeholder credential is added only if none is
configured. The proxy calls Bedrock with the user's AWS credentials.
- **Bedrock wins over Vertex and Foundry,** as it does in Claude Code
(checked: with both flags set, Claude Code calls the Bedrock endpoint).
- **Project-local settings aren't written in Bedrock mode,** since
daemon workers read them without the override.

Where routing isn't safe, wrap leaves the session alone and **says
Headroom is bypassed, and why**:
- the flag is in managed settings (they outrank `--settings`);
- a Bedrock gateway (`ANTHROPIC_BEDROCK_BASE_URL` /
`CLAUDE_CODE_SKIP_BEDROCK_AUTH`);
- `--no-proxy`;
- a non-Bedrock `--backend` / `HEADROOM_BACKEND`;
- the user's own `--settings`.

Also:
- **Managed settings are read tolerantly.** An unreadable file is
reported and skipped instead of stopping every `wrap claude`.
- **The env overlay moves to `providers/claude/runtime.py`**
(`claude_effective_env`) and is shared with the auth-conflict check.
That check now uses the same shell-first order, so settings files
outrank the shell as they do in Claude Code.

## Testing
- **Verified against Claude Code 2.1.304** with a loopback recorder:
  - `settings.json` `env` beats the shell;
  - `--settings` beats `settings.json`;
  - Bedrock beats Vertex.
- **Unit:** 44 tests in `test_wrap_claude_vertex_proxy_env.py`, one per
case above, including the bypass reasons, the unreadable managed file,
region precedence, and the AWS profile reaching the proxy. A conftest
fixture keeps the host's managed-settings file out of CLI tests.
- **Wider suites:** `tests/test_cli`, the Claude provider and doctor
suites pass, except 5 tests that already fail on `main` on macOS:
- 4 in `test_wrap_persistent.py`: the fake `_Manifest` lacks
`runtime_kind`, which the darwin-only branch reads;
- `test_mcp_reconcile::test_ordinary_install_does_not_adopt_serena`,
which depends on whether `headroom` is on PATH.
- **Live, real Bedrock** (Sonnet 4.6, us-east-1), with this change on
core 0.41.0. Customer setup: `CLAUDE_CODE_USE_BEDROCK=1` only in
`~/.claude/settings.json`, plain `headroom wrap claude`:
  - routed through Headroom: 13 requests, 0 failed;
- first request 18,312 tokens vs 22,648 sent straight to Bedrock (−19%,
with the tool-search and skill-search plugins).

## Related
- **#1220** routes Bedrock differently: it points
`ANTHROPIC_BEDROCK_BASE_URL` at the proxy and re-signs requests with
SigV4. In a live test it compressed nothing (Bedrock-mode bodies reach a
handler that runs no compression or hooks), and one stream hung for over
5 minutes. This PR uses the Anthropic-mode path the Bedrock backend
already serves.

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

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4316"
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 post-merge qualification
Published `f1f11da91d481e48e57526a784187810f762c209` incorporates
upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 44 existing
handoff tests pass; both existing effective-client probes fail:
competing Vertex flag remains enabled and user-settings remote base URL
wins over launched proxy URL. Ruff/format/diff pass; clean main sync, no
routing rewrite. Existing Changes Requested decision remains applicable;
unchanged findings are not reposted. Scoped Windows probes use the real
CLI configuration harness or actual metrics object, not live
cloud-provider traffic. Contributor correctness logic was not rewritten;
hosted checks are handled by maintainers. Nothing merged.


### Maintainer current-main requalification

Exact head `79b861ef2351bd321900b221f6cf99ad5cbedf27`, upstream main
`ecbaf86d78cf52d185fbffa306157b9a4cc1b906`.

Mechanically updated from upstream/main
ecbaf86d78 with a clean merge and no
contributor routing-policy rewrite. Reviewed existing discussion and
integration delta. All 54 existing Bedrock handoff/Gemini tests pass;
Ruff0.17.3 lint/format and whitespace checks pass.

Both prior effective-client probes still fail on this combined tree:
user-settings Bedrock plus shell Vertex leaves effective
CLAUDE_CODE_USE_VERTEX=1; user-settings Bedrock plus remote
ANTHROPIC_BASE_URL retains https://example.invalid instead of the
launched http://127.0.0.1:8787 proxy. These probes combine the real CLI
harness's captured launch environment and settings overlay; child/proxy
processes are stubbed and no live-provider request is claimed. Retain
the existing requested complete session overrides for competing provider
flags and proxy base URL while respecting managed-policy precedence,
with assertions on effective launched-client configuration. This is not
an inherited-main CI hold. Maintainers handle hosted checks; nothing
merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `4187711078787567dff800087f4e68e814c0aaa9`, upstream main
`8d3e9e5ca7cd645eb73084b848edbea5fc796e1a`.

Clean mechanical sync with upstream
main8d3e9e5ca7cd645eb73084b848edbea5fc796e1a, with no contributor
routing policy rewrite. Existing discussion/source
re-reviewed.54existing Bedrock handoff/Gemini tests pass;5changed Python
files Ruff0.17.3check/format and whitespace pass.

Both prior effective-client probes freshly fail on this combined tree:
user-settings Bedrock plus shell Vertex leaves effective
CLAUDE_CODE_USE_VERTEX=1; user-settings Bedrock plus remote
ANTHROPIC_BASE_URL retains https://example.invalid rather than launched
loopback proxy. Probes combine the real CLI harness launch environment
and settings overlay with stubbed child/proxy, not a live provider.
Supply complete session overrides for competing provider flags and proxy
base URL while preserving managed-policy precedence; assert effective
launched configuration. This is not inherited-main CI. Maintainers
handle hosted checks; copied extension is not fresh-native-build proof.
Nothing merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `2c94a2f3dacaeba93c2ff846b3c7ea9614f8165d`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.

Clean integration with upstream/main
2d3ee51846. Re-reviewed current discussion
and the composed tree. Exact comparison of CLI launch and Claude
provider implementation plus the Bedrock handoff test file against prior
reviewed 418771107 shows no changes. All 131 Bedrock
handoff/release/version/MCP/memory/Gemini tests pass; whitespace passes.
Prior changed-file lint/format applies to identical contributor inputs.

The existing effective-client configuration finding remains:
user-settings Bedrock combined with shell Vertex or settings
ANTHROPIC_BASE_URL can preserve the competing provider flag or remote
URL. Earlier harness probes remain evidence for the unchanged launch
paths; they were not rerun or claimed as live-provider proof after these
unrelated main merges. Preserve the requested complete per-session
overrides and launched-configuration regressions while respecting
managed policy precedence. No routing-policy winner selected between
overlapping PRs. No contributor correctness logic rewritten, no fresh
native build claimed. Maintainers handle checks; nothing merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `26ad500eadcd958cbea4d433333958e0e36a766c`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Clean integration with upstream/main
c01cf07d94 after the
release/runtime/dependency merges. Resolved the test-fixture-only
conflict by retaining both the author's proxy environment capture and
main's actual-port override; original UTF-8 banner assertions and
contributor production logic are preserved.107 Bedrock
handoff/region/Hermes tests pass with actual Click8.5.0 and the fresh
native binding; changed-source Ruff and whitespace pass.

The two existing effective-client routing blockers freshly reproduce on
this composed tree. With Bedrock selected in user settings and Vertex
enabled in the shell, the launched effective configuration still has
CLAUDE_CODE_USE_VERTEX=1. With user-settings
ANTHROPIC_BASE_URL=https://example.invalid, the launched settings retain
that gateway while the shell points to the proxy. The proxy backend is
Bedrock in both cases, so the client route disagrees with the announced
route. Please provide complete per-session overrides, or explicitly
refuse incompatible effective configurations, with
launched-configuration regressions while respecting managed-policy
precedence. Current author discussion and Devin findings considered; no
policy winner or new unsupported cloud-runtime claim introduced. No real
AWS call was made. Maintainers handle exact-head hosted checks; nothing
merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `3fa44885c12e14e95ac55e8352d30542328a90d2`, upstream main
`da6d9736cd82074988c7d0a2360b49d9d8b6c0a0`.

Current-main requalification against
da6d9736cd. All69 integration patches
exactly match c01cf07-to-current-main delta after diff-location
normalization; contributor handoff/ownership policy unchanged.107
Bedrock handoff/region/Hermes tests pass.31 changed Python files pass
Ruff lint/format; offline lock and whitespace pass. Existing pr3982
native DLL verified complete native input hashes/artifact checksum; no
fresh build claimed. Author and Devin discussions considered. Both
effective-client routing blockers freshly reproduce with captured launch
configuration: user-settings Bedrock plus shell CLAUDE_CODE_USE_VERTEX=1
leaves Vertex enabled; user-settings
ANTHROPIC_BASE_URL=https://example.invalid survives while shell proxy
base URL points locally. Announced Bedrock backend and effective client
route disagree. Provide complete per-session overrides or explicitly
reject incompatible effective configuration, respecting managed-policy
precedence, with launched-configuration regressions. No real AWS request
or live cloud claim. Maintainers handle hosted checks; no contributor
semantics rewritten or merge.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-09 12:29:52 -06:00
2649835a51 feat(wrap): make the Serena code-memory MCP opt-in (#4509)
## What changes

`headroom wrap claude|codex|grok|opencode` no longer registers Serena by
default.

| | Before | After |
|---|---|---|
| Default | Serena registered | No code-memory MCP |
| Opt in | (default) | `--code-memory serena` or
`HEADROOM_CODE_MEMORY=serena` (deprecated `--serena` still works) |
| Opt out | `--code-memory none` / `--no-serena` | Still accepted |
| Upgrading user, Serena installed by Headroom | Kept | Removed on next
wrap, with the message "Serena is now off by default; pass --code-memory
serena to keep it" |
| Upgrading user, Serena added by hand | Kept | Kept, no message (shown
only with `--verbose` or an explicit opt-out) |

OpenCode now accepts `--code-memory` and uses the same setup path as the
other agents. Its `--no-serena` flag is hidden and deprecated.

## Why

Measured on 2026-10-27, Serena started exactly as `wrap` registers it:

- It adds 22 tools, about 5.9K tokens of tool definitions on every
request where tools aren't deferred. Its server instruction tells the
model to call `initial_instructions`, which costs another 2K tokens.
- Each launch takes about 6 s cold via `uvx`, plus a background `serena
project index` that starts language servers. It also writes a `.serena/`
folder into the user's repo.
- Serena was registered in 6 of our own Claude Code sessions and called
0 times. Separately, an offline replay of about 108K tool calls found
that symbol-level reads have little to recover for Claude Code.

## Not in this PR

- `headroom.integrations.strands` still defaults
`enable_serena_mcp=True`. It's public integration API, so it needs a
deprecation step instead of a silent flip.
- The opt-in `--serena-instructions` block in CLAUDE.md/AGENTS.md is
never removed, by unwrap or anything else. Users who opted into it keep
instructions that point at tools no longer registered. This predates
this PR and will be fixed separately.
- For Claude Code, Serena entries are per project, so removal happens
the next time `wrap` or `unwrap` runs in each project. The docs say so.

## Tests

- `pytest tests/test_wrap_code_memory.py tests/test_cli
tests/test_mcp_registry`: 1368 passed. 5 failed, and those 5 fail the
same way on `main` in my local venv:
`test_mcp_reconcile.py::test_ordinary_install_does_not_adopt_serena` and
4 in `test_wrap_persistent.py`, all from an environment/install
mismatch.
- New tests:
- The default wrap removes a Serena entry Headroom installed and prints
how to keep it.
- The default wrap leaves a hand-added Serena alone and prints nothing.
  - `--serena --no-serena` resolves to none.
- `wrap opencode --code-memory serena` registers Serena with the `agent`
context.
- `ruff check`, `ruff format --check` and `mypy` are clean on the
changed files.

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

## Real Behavior Proof

- **Environment:** macOS (Darwin 27.2), Python 3.12.13, Claude Code
2.1.318, real `claude` CLI doing every `claude mcp add`/`remove`. A
temporary `HOME`, so `~/.claude.json` starts empty, and a fresh git repo
per case.
- **Builds:** "before" = `main` at `12864fc8`; "after" = this PR at
`56557dc9`.
- **Command:** `headroom wrap claude --no-proxy [flags] -- --version`.
Wrap does its full MCP setup, then launches Claude Code, which prints
its version and exits, so no model call is made. `state` is read from
`~/.claude.json` (user scope and this project's local scope) and the
project's `.mcp.json` after each run.

```
== 1. Upgrade: Serena installed by Headroom (project/local scope)
    $ headroom wrap claude --no-proxy -- --version    (cwd=projA, build=12864fc8)
    exit=0
    wrap|   Serena MCP: registered (restart Claude Code if it was already running)
    wrap|     scoped to this project — pass --code-memory-scope user to register it for every Claude Code session
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projA): ['serena'] | .mcp.json: -
    $ headroom wrap claude --no-proxy -- --version    (cwd=projA, build=56557dc9)
    exit=0
    wrap|   Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it)
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projA): - | .mcp.json: -

== 2. Upgrade: Serena added by hand (claude mcp add)
    state| user: ['headroom'] | local(projB): ['serena'] | .mcp.json: -
    $ headroom wrap claude --no-proxy -- --version    (cwd=projB, build=56557dc9)
    exit=0
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projB): ['serena'] | .mcp.json: -
    $ headroom wrap claude --no-proxy --code-memory none -- --version    (cwd=projB, build=56557dc9)
    exit=0
    wrap|   Serena MCP is present but user-managed — leaving it in place (Headroom only removes entries it installed)
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projB): ['serena'] | .mcp.json: -

== 3. Explicit opt-in, then rollback to the default
    $ headroom wrap claude --no-proxy --code-memory serena -- --version    (cwd=projC, build=56557dc9)
    exit=0
    wrap|   Serena MCP: registered (restart Claude Code if it was already running)
    wrap|     scoped to this project — pass --code-memory-scope user to register it for every Claude Code session
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projC): ['serena'] | .mcp.json: -
    $ headroom wrap claude --no-proxy -- --version    (cwd=projC, build=56557dc9)
    exit=0
    wrap|   Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it)
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projC): - | .mcp.json: -
    $ headroom wrap claude --no-proxy -- --version    (cwd=projC, build=56557dc9)
    exit=0
    wrap|   Serena MCP: registered (restart Claude Code if it was already running)
    wrap|     scoped to this project — pass --code-memory-scope user to register it for every Claude Code session
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projC): ['serena'] | .mcp.json: -
    $ headroom wrap claude --no-proxy --serena -- --version    (cwd=projC, build=56557dc9)
    exit=0
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projC): ['serena'] | .mcp.json: -

== 4. User scope: installed by Headroom with --code-memory-scope user
    $ headroom wrap claude --no-proxy --code-memory-scope user -- --version    (cwd=projD, build=12864fc8)
    exit=0
    wrap|   Serena MCP: registered (restart Claude Code if it was already running)
    wrap|     registered for every Claude Code session on this machine (--code-memory-scope user)
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom', 'serena'] | local(projD): - | .mcp.json: -
    $ headroom wrap claude --no-proxy -- --version    (cwd=projD, build=56557dc9)
    exit=0
    wrap|   Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it)
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projD): - | .mcp.json: -

== 5. User scope opt-in on the PR build
    $ headroom wrap claude --no-proxy --code-memory serena --code-memory-scope user -- --version    (cwd=projE, build=56557dc9)
    exit=0
    wrap|   Serena MCP: registered (restart Claude Code if it was already running)
    wrap|     registered for every Claude Code session on this machine (--code-memory-scope user)
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom', 'serena'] | local(projE): - | .mcp.json: -
    $ headroom wrap claude --no-proxy -- --version    (cwd=projE, build=56557dc9)
    exit=0
    wrap|   Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it)
    wrap| 2.1.318 (Claude Code)
    state| user: ['headroom'] | local(projE): - | .mcp.json: -
```

What this shows:
1. A Serena entry Headroom installed on `main` is removed on the first
wrap after upgrading, with the "off by default" message. This holds for
both scopes (cases 1 and 4).
2. A hand-added Serena entry is kept, and the default wrap prints
nothing. `--code-memory none` keeps it and says it's user-managed (case
2).
3. Opting in works with `--code-memory serena`,
`HEADROOM_CODE_MEMORY=serena` and the deprecated `--serena`, at project
scope and user scope (cases 3 and 5). Running the default afterwards
rolls it back.
4. Project scope here means Claude Code's `local` scope, which is where
wrap registers. Wrap never writes `.mcp.json`.

Not tested live: `wrap codex|grok|opencode` (unit tests only), Windows,
and an interactive Claude session that calls Serena tools.

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4509"
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 post-merge qualification
Published `983b6bb15119a3ecb8f6e20bf014b8bed123e95d` includes upstream
main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 19 selector/Serena
tests pass,1optional skip; Ruff/format/diff pass. Clean main sync;
contributor selector/ownership code unchanged. Existing real
upgrade/configuration/launch proof requirement remains; jCodeMunch
proposal is unrelated to this source delta. Contributor correctness
logic was not rewritten. Existing Changes Requested decision retained
without duplicate findings. Scoped Windows validation uses the existing
development native extension, not a fresh build. Hosted qualification is
handled by maintainers; nothing merged.


### Maintainer current-main requalification

Exact head `e8e3011187a2ffdfbb6c9932db26b22ec911ab39`, upstream main
`ecbaf86d78cf52d185fbffa306157b9a4cc1b906`.

Mechanically updated from upstream/main
ecbaf86d78 without changing contributor
selector/ownership logic. Reviewed the current discussion and
integration delta. All 29 focused code-memory/Serena-disable/Gemini
tests pass with one optional skip; Ruff0.17.3 lint/format and whitespace
checks pass. Existing Windows HOME/USERPROFILE fixture isolation remains
intact.

The prior upgrade/runtime qualification requirement remains unresolved:
post-patch real configuration/launch evidence must cover an existing
Headroom-owned Serena entry, a hand-managed entry, explicit opt-in, and
Claude project/user scopes, with commands/results and untested-agent
limits. No new author evidence was found to close it. This pass does not
claim those actual launch/upgrade flows were executed; passing unit
tests and the main sync do not establish that deployment behavior. The
hold is not an inherited-main CI defect. Maintainers handle hosted
checks; no contributor CI execution requested. Nothing merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `0b49a79cb192b294dde7ecb1c72b75fffa2733d5`, upstream main
`8d3e9e5ca7cd645eb73084b848edbea5fc796e1a`.

Clean mechanical sync with upstream
main8d3e9e5ca7cd645eb73084b848edbea5fc796e1a without changing
contributor selector/ownership logic. Current source, author discussion
and Devin findings reviewed.29focused code-memory/Serena-disable/Gemini
tests pass with1optional skip; changed Python Ruff0.17.3check/format and
whitespace pass. Windows HOME/USERPROFILE fixture isolation preserved.

Existing real upgrade/runtime qualification remains missing: existing
Headroom-owned Serena versus hand-managed entry, explicit opt-in, and
Claude project/user scopes need observed configuration/launch results
with explicit untested-agent limits. No new evidence found to close it;
these launch/upgrade paths were not executed in this pass. Passing unit
tests and clean main integration do not establish deployment behavior.
No new provider/native-build claim or inherited-main pipeline
attribution. Maintainers handle hosted checks; nothing merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `30dfb386fa7284c9817bf5d7db0648fb10830055`, upstream main
`7592e681459f14a2041eb5f524a658cb6ad1dd92`.

Clean current-main
sync7592e681459f14a2041eb5f524a658cb6ad1dd92,including HNSW re-index and
memory relation-key fixes after917release-recovery merge. Contributor
selector/ownership logic unchanged; fresh discussion
considered.37wrapper/Serena/memory-regression/Gemini tests pass
with1optional skip;whitespace passes. PriorRuff0.17.3validation applies
to unchanged PR files.

Existing real upgrade/launch evidence hold remains: Headroom-owned
versus hand-managed Serena
entries,explicitoptin,andClaudeproject/userscopes need
observedpostpatchresults. No newevidence closesit;actualupgrade/launch
pathsnotrerun. No freshnativebuild/provider claim.
MaintainershandleCI;nothingmerged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `e1778a5368626547ad958926d5570edf153182f6`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.

Clean integration with upstream/main
2d3ee51846 after the external 0.43.1
release merge. Exact headroom/crates/tests comparison against previously
reviewed 30dfb386f shows no changes. Re-reviewed generated metadata; 78
release/version/MCP tests pass on this tree and whitespace passes.
Earlier 37 wrapper/Serena/memory/Gemini passes and one optional skip
remain scoped to unchanged inputs.

Existing actual upgrade/launch proof hold remains: Headroom-owned versus
hand-managed Serena entries, explicit opt-in, and Claude project/user
scopes need observed postpatch results. Those runtime paths were not
rerun and no new evidence closes the hold. No contributor ownership
policy changed, no fresh native-build/provider claim. Maintainers handle
checks; nothing merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `173c5739d7357ca9398faa41b4d1ce3b72d6c550`, upstream main
`7877241d84c93b3ec487e07324245838ddae85cc`.

Cleanly integrated upstream/main7877241d84c93b3ec487e07324245838ddae85cc
and re-reviewed the wrapper overlap with Hermes registration and port
discovery.35 selector/Serena-disable/Hermes provider and wrapper tests
pass,1optional skip; Ruff and whitespace pass. Contributor
ownership/default policy is unchanged. Existing actual
upgrade/configuration/launch proof requirement remains open for
Headroom-owned versus user-managed entries, explicit opt-in, and Claude
project/user scopes. No runtime proof is inferred from mocks or
native-build claim made. Maintainers handle hosted checks; nothing
merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

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

Final post-Dependabot requalification against upstream/main
c01cf07d94. All six Dependabot updates are
now merged. Relative to this branch's freshly tested prepared tree, the
final main sync changes only the three intended Cargo.lock records;
Python/source/test inputs are unchanged. Re-reviewed the integration and
confirmed complete native source/lock/toolchain objects match the tested
combined build and exact fresh native DLL used for this branch's local
tests.

Focused fresh-native qualification: 35 passed, 1 skipped in 2.93s.
Selected real dependency overlays and native DLL paths are recorded in
final4509-fresh-native-tests.log; the DLL provenance/input hashes are in
final-native-artifact-proof.json. No redundant rerun is implied after
this Cargo-only merge. Whitespace passes. Prior source review and scoped
real-behavior evidence remain applicable to unchanged contributor
inputs.

Existing real upgrade/configuration/launch qualification remains open
for Headroom-owned versus user-managed Serena entries, explicit
opt-in/rollback, and Claude project/user scopes. No new author evidence
closes it; contributor ownership/default policy is unchanged.

Maintainers handle hosted checks; no external-provider claim,
contributor semantic rewrite or non-Dependabot merge.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `43bfea8a164c21ab69793b3905fbf1457fef7bc2`, upstream main
`da6d9736cd82074988c7d0a2360b49d9d8b6c0a0`.

Current-main requalification against
da6d9736cd. All69 integration patches
exactly match c01cf07-to-current-main delta after diff-location
normalization; contributor selector/default/Serena ownership logic
unchanged.162 focused code-memory,Serena disable,Hermes,Windows
supervisor,search-compressor tests pass;3 platform/optional skips. All31
changed Python files pass Ruff lint/format; offline lock and whitespace
pass. Native pr3982 DLL verified against complete tracked native-input
hash proof and artifact checksum; no fresh native-build claim.
Author/Devin discussion checked. Existing real
upgrade/configuration/launch qualification remains open: prior
Headroom-owned Serena entry versus user-managed entry, explicit
opt-in/rollback, Claude project/user scopes. No new author evidence
closes it; this run does not assert actual agent launch or deployment
proof. Maintainers handle hosted checks; no contributor policy rewrite
or merge.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `56557dc91725422257f90c3cb5c5f04a665e6043`, upstream main
`0ddaa56c21cdc01c4774391fdcc69e987ecc4e5c`.

Clean integration with upstream/main
0ddaa56c21. All 19 integration patches
exactly match the prior-reviewed-main da6d9736 to current-main delta
after diff-location normalization; contributor selector/default/Serena
ownership logic is unchanged. Fresh code-memory/Serena
disable/scope/reconciliation/migration, doctor and incoming
Vertex/backend/CLI tests: 330 passed, 12 skipped, 1 warning. Fourteen
changed Python files pass Ruff lint/format; offline lock and whitespace
checks pass.

Author/Devin discussion read. Existing real upgrade/configuration/launch
qualification remains open: prior Headroom-owned entry versus
user-managed entry, explicit opt-in/rollback, Claude project/user
scopes. This run establishes no actual agent launch or deployment proof.
Static source/test scope and security inspection found no new workflow,
dependency or setup path; the inherited flagged workflow-validation job
is excluded by the exact PR's unchanged workflow paths. Native DLL
reused after complete tracked input-set/hash and artifact-checksum
verification; no fresh build claimed. Maintainers handle exact-head
hosted checks; no PR merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-09 12:23:08 -06:00
bb8d18a56a feat(wrap): add headroom wrap droid for Factory Droid (#4143)
## Description

Add `headroom wrap droid` so Factory subscription traffic, including
Droid Core, can be compressed on the existing Factory plan.

Droid ignores `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` for
Factory-served models. It honors `FACTORY_API_BASE_URL`. This wrapper
points that at the local proxy and gives the proxy a Factory upstream
(`--factory-api-url` / `FACTORY_TARGET_API_URL`, default
`https://api.factory.ai`).

With a Factory upstream configured the proxy registers:

- `POST /api/llm/a/v1/messages` — compressed with the existing Anthropic
pipeline and forwarded to `{factory}/api/llm/a/v1/messages`. A
client-sent `x-headroom-base-url` is ignored. `x-headroom-*` headers are
stripped. Operator Anthropic extra headers are withheld from the
untrusted Factory host.
- Every other `/api/*` path — forwarded verbatim to Factory, except
Hermes Studio's scoped prefixes and requests that name their own
`x-headroom-base-url`.

Nothing outside `/api/` is sent to Factory.
`select_passthrough_base_url` and `upstream_trust` are untouched, so a
leftover Codex, Claude, or Copilot config pointed at a Factory-mode
proxy keeps its own upstream and credentials. That is the deliberate
difference from https://github.com/headroomlabs-ai/headroom/pull/2352,
which is still open and which this does not close. #2352 sends every
unrouted request on a Factory-mode proxy to Factory.

`wrap droid` writes no Droid config. It threads `factory_api_url`
through the existing proxy-reuse logic. With `--no-proxy` it refuses
unless `/health` shows a Headroom proxy serving the same Factory
upstream. OpenAI-shaped `/api/llm/o/*` traffic is forwarded
uncompressed. Those routes are deferred.

This commit is `74c889fb` rebased onto current `main` (`0dd8e0b5`). The
only conflicts were `docs/content/docs/meta.json` (kept both the new
`hermes` page and `droid`) and the `--no-proxy` branch in
`headroom/cli/wrap.py` (kept upstream's OpenAI upstream check and the
Factory check).

Refs #2351

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

## Changes Made

- `headroom wrap droid` sets `FACTORY_API_BASE_URL` to the local proxy
and resolves the Factory upstream from `--factory-api-url`, then
`FACTORY_API_BASE_URL`, then `https://api.factory.ai`. Loopback,
credential, query, and fragment URLs are rejected.
- Factory inference and `/api/*` passthrough routes are registered only
when a Factory upstream is configured. The default proxy is unchanged.
- `/health` reports `factory_api_url`.
- Docs: `docs/content/docs/droid.mdx`.

## Testing

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

### Test Output

Rebased tree `/home/hermes/workspace/headroom-rebase` at `0dd8e0b5`,
importing that tree via `PYTHONPATH` and the existing venv at
`/home/hermes/workspace/headroom/.venv` (Python 3.11.16).

```text
tests/test_cli/test_wrap_droid.py ............................           [ 31%]
tests/test_provider_droid_runtime.py ................................    [ 66%]
```

60 passed. Those are the wrap launch-env tests and the Factory runtime
tests.

`tests/test_proxy/test_factory_decoy_proof.py` did not complete in this
worktree. The proxy refuses to start because `headroom._core` is not
built here (`ModuleNotFoundError`, exit 78). Setting
`HEADROOM_REQUIRE_RUST_CORE=false` still did not finish within 180s. The
decoy proof (decoy upstream stays silent, Factory stand-in receives the
inference request, spoofed `x-headroom-*` headers, REST passthrough,
`--no-proxy` refusals) was written for this change and passed in the
pre-rebase review session. It was not re-run to a green result after
this rebase.

`ruff` and `mypy` were not re-run after the rebase.

## Real Behavior Proof

- Environment: Linux, Python 3.11.16, rebased commit `0dd8e0b5` on top
of `upstream/main` `8c1beb20`. No Factory token. No call to
`api.factory.ai`.
- Exact command / steps:
`PYTHONPATH=/home/hermes/workspace/headroom-rebase
/home/hermes/workspace/headroom/.venv/bin/python -m pytest
tests/test_cli/test_wrap_droid.py tests/test_provider_droid_runtime.py`
- Observed result: 60 passed.
- Not tested: a live Factory subscription, `droid` itself, the socket
decoy proof on this rebased commit (blocked locally by the missing Rust
extension), `ruff`, `mypy`, and CI on GitHub.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. Factory routes register only when
`factory_api_url` / `--factory-api-url` is set.
- Minimum rollout channel: stable. Default proxy behavior is unchanged.
- Stable/default behavior changed: no, unless a Factory upstream is
configured.
- Kill switch / disable path: do not pass `--factory-api-url` and do not
set `FACTORY_TARGET_API_URL`. `wrap droid` is opt-in.
- Unsafe override required: no.
- Qualification impact: none on the default proxy.
- Rollback path: revert this commit. No config is written into Droid.

## Review Readiness

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

The pre-rebase commit `74c889fb` was approved by a fresh Claude Opus 5.5
high review with an empty blocking list. This commit is that change
rebased onto current main. The two conflict resolutions are described
above and have not had a second Opus pass.

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

Does not close #2352. That PR is the prior attempt. This one is a
current-main rebuild with the catch-all leak removed: only `/api/*` is
forwarded to Factory.

akbarkanso is not a Headroom maintainer. Please do not expect this
account to merge.

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4143"
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 `e28dfe6422dfcb9b2cbd5ce0fe673196d3b6ad40`, upstream main
`e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`.

Updated against upstream/main e4a60ed7. Resolved the OpenAI passthrough
overlap by retaining main's prepared-request/model/timing parameters and
soft-passthrough guard alongside the contributor's verbatim flag;
generic compression requires both guards to permit it. Re-reviewed
Factory direct-routing/verbatim semantics and existing discussion. All
93 wrapper/runtime/Factory passthrough/socket-decoy tests pass with
existing native extension; changed-file Ruff lint/format and whitespace
checks pass. No contributor routing policy was rewritten.

Independently reran the official Droid1.3.0 CLI with isolated home,
dummy API key, actual Headroom/Uvicorn proxy and controlled LAN HTTP
upstream on this exact combined head. The CLI consumed the controlled
Anthropic SSE reply and exited zero with HEADROOM_QUALIFICATION_OK. The
message request preserved dummy Authorization and forwarded no
x-headroom headers. This is controlled transport/runtime qualification,
not a live Factory subscription or savings benchmark, and not a fresh
native build. Applied shared test-only Gemini fixture repair for
independently established main failures; all ten cases pass. Formal
approval awaits exact-head hosted qualification.


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


### Maintainer current-main requalification

Exact head `7dd0725a9ac4dd8103dedf78552ceca886fc3620`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Clean mechanical merge with upstream main
c01cf07d94. Re-reviewed current
Factory/Droid routing and author/Devin discussion. Factory inference
retains force_direct to bypass translating backends; Factory passthrough
retains verbatim alongside main's soft-passthrough/prepared-request
guards. Hermes scoped proxy prefixes remain excluded from Factory
dispatch; the existing standalone environment precedence is
intentionally consistent with sibling targets, while Click/wrap retain
flag precedence. No contributor routing policy rewritten.

Fresh wrapper/runtime/Factory passthrough/socket-decoy/Hermes
verification: 100 passed, with test-client/runpy warnings only. All 14
changed Python files pass Ruff lint/format; main-relative whitespace
clean and owned tree clean. Tests use the current-main native DLL for
local startup. Earlier official Droid 1.3.0 controlled-upstream runtime
proof remains scoped to its original run; no fresh official CLI replay,
Factory subscription inference, savings benchmark or branch-native build
is claimed. No new blocker found; approval awaits exact-head hosted
checks. Nothing merged.


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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-07 20:48:53 -06:00
Rudy Mizrahi CelekliandClaude Sonnet 5.5 8f50884bd5 fix(init): handle non-UTF-8 directory names when deriving the init profile (#4673)
## Description

`headroom init` derives a profile id in `_local_profile` with
`sha1(str(root).encode("utf-8"))`. On POSIX a directory name can hold
bytes that are not valid UTF-8; pathlib represents them as surrogate
escapes, and `.encode("utf-8")` raises `UnicodeEncodeError`. The fix
falls back to `os.fsencode(root)` only when UTF-8 encoding fails, so
existing profile ids for normal paths are unchanged and distinct byte
names stay distinct.

Closes #4267

## Type of Change

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

## Changes Made

- `headroom/cli/init.py`: UTF-8 first, `os.fsencode` fallback in
`_local_profile`.
- `tests/test_cli/test_init_cli.py`: regression test using two distinct
non-UTF-8 byte names (POSIX only; fails on `main`, passes now).

## Testing

- [x] Unit tests pass: `tests/test_cli/test_init_cli.py`, 97 passed (1
failed on `main` with the new test)
- [x] Linting passes (`ruff check` / `ruff format --check` on touched
files)
- [ ] Type checking (`mypy headroom`): not run
- [x] New tests added

## Real Behavior Proof

- Environment: macOS, Python 3.12.
- Exact command / steps: called `headroom.cli.init._local_profile` on
`Path(os.fsdecode(b"/nonexistent/proj-\xff"))`, `...\xfe`, and a normal
UTF-8 name.
- Observed result: before, `UnicodeEncodeError: 'utf-8' codec can't
encode character '\udcff'`; after, three valid, distinct
`init-proj-<hash>` ids.
- Not tested: the actual `headroom init hook ensure` command in a real
non-UTF-8 directory (macOS/APFS cannot create such a directory, so the
paths above do not exist on disk), Linux, Windows, mypy, full suite,
pre-push hooks.

## Test Output

Author-reported results (not rerun by the maintainer for this body
clarification): `tests/test_cli/test_init_cli.py`: 97 passed; the new
regression failed on main before the fix. Scoped Ruff check and format
check passed. The Real Behavior Proof section above records the
helper-level before/after result and its untested scope.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; this is a profile-ID derivation bug
fix in `headroom init`.
- Minimum rollout channel: no new rollout channel or gate.
- Stable/default behavior changed: paths that can be encoded as UTF-8
retain the existing digest input. Only `UnicodeEncodeError` selects
filesystem bytes for the digest.
- Kill switch / disable path: revert the fallback change; this restores
the previous error for the affected non-UTF-8 paths.
- Unsafe override required: no.
- Qualification impact: the reported helper regression covers distinct
surrogate-escaped byte names. Actual init/hook execution in a real
non-UTF-8 directory and broader platform behavior remain outside the
reported proof.
- Rollback path: revert the fallback change. This PR does not migrate
existing profiles or rewrite stored profile IDs.


## Review Readiness

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

## Checklist

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

This change was prepared with AI assistance (Claude Code).

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

---

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

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-07 20:35:35 -06:00
7877241d84 feat(providers): add Hermes agent wrap support (#934)
## Description

Adds first-class Hermes Agent support to `headroom wrap` while
preserving the current provider architecture. The wrapper prepares both
OpenAI- and Anthropic-compatible environment variables, supports
argument forwarding and `--prepare-only`, and reports a clear
installation error when the Hermes binary is unavailable.

This update also changes the missing-binary test to assert the complete
CLI output, resolving CodeQL's URL-substring sanitization false positive
without weakening coverage.

## Changes Made

- integrate Hermes launch-environment construction into the existing
provider module
- route OpenAI and Anthropic endpoints through Headroom
- support Hermes argument forwarding and prepare-only setup
- cover missing-binary, launch, and compression/passthrough behavior
- use an exact expected error message in the CLI test for CodeQL
compatibility

**Provider contract:** `headroom wrap hermes` requires `--provider
anthropic` or `--provider openai`. Any other selection, or no flag,
exits with code 1 before the proxy or Hermes starts.

## Testing

- [x] Unit tests pass
- [x] Linting and formatting pass
- [x] New tests added

### Test Output

```text
20 focused Hermes tests passed
ruff check: passed
ruff format --check: passed
git diff --check: passed
```

- `uv run --extra dev pytest tests/test_providers/test_hermes.py
tests/test_cli/test_wrap_hermes.py
tests/test_hermes_passthrough_compression.py -q` (20 passed)
- `uv run --extra dev ruff check tests/test_cli/test_wrap_hermes.py`
- `uv run --extra dev ruff format --check
tests/test_cli/test_wrap_hermes.py`
- `git diff --check`

## UI evidence

Not applicable. This PR changes CLI/provider behavior and tests; it does
not alter a graphical UI.

## Checklist

- [x] Tests added or updated
- [x] Focused tests pass locally
- [x] Formatting and lint checks pass
- [x] No UI screenshots required
- [x] No changelog entry required for this focused provider integration


## Type of Change

- [ ] Bug fix
- [x] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Real Behavior Proof

- Environment: current Hermes provider/wrapper test environment.
- Exact command / steps: ran the Hermes provider, CLI wrapper, and
passthrough/compression suites plus Ruff, formatting, and diff checks.
- Observed result: 20 focused tests pass; OpenAI and Anthropic endpoints
route through Headroom, arguments and prepare-only work, and missing
binaries produce the exact expected error.
- Not tested: a live Hermes Agent session against production providers.

## Runtime Rollout Safety

- Rollout-managed feature(s): None. This adds a new opt-in `headroom
wrap hermes` command.
- Minimum rollout channel: N/A
- Stable/default behavior changed: No. Other wrap commands and proxy
behavior do not change.
- Kill switch / disable path: Do not run `headroom wrap hermes`. Hermes
can also be started without the wrapper.
- 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

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/934"
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 `ef4c2c11cd6359aaf4239f9cc394c28c23985c15`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.

Clean mechanical synchronization with upstream main
2d3ee51846435ef5b320eea4806af14e602b0d8c; contributor routing policy
unchanged. Current author replies and Devin findings reviewed. The
previous default-routing blocker is addressed: the wrapper rejects
absent/unsupported provider flags before calling _launch_tool, and
permits explicitly selected anthropic/openai providers. The
launch-boundary regressions exercise both rejected/default and supported
paths. Explicit empty environments remain isolated, and the shared port
callback is retained.

Hermes/provider/port-alignment tests pass; changed-file Ruff lint/format
and main-relative whitespace checks pass. Existing native extension
supports Python startup, not a fresh native build. The author's
Hermes0.22.2 WSL rejected/default and explicit-provider startup evidence
is considered; this round does not claim live authenticated provider
traffic. Project attribution, retrieval-plugin setup and a possible
registry consolidation remain separate follow-ups rather than claims
that the wrapper installs the plugin or supports other providers.

No remaining finding in the previously requested provider-guard scope.
Formal approval awaits exact-head hosted qualification, handled by
maintainers. Author readiness state preserved; 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 Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 21:11:37 -06:00
02c4e922f7 fix(cli): resolve active proxy port for read commands (#3522)
## Description

`headroom wrap copilot` can intentionally start a dedicated proxy on
port 8788
(or fall forward when 8787 is busy), but read-only CLI commands
previously
defaulted directly to 8787. As a result, `headroom dashboard` could open
a dead
or unrelated dashboard even though the wrapped session reported its
proxy on
8788.

This change extends the shared `headroom/cli/port_discovery.py` resolver
(introduced by #3855) to include live wrap-client markers, preferring
the
newest healthy session while preserving explicit `--port` and
`HEADROOM_PORT`
overrides.

Closes: N/A (no matching open issue found)

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

- Extended the shared port discovery module from #3855 with live
wrap-client
marker validation (PID liveness and reuse checks), newest-session
ordering,
  and `/health` verification.
- Updated `dashboard`, `inspect`, and the runtime probe used by `learn`
to
  follow the newest healthy live wrap session after explicit and
  `HEADROOM_PORT` overrides.
- Kept `doctor`'s requested-port behavior; it now reports a healthy
proxy
  discovered from wrap-client markers elsewhere, with a `--port` hint.
- Added a warning when `dashboard` cannot reach the resolved port.
- Exported the actual proxy port as `HEADROOM_PORT` into every wrapped
agent
  environment.
- Reused #3855's port-discovery module rather than introducing a
parallel
  resolver.
- Added regression coverage for stale/recycled markers, multiple
sessions,
  explicit/environment overrides, dashboard output, doctor diagnostics,
  inspect/learn routing, and wrapped child environments.
- Documented automatic discovery and wrong-port troubleshooting.

## Testing

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

### Test Output

```text
$ uv run pytest tests/test_cli/test_proxy_port_discovery.py \
    tests/test_cli/test_dashboard_port_discovery.py \
    tests/test_cli/test_port_alignment.py \
    tests/test_cli/test_wrap_helpers.py \
    tests/test_cli_doctor.py tests/test_cli_inspect.py tests/test_cli_learn.py -q
267 passed in 5.49s

$ uv run ruff check .
All checks passed!

$ uv run ruff format --check .
1677 files already formatted

$ uv run mypy headroom/cli/port_discovery.py headroom/cli/proxy.py \
    headroom/cli/doctor.py headroom/cli/inspect.py headroom/cli/learn.py
Success: no issues found in 5 source files

$ uv run pre-commit run --all-files
Sync plugin versions.....................................................Passed
Verify Ruff version alignment............................................Passed
check for merge conflicts................................................Passed
ruff (legacy alias)......................................................Passed
ruff format..............................................................Passed
mypy.....................................................................Passed
```

After the first rebase, `make ci-precheck` completed `cargo fmt --check`
and
`cargo clippy --workspace -- -D warnings`, then stalled in the existing
Rust
Magika/detection tests (multiple tests exceeded 60 seconds). The same
stall
recurred during the push hook; it was stopped after confirming the
affected
suite. The final rebase onto #3883 was followed by the Python/CLI
regression
suite and all repository pre-commit gates above, but not another Rust
test run.

## Real Behavior Proof

- Environment: Ubuntu 22.04.5 LTS x86_64; Python 3.10.12; uv 0.12.10;
Headroom proxy 0.40.0-dev, started on isolated port 18788 with an
isolated live-client marker.
- Exact command / steps: Started an isolated process that wrote its live
PID marker and launched `headroom proxy --port 18788` under a temporary
workspace, with `HEADROOM_PORT` unset; then ran `env -u HEADROOM_PORT -u
HEADROOM_PORT_DISCOVERY
HEADROOM_WORKSPACE_DIR=/tmp/headroom-port-discovery-proof-20260930/workspace
./.venv/bin/headroom dashboard --no-open` and curled
`http://127.0.0.1:18788/dashboard`.

```text
$ env -u HEADROOM_PORT -u HEADROOM_PORT_DISCOVERY \
    HEADROOM_WORKSPACE_DIR=/tmp/headroom-port-discovery-proof-20260930/workspace \
    ./.venv/bin/headroom dashboard --no-open
  Detected live proxy on port 18788
  Dashboard: http://127.0.0.1:18788/dashboard

$ curl --max-time 5 -sS -o /dev/null -w '%{http_code}\n' \
    http://127.0.0.1:18788/dashboard
200

# Proxy health before discovery returned:
service=headroom-proxy status=healthy ready=true
```

- Observed result: With `HEADROOM_PORT` unset, the CLI selected the
marker-associated healthy proxy on 18788, printed the matching dashboard
URL, and the endpoint returned HTTP 200. The earlier manual run with a
real wrapped Copilot session also confirmed discovery on 8788 before
this rebase.
- Not tested: Starting a new interactive `wrap copilot` session after
this rebase (avoided launching an agent); Windows/macOS PID-identity
behavior; multiple simultaneous real proxies; browser UI launch. Unit
tests cover marker ordering, PID reuse, and explicit/environment
overrides.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: `dashboard`, `inspect`, and `learn`
now follow
the newest healthy live wrap proxy when no port override is set;
`doctor`
remains on the requested/default port and reports a live proxy
elsewhere.
- Kill switch / disable path: Pass `--port`, set `HEADROOM_PORT`, or set
  `HEADROOM_PORT_DISCOVERY=0` to bypass automatic discovery.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit; commands return to the fixed 8787
default.

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A — terminal output above captures the behavior.

## Additional Notes

Port discovery is integrated into #3855's shared `port_discovery.py`;
candidates
are accepted only when `/health` identifies `service: headroom-proxy`,
so an
unrelated local JSON service cannot be mistaken for a Headroom proxy.

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3522"
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 `e66a6393f83278aa07e9965f5b87fed820603677`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.

Re-reviewed latest integration head 420c2d636 and current author
response, including isolated workspace/port fixtures and live-marker
ordering/pruning regressions. Clean integration with upstream/main
2d3ee51846. Explicit CLI ports and
HEADROOM_PORT retain precedence; discovery bounds candidate probes,
verifies Headroom health identity, prefers newest live wrap markers, and
preserves configured-agent discovery. No new PR-specific correctness
blocker found in scope.

All 436
dashboard/port/discovery/wrap/doctor/inspect/learn/release/version/MCP
tests pass. All 14 changed Python files pass Ruff check/format;
whitespace passes. Previous cached-read freeze-boundary failure was
independently reproduced on main and is not a contributor-code blocker.
Maintainers handle fresh exact-head qualification and distinguish
inherited failures; no contributor CI execution requested. Existing
native extension supported startup, not a fresh native build. No
contributor discovery logic rewritten; 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: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 21:10:06 -06:00
05431b264f fix(install): make install status agree with doctor when the proxy is reachable (#3072) (#3141)
## Description

`headroom install status` could report `Status: stopped` next to
`Healthy: yes`, while `headroom doctor` reported the same proxy as
running (#3072, bug 2). The commands used independent process views:
`install status` trusted PID/container bookkeeping for `Status`, while
both commands used the live HTTP health endpoints to establish health.

This change treats a successful `/readyz` probe as authoritative
evidence that the deployment is running. If the proxy is not ready,
`runtime_status` still distinguishes a running-but-unhealthy process
from a stopped process.

The PR also adds a focused macOS pytest lane for CLI and install code,
closing the Darwin test-coverage gap described in #3065 without
duplicating the full four-shard Linux suite.

Bug 1 from #3072 (`HEADROOM_PORT` being ignored by `install apply` and
`deploy`) was already fixed on `main` by #3085 and is not reimplemented
here.

Closes #3072
Closes #3065

## Type of Change

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

## Changes Made

- Updated `headroom/cli/install.py` so `install_status` performs one
readiness probe and reports `Status: running` whenever `/readyz` is
healthy.
- Kept `runtime_status` as the fallback when the proxy is not ready,
preserving the distinction between running-but-unhealthy and stopped.
- Added regression coverage for the formerly contradictory `Status:
stopped` plus `Healthy: yes` output.
- Added regression coverage for the not-ready case where process status
must still come from `runtime_status`.
- Added a `test-macos` CI job that runs the CLI/install pytest subset on
`macos-latest`.

## Testing

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

### Test Output

```text
$ uv run --frozen --extra dev pytest tests/test_cli/test_install_cli.py -q
============================= test session starts ==============================
platform darwin -- Python 3.11.15, pytest-9.0.3, pluggy-1.6.0
collected 42 items

tests/test_cli/test_install_cli.py ..................................... [ 88%]
.....                                                                    [100%]

============================== 42 passed in 1.79s ==============================

$ uv run --frozen ruff check headroom/cli/install.py tests/test_cli/test_install_cli.py
All checks passed!

$ uv run --frozen ruff format --check headroom/cli/install.py tests/test_cli/test_install_cli.py
2 files already formatted

$ uv run --frozen mypy headroom/cli/install.py --ignore-missing-imports
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS (Apple Silicon), CPython 3.11.15 via `uv`, pytest
9.0.3.
- Exact command / steps: ran `uv run --frozen --extra dev pytest
tests/test_cli/test_install_cli.py -q`. The new regression test invokes
`headroom install status` through Click's `CliRunner` with `/readyz`
returning healthy while PID/runtime bookkeeping returns `stopped`.
- Observed result: the command exits successfully and prints `Status:
running` with `Healthy: yes`; `Status: stopped` is absent. A second test
verifies that when readiness is false, a live runtime still prints
`Status: running` with `Healthy: no`.
- Not tested: an end-to-end persistent-service installation with a real
OS supervisor or Docker daemon. The new macOS CI job itself will be
exercised by GitHub Actions rather than locally.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; this changes diagnostic display
logic and CI coverage only.
- Minimum rollout channel: stable/default patch release.
- Stable/default behavior changed: yes; `install status` now reports a
ready deployment as running even if PID/container bookkeeping says
stopped. Unready deployments retain the existing runtime-status
behavior.
- Kill switch / disable path: no runtime flag; revert this PR if the
readiness precedence causes an unforeseen regression.
- Unsafe override required: none.
- Qualification impact: `tests/test_cli/test_install_cli.py` and the new
`test-macos` CI job must remain green.
- Rollback path: revert commit `f3ae269b`; no persisted state, schema,
manifest, or configuration migration is involved.

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

Not applicable; this is terminal status output and CI configuration.

## Additional Notes

- Documentation was not changed because no command, option,
configuration contract, or documented workflow changed; this corrects
contradictory diagnostic output.
- #2787 was also reviewed as an urgent author-reported issue, but it
already has active implementation PR #2992. This PR deliberately avoids
duplicating or conflicting with that work.

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3141"
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 `f550bf1d05873b20b773d935aa7cb93025b63262`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.

Re-reviewed latest integration head 3c11d4a96 and current discussion;
clean integration with upstream/main
2d3ee51846. Install status still treats a
ready reachable proxy as running, preserving runtime-status fallback
when unhealthy. All 160 install-status/release/version/MCP tests pass;
no PR-specific production-code blocker found in scope.

Downloaded the latest failing native macOS job 126368233730 from run
41765101507: four persistent-wrap recovery tests still failed because
_Manifest/TaskManifest lacked runtime_kind. Repaired test doubles with
the Python runtime declaration and explicitly mocked the readiness
boundary those tests control through health probes; real ownership
classification remains exercised. Parametrized the four affected
recovery cases across Darwin/Linux/Windows by replacing only runtime
module's sys reference, without global platform emulation. All 83
persistent-wrap tests pass, preserving matching deployment recovery,
bound-socket recovery, healthy reuse, and task warning coverage. No
production recovery logic changed.

Changed-file Ruff check/format and whitespace pass. These local platform
variants are not native macOS validation; exact-head hosted macOS lane
must qualify before approval. Existing native extension supports Python
startup, not a fresh native build. 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: vishal veerareddy <vishalveera.reddy@servicenow.com>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-05 21:09:29 -06:00
2892214881 fix(packaging): use direct CLI module entry point (#2665)
## Description

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

## Type of Change

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

## Changes Made

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

## Testing

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

### Test Output

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

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

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

## Real Behavior Proof

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

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A - packaging entry-point change only.

## Additional Notes

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

---

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

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
Co-authored-by: jd <jd@headroomlabs.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-11-04 08:27:36 -06:00
Glen JungandJerrett Davis fae1e849cb fix(wrap): route OMP OpenAI providers through Headroom (#2755)
## Description

`headroom wrap omp` advertised OMP support but only redirected OMP's
`anthropic` provider. OMP models under `openai` and
`openai-codex`—including the current `openai-codex/gpt-5.6-sol`
model—kept their native endpoints and bypassed Headroom.

This change adds reversible `models.yml` base URL overrides for both
OpenAI provider IDs while preserving the existing Anthropic route,
provider credentials/headers, custom models, byte-for-byte backup, and
`headroom unwrap omp` behavior.

Follow-up to #1811.

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

- Route `providers.openai.baseUrl` through the project-prefixed Headroom
`/v1` endpoint.
- Route `providers.openai-codex.baseUrl` through the same endpoint; OMP
appends `/codex/responses`, which Headroom already supports for HTTP and
WebSocket traffic.
- Preserve all existing provider fields and the established
backup/reinject/unwrap contract.
- Show all three managed provider routes at launch and document the
expanded OMP support.
- Extend the existing OMP wrap tests for fresh injection, user-config
preservation, reinjection, and CLI display.

## Testing

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

### Test Output

```text
$ uv run --extra dev pytest -q tests/test_cli/test_wrap_omp.py
15 passed in 0.31s

$ uv run --extra dev ruff check .
All checks passed!

$ uv run --extra dev ruff format --check .
1343 files already formatted

$ uv run --extra dev mypy headroom
Success: no issues found in 511 source files
```

The full pytest suite was started but not completed: after roughly 17
minutes it was still running unrelated Codex unwrap tests that
repeatedly install/index Serena. No failure was observed before
cancellation; the affected OMP suite is green.

## Real Behavior Proof

- Environment: macOS Darwin 25.4 arm64 (Apple M5 Pro), Python 3.13.13,
CLI code from this branch, published Headroom 0.33.0 proxy on port 8787,
OMP 17.2.7, `openai-codex/gpt-5.6-sol` with stored ChatGPT/Codex OAuth.
- Exact command / steps: Run the command below against the existing
proxy, then inspect `/stats` and the managed `models.yml`.
  1. Start or reuse the local proxy on `127.0.0.1:8787`.
  2. Run:
     ```bash
headroom wrap omp --no-proxy -- -p "Reply with exactly:
HEADROOM_OMP_CODEX_OK" \
       --model openai-codex/gpt-5.6-sol --no-session --no-tools \
--no-extensions --no-skills --no-rules --thinking off --max-time 30s
     ```
  3. Inspect `/stats` and the managed `~/.omp/agent/models.yml`.
- Observed result: OMP returned the expected sentinel, Headroom recorded
one new project request, and all three provider overrides were present.
  - Wrap printed all three routes:
    ```text
    providers.anthropic.baseUrl=http://127.0.0.1:8787/p/headroom
    providers.openai.baseUrl=http://127.0.0.1:8787/p/headroom/v1
    providers.openai-codex.baseUrl=http://127.0.0.1:8787/p/headroom/v1
    ```
  - OMP returned exactly `HEADROOM_OMP_CODEX_OK`.
- Headroom `/stats` recorded the new request under project `headroom`
(`requests` increased from 2 to 3;
`last_activity_at=2026-08-04T02:14:07Z`).
- The managed `models.yml` contained all three overrides; the pristine
backup remained the restore source.
- The running 0.33.0 proxy does not contain the project-prefixed
WebSocket fix from #2379, so this proves fallback-capable request
completion rather than a clean WebSocket upgrade.
- Not tested: a clean project-prefixed WebSocket upgrade against a
release containing #2379; live `openai` API-key request; Windows/Linux;
a long interactive or explicitly isolated WebSocket session; completion
of the full unrelated pytest suite.

## Review Readiness

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

An independent review pass found no correctness or security findings
(confidence 0.96).

## Checklist

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

## Screenshots (if applicable)

N/A — terminal evidence is included above.

## Additional Notes

Release prerequisite: Headroom 0.33.0 has a `/p/<project>` WebSocket
upgrade bug that returns 403 before routing. It was independently fixed
and merged in #2379 (`789a4f3060aa33a5bae82680968c3e367fa2db83`). This
PR builds on `main`, which already contains that fix; stable interactive
OMP WebSocket routing requires a release/backport containing #2379.

The OpenAI API-key provider and ChatGPT/Codex OAuth provider
intentionally share the local `/v1` base URL. Headroom distinguishes
PAYG API keys from Codex OAuth JWT/account headers and forwards each
request to the correct upstream.
<!-- devin-review-badge-begin -->

---

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

Co-authored-by: Jerrett Davis <mxjerrett@gmail.com>
2026-11-03 22:29:59 -06:00
342c495ea5 test(wrap): isolate two auth-precedence tests from the caller's ANTHROPIC_* env (#4601)
## Description

Two tests in `tests/test_cli/test_wrap_claude_vertex_proxy_env.py` fail
whenever the shell running pytest has `ANTHROPIC_AUTH_TOKEN` set:

- `test_wrap_claude_rejects_conflicting_auth_before_proxy_mutation`
- `test_wrap_claude_includes_shared_project_settings_in_auth_precedence`

Both came in with #2993. They put `ANTHROPIC_AUTH_TOKEN` in a settings
file and expect `headroom wrap claude` to name that file as the
conflicting source. Unlike the other tests in the module, they don't
call `_clear_claude_mode_env(monkeypatch)`. `CliRunner.invoke(env=...)`
adds to `os.environ` and doesn't replace it, so a shell-level token wins
the precedence check and the error names `shell environment` instead of
the settings file. Gateways and local routers that front Claude Code
(for example a local proxy or account switcher) commonly export
`ANTHROPIC_AUTH_TOKEN`, so on those machines the tests fail on clean
`main`.

The fix calls the module's existing helper at the start of both tests,
as the other tests already do. Nothing outside the tests changes.

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

- `tests/test_cli/test_wrap_claude_vertex_proxy_env.py`: call
`_clear_claude_mode_env(monkeypatch)` first in the two tests above. The
helper already clears `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`,
`ANTHROPIC_BASE_URL` and the other Claude-mode variables (2 lines
added).

## Testing

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

### Test Output

```text
# shell has ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL exported (values not shown)
$ HOME=$(mktemp -d) pytest -q tests/test_cli/test_wrap_claude_vertex_proxy_env.py      # main fc1ba891
E   AssertionError: assert '/private/var/folders/.../user-settings.json' in 'Error: Claude Code has both ANTHROPIC_API_KEY (shell environment) and ANTHROPIC_AUTH_TOKEN (shell environment) set. ...'
2 failed, 27 passed in 0.44s
$ HOME=$(mktemp -d) pytest -q tests/test_cli/test_wrap_claude_vertex_proxy_env.py      # this branch
29 passed in 0.99s
$ env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_BASE_URL HOME=$(mktemp -d) pytest -q tests/test_cli/test_wrap_claude_vertex_proxy_env.py   # this branch, variables unset
29 passed in 0.53s
$ ruff check tests/test_cli/test_wrap_claude_vertex_proxy_env.py && ruff format --check tests/test_cli/test_wrap_claude_vertex_proxy_env.py   # ruff 0.16.8
All checks passed!
1 file already formatted
```

## Real Behavior Proof

- Environment: macOS 27 (arm64), Python 3.11.17, shell with
`ANTHROPIC_AUTH_TOKEN` exported by a local Claude Code gateway; main at
`fc1ba891` and this branch at `73436b84`, each in its own worktree.
- Exact command / steps: `HOME=$(mktemp -d) pytest -q
tests/test_cli/test_wrap_claude_vertex_proxy_env.py` in each worktree,
then again on this branch under `env -u ANTHROPIC_API_KEY -u
ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_BASE_URL`.
- Observed result: main fails the two tests above because the error
names `shell environment` instead of the settings file. This branch
passes all 29 tests with the variables set and with them unset.
- Not tested: CI runners, which don't export these variables, so the
tests already pass there; the change only removes the dependence on the
caller's shell.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a, test-only change
- Stable/default behavior changed: no; only test setup changes
- Kill switch / disable path: none needed
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A

## Additional Notes

N/A items: the fix is in the tests themselves, so there is no new test,
no code comment and no docs change. `mypy headroom` is unaffected
(test-only change).

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

---

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

Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-03 18:24:38 -06:00
rNoz 2643f34a54 fix(wrap): overwrite drifted selfheal hook command instead of skipping it (#2723)
## Description

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

Retain two originally published self-heal regression tests. Current
`main` already contains the stronger runtime repair, so this refreshed
proposal is test-only and does not replace or reintroduce the superseded
runtime implementation.

Related issue: headroomlabs-ai/headroom#2221.

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

Existing regression coverage only; the template has no test-only
category.

## Changes Made

- Preserve coverage for removing an empty Headroom-owned environment
section and retaining unrelated user environment values.
- Pin the retained fixture writes to LF.
- Leave the current upstream self-heal runtime implementation unchanged.

## Testing

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

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

### Test Output

```text
env -u OPENAI_API_KEY -u ANTHROPIC_API_KEY -u GEMINI_API_KEY -u GOOGLE_API_KEY HF_HUB_OFFLINE=1 uv run --no-sync pytest tests/test_cli/test_wrap_dead_marker_selfheal.py -q
22 passed

uv run --no-sync ruff check .
All checks passed!
uv run --no-sync ruff format --check .
1869 files already formatted

uv run --no-sync mypy headroom
2 existing errors: memory/adapters/embedders.py:389 and integrations/langchain/chat_model.py:380
```

The test-related checkboxes refer to retained regression coverage, not
new runtime functionality or a claim that the global baseline is green.

## Real Behavior Proof

- Environment: macOS arm64, Python 3.14.5, actual temporary settings
files and an actual bound TCP listener; no mocked liveness function.
- Exact command / steps: ran `uv run --no-sync python` with the
following script, then let its temporary directory clean itself up.

```python
import json
import socket
import tempfile
from pathlib import Path
from headroom.cli import wrap

with tempfile.TemporaryDirectory(prefix="headroom-selfheal-runtime-") as home:
    settings = Path(home) / ".claude" / "settings.local.json"
    settings.parent.mkdir()
    settings.write_text(json.dumps({"env": {"KEEP": "preserved"}}), encoding="utf-8", newline="\n")
    with socket.socket() as listener:
        listener.bind(("127.0.0.1", 0))
        listener.listen()
        port = listener.getsockname()[1]
        wrap._write_claude_wrap_base_url(f"http://127.0.0.1:{port}", settings_path=settings)
        wrap._write_wrap_marker(settings, port=port, key="ANTHROPIC_BASE_URL", previous="https://previous.example")
        before = settings.read_bytes()
        wrap._check_and_clear_dead_wrap_marker(settings, key="ANTHROPIC_BASE_URL")
        assert settings.read_bytes() == before
    wrap._check_and_clear_dead_wrap_marker(settings, key="ANTHROPIC_BASE_URL")
    payload = json.loads(settings.read_text())
    assert payload["env"] == {"KEEP": "preserved", "ANTHROPIC_BASE_URL": "https://previous.example"}
    assert not wrap._wrap_marker_path(settings).exists()
    repaired = settings.read_bytes()
    wrap._check_and_clear_dead_wrap_marker(settings, key="ANTHROPIC_BASE_URL")
    assert settings.read_bytes() == repaired
```

- Observed result: live-listener settings and ownership marker were
preserved. After closing that listener, the previous URL was restored,
the unrelated value survived, and the marker disappeared. Repeating
repair was a byte-identical no-op.
- Not tested: a real Claude session, paid inference, Windows runtime
execution, or a fresh complete repository suite. This demonstrates
current upstream runtime behavior with the retained coverage, not a new
runtime fix in this PR.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; tests only.
- Minimum rollout channel: not applicable.
- Stable/default behavior changed: no.
- Kill switch / disable path: no runtime feature is introduced.
- Unsafe override required: no.
- Qualification impact: retained regressions and actual
filesystem/liveness behavior were checked.
- Rollback path: revert the test-only delta; runtime remains unchanged.

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

Not applicable; filesystem/runtime evidence is recorded above.

## Additional Notes

<!-- Mention any N/A checklist items, tradeoffs, follow-ups, or
maintainer context. -->

The supersession feedback is correct. There is no request to replace the
stronger implementation already in `main`, and no new test-only PR was
opened to chase a known main failure. The unchecked documentation item
is not applicable to retaining these two tests. Maintainers can decide
whether this remaining coverage is useful or redundant.
2026-11-03 18:01:01 -06:00
222f2d1df3 fix(doctor): detect root openai_base_url Codex routing and agent-configured proxy ports (#4490)
## Description

`headroom doctor` gives two false negatives on machines where the proxy
is healthy (reported by a Headroom Desktop user on Windows 11;
reproduced on macOS):

1. **Codex "not routed" when Codex routes through a root
`openai_base_url`.** `check_codex_routing` only reads
`[model_providers.<active>].base_url`. Codex also routes its built-in
`openai` provider (the default when `model_provider` is unset) through a
root `openai_base_url`. Headroom Desktop writes that layout, because the
ChatGPT desktop app hides Dots, dictation and voice for any other
`model_provider` (`openai/codex#55783`). Doctor now reads the root key
for the `openai` provider and for configs with no `model_provider`,
where it wins over a leftover `[model_providers.headroom]` table. Both
keys only count at the TOML root (before the first table header): a
`model_provider` under `[profiles.*]` applies only when that profile is
selected, so it no longer hides the default session's route.
2. **A bare `headroom doctor` can't find a proxy on a port only the
agents know about.** Without `--port`, discovery probes 8787,
`HEADROOM_PORT`, deployment manifests and the wrap marker. Headroom
Desktop (port 6767) and `wrap --port N` leave none of these, so the
proxy row read "not reachable at 8787" with no hint. Discovery now also
probes the loopback ports in Claude Code's `ANTHROPIC_BASE_URL` and
Codex's active base URL, read from the same project and user configs as
the routing rows (`.claude/settings.local.json`,
`.claude/settings.json`, `.codex/config.toml`, then the user files),
through the existing `extra=` hook of `find_live_proxy_elsewhere`. It
still never adopts a port silently: the proxy row names the live port,
as it already does for manifest ports.

`codex_active_base_url` is shared with `init`'s port-alignment warning,
which now sees the same routing.

## Type of Change

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

## Changes Made

- `headroom/cli/doctor.py`: `codex_active_base_url` reads
`model_provider` and `openai_base_url` from the TOML root only; with no
root `model_provider` (or `"openai"`), a root `openai_base_url` wins,
else the active provider table, else the legacy
`[model_providers.headroom]` table.
- `headroom/cli/doctor.py`: new `_configured_client_ports(claude_paths,
codex_paths)` feeds the project and user Claude/Codex loopback ports to
`find_live_proxy_elsewhere(extra=...)`.
- `tests/test_cli_doctor.py`: root `openai_base_url` passes (with and
without `model_provider`), beats an inactive
`[model_providers.headroom]` table, is not hidden by a `[profiles.work]
model_provider`; an `openai_base_url` inside a table is not root; a bare
`doctor` names a live proxy on the port a user config, a project
`.codex/config.toml` or a project `.claude/settings.local.json` routes
to.
- `tests/test_cli/test_port_alignment.py`: `init`'s alignment warning
reads the root `openai_base_url` over an inactive
`[model_providers.headroom]` table.

## Testing

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

### Test Output

```text
$ uv run --frozen --extra dev pytest tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py -q
167 passed in 0.99s
$ uv run --frozen --extra dev pytest tests/test_cli_doctor.py tests/test_cli/test_init_cli.py tests/test_cli/test_port_alignment.py tests/test_cli/test_wrap_stale_marker.py tests/test_corporate_tls.py tests/test_install/test_codex_install.py tests/test_offline_egress_chokepoint.py -q
477 passed, 2 skipped in 81.50s
$ uvx ruff@0.17.0 check headroom/cli/doctor.py tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py
All checks passed!
$ uvx ruff@0.17.0 format --check headroom/cli/doctor.py tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py
3 files already formatted
$ uv run --frozen --extra dev mypy headroom/cli/doctor.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS, Headroom Desktop proxy (wheel 0.41.0) live on
127.0.0.1:6767, `~/.codex/config.toml` with root `model_provider =
"openai"` + `openai_base_url = "http://127.0.0.1:6767/v1"`, Claude
`ANTHROPIC_BASE_URL=http://127.0.0.1:6767` in `~/.claude/settings.json`.
- Exact command / steps: `headroom doctor --json` and `headroom doctor
--port 6767 --json`, once with the installed 0.41.0 wheel and once from
this branch (`uv run --frozen headroom doctor`).
- Observed result: The branch reports Codex as routed and names the live
6767 proxy, where 0.41.0 reported Codex as not routed and gave no hint.

```text
0.41.0, no --port:   proxy  fail  not reachable at http://127.0.0.1:8787
                     codex  warn  not routed (no active provider base_url in config.toml)
0.41.0, --port 6767: codex  warn  not routed (no active provider base_url in config.toml)
branch, no --port:   proxy  fail  not reachable at http://127.0.0.1:8787; a Headroom proxy IS running on port 6767
                     codex  warn  routed to port 6767, but doctor probed port 8787 (~/.codex/config.toml)
branch, --port 6767: proxy  pass  running at http://127.0.0.1:6767
                     claude pass  routed via ~/.claude/settings.json
                     codex  pass  routed via ~/.codex/config.toml
```

Review follow-up (fd5e6fd5): a real `headroom doctor --json` process
from 85d32990 and from fd5e6fd5, each in a clean `HOME` (`env -i
HOME=<tmp> PATH=/usr/bin:/bin`, so no `ANTHROPIC_BASE_URL` from the
shell), against the same live 6767 proxy:

```text
A  root openai_base_url 6767 + [model_providers.headroom] 8787, no model_provider, --port 6767
   85d32990  codex warn  routed to port 8787, but doctor probed port 6767
   fd5e6fd5  codex pass  routed via <home>/.codex/config.toml
B  root openai_base_url 6767 + [profiles.work] model_provider = "azure", --port 6767
   85d32990  codex warn  not routed (no active provider base_url in config.toml)
   fd5e6fd5  codex pass  routed via <home>/.codex/config.toml
C  only <project>/.codex/config.toml (root openai_base_url 6767), no --port
   85d32990  proxy fail  not reachable at http://127.0.0.1:8787
   fd5e6fd5  proxy fail  not reachable at http://127.0.0.1:8787; a Headroom proxy IS running on port 6767
```

Live, for the built-in provider's credentials: Codex CLI 0.164.0 signed
in with ChatGPT (`auth_mode = chatgpt`, no API key), config root
`model_provider = "openai"` + `openai_base_url =
"http://127.0.0.1:6767/v1"`, `codex exec --skip-git-repo-check -s
read-only "Reply with exactly the word OK and nothing else."` answered
`OK` (16,982 tokens). A routed request without credentials would have
been rejected upstream.

- Not tested: Windows, the reporter's platform (the change is
platform-independent TOML and URL parsing).

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Stable.
- Stable/default behavior changed: Yes, diagnostics only: `doctor`
reports Codex as routed for root `openai_base_url` configs and probes
the agents' configured loopback ports; the proxy is untouched.
- Kill switch / disable path: `HEADROOM_PORT_DISCOVERY=0` disables the
extra probing; the Codex detection has none, as it only changes a
read-only report.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

Not applicable (CLI output above).

## Additional Notes

Documentation: no doc describes the doctor's Codex detection or
discovery candidates, so nothing to update. Related: #842 (Codex Desktop
doctor support) and #3855 (doctor/live-port alignment).

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

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

---

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-28 23:38:11 -05:00
4a851ed254 fix(codex): accept multi-line inline tables in Codex config.toml (#4436)
## Description

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

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

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

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

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

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

Fixes #4378

## Type of Change

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

## Changes Made

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

## Testing

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

### Test Output

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

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

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

With the fix:

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

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

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

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

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

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

With `dc193870`:

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

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

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

tomlkit versions on the issue's snippet:

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

## Real Behavior Proof

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

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

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

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

  After:

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

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

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

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

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

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

## Runtime Rollout Safety

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

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A

## Additional Notes

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

---------

Co-authored-by: Abelo9996 <Abelo9996@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-28 23:31:18 -05:00
9ac1b52c27 fix(zcode): skip providers that point at the Headroom proxy itself (#4413)
## Description

`detect_upstream` returned the first enabled ZCode provider with a
`baseURL`, even when that URL is the Headroom proxy (the URL the setup
lines tell the user to configure), so `headroom wrap zcode` started the
proxy with itself as upstream. A provider with `"baseURL": null` also
raised `AttributeError` instead of falling back. `wrap zcode` now
resolves the port the proxy will bind (the requested port, or the next
free one when a non-Headroom service holds it) and passes it to
`detect_upstream`, which skips URLs whose host is the proxy's advertised
host (`127.0.0.1`, or `localhost` treated as the same host) on that
port. `[::1]` is not treated as the proxy: it is a different socket, so
an IPv6 provider on the same port stays selectable. Non-string `baseURL`
values are skipped.

Fixes #4409

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

- `detect_upstream(config_path=None, proxy_port=None)`: new optional
`proxy_port`; skip providers whose `baseURL` host is `127.0.0.1` or
`localhost` on that port (not `[::1]`, review round 2); skip non-string
`baseURL`.
- `wrap zcode` resolves the port first (`_find_available_port` when the
requested port is free or held by a non-Headroom listener; unchanged
when a Headroom proxy already runs there or with `--no-proxy`) and
passes it as `proxy_port`. Without this, `_ensure_proxy` could move the
proxy after the upstream was chosen: a backend on the occupied port was
skipped, and a provider on the replacement port (the proxy itself) could
be picked.
- Seven new tests in `tests/test_cli/test_wrap_zcode.py` (four for
`detect_upstream`, three for the port fallback). The new one,
`test_detect_upstream_keeps_ipv6_provider_when_proxy_is_ipv4`, drives
`detect_upstream` with an enabled provider at `http://[::1]:8787` and
`proxy_port=8787` and asserts that provider is selected.

## 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
# new tests, source change reverted
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_skips_provider_pointing_at_proxy
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_only_proxy_provider_falls_back
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_non_string_baseurl_skips[null]
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_non_string_baseurl_skips[int]
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_non_string_baseurl_skips[list]
5 failed, 20 passed

# port-fallback tests (second commit), source change reverted
FAILED tests/test_cli/test_wrap_zcode.py::test_wrap_zcode_port_fallback_keeps_backend_on_busy_port
FAILED tests/test_cli/test_wrap_zcode.py::test_wrap_zcode_port_fallback_skips_provider_on_replacement_port
2 failed, 26 passed

# review round 2 ([::1] regression), source change reverted
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_keeps_ipv6_provider_when_proxy_is_ipv4
1 failed, 28 passed

# with the fix
tests/test_cli/test_wrap_zcode.py: 29 passed
tests/test_cli/test_wrap_zcode.py test_wrap_antigravity.py test_wrap_bob.py: 108 passed

ruff check: All checks passed!
ruff format --check: 2 files already formatted (the two files touched in round 2)
```

## Real Behavior Proof

- Environment: Ubuntu (WSL2), Python 3.12.15, upstream main e995eb9f (PR
head 98ff36c7). The Rust core `_core.abi3.so` was copied (not committed)
from the official `headroom-ai` 0.41.0 wheel. `HOME` pointed at a
scratch directory holding `~/.zcode/v2/config.json`. Real provider = a
local stub on 127.0.0.1:18831 that answers `POST /v1/messages` with a
200 message.
- Exact command / steps: with a config listing a Headroom provider
(`baseURL` http://127.0.0.1:18830) before the stub provider
(http://127.0.0.1:18831), run `HOME=<scratch> python -c "from
headroom.cli.main import main; main()" wrap zcode --port 18830`, wait
for "Proxy ready", then send one `POST /v1/messages` to 127.0.0.1:18830
and read the stub's log. Repeat with the first provider's `baseURL` set
to `null`. "Before" = the source change reverted with `git apply -R`.
- Observed result: see below.
- Not tested: a real ZCode app or the real Z.ai API; Windows/macOS; a
proxy listening on `::1` (`build_proxy_targets` always advertises
`127.0.0.1`, so the code cannot express it, and the inverse case has no
test); the `[::1]` change (review round 2) is unit-level only, no real
proxy run and no real sockets, the earlier runs above were not repeated;
non-loopback aliases of the proxy (a hostname or LAN address that
resolves to the proxy is not detected; the check is by design limited to
the loopback names ZCode's setup lines print); a port that changes after
the check, such as a stale Headroom proxy being replaced on another
port, or another process taking the free port between the check and the
proxy start; the OpenAI-compatible `kind`; mypy.

Before (change reverted), proxy-on-itself config:

```
  Detected provider: Headroom
  Upstream: http://127.0.0.1:18830
proxy process: python -m headroom.cli proxy --port 18830 --workers 1 --anthropic-api-url http://127.0.0.1:18830
client: no response within 40 s
stub upstream received: (nothing)
```

Before, `"baseURL": null` first:

```
  File ".../headroom/providers/zcode/runtime.py", line 86, in detect_upstream
    base_url = opts.get("baseURL", "").strip()
AttributeError: 'NoneType' object has no attribute 'strip'
```

After (this change), both configs:

```
  Detected provider: Z.ai local stub
  Upstream: http://127.0.0.1:18831
proxy process: python -m headroom.cli proxy --port 18830 --workers 1 --anthropic-api-url http://127.0.0.1:18831
client: HTTP 200 {"id": "msg_first", "type": "message", "role": "assistant", ...}
stub upstream received: STUB-UPSTREAM call #1 POST /v1/messages -> 200
```

Port fallback (`wrap zcode --port 18840`, a non-Headroom stub holds
18840 and is the ZCode provider; the proxy moves to 18841). Before
(second commit's source change reverted):

```
  Port 18840 is in use, using port 18841 instead.
  Detected provider: Z.ai (default)
  Upstream: https://api.z.ai/api/anthropic
proxy process: python -m headroom.cli proxy --port 18841 --workers 1 --anthropic-api-url https://api.z.ai/api/anthropic
```

The backend on the occupied port was skipped. With the provider's
`baseURL` set to the replacement port 18841 instead, the proxy is its
own upstream:

```
  Detected provider: Local backend
  Upstream: http://127.0.0.1:18841
proxy process: python -m headroom.cli proxy --port 18841 --workers 1 --anthropic-api-url http://127.0.0.1:18841
```

After (this change), backend on the occupied port:

```
  Starting Headroom proxy on port 18841...
  Detected provider: Local backend
  Upstream: http://127.0.0.1:18840
proxy process: python -m headroom.cli proxy --port 18841 --workers 1 --anthropic-api-url http://127.0.0.1:18840
client (POST /v1/messages to 127.0.0.1:18841): HTTP 200 {"stub": "ok"}
stub upstream received: STUB-UPSTREAM POST /v1/messages body_bytes=89
```

After, provider on the replacement port 18841 (skipped as the proxy
itself):

```
  Detected provider: Z.ai (default)
  Upstream: https://api.z.ai/api/anthropic
proxy process: python -m headroom.cli proxy --port 18841 --workers 1 --anthropic-api-url https://api.z.ai/api/anthropic
```

In the runs where the upstream fell back to api.z.ai no request was
sent, so nothing reached the real API.

Note: to start the proxy through the CLI in the scratch venv, the
packages that `headroom proxy` checks for (mcp, zstandard, websockets,
orjson, transformers, magika, onnxruntime) were installed into a
separate directory on `PYTHONPATH`.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only for ZCode configs that list a
provider pointing at the proxy's own port (now skipped) or a non-string
`baseURL` (now skipped instead of raising)
- Kill switch / disable path: n/a
- Unsafe override required: no
- Qualification impact: none known
- Rollback path: revert the 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
- [ ] 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

Only the three listed test files were run, not the whole suite.
`detect_upstream`'s new parameter is optional, so other callers are
unaffected (the only caller is `wrap zcode`). The change is three
commits: the first adds the loopback check and the `baseURL` guard, the
second resolves the port before detection (review feedback on the
first), the third stops treating `[::1]` as the proxy (maintainer
review). Policy: a provider counts as the proxy only if its host is the
advertised `127.0.0.1` (or `localhost`, treated as that host) and the
port matches; no DNS is done. The sibling PR #4405 (cc-switch loop
guard) applies the same rule (`[::1]` is the proxy only when the proxy
itself is bound to `::1`). Produced with AI assistance (Claude Code)
operated by me (HetCreep); the reproduction was run on my machine on a
clone of the repository.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-24 08:45:28 -07:00
AP 4c7acba593 docs: correct Antigravity IDE setup instructions (no third-party model providers) (#4258)
## Description

Follow-up to the merged #3817. As flagged in the post-merge thread, the
Antigravity IDE doesn’t expose third-party model-provider settings, so
the setup text was telling users to add a custom model provider in a
panel that doesn’t exist. The instructions now describe what the
integration actually covers (MCP registration and the
`/v1internal:streamGenerateContent` endpoint for `google-antigravity`
clients) and distinguish the IDE from the Antigravity CLI (`agy`), which
is the surface that accepts a custom endpoint via
`GOOGLE_GEMINI_BASE_URL`.

Follow-up fix (Devin review on this PR): the `agy` note mentioned
`GOOGLE_GEMINI_BASE_URL` but only printed the OpenAI-compatible URL. It
now prints the Gemini-compatible base URL (scheme://host, the Gemini API
convention) as an explicit `GOOGLE_GEMINI_BASE_URL=...` assignment, and
the OpenAI block is labeled for OpenAI-speaking clients.

## Type of Change

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

## Changes Made

- `headroom wrap antigravity` help text and printed setup instructions
no longer reference IDE model-provider settings; they point at MCP
registration and the native endpoint, and name the CLI separately.
- The `agy` note now shows the Gemini-compatible base URL explicitly
(`GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:<port>`), with the project
prefix (`/p/<name>`) applied like the other URLs.
- `docs/content/docs/proxy.mdx` Antigravity section corrected the same
way.
- Tests updated to assert the corrected wording.

## Testing

- [x] Unit tests pass (`pytest`)

### Test Output

```text
$ pytest tests/test_provider_antigravity.py -q
12 passed, 1 warning in 2.07s

$ pytest tests/test_mcp_registry/test_antigravity_registrar.py -q
25 passed, 1 warning in 0.82s
```

(`test_cli/test_wrap_antigravity.py` was not run locally — `typer` is
not installed in this environment; CI covers it.)

## Real Behavior Proof

- Environment: docs/string-only change; no runtime behavior affected.
- What was checked: the removed claim ("add a custom OpenAI-compatible
model provider in Antigravity’s model-provider settings") was verified
false three ways — the reporter’s own `~/.gemini/settings.json` has no
model-provider keys; Antigravity IDE 2.5.5 exposes no third-party
model-provider settings panel (upstream report plus current docs); and
the `google-antigravity` clients the new text names really do speak
Cloud Code Assist (`POST /v1internal:streamGenerateContent` is served by
the proxy — see `CLOUDCODE_HANDLER_ROUTES` in `route_specs.py`).
- Observed result: `render_setup_lines(8787)` now prints the corrected
IDE/MCP/native-traffic text,
`GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8787` for `agy`, and the OpenAI
block labeled for OpenAI-speaking clients; the 37 tests above pass.
- Not tested: a live Antigravity IDE run — no Mac with the IDE installed
in this environment, and nothing in this change touches a runtime path,
so there is no behavior to smoke-test.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — documentation/strings only.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: no; rendered CLI text only.
- Kill switch / disable path: n/a.
- Unsafe override required: n/a.
- 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

## Checklist

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

## Additional Notes

Docs-only PR; the remaining `wrap` CLI test module is covered by CI.

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4258"
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-dark.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->
2026-10-20 21:48:29 -05:00
1dc7a183f5 fix(copilot): honour GitHub's advertised Business/Enterprise host by default (#4155)
## Description

Supersedes #3403 (parked, stacked on the conflicting #3402) as a
standalone change on `main`.

GitHub's token exchange advertises a per-plan chat host in
`endpoints.api`: `api.business.githubcopilot.com` for Business seats and
`api.enterprise.githubcopilot.com` for Enterprise seats, and GitHub's
own clients route with it. Since #2441 Headroom has folded both into the
generic `api.githubcopilot.com`, because the segmented hosts lagged on
newer Claude models at the time.

That fold breaks enterprises on GitHub's [subscription-based network
routing](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-access/manage-network-access):
their firewall allows only the plan host, the generic host is
unreachable, and the failure looks like a random connection error. It
also made the VS Code guide's Enterprise section wrong, which said
Headroom uses the advertised URL.

This PR honours the Business and Enterprise advertised hosts by default
and adds `GITHUB_COPILOT_USE_ADVERTISED_HOST=0` (also
`false`/`no`/`off`) to restore the generic-host fold for seats where the
segmented host still lags. An explicit `GITHUB_COPILOT_API_URL` or
enterprise domain still wins over both. The individual host keeps being
folded (#610 is unchanged).

Refs #2441, #610, #3352 (an Enterprise seat behind a corporate firewall;
the inline-completions 401 there is #4144).

## Type of Change

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

## Changes Made

- `headroom/copilot_auth.py`:
`_subscription_api_url_from_user_info_payload` returns the advertised
host for the two plan hosts unless `GITHUB_COPILOT_USE_ADVERTISED_HOST`
opts out, and logs the chosen host with the opt-out next to it. That
line is emitted where the host is resolved: the `wrap` process for the
subscription lanes, which does not write to `proxy.log`. The dedicated
proxy's `/health` (`config.openai_api_url`) is where the chosen host
shows up. The generic and individual hosts still normalize to
`DEFAULT_API_URL`. `resolve_copilot_api_url`'s docstring no longer
claims the advertised host is ignored on purpose. Every subscription
lane (`wrap vscode`, `wrap copilot --subscription`, OpenCode
`--copilot-subscription`) already pins `resolution.api_url` into the
dedicated proxy as `--openai-api-url` and `GITHUB_COPILOT_API_URL`, so
they pick this up without changes; `is_copilot_api_url`,
`copilot_completions_base_url` and `_github_host` already treat
`*.githubcopilot.com` as a public Copilot host (verified by an
independent review of the diff).
- `headroom/cli/wrap.py`: `wrap copilot` help text describes the
per-plan routing for `--subscription`; the implicit OAuth lane still
uses the generic host (it performs no token exchange), which the text
now says.
- Docs: `docs/content/docs/vscode-copilot.mdx` Enterprise section is now
true and names the opt-out and the firewall case;
`docs/content/docs/corporate-networks.mdx` lists the plan hosts;
`TESTING-copilot-subscription.md` host section split by lane:
`--subscription` / `wrap vscode` / OpenCode honour the plan host, the
implicit OAuth `wrap copilot` lane is explicitly generic-host (it
performs no token exchange at launch, and `resolve_copilot_api_url` is
pinned network-free by an existing test), and its "open an issue for
auto-detection" paragraph removed.
- Tests: Business and Enterprise honoured; individual and generic still
folded; opt-out restores the fold; explicit pin wins; `wrap copilot
--subscription` pins the advertised host; the implicit OAuth lane stays
on the generic host even when user-info advertises the Enterprise host;
OpenCode subscription lane expectation updated. Three existing tests
that asserted the fold were updated to the new contract.

Follow-ups, not in this PR: `headroom doctor --network` still probes
only `api.githubcopilot.com` (it should probe the resolved plan host);
the implicit OAuth `wrap copilot` lane could resolve the plan host
through the token exchange too.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy`)
- [x] New tests added for new functionality
- [x] Manual testing performed (live Copilot Business seat, 2026-10-13;
see Live verification)

### Test Output

```text
$ pytest tests/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_cli/test_wrap_vscode.py \
    tests/test_copilot_vscode_completions_routing.py tests/test_provider_copilot_vscode_config.py \
    tests/test_cli/test_wrap_opencode.py tests/test_proxy_copilot_auth_hooks.py tests/test_provider_proxy_routes.py \
    tests/test_copilot_integration_id_hmac.py tests/test_proxy/test_anthropic_copilot_upstream_auth.py \
    tests/test_copilot_native_mode.py tests/test_copilot_subscription_smoke.py tests/test_cli/test_copilot_auth.py \
    tests/test_cli/test_wrap_persistent.py
449 passed, 4 deselected
# the 4 deselected tests (test_wrap_persistent.py::*recover*) fail identically on the base commit 976aa714
# with AttributeError: 'TaskManifest' object has no attribute 'runtime_kind'; unrelated to this change

$ uvx ruff@0.16.8 check . && uvx ruff@0.16.8 format --check .
All checks passed! / 1777 files already formatted
$ mypy headroom/copilot_auth.py headroom/cli/wrap.py --ignore-missing-imports
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: macOS, Python 3.12, repo venv, native core loaded.
- Exact command / steps: the suites above, with the new regressions
failing when `_subscription_api_url_from_user_info_payload` is reverted
to the fold.
- Observed result: the token-exchange and user-info producers, `wrap
vscode`, `wrap copilot --subscription` and the OpenCode lane all hand
the dedicated proxy `https://api.enterprise.githubcopilot.com` (or
`.business.`) as both `--openai-api-url` and `GITHUB_COPILOT_API_URL`;
completions still resolve to `copilot-proxy.githubusercontent.com`.
- Live seat: see "Live verification" below. Not tested: an
Enterprise-plan seat (`api.enterprise.`; same code branch as Business),
and the `wrap copilot --subscription` lane (the test seat has the
Copilot CLI policy off).

### Verification needed before release

No Business or Enterprise seat is available to us. Carrier (Enterprise
seats behind a subscription-routed firewall) runs, on this branch, with
`SSL_CERT_FILE` unset and no `GITHUB_COPILOT_API_URL` exported:

```bash
headroom copilot-auth login            # device flow; approve in the browser
headroom wrap vscode                   # leave running; note the port it prints
curl -s http://127.0.0.1:<port>/health | python3 -m json.tool | grep openai_api_url
#   expected: "openai_api_url": "https://api.enterprise.githubcopilot.com"
# then send one Copilot Chat turn in VS Code (any model) and one inline completion
headroom wrap copilot --subscription -- --model claude-sonnet-4.6 -s -p "Reply with exactly: OK"
#   expected: the banner shows COPILOT_PROVIDER_API_URL=https://api.enterprise.githubcopilot.com and the reply is OK
```

`curl -s http://127.0.0.1:<port>/health` on the dedicated proxy should
report `"openai_api_url": "https://api.enterprise.githubcopilot.com"`
(the "advertised plan host" log line is printed by the wrap process, not
written to `proxy.log`). If a model that the generic host serves is
rejected on the plan host (`400 ... model is not supported`), the #2455
condition still holds for that seat: set
`GITHUB_COPILOT_USE_ADVERTISED_HOST=0`, restart the wrapper, and report
the model and the response body on this PR before it is released.

### Live verification (2026-10-13, Copilot Business seat)

Branch merged with #4154 on current `main`, isolated
`HEADROOM_WORKSPACE_DIR`, `SSL_CERT_FILE` and `GITHUB_COPILOT_API_URL`
unset, `headroom copilot-auth login` device flow.

- `/copilot_internal/user` for the seat: `copilot_plan: business`,
`endpoints.api: https://api.business.githubcopilot.com`. (For about
three hours after the seat was assigned GitHub still advertised
`api.individual.`; the plan host appeared on its own.)
- Resolution: default → `https://api.business.githubcopilot.com`;
`GITHUB_COPILOT_USE_ADVERTISED_HOST=0` →
`https://api.githubcopilot.com`; explicit `GITHUB_COPILOT_API_URL` wins.
`main`'s `copilot_auth.py` resolves the same seat to
`https://api.githubcopilot.com`.
- `headroom wrap vscode`: dedicated proxy started with `--openai-api-url
https://api.business.githubcopilot.com`; `/health` reports it.
- Model sweep through the proxy, one turn per picker model on each
endpoint it lists (plus `gpt-4o-mini`): **36/36 returned 200** on the
plan host (Claude Haiku/Sonnet/Opus 4.x–5.5 on `/v1/messages` and
`/chat/completions`, Gemini 3.7/3.8/4, GPT-5.x/6.x and Grok on
`/responses`, `gpt-5-mini`, `gpt-4o-mini`). No `model_not_supported`, so
the #2441/#2455 lag does not reproduce on Business today.
- Real VS Code (Copilot Chat 0.69): Ask mode on Auto (`gpt-6-luna`),
Claude Sonnet 5.5 chat (`/v1/messages`), and Agent mode with tool calls
(wrote and ran a pytest file) all went to
`api.business.githubcopilot.com`; every Copilot upstream call in the
proxy log used the plan host, none the generic host.
- Found while testing, not caused by this PR and present on `main`:
ghost text / next edits (`copilot-nes-*` on `/chat/completions`) are
sent to CAPI and get `400 model_not_supported` on both the plan host and
the generic host. Fixed separately in #4188.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; env-gated.
- Minimum rollout channel: stable.
- Stable/default behavior changed: yes. Business and Enterprise
subscription sessions now route to their advertised plan host instead of
`api.githubcopilot.com`. Individual seats, explicit pins and GHE domains
are unchanged.
- Kill switch / disable path: `GITHUB_COPILOT_USE_ADVERTISED_HOST=0`
restores the previous fold without a rollback; `GITHUB_COPILOT_API_URL`
pins any host.
- Unsafe override required: no.
- Qualification impact: adds plan-host routing coverage to the Copilot
auth and wrap suites.
- Rollback path: revert the 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 made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-13 15:20:50 -07:00
feea130f81 fix(wrap): carry the shared proxy's extensions over to a dedicated Copilot proxy (#4154)
## Description

A wrap that cannot reuse the proxy on its port starts a dedicated proxy
from the shell environment alone. That happens for every Copilot
subscription seed (`headroom wrap vscode`, `wrap copilot
--subscription`) and for a persistent deployment with other routing:
`_ensure_proxy_unlocked` prints "starting a dedicated local proxy
instance" and `_start_proxy` spawns `python -m headroom.cli proxy --port
N` with `os.environ.copy()` only.

An enterprise install enables its savings sinks on the shared proxy as
`--proxy-extension control_plane,observability,...` (`headroom start
--daemon`, `headroom-start.sh`). Nothing forwarded that flag, so the
dedicated proxy came up with no extensions: the local dashboard filled
while the team's dashboard stayed empty, with no error anywhere. This is
the shape a customer on VS Code Copilot Enterprise reported this week,
and one of the explanations for #3716.

## Type of Change

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

## Changes Made

- `headroom/proxy/server.py`: the loopback `/health` config block now
lists `proxy_extensions` (the enabled names only, sorted; no plugin
state).
- `headroom/cli/wrap.py`:
- `_dedicated_proxy_extensions(port, manifest)` reads the extension set
of the proxy that owns the requested port: the running proxy's `/health`
first, else the `HEADROOM_PROXY_EXTENSIONS` recorded in the persistent
manifest's `base_env` (`_manifest_proxy_extensions`; the installer has
no extension flag, so that is the only form a manifest records). A
running proxy that predates the field falls through to the manifest, and
a manifest without the entry is unknown rather than empty (the
deployment's runtime env layers on the launch environment). Returns `[]`
only for a non-Headroom port holder, a live `/health` reporting an empty
list, or an explicitly empty manifest value; `None` otherwise, which
triggers the warning.
- At the dedicated start, whenever this start leaves a running proxy on
the port in place (one `replaces_running_proxy` flag: Copilot seed
isolation, persistent routing mismatch, the attached non-persistent
routing mismatch, and the unknown-config branch) and
`HEADROOM_PROXY_EXTENSIONS` is absent from the environment (an empty
value counts as set: it is the way to start a bare dedicated proxy, and
click lets the flag outrank the envvar, so wrap must not pass the flag
then), the carried set is passed to
`_start_proxy(proxy_extensions=...)`, which adds `--proxy-extension
<csv>`. The banner prints `Extensions carried over from the proxy on
port N: ...`, or one `Warning:` line with the remedy
(`HEADROOM_PROXY_EXTENSIONS=<names>`) when the set could not be read.
- An explicit `HEADROOM_PROXY_EXTENSIONS` in the environment is
inherited by the subprocess and wins; nothing changes when no proxy owns
the port.
- Tests: `tests/test_cli/test_wrap_persistent.py` (carry-over from
`/health`, env wins for both a value and an empty string, warning when
unreadable, no warning for a foreign port holder, manifest fallback,
older proxy falling through to the manifest, older proxy with a silent
manifest warning, explicitly empty manifest value trusted, the attached
routing-mismatch branch, plain start unchanged; the two existing
isolated-seed tests now stub `_query_proxy_health` so they stay
hermetic), `tests/test_cli/test_wrap_helpers.py` (`_start_proxy` emits
the flag), `tests/test_proxy_healthchecks.py` (`/health` reports the
names).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for the fix
- [x] Manual testing performed (live run below)

### Test Output

```text
$ pytest -q tests/test_cli/test_wrap_persistent.py tests/test_cli/test_wrap_helpers.py \
    tests/test_proxy_healthchecks.py tests/test_cli/test_wrap_vscode.py \
    tests/test_cli/test_wrap_copilot.py tests/test_proxy_extensions.py
4 failed, 193 passed in 7.25s

# The 4 failures are on clean main too (same files, patch reverted):
# tests/test_cli/test_wrap_persistent.py::test_{ensure_proxy_recovers_matching_persistent_deployment,
#   ensure_proxy_recovers_persistent_deployment_when_socket_is_bound,
#   recover_persistent_proxy_reuses_healthy_deployment,recover_persistent_proxy_warns_for_task_deployment}
# AttributeError: '_Manifest' object has no attribute 'runtime_kind' (install/runtime.py:241, since #4123)

$ uvx ruff@0.16.8 check <touched files> && uvx ruff@0.16.8 format --check <touched files>
All checks passed! / 5 files already formatted
$ mypy headroom/cli/wrap.py headroom/proxy/server.py --ignore-missing-imports
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: macOS, Python 3.12, repo venv with the branch on
`PYTHONPATH`, native core present, `HEADROOM_WORKSPACE_DIR` pointed at a
scratch directory so the developer's `settings.json` (which already
enables `teams`) and client markers stay out of the run. No credentials
involved; nothing redacted.
- Exact command / steps:

```text
# 1. shared proxy with two extensions (the shape `headroom start --daemon` / headroom-start.sh produce)
$ python -m headroom.cli proxy --port 18903 --proxy-extension skill_search,lossless_guard --workers 1
  Extensions:   ENABLED lossless_guard,skill_search (available: foresight,kiro,lossless_guard,output_pro,routemegood,skill_search,teams,tool_search)

$ curl -s 127.0.0.1:18903/health   # config excerpt
{
  "backend": "anthropic",
  "openai_api_url": null,
  "proxy_extensions": ["lossless_guard", "skill_search"],
  "pid": 81870
}

# 2. another wrap client attached to it (marker under <workspace>/clients/18903/<pid>.json)
$ python -c "import time; from headroom.cli.wrap import _register_proxy_client; _register_proxy_client(18903); time.sleep(400)" &

# 3. a wrap that requests a different backend -> attached routing mismatch -> dedicated proxy
$ HEADROOM_BACKEND=openai python -m headroom.cli wrap cursor --port 18903
  Proxy on port 18903 has incompatible routing config (backend), but live session(s) are attached.
  Starting a dedicated proxy on a different port instead of reusing or disrupting it.
  Port 18903 is in use, using port 18904 instead.
  Extensions carried over from the proxy on port 18903: lossless_guard,skill_search
  Starting Headroom proxy on port 18904...
  Proxy ready — dashboard: http://127.0.0.1:18904/dashboard

$ curl -s 127.0.0.1:18904/health   # config excerpt
{
  "backend": "openai",
  "openai_api_url": null,
  "proxy_extensions": ["lossless_guard", "skill_search"],
  "pid": 82266
}
```

- Observed result: the dedicated proxy on the next port runs the same
two extensions as the shared proxy it was started beside, and the wrap
banner says so. The shared proxy was neither restarted nor killed.
- Control run worth knowing about: the same flow with the developer's
real `settings.json` (which stores `proxy_extensions: "teams"`) showed
no "carried over" line and the dedicated proxy ran `teams`:
`settings.json` is applied to the environment before the guard, so a
persisted `HEADROOM_PROXY_EXTENSIONS` takes the env-wins path by design.
- Unit coverage adds the Copilot-seed, persistent-manifest, older-proxy
and env-wins cases that the live run did not exercise.
- Live Copilot run (2026-10-13, Copilot Business seat, branch merged
with #4155 on current `main`): a shared proxy on 8898 with
`--proxy-extension e2e_probe` (a probe extension recording which proxy
loaded it and every request it saw, standing in for `control_plane`),
then `headroom wrap vscode -p 8898`. Banner: `Extensions carried over
from the proxy on port 8898: e2e_probe`; dedicated proxy args `--port
8899 --openai-api-url https://api.business.githubcopilot.com
--proxy-extension e2e_probe`. The probe saw every request on the
dedicated proxy: a 36-request model sweep plus real VS Code chat,
Claude, and Agent-mode turns, all 200. Same scenario with `main`'s
`wrap.py`: dedicated proxy args have no `--proxy-extension`, `/health`
`proxy_extensions: []`. Also checked live: `HEADROOM_PROXY_EXTENSIONS=`
→ bare proxy; `HEADROOM_PROXY_EXTENSIONS=control_plane` → env wins;
shared proxy with no extensions → none, no warning; no shared proxy →
wrap owns the port, nothing carried.
- Not tested: the portal heartbeat leg (`headroom login` +
`control_plane` reporting to the dashboard). The 4 pre-existing
`_Manifest` test failures named under Testing are unrelated.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: stable.
- Stable/default behavior changed: a dedicated proxy started beside a
shared one now starts with that proxy's extensions instead of none. A
user who wanted a bare dedicated proxy sets `HEADROOM_PROXY_EXTENSIONS=`
explicitly.
- Kill switch / disable path: `HEADROOM_PROXY_EXTENSIONS=` (empty)
starts a bare dedicated proxy; revert the commit.
- Unsafe override required: no.
- Qualification impact: wrap proxy-lifecycle and health suites.
- Rollback path: revert.

## 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 added tests that prove my fix is effective
- [x] New and existing unit tests pass locally with my changes (except
the 4 pre-existing failures named above)
- [x] I did **not** edit `CHANGELOG.md`

Refs #3716

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-13 15:20:34 -07:00
f3d240bcae fix(cli): say why the proxy failed to start (#4120)
## Description

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

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

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

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

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

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

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

Refs #4136

## Type of Change

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

## Changes Made

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

## Testing

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

### Test Output

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

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

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

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

## Real Behavior Proof

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

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

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

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

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

## Runtime Rollout Safety

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

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A

## Additional Notes

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

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

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

---

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-12 18:59:35 -07:00
Tejas ChopraandClaude Opus 5.5 976aa714ef fix(cli): name the broken Codex config, write init configs atomically, keep the identity check (#4129)
## Description

This PR fixes four small CLI problems.

1. **`wrap codex` with a broken `~/.codex/config.toml`.** The warning
looked like this:

   ```
Warning: could not update Codex config: Invalid value (at line 6, column
10)
   ```

The line number pointed into Headroom's own merged text, not the user's
file, and the file was never named. The warning now names the file,
gives the parse error in the user's own lines, and says what to do. The
generic Codex and Grok config warnings now also name the file.

2. **`headroom init` truncated config files while rewriting them.** It
rewrote `~/.claude/settings.json`, Codex `hooks.json` and
`~/.codex/config.toml` with `Path.write_text`. That truncates the file
before writing, so a crash or ENOSPC mid-write left a half-written file.
`init` now uses `fsutil.write_text`, the atomic writer `wrap` already
uses for these same files.

3. **The runtime identity check could be silently skipped.** `init` and
`wrap` each had a `_wait_for_runtime_ready` wrapper. It caught
`TypeError` "for test doubles" and then retried `wait_ready` without
`require_identity=True`. So any real `TypeError` inside `wait_ready`
dropped the runtime identity check. Both wrappers are removed, and
callers now pass `require_identity=True` directly.

4. **A failed hook recovery left no trace.** `_ensure_profile_running`
(the init hook's recovery path) ended in `except Exception: return`. It
now catches only what the start paths raise (`click.ClickException`,
`RuntimeError`, `OSError`, `subprocess.SubprocessError`) and logs one
WARNING after the suppressed-output block: `headroom: could not start
persistent proxy '<profile>': <error>. Check it with `headroom install
status --profile <profile>`.` A start that succeeds but never becomes
ready within 45s logs the same line with `it did not become ready within
45s` as the reason. It goes to stderr; stdout stays clean for the hook.
Any other exception is a bug and now surfaces.

Refs #4136
## Type of Change

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

## Changes Made

- `headroom/cli/wrap.py` `_inject_codex_provider_config`: it now parses
the user's own content, with Headroom blocks stripped, before building
the candidate.
- If that content does not parse, it warns `could not update Codex
config <path>: it is not valid TOML (<user's own parse error>); Codex
WebSocket traffic will bypass Headroom. Fix or remove the file, then
re-run.`
- If the content parses only once the Headroom block is removed, the old
repair path runs instead.
- The snapshot still happens first, so `unwrap codex` restores the file
exactly as before.
- `headroom/cli/wrap.py`: the generic Codex and Grok config warnings now
include the file path (`grok_config_paths()`).
- `headroom/cli/init.py`: `_write_json`, `_ensure_codex_provider` and
the Codex feature-block writer now call `fsutil.write_text`.
- `headroom/cli/init.py` and `headroom/cli/wrap.py`: removed
`_wait_for_runtime_ready`; callers call `wait_ready(...,
require_identity=True)` directly.
- `headroom/cli/init.py` `_ensure_profile_running`: narrowed `except
Exception: return` to the start-path exceptions and log the failure
once, as above.
- Tests:
- New `test_invalid_user_config_is_named_and_left_untouched` in
`test_wrap_codex.py`.
- New `test_write_json_keeps_the_existing_file_when_the_write_fails` in
`test_init_cli.py`. It simulates ENOSPC at fsync and checks that the
original file survives and no temp file is left.
- New
`test_ensure_profile_running_never_retries_wait_ready_without_identity`:
its `wait_ready` double raises `TypeError` whenever `require_identity`
is passed. It asserts the error propagates and `wait_ready` was called
once, with `require_identity=True`. It fails if the fallback comes back.
- New `test_ensure_profile_running_logs_a_failed_recovery`: no log on a
clean start; exactly the one WARNING above when `start_supervisor`
raises.
- New
`test_ensure_profile_running_logs_a_recovery_that_never_becomes_ready`:
the start succeeds, the 45s `wait_ready` returns False, and the WARNING
names that reason.
- The `wait_ready` doubles in `test_init_cli.py` and
`test_wrap_persistent.py` now accept, or assert, `require_identity`;
`test_recover_persistent_proxy_routes_docker_task_to_docker_supervisor`
asserts `require_identity=True`.
  - All four new tests fail on origin/main and pass here.

## Testing

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

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_cli/test_init_cli.py tests/test_cli/test_wrap_persistent.py tests/test_cli/test_wrap_codex.py tests/test_cli/test_wrap_grok.py tests/test_cli/test_init_enable_tool_search.py tests/test_cli/test_install_cli.py tests/test_install/test_providers.py tests/test_install/test_runtime.py tests/test_plugin_manifests.py tests/test_cli/test_wrap_helpers.py tests/test_cli/test_port_alignment.py
4 failed, 595 passed in 29.13s
# The 4 failures are in tests/test_cli/test_wrap_persistent.py ("'_Manifest' object has no attribute 'runtime_kind'"). They are pre-existing: clean origin/main gives "4 failed, 59 passed" for that file.

# The new tests against origin/main code:
test_invalid_user_config_is_named_and_left_untouched: 1 failed (old message names no file)
test_write_json_keeps_the_existing_file_when_the_write_fails: 1 failed (DID NOT RAISE: the old write_text never fsyncs and overwrote the file)
test_ensure_profile_running_never_retries_wait_ready_without_identity: 1 failed (DID NOT RAISE: the fallback retried without require_identity)
test_ensure_profile_running_logs_a_failed_recovery: 1 failed (no log record)

$ uvx ruff@0.16.8 check headroom/cli/init.py headroom/cli/wrap.py tests/test_cli/test_init_cli.py tests/test_cli/test_wrap_persistent.py tests/test_cli/test_wrap_codex.py
All checks passed!
$ mypy headroom/cli/init.py headroom/cli/wrap.py --ignore-missing-imports
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: macOS 25.6, Python 3.12, repo `.venv`.
- Exact command / steps:
1. Ran `python -m headroom.cli wrap codex --prepare-only` with a scratch
`HOME` whose `.codex/config.toml` is `model = [unterminated`. This is
the audit's reproduction, and the new test covers it.
2. Called `_recover_persistent_proxy` and `_restart_persistent_proxy`
directly, with the supervisor and `wait_ready` stubbed, and recorded the
arguments `wait_ready` received.
- Observed result:
1. Before: `Warning: could not update Codex config: Invalid value (at
line 6, column 10)`. After: the warning names
`<HOME>/.codex/config.toml`, reports the error at line 1 (the user's
line), and tells the user to fix or remove the file.
2. Both calls passed `{'timeout_seconds': 45, 'require_identity':
True}`.
- Smoke harness (real proxy started from this checkout against a local
fake upstream; temp HOME and workspace, offline):

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

```text
## pr5
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom init hook ensure --profile hookdemo
exit=0
--- stdout

--- stderr
headroom: could not start persistent proxy 'hookdemo': [Errno 2] No such file or directory: 'docker'. Check it with `headroom install status --profile hookdemo`.
## clean
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom init hook ensure --profile hookdemo
exit=0
--- stdout

--- stderr
## pr5
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom wrap codex --prepare-only
exit=0
--- stdout
  Warning: could not update Codex config <tmp>/codex/config.toml: it is not valid TOML (Invalid value (at line 1, column 10)); Codex WebSocket traffic will bypass Headroom. Fix or remove the file, then re-run.
--- stderr
## clean
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom wrap codex --prepare-only
exit=0
--- stdout
  Warning: could not update Codex config: Invalid value (at line 6, column 10)
--- stderr
```
- Not tested: a real disk-full condition; the regression test simulates
ENOSPC at fsync. Windows was not tested either.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A, not rollout-managed.
- Stable/default behavior changed: Yes, in small ways:
- The warning text for an invalid Codex config changes. It stays
non-fatal, and `--prepare-only` still exits 0.
- `init` writes its config files atomically. On Windows they get LF line
endings, the same as `wrap` already writes. New files get mode 0600 from
mkstemp, and existing files keep their mode.
  - `wait_ready` is always called with the identity check.
- A failed init-hook recovery now writes one WARNING line to stderr
instead of nothing.
- Kill switch / disable path: None needed.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A

## Additional Notes

- Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.
- Docs impact is recorded in the cleanup docs ledger; there are no doc
edits in this PR.
- **For the maintainer:** should `wrap codex --prepare-only` exit
non-zero when it cannot inject? `scripts/install.sh` relies on that
command. I left it non-fatal, as before.
- **Test-isolation hazard (separate issue, not fixed here):** while
checking the 4 pre-existing `test_wrap_persistent.py` failures, I added
a `runtime_kind` attribute to its `_Manifest` fixture locally. With that
one change, `test_ensure_proxy_restarts_*` started a **real** `headroom
proxy --port 8787` with the real `HOME`. Those tests do not fully stub
process start.

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

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

---

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 09:06:21 -07:00
Tejas Chopra 2c2357ad34 refactor(cli): one missing-binary error for every wrap command (#4122)
## Description

Ten `headroom wrap <tool>` commands each repeated the same four-line
block for a missing binary: `shutil.which`, `click.echo("Error: '<x>'
not found in PATH.")`, then an install hint, then `SystemExit(1)`. The
messages went to **stdout**, while `wrap openclaw` and `headroom init`
already used `click.ClickException`, which writes to stderr.

This PR replaces the ten copies with one helper, `_require_binary`. It
also folds three identical copies of the hidden legacy code-memory flags
into one decorator.

Refs #4136
## Type of Change

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

## Changes Made

- `headroom/cli/wrap.py`: new `_require_binary(*names,
install_hint=...)`.
- It returns the first name found on PATH, or raises
`click.ClickException("'<x>' not found in PATH.\n<hint>")`.
- It replaces the blocks in `claude`, `copilot`, `codex`, `aider`,
`vibe`, `kimi`, `grok`, `opencode` and `omp`, and in the
registry-generated commands (goose, openhands, openclaude, bob).
  - `kimi` keeps its `'kimi' (or 'kimi-cli')` wording.
- The output is the same `Error: ...` text, followed by the hint, with
exit code 1. The one difference is that it now goes to stderr.
- `headroom/cli/wrap.py`: new `_legacy_code_memory_options` decorator.
- It replaces the three identical hidden `--no-tokensave` / `--serena` /
`--no-serena` declarations on `wrap claude`, `wrap codex` and `wrap
grok`.
- It sits next to the existing `_code_memory_option`, the module's idiom
for shared options.
  - The option order is preserved.
- `tests/test_cli/test_wrap_helpers.py`: new
`test_missing_binary_error_goes_to_stderr_only`, for `wrap aider`
(hand-written), `wrap goose` (registry) and `wrap kimi` (two names). It
reads stdout and stderr separately: exit 1, empty stdout, the error on
stderr, and no proxy start. It fails on origin/main, where the message
went to stdout.

## Testing

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

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_cli/test_wrap_*.py tests/test_cli/test_tokensave_scope.py tests/test_cli/test_serena_disable.py tests/test_cli/test_serena_migrate.py tests/test_cli/test_serena_reconcile.py tests/test_cli/test_serena_scope.py tests/test_cli/test_unwrap_claude.py tests/test_cli/test_port_alignment.py
4 failed, 837 passed, 1 skipped in 23.28s
# The 4 failures are in tests/test_cli/test_wrap_persistent.py ("'_Manifest' object has no attribute 'runtime_kind'"). They are pre-existing: clean origin/main gives "4 failed, 59 passed" for that file.

# Every wrap/unwrap command's params (name, opts, hidden, help, default), dumped before and after:
267 lines, diff IDENTICAL

$ uvx ruff@0.16.8 check headroom/cli/wrap.py
All checks passed!
$ mypy headroom/cli/wrap.py --ignore-missing-imports
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS 25.6, Python 3.12, repo `.venv`,
`PATH=/usr/bin:/bin`, and a scratch `HOME`.
- Exact command / steps: `python -m headroom.cli wrap claude`, `wrap
kimi` and `wrap goose`, with stdout and stderr captured separately.
- Observed result: each exits rc=1 with empty stdout. Stderr shows, for
example, `Error: 'claude' not found in PATH.` followed by `Install
Claude Code: https://docs.anthropic.com/en/docs/claude-code`. For kimi
it is `Error: 'kimi' (or 'kimi-cli') not found in PATH.` followed by
`Install Kimi CLI: ...`.
- Smoke harness (real proxy started from this checkout against a local
fake upstream; temp HOME and workspace, offline):

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

```text
## pr3
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom wrap aider
exit=1
--- stdout

--- stderr
Error: 'aider' not found in PATH.
Install aider: pip install aider-chat
## clean
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom wrap aider
exit=1
--- stdout
Error: 'aider' not found in PATH.
Install aider: pip install aider-chat
--- stderr
```
- Not tested: Windows; nothing in this change is platform-specific.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A, not rollout-managed.
- Stable/default behavior changed: Only the stream: the missing-binary
error moves from stdout to stderr. The text and the exit code (1) are
unchanged. The tests that assert the text use CliRunner's merged
`result.output` and still pass. `scripts/install.sh` has its own
`command -v` check and does not parse this message.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A

## Additional Notes

- Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.
- No new test: the existing per-command missing-binary tests (goose,
openhands, kimi, vibe, opencode, copilot, openclaw) cover the helper.

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

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4122"
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 -->
2026-10-10 09:05:16 -07:00
Tejas ChopraandClaude Opus 5.5 9266b0300d test(cli): parametrize the registry-target wrap tests (#4119)
## Description

`headroom wrap goose`, `wrap openhands`, `wrap openclaude` and `wrap
bob` are all generated from one `WrapTarget` factory
(`_make_registry_command`). Despite that, goose, openhands and
openclaude each had their own near-identical test file, checking a
missing binary, env fan-out and `--prepare-only`.

This PR folds those three files into parametrized tests in
`test_wrap_registry.py`, keyed on the registry. The missing-binary,
`--prepare-only` and launch-env checks now also cover `bob`.

Refs #4136
## Type of Change

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

## Changes Made

- Deleted `tests/test_cli/test_wrap_goose.py`, `test_wrap_openhands.py`
and `test_wrap_openclaude.py`.
- Added three tests to `tests/test_cli/test_wrap_registry.py`:
- `test_missing_binary_fails_with_install_hint`, run for every target.
It checks exit code 1, the `'<binary>' not found in PATH` text and the
target's install hint.
  - `test_prepare_only_succeeds_unpatched`, run for every target.
- `test_launch_routes_tool_env_through_proxy`, run for all four targets:
bob, goose, openhands and openclaude. The bob case asserts
`BOB_GATEWAY_URL` is the bare proxy origin with the `/p/<project>`
prefix. The other cases keep the exact env values the old files asserted
(including goose's `ANTHROPIC_HOST`, openhands' `LLM_BASE_URL` and
openclaude's `/p/<project>` prefix), plus the tool label, agent type and
passthrough args.
- `test_wrap_bob.py` is unchanged. It covers Bob's gateway preflight,
which only Bob has.
- No product code changes.

## Testing

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

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_cli/test_wrap_registry.py tests/test_cli/test_wrap_bob.py
90 passed in 2.70s
$ pytest --collect-only -q tests/test_cli/test_wrap_registry.py
16 tests collected
$ uvx ruff@0.16.8 check tests/test_cli/test_wrap_registry.py
All checks passed!
```

## Real Behavior Proof

- Environment: macOS 25.6, Python 3.12, repo `.venv`, branch cut from
origin/main at a9815bbb.
- Exact command / steps: ran the two test files above. The new
parametrized cases invoke `headroom wrap <target>` through `CliRunner`
with `shutil.which` and `_launch_tool` patched, the same way the deleted
files did.
- Observed result: all cases pass. Every assertion from the three
deleted files has an equivalent in the new tests.
- Smoke harness (real proxy started from this checkout against a local
fake upstream; temp HOME and workspace, offline):

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

```text
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom wrap bob --prepare-only
exit=0
--- stdout

--- stderr
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom wrap goose
exit=1
--- stdout
Error: 'goose' not found in PATH.
Install Goose: https://block.github.io/goose/
--- stderr
```
- Not tested: nothing beyond unit tests; this is a test-only change.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A, test-only change.
- Stable/default behavior changed: No.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A

## Additional Notes

- Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.
- `REALIGNMENT/09-phase-G-rtk-observability.md:52-53` names the deleted
test files. That is an old planning doc, so I recorded it in the docs
ledger and did not edit it here.

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

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

---

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 09:01:12 -07:00
Tejas ChopraandClaude Opus 5.5 73f59a32cc refactor(cli): remove test-only and dead helpers from wrap, proxy and mcp (#4118)
## Description

Removes private CLI helpers that no product code calls any more. Each
one lost its last caller in an earlier rewrite, so only its own unit
tests still called it. The tests that pinned the dead code go with it.

Refs #4136
## Type of Change

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

## Changes Made

- `headroom/cli/wrap.py`: removed six dead helpers and constants.
- `_wrap_marker_proxy_is_dead`: the self-heal path now calls
`_wrap_proxy_alive` inline.
- `_agent_savings_config_mismatches` and `_AGENT_SAVINGS_TARGET_AGENTS`:
the live restart check only compares `savings_profile`.
- The `_normalize_openclaw_gateway_provider_ids` forwarder and its
import alias.
- A dead copy of `_opencode_home_dir`; the real one lives in
`providers/opencode/config.py`.
- The unused `_CONTEXT_1M_SUFFIX` and `_OPENCLAUDE_INSTRUCTIONS_FILE`
constants.
- `headroom/cli/proxy.py`: removed `_get_env_float_optional`, which had
no callers.
- `headroom/cli/mcp.py`: removed `get_headroom_command`,
`load_mcp_config`, `save_mcp_config`, `find_headroom_registration` and
the `CLAUDE_CONFIG_DIR` / `MCP_CONFIG_PATH` / `CLAUDE_JSON_PATH`
constants.
- `mcp install`, `mcp status` and `mcp uninstall` all go through
`headroom.mcp_registry` registrars now.
- `load_mcp_config` returned `{}` on corrupt JSON, and `save_mcp_config`
would then overwrite the file. That data-loss path goes away with them.
- Tests removed, because they only exercised the deleted code:
- `tests/test_cli/test_mcp_status.py`, all of which tested
`find_headroom_registration`;
- `TestMCPConfigFunctions` and its path fixtures in
`tests/test_cli/test_mcp.py`;
  - 3 `_wrap_marker_proxy_is_dead` tests;
  - 5 `_agent_savings_config_mismatches` tests;
  - 1 forwarder test.
- The remaining `mcp uninstall` / `mcp status` tests already patch the
registrars. They no longer take the path fixture.

Evidence: `rg -n -w '<name>' headroom crates plugins sdk examples
benchmarks scripts e2e docs wiki .github pyproject.toml tests <consumer
repos>` for each name finds only the definition and the removed tests.
Live behaviour stays covered:
- `test_wrap_dead_marker_selfheal.py`: `test_dead_port_*`,
`test_live_port_is_never_cleared` and the `_wrap_proxy_alive` tests;
- `tests/test_provider_openclaw_wrap.py`;
- `test_mcp.py::TestMCPStatusCommand` / `TestMCPUninstallCommand`.

## Testing

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

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_cli/test_wrap_dead_marker_selfheal.py tests/test_agent_savings.py tests/test_cli/test_wrap_openclaw.py tests/test_cli/test_wrap_opencode.py tests/test_cli/test_mcp.py tests/test_cli/test_wrap_helpers.py tests/test_provider_openclaw_wrap.py tests/test_cli/test_main_help_version.py
253 passed in 33.08s
$ uvx ruff@0.16.8 check headroom/cli tests/test_cli tests/test_agent_savings.py
All checks passed!
$ mypy headroom/cli/wrap.py headroom/cli/mcp.py headroom/cli/proxy.py --ignore-missing-imports
Success: no issues found in 3 source files
```

## Real Behavior Proof

- Environment: macOS, Python 3.12, repo `.venv`, branch cut from
`origin/main` at a9815bbb.
- Exact command / steps: ran the pytest files above, which cover `wrap`,
`unwrap`, `mcp status` and `mcp uninstall` via CliRunner, plus `headroom
--help` / `--version`.
- Observed result: all 253 passed; ruff and mypy are clean.
- Smoke harness (real proxy started from this checkout against a local
fake upstream; temp HOME and workspace, offline):

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

```text
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom mcp install --agent claude
exit=0
--- stdout
Installing Headroom MCP server...
  claude: registered (restart the agent if it was already running)

Next steps:
  1. Start the Headroom proxy (if not running): headroom proxy
  2. Start your agent (e.g.) ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude
  3. Restart any agent that was already running so it picks up the new MCP server.
--- stderr
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom mcp status
exit=0
--- stdout
Headroom MCP Status
========================================
MCP SDK:        ✓ Installed
Agent Config:
  Antigravity IDE: ✗ Not detected
  Claude Code: ✓ Configured
$ HOME=<tmp>/home HEADROOM_WORKSPACE_DIR=<tmp>/ws CODEX_HOME=<tmp>/codex headroom mcp uninstall
exit=0
--- stdout
✓ Claude Code: removed headroom MCP server(s)
--- stderr
```
- Not tested: a live `headroom wrap` session against a real agent
binary. Only unreferenced private code was deleted, so no runtime path
changes.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A, no rollout-managed behaviour.
- Stable/default behavior changed: No. Only code with no callers is
removed.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A

## Additional Notes

- Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.
- No new tests or docs are needed, because this is a pure removal and
none of the removed names were documented.
- `_DEFAULT_1M_MODEL` stays, because
`tests/test_cli/test_wrap_helpers.py` pins it.

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

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

---

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

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 09:01:00 -07:00
07b4511537 [codex] Make Claude project settings injection opt in (#1600)
## Description

Closes #1599

`headroom wrap claude` now applies routing in the child environment by
default, leaving project-local settings untouched. `--project-settings`
or `HEADROOM_CLAUDE_PROJECT_SETTINGS=1` explicitly enables project-local
routing writes. This prevents ordinary wraps from leaving routing state
that affects daemon-spawned workers or later direct Claude sessions.
Existing opt-in ownership, selected-port routing, Foundry/Vertex
behavior, and cleanup are retained.

Opted-in cleanup ownership is recorded immediately after the base-URL
write. If self-heal hook installation fails afterward, the original base
URL and user settings are restored and the session marker cleared. The
runtime settings lock file is removed from version control and ignored.

## Validation

### Test Output

```text
132 focused tests passed
63 related lifecycle/Foundry tests passed; 1 SIGHUP-only case excluded on Windows
Ruff lint/format and whitespace: pass
Linux-target mypy: Success: no issues found in 566 source files
REAL CLI opt_in=False: child process used proxy URL; user base URL restored; session marker absent.
REAL CLI opt_in=True: child process used proxy URL; user base URL restored; session marker absent.
```

The exception regression performs real settings-file writes. The runtime
smoke launches a real local fake-Claude child process; default mode
preserves settings byte-for-byte, and opt-in restores the user base URL.
Fresh hosted CI and review remain pending at
`b6999e0b566093e767474cd44d3143c8da506e91`.

## Runtime Rollout Safety

Project writes require explicit opt-in. Default mode scopes routing to
the launched child and preserves project state. Opted-in writes retain
ownership-aware restoration, including the hook-install failure path,
with Vertex and Foundry routing covered by regressions.


### Current validation (2026-10-08, 1a97aeae9)

Default wraps recover the project URL recorded by an older crashed wrap
before launch, but only when the current URL still belongs to that
writer. A manually repaired URL remains byte-for-byte unchanged;
recovery retires only the stale marker. Recovery and opted-in settings
writers share the same settings lock, preventing retirement of a newer
session marker. Windows lock initialization checks file-size metadata
instead of reading a byte locked by another writer.

Four process-level smoke cases use the actual Headroom CLI and a
separate local child executable reading its environment and on-disk
settings: fresh default, opt-in with restoration, default with a stale
marker, and default with a manually repaired URL. All pass on this head.
This proves CLI/environment/settings lifecycle and does not claim
authenticated Claude API traffic. The smoke checks the real marker path;
a synchronization lock may remain after recovery of existing stale
state, while fresh default creates no wrap artifacts.

99 lifecycle tests and 82 concurrency/lock-helper tests pass; one
pre-existing Windows unwrap-hook test remains excluded after reproducing
the same failure on unchanged b6999e0b5. Ruff lint/format, whitespace,
and Linux-target mypy (566 files) pass. Approval is held for
current-head hosted CI and review.

---------

Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net>
Co-authored-by: Jerrett Davis <mxjerrett@gmail.com>
2026-10-08 11:12:35 -05:00
1fb4cbaea0 fix(proxy): astgrep disk verify truncation (#3192)
## Description

`_detect_truncation()` currently relies on client-specific truncation
banners in `tool_result` text. This works for clients that emit a
recognizable line-count banner, but not for clients such as Cursor
(byte-based, direction-reversed truncation) and OpenCode (placeholder +
external file pointer).

Because `headroom proxy` runs alongside the client it wraps, it can
optionally verify the returned content against the actual file on disk.
If the `tool_result` is a strict prefix of the file, we can identify
truncation without depending on client-specific output formatting.

This adds disk verification as an opt-in fallback: the existing
banner-based detection always runs first, and disk verification is only
attempted when no banner is found. All disk-verification failures or
ambiguous cases return `UNKNOWN` rather than guessing.

Following review, the verifier is also constrained to a trusted,
confined workspace root rather than trusting caller-supplied input
directly — see the last four bullets under Changes Made.

**Current scope:** the session-token workspace binding this fallback
requires is wired for `headroom wrap claude` and plugin-loaded `headroom
wrap opencode` only. Cursor remains unsupported/not tested — it has no
header-injection surface today to transmit an authoritative session
token, so disk verification stays `UNKNOWN` for it; extending Cursor
support needs a separate, safe transport design.

Related to #2430
Closes #2421

## Type of Change

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

## Changes Made
- Added optional disk-based Read truncation verification behind
`HEADROOM_VERIFY_TRUNCATION_ON_DISK`.
- Disk verification compares the visible `tool_result` against the file
on disk and distinguishes `COMPLETE`, `TRUNCATED`, and `UNKNOWN`.
- Disk verification only runs when the existing `_detect_truncation()`
banner check finds no truncation marker, avoiding unnecessary file I/O
when the client already provides a signal.
- Added a `current_cwd` contextvar populated from `x-headroom-cwd` so
relative Read paths can be resolved against the client's working
directory.
- Registered `HEADROOM_VERIFY_TRUNCATION_ON_DISK` as a hot-reloadable
runtime setting.
- Gated verification on a new `is_current_request_trusted` contextvar,
set from `is_loopback_host(request.client.host)` — a server-observed
fact, not the caller-supplied header — so `x-headroom-cwd` is never
sufficient authority on its own.
- Confined all path resolution strictly under the canonicalized `cwd`
(`.resolve()` + `relative_to()`), rejecting `..` traversal,
absolute-path escapes, and post-resolution symlink escapes.
- Required the resolved target to be a regular file and under a byte cap
(new `HEADROOM_VERIFY_TRUNCATION_MAX_BYTES` knob, default 5MB), both
checked via `fstat` on the open fd before any read.
- Opened with `O_NONBLOCK` so a non-regular/special file can't park the
read indefinitely; disk I/O already runs off the event loop via the
existing compression thread pool.
- Added unit and integration tests covering successful verification,
missing/unreadable paths, relative paths, content races, feature gating,
banner precedence, and the adversarial cases below.

## Testing

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

### Test Output

```text
$ pytest tests/test_tool_result_interceptors.py -v
51 passed in 2.21s
(includes TestVerifyReadAgainstDisk::* [14 cases, incl. absolute-path escape, `..`
traversal, symlink escape, sibling-prefix boundary, non-regular file, oversized
file, and untrusted-request-touches-no-disk], plus the end-to-end disk-verification
and banner-precedence cases)

$ pytest tests/test_proxy_loopback_gating.py -k trusted
16 passed
(includes test_record_headroom_stack_binds_trusted_true_for_loopback_client and
..._false_for_non_loopback_client — proves a spoofed x-headroom-cwd from a
non-loopback peer does not bind trust)

$ ruff check headroom/proxy/interceptors/astgrep.py headroom/proxy/project_context.py \
    headroom/proxy/server.py headroom/proxy/runtime_env.py \
    tests/test_tool_result_interceptors.py tests/test_proxy_loopback_gating.py
All checks passed!

$ mypy headroom/proxy/interceptors/astgrep.py headroom/proxy/project_context.py \
    headroom/proxy/server.py headroom/proxy/runtime_env.py
Success: no issues found in 4 source files
```

## Real Behavior Proof

- Environment: Mac OS local dev machine, no live proxy/network involved.
Exercised the real interceptor pipeline (`apply_to_messages`) directly
against an actual file on disk, using the same fixture and cwd-binding
path a live proxy request would use.
- Exact command / steps: wrote a 9-function Python fixture to a temp
file, built a client-truncated `tool_result` (first 8 functions, cut
mid-file, **no truncation banner text anywhere**), bound
`x-headroom-cwd` to the temp directory via `set_current_cwd()`, then
called `apply_to_messages()` once with
`HEADROOM_VERIFY_TRUNCATION_ON_DISK` unset and once with it set to `1`.
- Observed result: With disk verification disabled, the existing
ast-grep interceptor produced its normal header without indicating that
the input was truncated. With HEADROOM_VERIFY_TRUNCATION_ON_DISK=1, disk
verification detected that the 50-line tool_result was a strict prefix
of the 59-line file and produced:
 ```text
=== HEADROOM_VERIFY_TRUNCATION_ON_DISK unset (default) ===
[headroom: outlined by ast-grep — 8 definition(s); bodies elided.
Re-read the file with a line range to see a specific body.]

=== HEADROOM_VERIFY_TRUNCATION_ON_DISK=1, x-headroom-cwd bound to the
real directory ===
[headroom: outlined by ast-grep — 8 definition(s) in the visible
portion; input was truncated upstream (showing through line 50 of 59
total). Bodies elided. Re-read remaining lines to see more.]
```

**Trust-gate behavior:** same fixture and disk layout, `HEADROOM_VERIFY_TRUNCATION_ON_DISK=1`, but the request context's trust flag left at its default (`False`, simulating a non-loopback caller) instead of being marked trusted.

```text
=== trusted context (loopback) ===
[headroom: outlined by ast-grep — 8 definition(s) in the visible
portion; input was truncated upstream ...]

=== untrusted context (non-loopback) — same file, same cwd header, same
tool_result ===
[headroom: outlined by ast-grep — 8 definition(s); bodies elided.
Re-read the file with a line range to see a specific body.]
(no disk read attempted — verified via a call-recording wrapper around
os.open asserting zero invocations)
```
Also verified at the HTTP-middleware level with `TestClient(..., client=("100.90.0.5", 12345))`: a request carrying a spoofed `x-headroom-cwd` header from a non-loopback client IP does not bind trust, regardless of header content.

- Not tested: a live `headroom proxy` session with a real coding-agent client; the WebSocket/Codex responses-WS path.

## Runtime Rollout Safety

- Rollout-managed feature(s): None. The feature is gated by `HEADROOM_VERIFY_TRUNCATION_ON_DISK`
- Minimum rollout channel: N/A. `--intercept-tool-results` must already be enabled for the ast-grep interceptor to run.
- Stable/default behavior changed: no
- Kill switch / disable path: Unset `HEADROOM_VERIFY_TRUNCATION_ON_DISK`; the setting is hot-reloadable and does not require a restart.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit, or unset the env var on a running proxy (takes effect immediately, no restart).

## Review Readiness

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

## Checklist

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

## Additional Notes

this branch is based on `fix/astgrep-truncation-marker` #2430 not main


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

---

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

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-08 10:52:09 -05:00
a6523b1967 fix(codex): preserve auth.json API keys through Headroom (#3355)
## Description

Closes #3354.

When Codex uses an OpenAI API key stored in auth.json, Headroom's
generated provider block did not configure authentication. Codex
therefore sent requests to the local Headroom proxy without an
Authorization header and received 401 Missing bearer.

This is separate from #3206: that issue covers ChatGPT OAuth
authentication, while this change covers file-backed API-key
authentication.

## Type of Change

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

## Changes Made

- Resolve API-key and OAuth credentials from `codex_home_dir()` for both
project and user configurations, honoring `CODEX_HOME`.
- Generate a private, config-specific helper beside `auth.json`; API
keys stay out of generated TOML and Headroom environment variables.
- Configure Codex's supported `auth.command` field for persistent
install, init, and wrap.
- Serialize command and argument paths with literal Unicode and validate
generated TOML before writing provider configurations.
- Abort provider updates with an actionable error if a helper collides
with another file/symlink or cannot be created.
- Use exclusive creation, 0600 permissions on Unix, and content checks
for helper ownership.
- Give project and user configurations independent helper lifetimes.
Retain legacy shared helpers and helpers referenced by
restored/remaining providers or unparseable configurations.
- Preserve unrelated files and the original provider config when
authentication setup fails.
- Remove an unused config-specific helper on uninstall/unwrap.

## Testing

- [x] Focused unit and integration tests pass
- [x] Linting and formatting pass
- [ ] Type checking
- [x] New regression tests added
- [x] Manual runtime testing performed

### Test Output

```text
$ .venv/bin/python -m pytest tests/test_provider_codex_install.py tests/test_install/test_codex_install.py tests/test_cli/test_init_cli.py tests/test_install/test_providers.py tests/test_cli/test_wrap_codex.py -q
284 passed

$ .venv/bin/ruff check .
All checks passed!
$ .venv/bin/ruff format --check .
1744 files already formatted
```

Ruff 0.16.8 matches this branch's CI pin. A focused coverage run reports
93% line/branch coverage for `headroom/providers/codex/install.py` and
covers 44/45 newly added executable lines across the three production
files in this follow-up. This is local focused coverage, not a claim
about the hosted Codecov aggregate. Before the follow-up implementation,
the added local-init/Unicode/helper-isolation regressions produced 6
failures while 118 existing tests passed.

## Real Behavior Proof

- Environment: macOS 26.6.2, Apple Silicon arm64, Python 3.12.11,
Headroom source from this PR, Codex CLI 0.160.0, Sub2API
OpenAI-compatible provider, model `gpt-6-luna`, existing API key in the
user's Codex `auth.json`.
- Setup: start an isolated Headroom proxy on an unused loopback port
with `ProxyConfig(optimize=False, cache_enabled=False,
rate_limit_enabled=False, openai_api_url=<existing upstream>)`. Generate
a temporary provider config with `_ensure_codex_provider(config_path,
port)` while credentials resolve from the user's Codex home. Add `model
= "gpt-6-luna"` and `model_reasoning_effort = "low"` at the document
root. Run the child with its own temporary `CODEX_HOME` and no
`OPENAI_API_KEY` or `OPENAI_BASE_URL` environment variable; its home
contains the generated config, not a copied credential file.
- Exact child command:

```sh
CODEX_HOME=<temporary-home> codex exec --ephemeral --skip-git-repo-check --sandbox read-only --json -C <temporary-workspace> 'Reply with exactly OK. Do not call tools.'
```

Captured after-fix output on 2026-10-07:

```text
Headroom test proxy: ready (optimization disabled)
Codex: 0.160.0; model: gpt-6-luna; auth: generated command, no API-key environment variable
codex exec exit: 0
agent messages: ['OK']
Responses bearer matches auth.json: True
```

The last line comes from an ASGI wrapper that compares the
HTTP/WebSocket Responses request bearer with the file-backed key without
logging either value. The command completed against the real upstream;
no mocked model response was used. The temporary provider config/helper
and test proxy were removed after validation.

- Observed limitation: this upstream rejects WebSocket negotiation with
HTTP 426, so Headroom's existing HTTP streaming fallback completed the
request. This run proves file-backed command authentication and
successful proxy routing, not a successful upstream WebSocket session.
- Not tested in this follow-up: a new Windows/Linux runtime run, full
test suite, native-extension rebuild, or optimization behavior. The
focused Python suite reused the existing local native extension; no Rust
code changed.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: Yes, only when Codex has a
file-backed API key and Headroom writes a provider block.
- Kill switch / disable path: Remove the Headroom-managed provider block
or run the existing Codex unwrap command.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert the generated provider block; auth.json is
unchanged.

## 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 the code
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective
- [x] New and existing unit tests pass locally with my changes
- [x] I did not edit CHANGELOG.md

## Additional Notes

Helpers contain no credential value and read the user's existing
credential file at runtime, so key rotation does not require
reinstalling. Helper names now include a hash of the owning config's
canonical path. Legacy fixed-name helpers are retained conservatively
because other project configurations may still use them.

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

---

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-08 10:46:55 -05:00
Mansurshakh Japarov 79f2c2781a fix(install): distinguish protocol targets in status (#4040)
## Description

Closes #2615.

`headroom install status` labelled the default backend as the generic
`Backend`, even when an OpenAI target was configured independently. This
made a healthy OpenAI-only deployment look like an Anthropic-only
deployment.

## Type of Change

- [x] Bug fix
- [x] Documentation update

## Changes Made

- Label the fallback/backend choice as `Default backend`.
- Show `Anthropic target` and `OpenAI target` separately as `configured`
or `default`, based on the existing live loopback health configuration.
- Do not print upstream target URLs or their embedded credentials.
- Preserve the existing non-dict health-config guard and all
lifecycle/routing behavior.
- Document the distinction in the existing persistent-installs page.
- Cover configured/default/unknown targets,
missing/non-dict/partial/malformed health configuration, manifest
fallback, credential withholding, and actual HTTP status probes.

## Testing

- Complete install/CLI owner suites: **296 passed, 5 skipped**, one
existing Starlette/httpx deprecation warning.
- Ruff lint and format checks for both changed Python files: passed.
- `mypy headroom/cli/install.py`: passed, one source file checked.
- Installed commit hooks: passed (including whole-project mirrored mypy
and commit lint).
- Required `make ci-precheck`, run by the actual pre-push hook: passed —
Rust fmt, strict Clippy, full workspace tests, native extension
build/import, **177 Python passed / 4 skipped** (one existing
provider-counting warning), and commitlint.
- First pre-push attempt hit the unchanged native
`first_dispatch_never_blocks_on_model_init` 500 ms bound at 592.8 ms.
The isolated test and then the complete unchanged gate passed. No
threshold, test, native source, or gate was modified or skipped.
- Independent installed-LangChain whole-project typing failure at
`chat_model.py:394` is tracked in #4039; this changed CLI file's scoped
check passes. No claim that the CLI change fixes that separate error.
- Hosted Codecov's automated advisory reports 0% patch coverage for the
three display lines. The real CLI before/after runs above exercise them;
no wording-only mock test was added to manufacture coverage. At the
observed SHA, there is no failing Codecov check; remaining hosted jobs
were still in progress.

## Real Behavior Proof

Linux x86_64, Python 3.13.14; base
`3c418f6f0b190ad1060413c0eadd77f20ab3cf46`.

Created a real manifest with the production planner and atomic
persistence API, then ran the actual `headroom install agent run` and
`headroom install status` CLI. HOME, canonical workspace/config roots,
profiles, logs, and ports were isolated under the project verification
directory. No system supervisor or provider configuration was installed
or modified. Compression/caching were disabled through supported raw
proxy flags because this is status-display proof, not compression proof;
the anonymous beacon was disabled.

Before, live `/health` reports `backend=anthropic`, a configured OpenAI
URL, and no configured Anthropic URL; status is running/healthy but ends
with `Backend: anthropic` only.

After, the same configuration reports:

```text
Default backend:  anthropic
Anthropic target: default
OpenAI target:    configured
```

A second actual run with both protocol URLs configured reports both
targets as configured. The intentionally unreachable Anthropic test
endpoint reports `Healthy: no` there; configured is not misrepresented
as reachable/healthy. A fake secret embedded in each verification URL
does not appear in status output. Agents were explicitly terminated
after each observation; no graceful-exit claim.

Not tested: paid upstream requests, a running compression workload,
macOS, Windows, or a real platform supervisor installation.

## Runtime Rollout Safety

No channel, feature flag, routing, auth, or persisted-data format
changes. Only operator display changes. Revert this commit to restore
the old display; deployment profiles remain valid.

## Review Readiness

- [x] Changed consumers and existing health-config contract reviewed
- [x] Actual before/after CLI surface verified

## Checklist

- [x] Existing documentation updated
- [x] No warnings introduced in the changed Python files
- [x] No CHANGELOG edit (release-please owns it)

AI-assisted: omp / GPT-6.1 Sol, without subagents. No hosted-CI claim.


## Follow-up qualification at 2969351e3d

When the health response withholds configuration or omits a target
field, status now reports `unknown` instead of asserting the default.
Malformed target values also remain unknown. Explicit null/empty URL
fields report default; configured string URLs report configured without
exposing their contents.

Reproduce the committed HTTP regressions from a configured repository
Python environment:

```sh
python -m pytest tests/test_cli/test_install_cli.py -k status -q
```

For the actual proxy/CLI replay, save the complete script in [the
maintainer evidence
comment](https://github.com/headroomlabs-ai/headroom/pull/4040#issuecomment-6062359335)
as `verify_status.py` in the repository root, then run `python
verify_status.py`. It creates temporary production manifests and an
actual uvicorn proxy, verifies direct health configuration and
configuration withheld by the real health guard through a relay, and
checks that status never prints URLs/credentials. The same script fails
on the original 39e7d46fa head and passes on this head. This is not a
real Docker networking or OS-supervisor installation claim.

Independent Windows/Python 3.12 verification: 319 install/CLI tests
pass, 2 platform skips, one existing warning; Ruff lint/format and
Linux-platform mypy over 566 files pass. The complete suite also
reproduced one unrelated Windows planner test mismatch: it expects
persistent-service defaults although unchanged Windows planning
intentionally converts that preset to persistent-task (#2552). That test
was deselected in the follow-up suite; no planner source/test changed.
Exact setup, limitations, before/after output assertions, and script are
in the linked evidence.
2026-10-08 10:18:32 -05:00
326079517b fix(codex): make unwrap codex remove headroom init routing (#3920)
## Description

`headroom init -g codex` writes a block into `~/.codex/config.toml` that
points Codex at the local proxy:

```toml
# --- Headroom init provider ---
model_provider = "headroom"
openai_base_url = "http://127.0.0.1:8787/v1"
...
# --- end Headroom init provider ---
```

There was no command to take it out again. `headroom unwrap codex` only
recognises the markers that `headroom wrap codex` writes, so on an
init-written config it prints "Nothing to undo" and then "✓ Codex is no
longer routed through the Headroom proxy." The routing is still there.

This matters most on Windows. `init` relies on Codex session hooks to
start the proxy, and those hooks are disabled upstream on Windows (init
already prints a warning about that). So after a reboot or a proxy
crash, Codex keeps calling `127.0.0.1:8787`, nothing restarts the proxy,
and the obvious undo command claims it worked. That matches the symptom
in #3749: Codex stuck on a dead local proxy until the override was
deleted by hand.

This PR makes `unwrap codex` remove the init block. It also makes the
Windows warning say what it means for the user, and documents how to
remove init routing.

Refs #3749. It doesn't close the issue, which also asks wider questions
about the Windows lifecycle; I'll answer those on the issue.

## Type of Change

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

## Changes Made

- `headroom/cli/wrap.py` (`_restore_codex_provider_config`): if the
config contains the `# --- Headroom init provider ---` marker, strip it
with the existing (already tested) `init._strip_codex_init_block` before
the usual wrap cleanup. The existing `cleaned` / `removed` / thread
re-tag flow then runs unchanged. `_codex_config_has_headroom_markers` is
deliberately not changed, because wrap's pre-wrap backup logic also uses
it.
- `headroom/cli/wrap.py` (`_restore_codex_provider_config`, backup
branch): a pre-wrap snapshot taken *after* `headroom init codex` carries
init's block, so restoring it verbatim left Codex pinned to the proxy
while unwrap printed "Restored". The snapshot is now passed through
`_strip_codex_init_block` too (and the config removed if nothing else is
left). The snapshot is read first and deleted only after the config has
been written, so a failed write leaves it in place for a retry instead
of losing it. Review findings from @JerrettDavis / Devin.
- `headroom/cli/init.py` (new `_strip_codex_root_routing_orphans`): the
orphan-key safety net (`model_provider = "headroom"`, loopback
`openai_base_url`) in both `_strip_codex_init_block` and wrap's
`_strip_codex_headroom_blocks` used to match anywhere in the file, so a
newly-reachable unwrap would delete user-owned `[profiles.*]` overrides.
It now only touches the document root, using the same first-table split
`_ensure_codex_provider` already uses. Neither writer ever puts these
keys inside a table. Review finding from @JerrettDavis / Devin.
- `headroom/cli/init.py` (`_init_codex`): on Windows, after the existing
hook warning, add one message. It says nothing starts the proxy there,
and points to `headroom install apply` for a supervised proxy and to
`headroom unwrap codex` (or deleting the project block) to remove the
routing.
- `docs/content/docs/proxy.mdx`: the "routing is persistent until you
remove it" sentence now says how to remove it, that unwrap leaves init's
Codex `SessionStart` hook in `hooks.json` (routing only), plus the
Windows caveat.
- Tests: five new `unwrap codex` cases: init block plus user content
(user content preserved), init-only file (file removed), init → `wrap
codex --prepare-only` → unwrap (snapshot restored without init routing),
the same sequence with the first unwrap's config write failing (snapshot
kept, a second unwrap restores it cleanly), and init → unwrap with a
`[profiles.work]` that sets `model_provider = "headroom"` + a loopback
`openai_base_url` (profile survives). One assertion added to the
existing Windows init warning test.
`TestSubscriptionRouting::test_strip_cleans_orphaned_openai_base_url`
used a key inside `[profiles.default]` as its "orphan"; it now puts the
orphan at the root and asserts a profile-level key survives.

## Testing

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

### Test Output

Both new tests fail on `main`; the failure reproduces the bug:

```text
tests/test_cli/test_wrap_codex.py FF
E   AssertionError: assert 'Nothing to undo' not in '...'
E         Nothing to undo: ...\.codex\config.toml has no Headroom wrap markers.
E       ✓ Codex is no longer routed through the Headroom proxy.
FAILED tests/test_cli/test_wrap_codex.py::test_unwrap_codex_removes_init_provider_routing
FAILED tests/test_cli/test_wrap_codex.py::test_unwrap_codex_removes_init_only_config_file
```

With this branch:

```text
$ pytest tests/test_cli/test_wrap_codex.py tests/test_cli/test_init_cli.py tests/test_cli/test_wrap_opencode.py -q -n 4
228 passed in 7.50s

$ ruff check .
All checks passed!
$ ruff format --check headroom/cli/wrap.py headroom/cli/init.py tests/test_cli/test_wrap_codex.py tests/test_cli/test_init_cli.py
4 files already formatted
$ mypy headroom --ignore-missing-imports --no-site-packages
headroom\fileperms.py:71: error: Module has no attribute "fchmod"  [attr-defined]
Found 1 error in 1 file (checked 554 source files)
```

The mypy error is the Windows-only `os.fchmod` false positive in an
untouched file; it passes on Linux CI.

The full `tests/test_cli` suite on Windows: 907 passed, 12 failed. Five
of those also fail on a clean `upstream/main` worktree with the same
environment (`test_recover_codex` ×2, `test_wrap_stale_marker`,
`test_unwrap_claude` ×2), so they're pre-existing Windows issues. The
other seven (`test_wrap_persistent`,
`test_install_apply_announces_windows_service_fallback`) only failed
under `-n 6` and pass when run serially on this branch (63 passed).

### Review round (rebased on `upstream/main` 1b7977ce)

The two new regression tests fail without the fix:

```text
E   AssertionError: assert {'model': 'gp... {'work': {}}} == {'model': 'gp....1:9999/v1'}}}
FAILED tests/test_cli/test_wrap_codex.py::test_unwrap_codex_after_init_then_wrap_removes_init_routing
FAILED tests/test_cli/test_wrap_codex.py::test_unwrap_codex_init_cleanup_keeps_profile_overrides
====================== 2 failed, 103 deselected in 1.21s ======================
```

With the fix (serial, Windows):

```text
$ pytest tests/test_cli tests/test_install/test_providers.py -q
FAILED tests/test_cli/test_install_cli.py::test_install_apply_restores_previous_deployment_after_failed_update
FAILED tests/test_cli/test_recover_codex.py::test_discover_dangling_homes_only_returns_codex_homes
FAILED tests/test_cli/test_recover_codex.py::test_recovery_never_writes_through_target_symlinks
FAILED tests/test_cli/test_unwrap_claude.py::test_unwrap_claude_removes_mcp_purges_retired_hook_and_stops_proxy
FAILED tests/test_cli/test_unwrap_claude.py::test_unwrap_claude_stops_claude_owned_persistent_deployment
FAILED tests/test_cli/test_wrap_stale_marker.py::test_signal_handler_unwinds_so_the_restore_can_run
====== 6 failed, 1026 passed, 6 skipped, 17 warnings in 90.47s (0:01:30) ======

$ ruff check headroom/cli/init.py headroom/cli/wrap.py tests/test_cli/test_wrap_codex.py tests/test_cli/test_init_cli.py
All checks passed!
$ ruff format --check (same files)
4 files already formatted
```

All six failures reproduce identically on a clean `upstream/main`
worktree in the same environment (`6 failed, 46 passed, 2 skipped` for
those files), so none come from this branch.

### Review round 2 (rebased on `upstream/main` 0d7d61d5)

`test_unwrap_codex_keeps_snapshot_when_init_cleanup_write_fails` fails
on the previous head (the snapshot was already deleted when the write
raised):

```text
E    +    where exists = WindowsPath('.../.codex/config.toml.headroom-backup').exists
FAILED tests/test_cli/test_wrap_codex.py::test_unwrap_codex_keeps_snapshot_when_init_cleanup_write_fails
====================== 1 failed, 105 deselected in 0.94s ======================
```

With the fix:

```text
$ pytest tests/test_cli/test_wrap_codex.py tests/test_cli/test_init_cli.py -q
188 passed in 9.21s
$ ruff check headroom/cli/wrap.py tests/test_cli/test_wrap_codex.py
All checks passed!
$ ruff format --check headroom/cli/wrap.py tests/test_cli/test_wrap_codex.py
2 files already formatted
$ mypy headroom --ignore-missing-imports --no-site-packages
headroomileperms.py:92: error: Module has no attribute "fchmod"; maybe "chmod"?  [attr-defined]
Found 1 error in 1 file (checked 561 source files)
```

Same Windows-only `os.fchmod` false positive as above.

## Real Behavior Proof

- Environment: Windows 11, Python 3.13, this branch vs. `upstream/main`
d5318ac2, isolated `HOME`/`USERPROFILE`/`CODEX_HOME` in a temp dir.
- Exact command / steps: wrote `model = "gpt-5"` to `config.toml`, added
the init block with `init._ensure_codex_provider(cfg, 8787)` (the same
writer `headroom init -g codex` uses), then ran the real `headroom
unwrap codex --no-stop-proxy` Click command and printed the file.
- Observed result: on `main`, unwrap prints "Nothing to undo ... has no
Headroom wrap markers." and "✓ Codex is no longer routed through the
Headroom proxy.", and the file still has `openai_base_url =
"http://127.0.0.1:8787/v1"`. On this branch it prints "Removed Headroom
block from ...\.codex\config.toml; other content preserved." and the
file is just `model = "gpt-5"`. Review round, same isolated setup with a
`[profiles.work]` table that sets `model_provider = "headroom"` and
`openai_base_url = "http://127.0.0.1:9999/v1"`: (a) `init` → `headroom
wrap codex --prepare-only --port 8787` → `headroom unwrap codex`: before
the fix the restored file still began with the full `# --- Headroom init
provider ---` block (`openai_base_url = "http://127.0.0.1:8787/v1"`);
after it, it prints "Restored prior ... from pre-wrap backup." and the
file is `model = "gpt-5"` plus the untouched profile. (b) `init` →
`unwrap`: before the fix `[profiles.work]` came back empty; after it
both profile keys survive.
- Not tested: running the full `headroom init -g codex` command end to
end (it also writes hooks and a deployment manifest, so I wrote the
block with the same function directly); a real Codex Desktop session;
project-scope `.codex/config.toml` init blocks, which `unwrap codex`
doesn't target (the docs now say to delete that block by hand).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; CLI-only change to `headroom unwrap
codex` and an extra `headroom init codex` message on Windows
- Minimum rollout channel: stable
- Stable/default behavior changed: yes, narrowly. `unwrap codex` now
also removes the `# --- Headroom init provider ---` block from the
active Codex config; previously it left it in place and reported
success. The orphan-key safety net shared with `wrap codex` re-injection
is narrowed to the document root, so it no longer deletes matching keys
inside `[profiles.*]`
- Kill switch / disable path: not needed; the only new action runs when
the user explicitly runs `headroom unwrap codex`
- Unsafe override required: no
- Qualification impact: none; no proxy, compression or request-path code
changed
- Rollback path: revert this commit; `headroom init -g codex` re-adds
the routing if a user wants it back

## Review Readiness

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

## Checklist

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

## Additional Notes

- Open PR #3355 also edits `_restore_codex_provider_config` (auth-helper
cleanup). The changes don't overlap logically, but whichever lands
second may need a small rebase.
- Open PR #749 (consolidated `headroom uninstall`) detects Codex only
through wrap markers, so it has the same blind spot for init routing; it
would get this for free by calling `unwrap codex`.
- Not in scope, and a maintainer call: whether `init codex` on Windows
should refuse to write routing, or should set up a supervisor, given
that nothing starts the proxy there.
- Deferred (Devin "existing Codex provider settings lost"): `init codex`
already deletes a user's prior root `model_provider` / `openai_base_url`
when it writes its block, and saves them nowhere. That is pre-existing
`init` behaviour on `main`, which this PR neither introduces nor
worsens, and there is no stored value for unwrap to restore. A clean fix
belongs in `init` (stash the replaced values inside its block, restore
them on unwrap), so I'd rather do it as a follow-up than widen this PR.

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

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

---

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-07 20:59:10 -05:00
944eafc6d4 fix(wrap): reject saved bob gateway URLs the proxy would not route (#3975)
## Description

Follow-up to #3801, promised on its Devin threads ([path
shape](https://github.com/headroomlabs-ai/headroom/pull/3801#discussion_r4175286291),
[invalid
port](https://github.com/headroomlabs-ai/headroom/pull/3801#discussion_r4175286403)).
Both findings landed after that PR was approved, so they ship here
rather than resetting its review.

`bob_preflight` guards against a saved `~/.bob/settings/settings.json`
`gatewayUrl`, which bobshell resolves over `BOB_GATEWAY_URL` at startup.
It compared only scheme/host/port, so two classes of saved URL got
through or crashed it:

- A proxy URL with an extra path segment, query or fragment
(`http://127.0.0.1:8787/p/work/v1`, `…/p/work?team=a`) passed. Bob then
appended `/inference/v1/...` to it; `split_project_path` strips only one
`/p/<project>` segment, so the request arrived as `/v1/inference/v1/...`
and matched nothing. The wrap launched and Bob failed.
- A non-numeric port (`http://127.0.0.1:not-a-port`) made
`urlsplit(...).port` raise outside the parse `try`, so the user got a
traceback instead of the guidance.

Two helpers now answer the two questions separately: `_origin` gives
(scheme, host, port) or None for an unparsable value;
`_routable_proxy_path` is true only for a bare origin or exactly one
`/p/<project>` prefix (reusing `split_project_path`, the router's own
grammar), checked on the **decoded** path the ASGI server hands the
router (so `%2F` in the project segment counts as the extra segment it
becomes, while the `%20` that `with_project_prefix` itself emits is
fine) and with no `?`/`#` anywhere, even bare, since Bob appends to the
string. The abort message names the real problem: "could not be parsed"
/ "is not a URL the proxy can route" when it points at the proxy with a
bad shape / "would bypass the Headroom proxy" for any foreign host,
regardless of its path. A trailing slash remains accepted: bobshell's
`AJ()` collapses repeated slashes and strips a trailing one before
appending paths (verified in 2.0.5).

Closes # (no issue; follow-up to #3801)

## Type of Change

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

## Changes Made

- `headroom/providers/wrap_registry.py`: `_origin_key` → `_origin` +
`_routable_proxy_path`; `bob_preflight` passes only when the saved
origin equals the proxy's and the path is routable, and picks the
message by cause. `split_project_path` is imported from
`headroom.proxy.project_context` alongside the existing
`with_project_prefix`.
- `tests/test_cli/test_wrap_bob.py`:
`TestBobPreflight::test_fails_on_non_proxy_shapes` (12 rejected shapes,
each asserting its reason: bypass / unroutable / unparsable) and
`test_unparsable_env_url_never_matches` (two `None` identities must not
compare equal). Passing cases now also cover `/p/my%20proj` and
`HTTP://LOCALHOST:8787/`.

## Testing

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

### Test Output

```text
$ PYTHONPATH=$PWD python -m pytest -q -p no:cacheprovider tests/test_cli/
981 passed, 1 skipped, 17 warnings in 19.79s

$ git stash push headroom/   # previous head's wrap_registry, new tests
$ pytest tests/test_cli/test_wrap_bob.py -k "non_proxy_shapes or unparsable_env"
5 failed, 3 passed   # the two cases already rejected by #3801 plus one message-only case pass; all new shapes fail

$ uvx ruff@0.16.8 check headroom/providers/wrap_registry.py tests/test_cli/test_wrap_bob.py
All checks passed!
$ uvx ruff@0.16.8 format --check ...
2 files already formatted
$ uvx mypy==1.20.2 headroom --ignore-missing-imports
Success: no issues found in 556 source files
```

## Real Behavior Proof

- Environment: macOS, bobshell 2.0.5, isolated `HOME` whose
`.bob/settings/settings.json` holds
`{"gatewayUrl":"http://127.0.0.1:8788/p/work/v1"}`; proxy code from each
head via `PYTHONPATH`.
- Exact command / steps: `HOME=<fakehome> PYTHONPATH=<checkout> python
-m headroom.cli wrap bob --port 8788 -- --version`, once on
`upstream/main` (`befdb52f`, contains #3801) and once on this branch.
- Observed result: main launched Bob; this branch aborted before the
spawn. Details:
- main: `Launching BOB (API routed through Headroom)...
BOB_GATEWAY_URL=http://127.0.0.1:8788/p/scratchpad` then Bob prints
`2.0.5` — the guard passed and Bob would have used the saved
`/p/work/v1` URL.
- this branch: `Error: Bob's saved gatewayUrl
(http://127.0.0.1:8788/p/work/v1) is not a URL the proxy can route (use
the bare proxy origin, optionally with one /p/<project> prefix). Remove
the gatewayUrl entry from <fakehome>/.bob/settings/settings.json ...` —
Bob never spawned.
- Not tested: a full Bob inference round trip (this change only alters
the pre-launch guard; the account's IBM plan is suspended, see #3801).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only `headroom wrap bob` on a machine
whose saved Bob `gatewayUrl` points at the proxy with an extra
path/query/fragment, or is unparsable. Those launches used to proceed
(and then fail inside Bob) or crash with a traceback; they now abort
with guidance.
- Kill switch / disable path: remove `gatewayUrl` from Bob's settings
(the message says so); no other wrap target has a preflight.
- 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

## 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, the guard's behavior is explained by its own error
message.
- Self-review found and fixed, beyond the two Devin findings:
query/fragment acceptance, scheme-less/host-less URLs comparing equal to
an unparsable env URL, and the "bypass" wording being wrong for
proxy-pointing URLs.
- Deliberately unchanged: `localhost`→`127.0.0.1` normalization does not
cover `[::1]`/`0.0.0.0` (pre-existing; `with_project_prefix` only ever
emits `127.0.0.1`).

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

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

---

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

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-07 20:56:28 -05:00
1d4b357ca7 feat(opencode): support the OpenCode 2.x plugin API (#3999)
## Description

Takeover of #3719 by @laurence-diack-pk, who has been unavailable since
Sep 23 and whose branch was left conflicted with `main`. The original
commit is preserved and @laurence-diack-pk remains its author; this
branch adds follow-up commits addressing @JerrettDavis's review and the
findings from live OpenCode 2.x testing.

It makes the OpenCode plugin and `headroom wrap opencode` work on both
OpenCode 1.x and 2.x. On 2.x the 1.x function plugin was silently
dropped (the loader requires a `{ id, setup }` default export loaded
from a directory), and Effect's `FetchHttpClient` keeps its own `fetch`
reference from before plugins load — so `wrap opencode` loaded no plugin
and routed nothing.

Closes #3669. Supersedes #3719.

## Type of Change

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

## Changes Made

Carried from #3719:
- One plugin for both versions: default export `{ id: "headroom",
server, setup }`; 1.x calls `server`, 2.x calls `setup`.
- 2.x `setup`: registers `headroom_retrieve` via `ctx.tool.transform`
(`codemode: false`), sets `HEADROOM_*` shell env through the
`create.before` hook, and returns a cleanup that releases the refcounted
transport so hot reloads do not stack interceptors.
- 2.x model routing: `ctx.model.transform` points remote OpenAI-wire
models at the proxy with `x-headroom-base-url` /
`x-headroom-original-path` headers, since 2.x keeps its own `fetch`
reference and the transport patch alone misses model traffic.
- Wheel ships the bundle as `_dist/index.js`;
`headroom_opencode_plugin_path()` returns the directory; `wrap opencode`
adds `--standalone` on 2.x so the private server sees
`OPENCODE_CONFIG_CONTENT`.

Follow-up commits (review from #3719 + live testing):
- Rebased on current `main` (0.40.0). Fixed the routing-contract
conflict: replaced `routesThroughProxy` (TS2554 against `shouldRoute`'s
3-arg signature) with `modelBaseRoutesThroughProxy`, a deliberate
model-base eligibility check that keeps the shared protocol / loopback /
proxy-origin / excluded-host contract but drops the endpoint-suffix
requirement, since 2.x hands us model base URLs (e.g. `/v1`), not
inference endpoints.
- `setup` now resolves the effective `excludeHosts` once (option over
`HEADROOM_OPENCODE_EXCLUDE_HOSTS`) and applies it to both the transport
install and the model rewrite, with new tests for both paths.
- Fixed `test_build_launch_env_with_project` to decode
`OPENCODE_CONFIG_CONTENT` instead of substring-matching the raw path,
which JSON backslash escaping makes impossible on Windows.
- `opencode_major_version` now reads the `v2` channel marker in dev
builds (`opencode v0.0.0-v2-<stamp>`), which previously parsed as major
0, so `wrap` skips `--standalone` and the private server never loads
Headroom's config.
- Rebuilt `_dist/index.js` and `hook-shim/handler.js`; drift check
clean.

## Testing

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

### Test Output

```text
# plugins/opencode
$ npm ci && npm run typecheck && npm run build:standalone && npm test
tsc: clean (no TS2554)
vitest: Test Files 3 passed (3) | Tests 45 passed (45)
$ cmp dist-standalone/index.js ../../headroom/providers/opencode/_dist/index.js          # identical
$ cmp dist-standalone/hook-shim/handler.js ../../headroom/providers/opencode/hook-shim/handler.js  # identical

# focused Python suites (same set as #3719, plus the 2.x dev-build version case)
$ pytest tests/test_providers_opencode_plugin_path.py tests/test_providers_opencode_config.py \
    tests/test_providers_opencode_install.py tests/test_cli/test_wrap_opencode.py \
    tests/test_mcp_registry_opencode.py tests/test_learn/test_opencode_scanner.py -q
193 passed in 1.10s

$ ruff check / ruff format --check on changed paths: clean
$ mypy headroom/providers/opencode headroom/cli/wrap.py: Success: no issues found
```

## Real Behavior Proof

- Environment: macOS arm64, Node v26.10.0, Python 3.13, headroom from
this branch (0.41.0-dev). Tested against two real OpenCode 2.x clients,
each in throwaway XDG dirs with its own proxy port:
  - `opencode 2.0.19` (official 2.x binary);
- OpenCode 2.x head built from `anomalyco/opencode@v2`
(`0.0.0-v2-202610061051`, Bun 1.4.2, `bun run script/build.ts --single`
in `packages/cli`).
- Exact command / steps: throwaway XDG dirs and a dedicated proxy port;
fake key first (routing proof), then the real key (end-to-end proof):
  ```bash
  # fake key first (routing proof), then the real key (end-to-end proof)
OPENCODE_API_KEY=<key> headroom wrap opencode --port 8799 --no-serena --
\
run -m opencode-go/deepseek-v4.1-flash "reply with the single word ok"
  # exclusion check
HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai OPENCODE_API_KEY=<key>
headroom wrap opencode ...
  ```
(`opencode-go` declares `OPENCODE_API_KEY` as its env credential in the
catalog, so no interactive login is needed.)
- Observed result: routed 401 with the fake key and 200 with the real
key through the proxy, `--standalone` added automatically, exclusion
honored — details:
- **Fake key** — proxy log: `proxy_inbound_request POST
/v1/chat/completions` with `user-agent: opencode/latest/2.0.19/cli` (and
`opencode/v2/0.0.0-v2-202610061051/cli` for the head), headers
`x-headroom-base-url: https://opencode.ai` and
`x-headroom-original-path: /zen/go/v1/chat/completions`; forwarded
upstream, `401` from the fake key — routed through Headroom.
- **Real key** — the model answered `ok`; proxy `status=200` with
upstream `https://opencode.ai/inference/go/openai/v1/chat/completions`.
- `wrap` added `--standalone` automatically on 2.0.19, and again on the
v2 head after the dev-build version fix (explicit `--standalone` also
works, per the kill-switch path).
- **Exclusion** — with `HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai` the
model still answered while the proxy saw **zero** new chat requests: the
2.x model transform honors the exclusion list.
- Not tested: Windows; OpenAI "responses"-wire against a live 2.x
server; Anthropic-wire custom providers on 2.x; loading the plugin by
npm name (`headroom-opencode`), which needs a published release;
OpenCode 1.x older than 1.2.20.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: on OpenCode 2.x, `wrap opencode`
launches with `--standalone` (a private server per session); on 1.x
behaviour is unchanged apart from the plugin path now being a directory.
- Kill switch / disable path: pass `--server <url>` or `--standalone`
explicitly; `HEADROOM_OPENCODE_PLUGIN_PATH` still overrides the plugin
location.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR; the wheel bundle and plugin path revert
with it.

## Review Readiness

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

## Checklist

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

## Additional Notes

@laurence-diack-pk — thank you for the original implementation; the
commit is preserved verbatim at the base of this branch. @JerrettDavis —
this addresses the routing-contract conflict you described in #3719 (the
missing `excludeHosts` argument and the model-base vs endpoint
mismatch), the Windows assertion, and a dev-build version-detection gap
found while validating on macOS. Live 2.x validation is done on both
2.0.19 and today's `v2` head; details above.

---------

Co-authored-by: laurence <laurence.diack@peekrobotics.co.nz>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-07 20:52:53 -05:00
Mansurshakh JaparovandJD Davis 40955b0eef fix(install): preserve OpenCode edits during reactivation (#4022)
## Description

Reapply, restart, and automatic recovery temporarily remove the Headroom
provider before reactivating it. They must not restore the original
backup and erase user configuration added after installation. Final
removal must still restore the original snapshot.

Closes #4016.

## Type of Change

- [x] Bug fix
- [x] Documentation update

## Changes Made

- Separate transient provider deactivation from final backup
restoration, and propagate the intent through the existing install
registry/manifest lifecycle.
- During reactivation and activation rollback, remove only Headroom's
provider; retain unrelated providers, MCP settings, theme, and the
original backup.
- On true removal, restore and delete the original backup as before.
- Associate backups with the actual selected `opencode.json` or
`opencode.jsonc` filename, and pin edited writes to LF.
- Persist snapshot ownership independently of active mutations,
including activation persistence failures and stop/reload/final-remove.
- Migrate historical JSONC backup names (including custom config names)
before snapshotting/restoration in installer and wrapper callers; do not
claim a sibling JSON installation's backup.
- Accept JSONC comments/trailing commas without erasing user settings;
retain quoted URLs and delimiters.
- Restore the snapshot when a successful replacement drops OpenCode, but
retain it on replacement failure.
- Document preservation during reapply/restart/recovery and
original-snapshot behavior on final removal.

## Testing

- [x] Unit tests pass (`pytest`), including JSON/JSONC and all three
reactivation paths.
- [x] Changed-file lint, configured pre-commit mypy and manual
real-filesystem checks pass.

### Test Output

Real filesystem smoke output for both config suffixes:

```json
[{"final_removal_deletes_backup": true, "final_removal_restores_original": true, "headroom_reactivated": true, "original_backup_unchanged": true, "suffix": ".json", "theme": "edited-after-install", "user_mcp_preserved": true, "user_provider_preserved": true}, {"final_removal_deletes_backup": true, "final_removal_restores_original": true, "headroom_reactivated": true, "original_backup_unchanged": true, "suffix": ".jsonc", "theme": "edited-after-install", "user_mcp_preserved": true, "user_provider_preserved": true}]
```

The mandatory pre-push `make ci-precheck` passed: workspace Rust
fmt/clippy/tests, native extension build/import verification, the
complete configured Python gate, and Commitlint. The native gate
explicitly used the installed CPU `libonnxruntime.so.1.26.0` via
`ORT_DYLIB_PATH`, with cached-model assertions enabled.

```text
[build_rust_extension] headroom._core build + install + verify: OK
================== 177 passed, 4 skipped, 1 warning in 6.31s ===================
✅ ci-precheck PASSED — safe to push.
```

```sh
python -m pytest -q tests/test_providers_opencode_install.py tests/test_cli/test_install_cli.py tests/test_install/test_providers.py
```

Original lifecycle suite: **121 passed**. After the review corrections,
the combined provider/config/wrapper/install-CLI/recovery suite passed
**240 tests in 8.32s**:

```sh
python -m pytest -q tests/test_providers_opencode_install.py tests/test_providers_opencode_config.py tests/test_cli/test_wrap_opencode.py tests/test_cli/test_install_cli.py tests/test_install/test_providers.py tests/test_install_tool_env_reconcile.py
```

The regression suite checks real original bytes and persisted recovery
ownership, not mocked call order or incidental error wording. The
obsolete JSONC-trailing-comma rejection expectation was removed.

Changed-file Ruff, formatting, installed pre-commit `mypy headroom`, and
Commitlint hooks passed. Full-tree Ruff remains blocked locally by
executable permissions on five unchanged OAuth2 plugin files (tracked
100644). A separate full dev-environment mypy run found an unchanged
optional LangChain `truthy-function` error; the configured isolated
pre-commit hook passed. Unrelated code/permissions were not modified.

## Real Behavior Proof

- Environment: Linux x86_64, CPython 3.13.14; unchanged
`dea9092e19385f286b7f67a64f4d85de2708d756` and this branch, real
temporary config files and real installer mutation helpers, no mocked
file mutation or service installed on the workstation.
- Exact command / steps: for each suffix `.json` and `.jsonc`, write an
original theme/provider/MCP config; activate a provider-scoped OpenCode
manifest with `_activate_deployment_mutations`; edit the theme and add a
user provider plus remote MCP; call `_deactivate_deployment_mutations`
then `_activate_deployment_mutations`; inspect real files and the
original backup; finally invoke `revert_mutations(...,
restore_backup=True)`.
- Before: theme reset to `original`; added provider and MCP disappeared.
JSONC's actual-name backup was absent.
- Observed result: after the fix, theme remains `edited-after-install`;
both user additions survive; Headroom is active again; both actual-name
backups remain byte-identical to the original. Final removal restores
the original bytes and deletes the backup for both suffixes.
- Review correction proof against published head `4bc8e50c`: actual
temporary files and persisted manifests cover stop/reload/final-remove
for JSON and JSONC, legacy backup migration for default and custom
filenames, JSONC trailing commas and quoted `//`/`,}` text, successful
target removal, and activation-persistence failure followed by
reload/removal. All eight scenario outcomes pass after the correction;
the published baseline leaves or consumes the wrong snapshots and loses
JSONC edits. The actual `headroom unwrap opencode --no-stop-proxy`
command also restores the historical JSONC snapshot byte-for-byte and
consumes its backup. Only external process/service management and the
explicit persistence-fault boundary are substituted; config, manifest
and snapshot IO are real.
- Second review correction against `1c0855c4`: all four new findings
reproduced on real temporary config/backup files and persisted
manifests. After the fix, failed addition consumes its newly created
snapshot (a later install restores the later user edit); changed config
selection restores the recorded original path; an existing canonical
JSONC snapshot wins without deleting the ambiguous legacy backup; and
restoration failure retains ownership in the active replacement so a
retry after reload finishes restoration. Seven permanent boundary cases
initially gave **6 failures and 1 passing control**; the complete
affected suite now gives **247 passed**. OS supervisor calls and
explicit persistence/restoration faults are the only substituted
boundaries.
- Not tested: a real launchd/systemd supervisor or Windows process on
this Linux host. CLI regression tests exercise apply/restart/recovery
boundaries while replacing service management; the filesystem mutation
smoke uses real production helpers.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; lifecycle data-preservation fix.
- Minimum rollout channel: stable; no rollout-managed feature is
enabled.
- Stable/default behavior changed: transient reactivation stops
reverting unrelated user edits. Final uninstall still restores the
original snapshot.
- Kill switch / disable path: remove the persistent OpenCode
installation using its existing removal flow; no new flag.
- Unsafe override required: no.
- Qualification impact: provider-scoped OpenCode configuration only;
other providers retain their existing removal semantics.
- Rollback path: revert the commits; no deployment manifest schema
change. Backup ownership uses the existing artifact record, and legacy
JSONC snapshots migrate to the selected config's canonical filename.

## Review Readiness

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

## Checklist

- [x] Existing registry/lifecycle interfaces reused; persistent-install
docs updated.
- [x] Consumer-visible regressions cover edits, original-backup
invariants, both config suffixes, three reactivation paths, and final
removal.
- [x] `CHANGELOG.md` not edited; Conventional Commit title supplied.

Remote CI results are reported by GitHub, not assumed from local tests.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-07 17:46:39 -05:00
Mansurshakh Japarov 278bbc8771 fix(wrap): warn when reused proxy ignores compression settings (#4019)
## Description

A healthy shared proxy is intentionally not restarted: doing so would
interrupt other clients. Explicit startup compression settings must not
be silently ignored when a wrapper reuses it. This implements the
issue's warning-on-reuse alternative.

Closes #3588.

## Type of Change

- [x] Bug fix
- [x] Documentation update

## Changes Made

- Expose the effective tool exclusions alongside the existing effective
minimum-token setting in `/health`.
- Warn when explicitly supplied `HEADROOM_MIN_TOKENS` or
`HEADROOM_EXCLUDE_TOOLS` differs from the running configuration.
- Compare tool names case-insensitively and include built-in exclusions
on both sides. Skip comparisons when older health responses lack the
setting or the requested integer is invalid.
- Preserve the existing mode warning and shared-proxy lifecycle.
Document startup-only configuration and the restart/separate-port
remedies.
- Query the running settings for explicit compression environment
variables even with `--no-proxy` and no explicit `HEADROOM_MODE`.

## Testing

- [x] Focused unit tests: `python -m pytest -q
tests/test_cli/test_wrap_bob.py` — **59 passed**. With current main's
dashboard-license tests: **67 passed**.
- [x] New consumer-visible warning regressions: **4 failed on unchanged
baseline**; the additional no-start/MODE-unset cases produced **2
failures before the final fix**, passing afterwards.
- [x] Changed-file Ruff and formatting checks; installed pre-commit
hooks, including `mypy headroom` and Commitlint, passed.
- [x] Manual testing performed.
- [ ] Full-tree `ruff check .`: blocked locally by EXE002 on five
unchanged OAuth2 plugin files checked out with executable filesystem
permissions (Git tracks them as 100644). No unrelated plugin files or
permissions changed.
- [ ] Separate full dev-environment `mypy headroom`: found one
`truthy-function` error in unchanged
`headroom/integrations/langchain/chat_model.py:394`. The file is
byte-identical to baseline (SHA256
`701a9fe8457907406a2b2810211c1534bc9dfcacf3d841ec4c27d56897209bc7`); the
project's isolated pre-commit mypy environment passed.

The mandatory pre-push `make ci-precheck` completed: workspace Rust
fmt/clippy/tests, native extension build/import verification, Python
gate **177 passed / 4 skipped**, and Commitlint all passed. The native
model gate used `ORT_DYLIB_PATH` pointing to the installed CPU
`libonnxruntime.so.1.26.0`; the cached Kompress parity suite matched
**21 fixtures byte-for-byte**. Implicit runtime selection did not finish
and was cancelled, not reported as a pass; explicit CPU runtime
qualification completed without skipping the cached-model assertions.

### Test Output

```text
[build_rust_extension] headroom._core build + install + verify: OK
================== 177 passed, 4 skipped, 1 warning in 7.29s ===================
✅ ci-precheck PASSED — safe to push.
```

## Real Behavior Proof

- Environment: Linux x86_64, CPython 3.13.14; original baseline
`dea9092e19385f286b7f67a64f4d85de2708d756` and final fix rebased onto
current main `1ad92f0cbc3dea27676e253588100f64a2af6994`; real CLI proxy
and real health endpoint.
- Exact command / steps: start the real proxy, then reuse it with
`HEADROOM_MODE` unset and conflicting compression settings without
starting/restarting it; commands below.
  ```sh
HEADROOM_BEACON=off HEADROOM_MIN_TOKENS=120 HEADROOM_EXCLUDE_TOOLS='' \
headroom proxy --host 127.0.0.1 --port 18795 --stateless --no-optimize \
--no-cache --no-rate-limit --no-subscription-tracking --disable-kompress
  ```
- With `HEADROOM_MODE` unset, reuse it without starting/restarting a
proxy:
  ```sh
  HEADROOM_MIN_TOKENS=2000 HEADROOM_EXCLUDE_TOOLS=Bash,Read,Grep,Glob \
python -c 'from headroom.cli.wrap import _ensure_proxy; print("RESULT",
_ensure_proxy(18795, True))'
  ```
- Before the final no-start-path fix: only `RESULT (None, 18795)`; both
explicit settings were silent. The original baseline was also silent.
- Observed result: both explicit-setting warnings appeared after the
fix; the same PID and running configuration remained unchanged. Output:
  ```text
Warning: this session requested HEADROOM_MIN_TOKENS=2000 (running: 120);
HEADROOM_EXCLUDE_TOOLS=['bash', 'glob', 'grep', 'read'] (running: []),
but those settings are fixed at proxy startup. Restart the proxy, or use
--port for a separate one.
  RESULT (None, 18795)
{"proxy_pid_before": 1231619, "proxy_pid_after": 1231619, "min_tokens":
120, "exclude_tools": [], "no_proxy": true, "explicit_mode": null}
  ```
- Not tested: an external interactive agent session or paid upstream
model request. The actual proxy process, health response, and wrapper
reuse path were exercised.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; diagnostic-only wrapper fix.
- Minimum rollout channel: stable; no rollout-managed feature is
enabled.
- Stable/default behavior changed: a warning only when explicit settings
conflict with the running proxy; no configuration mutation or forced
restart.
- Kill switch / disable path: remove the conflicting explicit
environment setting, or revert the commit; no new switch.
- Unsafe override required: no.
- Qualification impact: wrapper diagnostics only; no model/compression
rollout change.
- Rollback path: revert this commit; the extra health field is additive.

## Review Readiness

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

## Checklist

- [x] Existing conventions reused; documentation updated.
- [x] Regression tests cover mismatches, matching settings, built-in
exclusions, missing fields, and invalid integers.
- [x] `CHANGELOG.md` not edited; Conventional Commit title supplied for
release-please.

The intentional warning is the requested behavior, not a new unsolicited
runtime warning. Full remote CI results will be reported by GitHub, not
inferred from local checks.
2026-10-07 14:17:35 -05:00
APandJerrettDavis cd4367b040 feat(antigravity): add native Google Antigravity IDE integration (#3817)
## Description

Native Google Antigravity IDE integration for Headroom. Antigravity
reads its
model endpoints from its own model-provider settings (not env vars), so
this
follows the existing proxy-only `wrap` pattern: start the Headroom proxy
and
print the custom OpenAI-compatible provider settings to add in the IDE.
A new
MCP registrar installs Headroom into Antigravity's global
`mcp_config.json`.

Closes #727

## Type of Change

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

## Changes Made

- `headroom wrap antigravity` — starts the proxy and prints the custom
OpenAI-compatible model-provider settings for Antigravity (same
proxy-only
pattern as `wrap cursor`; per-project `/p/<name>` base-URL prefixes for
  dashboard attribution).
- `headroom mcp install --agent antigravity` — new
`AntigravityRegistrar` for
the global `mcp_config.json` under `~/.gemini/`. Prefers an
already-existing
config location, refuses to overwrite unparseable JSON, clears
Antigravity's
  per-surface MCP cache dirs on uninstall.
- Registers the `antigravity` slice in the persistent install env
registry.
- Docs: `proxy.mdx` gains an Antigravity IDE section covering `wrap`,
  `mcp install`, and the existing `/v1internal:streamGenerateContent`
Cloud Code compatibility endpoint for native google-antigravity clients.

## 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
$ pytest tests/test_cli/test_wrap_antigravity.py \
         tests/test_mcp_registry/test_antigravity_registrar.py \
         tests/test_provider_antigravity.py
34 passed, 1 warning in 0.75s
(the warning is a pre-existing `asyncio_mode` config notice, unrelated)

$ ruff check <changed files>
All checks passed!

$ ruff format --check <changed files>
7 files already formatted
```

## Real Behavior Proof

- Environment: Linux, Python 3.12, branch
`fix/727-antigravity-integration`
- Exact command / steps: `wrap --help` (lists `antigravity`, exit 0);
`wrap antigravity --help` (prints the Antigravity IDE setup instructions
for the custom OpenAI-compatible model-provider flow); `wrap antigravity
--prepare-only` (exit 0).
- Observed result: the new command is wired into the CLI and its help
text
  documents the custom-provider setup flow.
- Not tested: end-to-end `mcp install` against a real Antigravity IDE
(the MCP
SDK extra is not installed in this environment; registrar behavior is
covered
by its unit tests); live proxy traffic from an actual Antigravity
client.

## Runtime Rollout Safety

- Rollout-managed feature(s): none (new additive commands only)
- Minimum rollout channel: n/a
- Stable/default behavior changed: no — existing `wrap` / `mcp install`
  flows are untouched
- Kill switch / disable path: do not run the new commands;
`headroom mcp uninstall --agent antigravity` removes the MCP
registration
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the single 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] 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

## Additional Notes

- `mypy` was not run (not installed in this environment); `ruff check`
and
  `ruff format` are clean on all changed files.
- Antigravity reads endpoints from its model-provider settings, not env
vars,
so `wrap antigravity` prints setup instructions instead of launching the
IDE.

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

---

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

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-07 13:33:59 -05:00
Ayush Kumar JhaandJerrett Davis 0d7d61d5cc fix(wrap): let wrap opencode target a third-party OpenAI-compatible upstream (#3125)
## Description

`headroom wrap opencode` had no way to say where OpenAI-compatible
traffic should go. `opencode()` forwarded `openai_api_url` to
`_ensure_proxy` only for `--copilot-subscription`; every other run
inherited the proxy default, `https://api.openai.com/v1`. A user
following the README's agent-wrap table with a DeepSeek key therefore
had that key presented to OpenAI, which rejected it with `401 Incorrect
API key provided` and pointed them at a `platform.openai.com` dashboard
for a key they never had. Meanwhile
`docs/content/docs/opencode-deepseek.mdx` said "Do not use `headroom
wrap`", with nothing reconciling the two.

This adds the missing plumbing (`--openai-api-url` /
`OPENAI_TARGET_API_URL`, mirroring `headroom proxy`) and the
documentation the issue asked for.

Closes #3107

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

- `headroom/cli/wrap.py`: `wrap opencode` gains `--openai-api-url`, with
`envvar="OPENAI_TARGET_API_URL"`, mirroring `headroom proxy
--openai-api-url`. It is passed to `_ensure_proxy`, which already knows
how to start the proxy with it and how to report a mismatch against an
already-running proxy.
- `headroom/cli/wrap.py`: combining `--openai-api-url` with
`--copilot-subscription` raises a `ClickException` before anything is
mutated — the subscription resolves its own upstream, so a manual
override would silently fight it.
- `headroom/cli/wrap.py`: the `opencode` docstring documents the default
upstream and both invocation forms.
- `headroom/cli/wrap.py`: `--no-proxy` combined with an upstream
override now fails closed (review). New
`_require_no_proxy_openai_upstream(port, url)` requires a healthy
Headroom listener whose `/health` config advertises the same
`openai_api_url` after `_normalize_proxy_api_url`; an absent listener, a
listener with no Headroom config, or a mismatched upstream each raise a
`ClickException` that names the exact `headroom proxy --port N
--openai-api-url URL` command to run. The check is opted into via a new
`require_openai_api_url` keyword on `_ensure_proxy_unlocked`, set only
by `wrap opencode`, so wrappers that pass a built-in upstream (`vibe`,
`kimi`, `grok`, `zcode`) keep their existing warn-and-reuse `--no-proxy`
behaviour. On a match wrap prints `Proxy on port N already targets URL`,
warns about a proxy-mode mismatch like the other reuse paths, and
continues. `wrap opencode` runs this check before it touches OpenCode's
config or registers a client marker, so a refused upstream leaves
nothing behind. `--prepare-only` skips it, since it never uses a proxy.
- `headroom/providers/opencode/config.py`:
`inject_opencode_provider_config(port, keep_user_entries=...)` keeps the
user's own `models` and `options` (an `apiKey`, say) under
`provider.headroom` instead of replacing the entry; Headroom still owns
`npm`, `name` and `baseURL`. `wrap opencode` passes `keep_user_entries`
only when `--openai-api-url` (or `OPENAI_TARGET_API_URL`) is set.
Without it the proxy forwards to OpenAI, so a kept third-party key would
be sent there, and wrap writes Headroom's entry as before. OpenCode only
resolves `headroom/<id>` for listed ids, so without this a DeepSeek user
had no DeepSeek model to select (`ProviderModelNotFoundError`) and no
key to send.
- `docs/content/docs/opencode.mdx`: `--openai-api-url` documented on the
canonical OpenCode page (Options block, prose, env-var table), with a
two-form example — wrap starts the proxy, or `headroom proxy
--openai-api-url …` then `wrap --no-proxy --openai-api-url …` — and a
paragraph stating that `--no-proxy` verifies and refuses rather than
re-points.
- `docs/content/docs/opencode-deepseek.mdx`: new "Common issues" entry
for the `Incorrect API key provided` 401 (it comes from OpenAI, not
DeepSeek) and a "When is `headroom wrap opencode` safe?" section — safe
as-is for the default OpenAI/Anthropic upstreams, needs
`--openai-api-url` for any third-party OpenAI-compatible provider, and
that wrap keeps the step 4 `models` and `apiKey` under
`provider.headroom` (DeepSeek needs both). The "Models appear but
requests fail" entry and the "What's NOT in this guide" bullet are
reworded to match, replacing the blanket "do not use `headroom wrap`".
- `README.md`: footnote on the OpenCode row of the agent compatibility
matrix naming the default upstream and the flag/env var.
- `tests/test_cli/test_wrap_opencode.py`: ten tests — the flag, the env
var, the unset default, the `--copilot-subscription` rejection; for
`--no-proxy`: absent, non-Headroom, matching (trailing slash, proving
normalization), and mismatched listeners; that wrappers without
`require_openai_api_url` keep lenient reuse; and that the CLI forwards
the flag. With the fix reverted, 5 of the 6 new tests fail. Review
follow-ups add: `wrap opencode --help` keeps its examples unwrapped and
`wrap.py` has no raw control bytes; a refused `--no-proxy` upstream
exits before any OpenCode config edit or client marker; the
matching-upstream path still warns about a mode mismatch.
- `tests/test_providers_opencode_config.py`: with `keep_user_entries`
the user's `headroom` models and `apiKey` survive re-injection, other
providers are untouched, and Headroom's `npm`/`baseURL` win; without it
they are dropped.
- `tests/test_cli/test_wrap_opencode.py` (second round): through the CLI
the key is kept with `--openai-api-url` and dropped without it, and
`--prepare-only --no-proxy --openai-api-url` writes config with no proxy
listening.

## Testing

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

Four failures in the wider `tests/test_cli` run are pre-existing and
Windows-only — they reproduce identically with this branch's changes
stashed: symlink/settings-path issues in `test_recover_codex.py` and
`test_unwrap_claude.py`, and `signal.SIGHUP` (absent on Windows) in
`test_wrap_stale_marker.py`. They are deselected below.
`tests/test_cli_proxy_improvements.py` and
`tests/test_memory/test_learn_flag.py` cannot run from this source
checkout because the Rust `headroom._core` extension is not built here
(same result on the clean branch); CI builds the wheel.

### Test Output

```text
$ python -m pytest tests/test_cli/test_wrap_opencode.py -q
50 passed, 1 warning in 1.96s

$ python -m pytest tests/test_cli -q     --deselect tests/test_cli/test_recover_codex.py     --deselect tests/test_cli/test_unwrap_claude.py     --deselect "tests/test_cli/test_wrap_stale_marker.py::test_signal_handler_unwinds_so_the_restore_can_run"
706 passed, 1 skipped, 46 deselected, 1 warning in 60.41s

$ git stash push -- headroom/cli/wrap.py && python -m pytest tests/test_cli/test_wrap_opencode.py -q -k no_proxy
5 failed, 2 passed   # the new tests fail without the fix; the 2 passing pin unchanged behaviour

$ python -m ruff check .
All checks passed!

$ python -m ruff format --check .
1577 files already formatted

$ python -m mypy headroom
Success: no issues found in 532 source files

$ python -m coverage run --include=headroom/cli/wrap.py -m pytest tests/test_cli/test_wrap_opencode.py -q
50 passed   # 17/17 statements added to wrap.py executed, 0 missing
# Review follow-ups (this branch, with current main merged in)
$ pytest tests/test_cli/test_wrap_opencode.py tests/test_providers_opencode_config.py
102 passed, 1 failed  # test_build_launch_env_with_project: a known Windows-only path-escaping failure, also on main
# each new test fails on the code before its fix:
test_inject_provider_config_keeps_the_users_models_and_options -> KeyError: 'apiKey'
test_no_proxy_with_openai_api_url_still_warns_about_a_mode_mismatch -> warning missing from output
test_wrap_opencode_no_proxy_rejects_a_mismatched_upstream_before_editing_config -> "MCP retrieve tool: registered", then _ensure_proxy reached
test_wrap_opencode_keeps_the_users_headroom_key_only_for_an_explicit_upstream[no flag] -> key kept (would go to OpenAI)
test_wrap_opencode_prepare_only_does_not_need_the_no_proxy_listener -> "No Headroom proxy is listening on port 9000"
# help test: dropping either no-rewrap marker, or writing a raw 0x08 byte, fails a test (3/3)
$ ruff check / ruff format --check (0.16.8): clean
$ mypy headroom/cli/wrap.py headroom/providers/opencode/config.py --ignore-missing-imports --follow-imports=silent
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.11.9, headroom 0.35.0 (`rust_core:
loaded`), with a stub `opencode` on `PATH` that curls the proxy's
`/health` — so the wrapped agent reports the upstream the proxy actually
resolved.
- Exact command / steps: (1) baseline against released 0.35.0 without
this fix on `sys.path` — `python -m headroom.cli wrap opencode --port
8799 --no-mcp --no-serena --openai-api-url https://api.deepseek.com/v1`;
(2) same command on this branch, port 8801; (3) env-var form on this
branch — `OPENAI_TARGET_API_URL=https://api.deepseek.com/v1 python -m
headroom.cli wrap opencode --port 8802 --no-mcp --no-serena`. For the
`--no-proxy` review: `python -m headroom.cli wrap opencode --port <P>
--no-proxy --no-mcp --no-serena --openai-api-url
https://api.deepseek.com/v1` on this branch against (4) nothing on 8811;
(5) `python -m http.server 8812`; (6) a real released-0.35.0 `headroom
proxy --port 8813` (default upstream, `/health` reports
`"openai_api_url": null`); (7) a real `headroom proxy --port 8814
--openai-api-url https://api.deepseek.com/v1`.
- Observed result: step 1 reproduces the bug exactly — wrap prints
`Extra args: --openai-api-url https://api.deepseek.com/v1` (the flag is
swallowed by `ignore_unknown_options` and handed to the agent) and the
proxy it started reports `"openai_api_url": null`, i.e. it would forward
to `api.openai.com`. Step 2 prints no `Extra args` line and the proxy
reports `"openai_api_url": "https://api.deepseek.com/v1"`. Step 3
reports the same. All three runs cleaned up their proxy on exit — no
listener left on 8799/8801/8802. Steps 4–6 each exit 1 before `opencode`
is launched, with: (4) `No Headroom proxy is listening on port 8811 …
Start it separately with `headroom proxy --port 8811 --openai-api-url
https://api.deepseek.com/v1`, or drop --no-proxy …`; (5) `The listener
on port 8812 did not report a Headroom config, so wrap cannot confirm it
forwards to https://api.deepseek.com/v1 …`; (6) `The Headroom proxy on
port 8813 forwards OpenAI-compatible traffic to
https://api.openai.com/v1, not https://api.deepseek.com/v1. Restart it
with …` — and the 8813 proxy is left running, still reporting `null`.
Step 7 prints `Proxy on port 8814 already targets
https://api.deepseek.com/v1` and launches the stub (exit 0). Both
proxies were stopped afterwards; 8811–8814 verified free.
- Real OpenCode (review follow-up): OpenCode 1.18.34 installed from npm
into a scratch directory with an isolated `HOME`, and a local fake
OpenAI-compatible "DeepSeek" upstream on 8792 that records each
request's model and `Authorization` header. The global `opencode.json`
declares `provider.headroom.models.deepseek-chat` and `options.apiKey:
"{env:DEEPSEEK_API_KEY}"`. Command: `headroom wrap opencode --port 8796
--openai-api-url http://127.0.0.1:8792/v1 --no-mcp --no-serena -- run
"say hi" -m headroom/deepseek-chat`.
- before this commit: `ProviderModelNotFoundError: Model not found:
headroom/deepseek-chat.` Nothing reached the upstream, and the config
after wrap held only `gpt-4o` and `gpt-4.1` under `headroom`, with no
`apiKey`.
- after (re-run on the final head e8754b61): OpenCode printed `> build ·
deepseek-chat` and `hello from fake deepseek`. The upstream logged
`{"path": "/v1/chat/completions", "model": "deepseek-chat", "auth":
"Bearer sk-fa...", "stream": true}`. The config kept `apiKey` and
`deepseek-chat` alongside Headroom's `baseURL` and defaults.
- Not tested: a live request against `api.deepseek.com` with a real key,
since none is available here. The real-OpenCode run above uses a local
fake upstream instead, so it proves model selection, key forwarding and
routing through Headroom but not DeepSeek's own API. The
`--copilot-subscription` rejection was exercised as a unit test, not
against a real Copilot subscription.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — a CLI option and its plumbing, not
gated by the rollout-channel machinery.
- Minimum rollout channel: n/a, not rollout-gated.
- Stable/default behavior changed: no — without the flag and without
`OPENAI_TARGET_API_URL`, `openai_api_url` stays `None` and the proxy
resolves its upstream exactly as before; a test pins this.
- Kill switch / disable path: omit the flag and leave
`OPENAI_TARGET_API_URL` unset — behavior is identical to the previous
default.
- Unsafe override required: no.
- Qualification impact: none — no change to compression, routing, or the
proxy request path; the option only chooses which upstream URL the proxy
is started with.
- Rollback path: revert this commit — no config, cache, or on-disk state
is written by the new option, so a revert needs no cleanup.

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

n/a — CLI and docs change.

## Additional Notes

- The `x-headroom-base-url` header workaround from the issue is
deliberately left out of the DeepSeek guide. With `--openai-api-url` the
proxy targets the right upstream directly, so the header is no longer
needed for this case. It stays documented where it belongs, in
`configuration.mdx` and `pipeline-extensions.mdx`, as a per-request
override.
- Scope is intentionally limited to `wrap opencode`, the command named
in the issue. Other `wrap` subcommands that hardcode an upstream
(`mistral`, `kimi`, `grok`) or detect one (`zcode`) are unaffected;
giving the whole wrap family a uniform upstream override is a reasonable
follow-up, not this fix.

---------

Co-authored-by: Jerrett Davis <mxjerrett@gmail.com>
2026-10-06 08:45:54 -05:00
Sudhindra DesaiandJD Davis aba75cbf6d fix(wrap): trim the wrap claude startup banner (#3900)
## Description

Implements the three banner cleanups from #3426. Routing, tool-search
and Remote Control behavior are unchanged; this only changes what the
banner prints.

1. **`127.0.0.1:<port>` repetition.** The "Proxy ready/already running
on …" line and the `Dashboard:` line are now one line that names
host:port once: `Proxy ready — dashboard:
http://127.0.0.1:8787/dashboard`. This applies to all three
`_ensure_proxy` sites. `ANTHROPIC_BASE_URL=…` stays, since it's what the
session actually uses.
2. **Remote Control notice.** By default this is now one actionable
line. It keeps the #1779 accuracy rule: it states the disable as fact
for a detected gated version, and names the `2.1.196+` threshold when
the version is unknown. `-v` restores the full explanation and the
session-accurate #746/#1158 sibling note.
3. **On-demand tool loading line.** By default this prints `On-demand
tool loading: kept on (this session)` or `… off (this session)`. `-v`
restores `ENABLE_TOOL_SEARCH=… (…; issue #746)`. The compact "off"
wording doesn't say "per your setting", because Foundry turns deferral
off by default without any `--tool-search` flag.

Closes #3426

## Type of Change

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

## Changes Made

- `headroom/providers/claude/runtime.py`: new
`remote_control_gate_short_message(version=...)`, which follows the same
version-accuracy rule as `remote_control_gate_message`. It's exported
from `headroom.providers.claude`.
- `headroom/cli/wrap.py`: new `_proxy_status_line()` used at the three
proxy status sites. `wrap claude` prints the compact RC and tool-search
lines unless `-v`/`--verbose` is set, in which case it prints the
existing full lines unchanged.
- Tests: the existing full-wording assertions in
`test_wrap_claude_vertex_proxy_env.py` now run with `-v`. New tests
cover the compact default banner, the compact "off" line (including
Foundry's default-off), and both short-message version branches in
`test_issue_1779_remote_control_gate.py`. `doctor` still uses the full
message and is untouched.

## Testing

- [x] Unit tests pass (`pytest`), with one unrelated failure noted below
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`): not run successfully. My
local mypy stops on an unrelated numpy stub syntax error in this env
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest tests/test_cli tests/test_issue_1779_remote_control_gate.py tests/test_cli_doctor.py -q
FAILED tests/test_cli/test_wrap_sighup_proxy_leak.py::test_sighup_on_launch_tool_releases_the_proxy
1 failed, 1067 passed, 1 skipped in 21.45s
```

`test_sighup_on_launch_tool_releases_the_proxy` fails identically on
unmodified `main` in my environment (checked with the change stashed),
so it's unrelated.

## Real Behavior Proof

- Environment: macOS, Python 3.12, Claude Code 2.1.290, branch head
`f971660d`
- Exact command / steps: live launch against a real proxy (no mocks).
The proxy was started by `wrap` on a free port, and `--version` makes
the real Claude Code binary exit right after the banner:
  ```text
headroom wrap claude --port 8799 --no-mcp --code-memory none --
--version
headroom wrap claude -v --port 8799 --no-mcp --code-memory none --
--version
  ```
- Observed result: by default the banner shows one Remote Control line
and one tool-loading line, and the proxy status and dashboard share one
line. `-v` prints the previous full RC and tool-search wording
unchanged.

  Default (fresh proxy start):
  ```text
    Starting Headroom proxy on port 8799...
    Logs: ~/.headroom/logs/proxy-8799.log
    Proxy ready — dashboard: http://127.0.0.1:8799/dashboard

    Launching Claude Code (API routed through Headroom)...
    ANTHROPIC_BASE_URL=http://127.0.0.1:8799
Remote Control (/rc) is disabled while routed through Headroom — run
`claude` directly (no wrap) for sessions that need it.
    Extra args: --version
Telemetry: anonymous usage counters — never prompts, code, or file
paths. See: headroom telemetry --show | Off: HEADROOM_BEACON=off

    On-demand tool loading: kept on (this session)
  2.1.290 (Claude Code)
  ```
  With `-v` (reusing the running proxy):
  ```text
    Proxy already running — dashboard: http://127.0.0.1:8799/dashboard
    Skipping MCP retrieve tool (--no-mcp)
    Skipping Serena MCP (--code-memory none)

    Launching Claude Code (API routed through Headroom)...
    ANTHROPIC_BASE_URL=http://127.0.0.1:8799
Remote Control: Claude Code 2.1.290 disables the /remote-control (/rc)
command while ANTHROPIC_BASE_URL points at a custom endpoint (the
wrapped Claude session's ANTHROPIC_BASE_URL). Headroom cannot override
this client-side gate — run Claude without Headroom for sessions that
need Remote Control.
Same base-URL gate also affects on-demand tool loading (#746 — Headroom
keeps it on for this session) and the 1M context window (#1158 — restore
with `headroom wrap claude --1m`).
    Extra args: --version
Telemetry: anonymous usage counters — never prompts, code, or file
paths. See: headroom telemetry --show | Off: HEADROOM_BEACON=off

    ENABLE_TOOL_SEARCH=true (on-demand tool loading kept on; issue #746)
  2.1.290 (Claude Code)
  ```
- Not tested: a full interactive session. The launch exits at
`--version` once the banner prints.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: Only the banner text. No routing or
env changes.
- Kill switch / disable path: `-v` shows the previous full lines
- 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: N/A, the
docs don't quote these banner lines
- [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

In the default mode, the `--1m` hint from the sibling note now only
appears under `-v`. If maintainers want that hint visible by default, a
short `(1M context: --1m)` suffix on the tool-loading line would be a
cheap way to keep it.


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

---

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

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-06 08:36:29 -05:00
c07fad0f37 fix(wrap): set ANTHROPIC_HOST so wrap goose actually proxies Anthropic (#2619)
## Description

`headroom wrap goose` never proxied Anthropic traffic. Goose's Anthropic
provider reads `ANTHROPIC_HOST`, not `ANTHROPIC_BASE_URL`, so the
wrapper started the proxy, printed the banner, and then sent every
request straight to `api.anthropic.com` — silently, with no error and
zero compression.

`ANTHROPIC_BASE_URL` appears in no `.rs` file in the goose repo. The
provider reads `ANTHROPIC_HOST` at
[`crates/goose/src/providers/anthropic_def.rs#L38-L40`](https://github.com/block/goose/blob/main/crates/goose/src/providers/anthropic_def.rs#L38-L40)
and appends `/v1/messages` itself, so `_claude_proxy_base_url(port)` is
already the correct value.

Note the README currently advertises `headroom wrap goose -- --provider
anthropic` as an example — that is the exact invocation that bypasses
the proxy. The OpenAI path was unaffected: goose does honour
`OPENAI_BASE_URL`.

## Type of Change

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

## Changes Made

- Set `ANTHROPIC_HOST` alongside the existing vars in `wrap goose`
(`headroom/cli/wrap.py`), and show it in the launch banner.
- Extend `test_wrap_goose_sets_provider_envs` to assert the value. This
test **fails before** the change with a `KeyError`.
- Update the command docstring.

## Testing

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

### Test Output

```text
# Test A - the env vars `wrap goose` sets today (ANTHROPIC_HOST explicitly unset)
$ env -u ANTHROPIC_HOST ANTHROPIC_API_KEY=*** \
    OPENAI_BASE_URL=http://127.0.0.1:8787/v1 \
    OPENAI_API_BASE=http://127.0.0.1:8787/v1 \
    ANTHROPIC_BASE_URL=http://127.0.0.1:8787 \
    goose run --no-session -t "Reply with exactly: PONG"

● new session · anthropic claude-haiku-4-5
PONG
===== LISTENER HITS =====
(hit count:        0)

# Test B - same, plus ANTHROPIC_HOST (this change)
(hit count: 7)
2026-07-27T12:13:09.381232 HIT POST /v1/messages host=127.0.0.1:8787
2026-07-27T12:13:09.382744 HIT POST /v1/messages host=127.0.0.1:8787
2026-07-27T12:13:10.245477 HIT POST /v1/messages host=127.0.0.1:8787
...

# Test C - OpenAI path, unchanged env (confirms scope is Anthropic-only)
(hit count: 8)  POST /v1/chat/completions
```

## Real Behavior Proof

- Environment: macOS 15 arm64, goose v1.44.0 built from source, headroom
main @ e530de5, provider anthropic / claude-haiku-4-5, isolated goose
config via GOOSE_PATH_ROOT, stub HTTP listener on 127.0.0.1:8787
standing in for the proxy.
- Exact command / steps: Ran `goose run --no-session -t "Reply with
exactly: PONG"` three times against the stub listener — (A) with the env
vars `wrap goose` sets today and ANTHROPIC_HOST explicitly unset, (B)
identical but with ANTHROPIC_HOST added, (C) OpenAI provider with
unchanged env. Full commands and output in the Test Output block above.
- Observed result: A got 0 requests at the listener and goose returned a
real completion from api.anthropic.com, so the bypass is silent rather
than a failure; B got 7 requests at the listener, proving the fix; C got
8 requests on /v1/chat/completions, confirming the OpenAI path already
worked and the scope is Anthropic-only.
- Not tested: pytest, ruff and mypy were not run locally because my
corporate network blocks files.pythonhosted.org so the dev environment
will not install — those three boxes are deliberately left unchecked and
CI should be the authority on them; the new assertion mirrors the
adjacent ANTHROPIC_BASE_URL one against the same `anthropic_base` value.

## Review Readiness

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

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

- Folded the assertion into the existing env-fan-out test rather than
adding a near-duplicate, to match the file's stated organisation.
- On port fallback, `_launch_tool` rewrites the child environment
(including the new var) but not `env_vars_display`, so the printed value
can show the requested port. Pre-existing for the other displayed URLs;
not addressed here.
- Possible follow-ups, happy to file separately: `wrap aider` sets
`OPENAI_API_BASE` but not `OPENAI_BASE_URL`; and `wrap goose` does not
call `with_project_prefix()`, so goose traffic isn't attributed per
project.

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

---

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

---------

Co-authored-by: Filip Kujawa <fkujawa@squareup.com>
Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-05 15:31:00 -05:00
Ayush Kumar JhaandJD Davis 7b68fc263a fix(copilot): warn when a VS Code profile cannot see the proxy settings (#3919)
## Description

`headroom wrap vscode` writes Copilot's two endpoint overrides into the
Default profile's `settings.json` and reports success. A VS Code window
that uses a profile with its own settings reads only
`User/profiles/<id>/settings.json`, and Copilot takes these overrides
from user settings alone. In that window Copilot keeps talking to GitHub
directly: Copilot works, Headroom records nothing, and setup said it
succeeded. That is exactly what #3716 describes. The reporter hasn't
confirmed yet that they use a profile (I asked on the issue), so this
says "Refs" rather than "Closes".

After writing a VS Code user directory's `settings.json`, `wrap vscode`
now reads the profiles VS Code records in that directory's
`globalStorage/storage.json`. That file is either the Default one or one
named with `--settings-file`. For each profile that keeps its own
settings and doesn't define both overrides as live settings, it prints a
warning with the exact `--settings-file` command that routes it.

Nothing is written to profile files automatically. The docs already
scope profile-specific settings to `--settings-file`, and the block
persists and fails closed after the proxy stops. Routing every profile
silently would therefore change Copilot in profiles the user never meant
to proxy.

Refs #3716

## Type of Change

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

## Changes Made

- `headroom/providers/copilot/vscode.py`:
`unrouted_vscode_profiles(user_dir)` returns `(name, settings.json)` for
each stored profile that has its own settings
(`useDefaultFlags.settings` unset) and doesn't define both endpoint
overrides as live settings.
- It parses the profile's JSONC with `_parse_settings`, split out of
`_validate_settings` so both share one parser. As a result, a marker or
keys that exist only in comments don't count.
- It accepts only a local folder name as a location (VS Code uses
`hash(uuid).toString(16)`, which can be negative). That skips remote
URIs and rules out path traversal.
  - Missing or unexpected VS Code state produces no warning.
- `headroom/cli/wrap.py`: after writing the settings file, `wrap vscode`
prints one `Warning:` line per such profile of the user directory that
holds that file.
- A profile's own `settings.json` has no profile state beside it, so
running the printed remedy produces no warning.
- A `--settings-file` in another user directory (Insiders, VSCodium,
portable) gets that directory's profiles checked.
  - There's no warning with `--no-configure`.
- `headroom/providers/copilot/__init__.py`: exports the helper alongside
the other VS Code helpers.
- `docs/content/docs/vscode-copilot.mdx`: adds a troubleshooting entry
for "no requests while Copilot keeps working".
- `tests/test_cli/test_wrap_vscode.py`:
`test_wrap_vscode_names_profiles_that_ignore_default_settings` walks the
whole flow. It warns by default and when the Default file is named
explicitly, stays silent for a shared-settings profile, and goes silent
once the printed remedy has run.
`test_wrap_vscode_checks_the_profiles_of_the_user_dir_it_configures`
covers another user directory.
- `tests/test_provider_copilot_vscode_config.py` covers:
  - own versus shared settings
  - a negative-hash folder
  - traversal and remote locations
- profiles that override both endpoints, whether managed or hand-written
- a marker-only file, commented-out keys, a single key, and unparseable
settings
  - a missing or malformed `storage.json`

## Testing

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

### Test Output

```text
# The new tests against the code before each commit.
# main (c46e74d0), before the first commit:
E   assert "VS Code profile 'Work'" in "  VS Code Copilot proxy settings added: ...\Code\User\settings.json\n  Keep using Copilot's normal model picker; ..."
# c887cbab, before the review follow-up. --settings-file naming the Default file printed no warning:
E   assert "VS Code profile 'Work'" in "  VS Code Copilot proxy settings updated: ...\Code\User\settings.json\n  Keep using Copilot's normal model picker; ..."
# ...and a profile whose settings only mention the marker in a comment counted as routed:
old code, marker-only profile -> []  (expected Work to be listed)
old code, commented-out keys profile -> []  (expected Work to be listed)

# With both commits:
$ pytest tests/test_cli/test_wrap_vscode.py tests/test_provider_copilot_vscode_config.py
27 passed in 1.19s

# Each mutation of the fix fails at least one test:
M1 ignore useDefaultFlags.settings: KILLED (2 failed, 25 passed)
M2 marker text counts as configured: KILLED (7 failed, 20 passed)
M3 one live key is enough: KILLED (1 failed, 26 passed)
M4 reject leading '-' in location: KILLED (2 failed, 25 passed)
M5 accept any location string: KILLED (1 failed, 26 passed)
M6 drop the CLI warning: KILLED (2 failed, 25 passed)
M7 scan only without --settings-file: KILLED (2 failed, 25 passed)
M8 always scan the Default user dir: KILLED (1 failed, 26 passed)

$ ruff check <changed files> && ruff format --check <changed files>   # ruff 0.16.8
All checks passed!
5 files left unchanged
$ mypy headroom/providers/copilot/vscode.py headroom/providers/copilot/__init__.py headroom/cli/wrap.py --ignore-missing-imports --follow-imports=silent   # mypy 1.19.1
Success: no issues found in 3 source files
# On the first commit, `mypy headroom --ignore-missing-imports` reported only
# headroom\fileperms.py:71 (Windows-only os.fchmod), a file this PR does not touch.

# Every test in the subsystems this touches, this branch vs its base (d5318ac2):
$ pytest tests/test_cli tests/test_copilot*.py tests/test_provider*.py -n 8
branch: 7 failed, 1621 passed, 8 skipped (14 more tests than base: the new ones)
base:  25 failed, 1589 passed, 8 skipped
# All 7 branch failures also fail on base: symlink, signal, service-supervisor and
# opencode-env tests that fail on this Windows machine. The other 18 base failures
# are test_wrap_persistent.py tests that vary from one xdist run to the next; that
# file passes serially (62 passed on both the branch and main).
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.11.9, VS Code 1.140.0 (official zip,
isolated `--user-data-dir`), this branch
- Exact command / steps: wrote Headroom's block into an isolated VS Code
user dir. Then opened VS Code with a small probe extension that records
`getConfiguration("github.copilot").inspect(key).globalValue` for both
keys, once in the Default profile and once with `--profile=Repro` (VS
Code created the profile and recorded it in `storage.json`). Next I ran
the `wrap vscode` command against that user dir (`APPDATA` pointed at
it). Only the Copilot subscription lookup and the proxy watcher were
stubbed, because there's no Copilot account on this machine. I ran the
command the warning printed, re-probed the profile window, and ran plain
`wrap vscode` again. For the review follow-up I repeated the CLI runs
against the same VS Code-written state with the cases from the two
findings.
- Observed result: the profile window doesn't see Headroom's settings
until the warning's command is run.
- Default profile window:
`"overrideCapiUrl":{"globalValue":"http://127.0.0.1:8788/p/a11y"}`, and
the same for `overrideProxyUrl`
- `--profile=Repro` window: `{"globalValue":null}` for both, so Copilot
falls back to the endpoints from its token, i.e. GitHub directly
- `wrap vscode` printed: `Warning: VS Code profile 'Repro' keeps its own
settings, so Copilot there still bypasses Headroom. Route it with:
headroom wrap vscode --settings-file
"V:\ud1\Code\User\profiles\6c87cdb4\settings.json"`
- after running that command, the `Repro` window sees both overrides
(`"globalValue":"http://127.0.0.1:8788/p/headroom"`), and plain `wrap
vscode` no longer warns
- review follow-up: with `Repro`'s settings holding only `// ---
Headroom Copilot proxy ---`, plain `wrap vscode` warns about `Repro`.
`--settings-file` naming the Default file warns too.
- review follow-up: the printed remedy refuses that half-written file
with the existing `Error: Incomplete Headroom marker block in
...\profiles\6c87cdb4\settings.json; refusing to edit.` Once the stray
marker is removed, the remedy succeeds and plain `wrap vscode` prints no
warning.
- Not tested: real Copilot traffic, macOS and Linux, the reporter's own
setup, and a complete local run of the full suite.
- real Copilot traffic, because there's no Copilot subscription on this
machine. I separately checked that the bundled Copilot Chat 0.66.0,
0.67.0 and 0.68.0 all read both keys as user-scope-only settings, and
that a proxy built from `main` logs both Copilot paths at INFO.
- macOS and Linux. VS Code uses the same `User/profiles` layout there,
and the unit tests cover the logic.
  - the reporter's own setup.
- the full test suite. A local run stalled at 97% and was killed after
40 minutes on this Windows machine, so I compared the touched subsystems
against the base instead; CI runs the full suite.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: `wrap vscode` prints one extra
warning line for each VS Code profile that keeps its own settings and
doesn't define both overrides. No file it writes changes.
- Kill switch / disable path: none needed. The warning is informational,
and pointing `--settings-file` at a file outside a VS Code user
directory skips the scan.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR; no persisted state or format 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
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

- The second commit addresses both Devin Review findings: a commented
marker hid an unrouted profile, and an explicit Default path skipped the
scan.
- For the second finding I scan the user directory of the file being
configured rather than comparing against `vscode_settings_path()`. That
covers the explicit Default path, and it also checks profiles for
Insiders, VSCodium or portable user directories. It also avoids
resolving `APPDATA` when `--settings-file` is given.
- Question for maintainers: would you rather `wrap vscode` write the
block into every profile with its own settings, and `unwrap vscode`
remove it from all of them? It would be a small change on top of this
helper. I left it out because it changes which windows fail closed while
the proxy is down.
- `unwrap vscode` still cleans only the file it's given. A profile
configured with `--settings-file` needs the same flag to undo it, as the
docs already say.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-05 10:03:08 -05:00
natoriandJD Davis 1b7977cecd fix: honor configured port in container startup and healthcheck (#2436)
## Description

Deploying on a non-default port produced a working proxy that the
surrounding
tooling reported as broken. Tracing the probe turned up a second defect
upstream of it: the container could not change its port via
`HEADROOM_PORT`
at all.

`headroom proxy --port` is a click option with `envvar="HEADROOM_PORT"`,
and an
explicit CLI argument beats the envvar. The Dockerfile baked `--port
8787` into
CMD, so `HEADROOM_PORT` was inert for a plain `docker run` — while
`docker-compose.yml` already passes `command: ["--host", "0.0.0.0"]`
with no
port, which is the intended shape. The Dockerfile was the outlier.

The two halves have to move together. An earlier revision of this change
fixed
only the HEALTHCHECK; that made the probe follow `HEADROOM_PORT` while
the
listener stayed pinned to 8787, and the container went from misleadingly
healthy to genuinely unhealthy. Evidence in Real Behavior Proof below.

Closes #2432

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

- `Dockerfile`, both runtime stages: dropped the baked `--port` from CMD
so
`HEADROOM_PORT` stays authoritative. `docker run` with no env still
binds
  8787 (click's default), so the published default is unchanged.
- `Dockerfile` (`runtime-slim-base`): shell-form HEALTHCHECK so
  `${HEADROOM_PORT:-8787}` expands at probe time.
- `Dockerfile` (`runtime-slim`): distroless, no shell — the port is
resolved
  inside Python instead, keeping exec form.
- `headroom/cli/doctor.py`: added `resolve_probe_port()`. `--port` /
`HEADROOM_PORT` wins, then an unambiguous deployment manifest (`default`
profile, or a lone named profile), then 8787. `headroom deploy --port N`
writes N into the deployment's environment, not into the shell `doctor`
runs
in, which is why the manifest tier is needed; with several named
profiles and
  no explicit request there is no non-arbitrary pick, so it stays on the
  default and the existing per-deployment section reports each one.
  `list_manifests()` is now read once and shared with that check.

## Testing

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

### Test Output

Full suite, run inside this repo's own builder image so the
maturin-compiled
Rust core is the one under test:

```text
9 failed, 9248 passed, 853 skipped, 2230 warnings in 384.56s (0:06:24)
```

All 9 failures reproduce unchanged on `origin/main` (c400f908) in the
same
container. Restricted to just those files, base and branch are
identical:

```text
origin/main c400f908: 13 failed, 119 passed, 15 skipped, 66 warnings in 14.57s
this branch:          13 failed, 119 passed, 15 skipped, 66 warnings in 14.58s
```

They are `test_cli/test_wrap_helpers.py`, `test_image_compression.py`,
`test_memory_bridge.py`, `test_proxy/test_cc_switch_reconciler.py` and
`test_startup_log_noise.py`. Counts differ between the full and
file-scoped
runs because `test_memory_bridge` and `test_startup_log_noise` are
order-dependent — also true on the base.

```text
$ mypy headroom --ignore-missing-imports
pyproject.toml: note: unused section(s): module = ['mlx.*']
Success: no issues found in 505 source files
```

New and changed tests, green on this branch:

```text
tests/test_docker_healthcheck_port.py ......                   [100%]
6 passed in 0.15s

tests/test_cli_doctor.py .............................         [100%]
67 passed in 0.68s
```

Both go red with only the tests applied on top of `origin/main`:

```text
FAILED tests/test_docker_healthcheck_port.py::test_no_healthcheck_hardcodes_the_default_port
FAILED tests/test_docker_healthcheck_port.py::test_every_healthcheck_resolves_the_port_from_the_environment
FAILED tests/test_docker_healthcheck_port.py::test_distroless_stage_healthcheck_stays_shell_free
FAILED tests/test_docker_healthcheck_port.py::test_debian_stage_healthcheck_expands_the_port_variable
FAILED tests/test_docker_healthcheck_port.py::test_no_stage_bakes_a_port_into_cmd
5 failed, 1 passed in 0.23s

tests/test_cli_doctor.py:
E   ImportError: cannot import name 'DEFAULT_PROXY_PORT' from 'headroom.cli.doctor'
```

## Real Behavior Proof

- Environment: macOS 15 (Darwin 25.3.0) arm64, Docker 29.1.3, image
built from this branch with `docker build -t headroom:pr2432 .`; control
is the published `ghcr.io/headroomlabs-ai/headroom:latest`.
- Exact command / steps: started three containers — the patched image
with `HEADROOM_PORT=8789`, the patched image with no env at all, and the
published image with `HEADROOM_PORT=8790` as a control — then read
`docker ps` health and probed `/readyz` from inside each. Full commands
below.
- Observed result: the patched image binds 8789 and its probe follows,
reporting healthy; with no env it still binds 8787, so the published
default is unchanged; the published image ignores `HEADROOM_PORT`
entirely and stays on 8787. Output below.
- Not tested: `headroom deploy` was not driven end to end — the manifest
was written directly rather than produced by the deploy command, so the
manifest *contents* are assumed to match what deploy records (`port` is
the field `headroom install status` already reads). Non-Docker
supervisors were not exercised.

### Containers

```bash
docker run -d --name hr-fixed   -e HEADROOM_PORT=8789 -p 8789:8789 headroom:pr2432
docker run -d --name hr-default                       -p 8791:8787 headroom:pr2432
docker run -d --name hr-control -e HEADROOM_PORT=8790 -p 8790:8790 \
    ghcr.io/headroomlabs-ai/headroom:latest
```

```text
NAMES        STATUS
hr-fixed     Up (healthy)   HEADROOM_PORT=8789 -> listener on 8789
hr-default   Up (healthy)   no env             -> listener on 8787
hr-control   Up (healthy)   HEADROOM_PORT=8790 -> listener on 8787
```

Probing from inside each container confirms which port is actually
serving:

```text
hr-fixed:   8789=OK
hr-default: 8787=OK
hr-control: 8787=OK
```

`hr-control` is the published image ignoring `HEADROOM_PORT` entirely —
the CMD
half of the bug. Baked image config, before and after:

```text
published: ["CMD","curl","--fail","--silent","http://127.0.0.1:8787/readyz"]
this PR:   ["CMD-SHELL","curl --fail --silent \"http://127.0.0.1:${HEADROOM_PORT:-8787}/readyz\""]
```

The distroless stage was verified the same way — `docker build --target
runtime-slim` with `-e HEADROOM_PORT=8795` reports healthy and answers
`GET /readyz` with 200 from the host.

### doctor

Running the real CLI against a seeded `default` deployment manifest
recording
port 8789, with `HEADROOM_PORT` unset in the shell — the reported
situation,
where the port lives in the deployment rather than in the shell:

```text
origin/main c400f908: doctor probed port: 8787
this branch:          doctor probed port: 8789
```

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A — no UI surface.

## Additional Notes

"I have made corresponding changes to the documentation" is checked in
the sense
that the `--port` help text now describes the new resolution order; no
prose
docs referenced the baked CMD port. `README.md` and the wiki reference
`headroom proxy --port 8787` as a host command, which is unaffected.

`docker/differential-network-capture/docker-compose.yml` passes `--port
8787`
explicitly in its own `command:`, which still overrides everything and
keeps
working.

Adjacent, deliberately not in this PR: `docker-compose.yml`'s
healthcheck is
hardcoded to 8787 the same way. It is inert today because that file
never sets
`HEADROOM_PORT`, and making it configurable also means parameterising
the
published `ports:` mapping — a separate change. Happy to open a
follow-up if
you want it.

## Runtime Rollout Safety

- Rollout-managed feature(s): Docker runtime port selection and
`headroom doctor` probe-port resolution.
- Minimum rollout channel: Standard Docker image release and persistent
Docker deployments.
- Stable/default behavior changed: No. Unset `HEADROOM_PORT` continues
to use port 8787.
- Kill switch / disable path: No new feature flag; revert the image or
this PR.
- Unsafe override required: No.
- Qualification impact: None. No data or schema migration; existing
port-8787 deployments remain compatible.
- Rollback path: Redeploy the previous image or revert this PR; no
migration cleanup is required.

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

---

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

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-05 08:36:54 -05:00
Rod BoevandJD Davis 44db755ee6 fix(install): replace the launchd wrapper with the proxy listener (#3224)
## Description

The persistent service path can leave a wrapper, listener, native
supervisor, or Docker container with conflicting ownership. Rebuild
runtime ownership so launchd directly owns Python, Docker owns Docker
across service/task presets, status and stop require deployment
identity, readiness cannot be health-only, and failed cleanup preserves
rollback state. Closes #3208

## Type of Change

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

## Changes Made

- Make the launchd-owned Python service exec the listener in place.
- Classify Docker ownership from both runtime and preset, with no
competing native supervisor.
- Route Docker service/task start, restart, recovery, and teardown
through the Docker owner.
- Verify exact process command, port, deployment profile, and runtime
before status or stop.
- Add POSIX, macOS, and Windows process identity fallbacks without
requiring psutil.
- Require identity on readiness and fail closed when cleanup cannot
prove the new owner stopped.
- Persist an inactive previous-deployment snapshot, keep active state
durable before owner start, and make environment/provider mutation
activation transactional.
- Surface cleanup, persistence, supervisor, Docker, and
recovery-snapshot deletion failures with actionable recovery guidance.

## Testing

- [x] Unit tests pass (`uv run --locked pytest
tests/test_provider_package_init.py::test_install_registry_apply_provider_scope_mutations_skips_missing_and_none
tests/test_install/test_providers.py tests/test_cli/test_install_cli.py
tests/test_install/test_runtime.py
tests/test_install/test_supervisors.py tests/test_install/test_paths.py
tests/test_install/test_state.py -q`)
- [x] Linting passes (`uv run --locked ruff check` on changed install,
provider, supervisor, and focused test files)
- [x] Type checking passes (`uv run --locked mypy headroom
--ignore-missing-imports`)
- [x] New tests added for the regression
- [ ] Manual testing performed through live process/supervisor
environments

### Test Output

```text
uv run --locked pytest tests/test_provider_package_init.py::test_install_registry_apply_provider_scope_mutations_skips_missing_and_none tests/test_install/test_providers.py tests/test_cli/test_install_cli.py tests/test_install/test_runtime.py tests/test_install/test_supervisors.py tests/test_install/test_paths.py tests/test_install/test_state.py -q
============================= 197 passed in 1.07s =============================
uv run --locked ruff check .
All checks passed!
uv run --locked ruff format --check .
1534 files already formatted
uv run --locked mypy headroom --ignore-missing-imports
Success: no issues found in 527 source files
git diff --check
passed; the only worktree change is the pre-existing unstaged uv.lock line-ending change
```

## Real Behavior Proof

- Environment: Windows focused process and supervisor tests, with
platform-specific launchd and Docker owner paths represented by fakes.
- Exact command / steps: run the focused lifecycle and state suite
listed above, targeted Ruff and format checks, and the full-head mypy
check.
- Observed result: each persistent mode has one owner; mismatched,
malformed, or unavailable identity cannot authorize cleanup; active
state is durable before owner start; failed cleanup retains recovery
state; mutation rollback preserves unreverted records.
- Not tested: owner-level POSIX exec, a live macOS launchd job, and a
Docker daemon

## Runtime Rollout Safety

- Rollout-managed feature(s): None. This changes the default persistent
install and recovery ownership paths.
- Minimum rollout channel: Stable, after platform-specific CI and
maintainer review.
- Stable/default behavior changed: Yes. Persistent Python service
ownership and Docker supervisor routing change.
- Kill switch / disable path: `headroom uninstall` removes the managed
deployment; users can reinstall with another supported preset or
runtime.
- Unsafe override required: No.
- Qualification impact: launchd, Docker, and Windows identity paths
require their platform-owned environments; local proof uses focused
tests and process/supervisor fakes.
- Rollback path: Revert the rollback-ordering commits in this PR, then
reinstall the prior deployment if needed. Uncertain cleanup retains the
active new manifest and inactive previous snapshot until the new owner
is removed and recovery is completed.

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

## Additional Notes

The changelog is generated by the release pipeline. Live launchd and
Docker-owner behavior remains platform-owned proof; local tests do not
claim those owner environments. Final implementation head: `4004e4a5`.

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

---

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

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-05 08:34:42 -05:00
宇宙的山峰andUniversePeak 6df4a963ae fix(codex): preserve remote compaction in init config (#3410)
## Description

Closes #3407.

`headroom init codex` writes a custom provider named `Headroom init
proxy`. Codex 0.152.1 derives remote-compaction capability from the
provider display name, so this configuration routes ordinary Responses
traffic through Headroom but silently falls back to local compaction.

## Type of Change

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

## Changes Made

- Keep the `headroom` provider id and loopback URLs unchanged for
routing.
- Emit the built-in `OpenAI` provider display name so Codex retains its
remote-compaction capability detection.
- Add a regression assertion covering the generated Codex configuration.

## Testing

- [x] Focused unit tests pass (`tests/test_cli/test_init_cli.py`)
- [x] Focused linting passes (`ruff check`)
- [x] Focused formatting passes (`ruff format --check`)
- [x] New regression coverage added
- [ ] Full test suite
- [ ] Live Codex 0.152.1 compaction run

### Test Output

```text
PYTHONPATH=. python -m pytest tests/test_cli/test_init_cli.py -q
73 passed in 22.15s

ruff check headroom/cli/init.py tests/test_cli/test_init_cli.py
All checks passed!

ruff format --check headroom/cli/init.py tests/test_cli/test_init_cli.py
2 files already formatted
```

The repository's documented `uv run --frozen --extra dev` setup was also
attempted, but dependency resolution stopped while building
`hnswlib==0.8.0`: its build environment raised `AttributeError: module
'pkgutil' has no attribute 'ImpImporter'`. The focused tests and checks
ran successfully with the already-installed Python 3.11 environment.

## Real Behavior Proof

- Environment: Windows 10, Python 3.11.9, generated temporary Codex
configuration.
- Exact command / steps: invoked `_ensure_codex_provider` against a
temporary config with port `8787`, parsed the result with Python
`tomllib`, and checked the provider id, display name, and loopback base
URL.
- Observed result: the generated `[model_providers.headroom]` section
contains `name = "OpenAI"`, `base_url = "http://127.0.0.1:8787/v1"`, and
`supports_websockets = true`; the root `model_provider` remains
`headroom`.
- Not tested: a live Codex 0.152.1 session against
`/v1/responses/compact`, because Codex 0.152.1 is not installed in this
environment.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Stable; this only changes the generated
display name for new or regenerated init configurations.
- Stable/default behavior changed: Codex-initialized Headroom
configurations now advertise the OpenAI-compatible capability name
expected by Codex while preserving the existing Headroom routing id and
URLs.
- Kill switch / disable path: Run `headroom unwrap codex` or revert the
generated config.
- Unsafe override required: No.
- Qualification impact: Existing generated configs need to be
regenerated with `headroom init codex` to receive the corrected name.
- Rollback path: Revert this commit.

## Review Readiness

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

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective
- [x] Focused unit tests pass locally
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

The provider remains registered as `headroom`; only its display name
changes. This preserves Headroom's proxy URLs, WebSocket setting, and
conditional `requires_openai_auth` behavior for both ChatGPT OAuth and
API-key users.

---------

Co-authored-by: UniversePeak <UniversePeak@users.noreply.github.com>
2026-10-05 08:33:36 -05:00
0b7dab47c6 feat(wrap): add headroom wrap bob for IBM Bob CLI (#3801)
## Description

Adds `headroom wrap bob` for the IBM Bob CLI as a wrap-registry target.
`BOB_GATEWAY_URL` points Bob at the proxy, and the proxy forwards to
`https://api.us-east.bob.ibm.com/inference/v1`. Bob's own
`Authorization: apikey …` credential and `~/.bob/settings` are left
untouched.

**Stacked on #3800.** Until that merges, this diff also contains its
commit. The Bob change is the last commit only (`feat(wrap): add
headroom wrap bob …`).

Bob's gateway needs three proxy seams, each declared on the target:

- **`extra_chat_routes`**: Bob posts to
`/inference/v1/chat/completions`. Without a real route that matches only
the catch-all and is forwarded **uncompressed**.
- **`origin_passthrough_prefixes`** (`/inference/`, `/admin/`, `/rag/`,
`/metrics-forwarder/`): Bob builds these paths itself against the bare
origin (inference and model info, profile and budget, the IBM
docs-search tools, telemetry). Joining them onto the `/inference` base
produces doubled or misrooted URLs
(`…/inference/inference/v1/model/info`, `…/inference/admin/v1/profile`)
that IBM's edge rejects with 403.
- **`origin_passthrough_strip_json_keys`**: Bob 2.0.1 through 2.0.5
rewrites its gateway host from `region_domain` in the
`/admin/v1/profile` response while keeping the proxy's port, so every
later request goes to an unreachable `api.<region>:<proxy-port>`. The
proxy removes that key.

Bob bills flat per token, so the target defaults `HEADROOM_MODE` to
`token`; an explicit `HEADROOM_MODE` still wins. `/health` now reports
the proxy's `mode`, and `headroom wrap` warns when it reuses a proxy
running a different mode than the session asked for. The warning applies
to every harness.

Replaces the Bob part of #3366, without its `wrap_targets.json` overlay,
and supersedes #3323.

Closes #

## Type of Change

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

## Changes Made

- `headroom/providers/wrap_registry.py`: `bare_origin` URL style;
`openai_api_url`, `extra_chat_routes`, `origin_passthrough_prefixes`,
`origin_passthrough_strip_json_keys`, `default_mode`, `preflight`
fields; the `bob` target; `bob_preflight`, which aborts the wrap when a
saved `~/.bob/settings/settings.json` `gatewayUrl` would override
`BOB_GATEWAY_URL` (bobshell re-resolves `settings.gatewayUrl ??
policy.GatewayUrl ?? env` at startup, verified in 2.0.5);
`resolve_origin_passthrough_url` /
`strip_origin_passthrough_response_keys` over a host-keyed index built
once from the static registry
- `headroom/providers/route_specs.py`: `OPENAI_HANDLER_ROUTES` gains the
registry's `extra_chat_routes`, built from static code data (no
user-file read)
- `headroom/proxy/handlers/openai.py`: catch-all passthrough uses the
origin-rooted URL for declared paths and strips declared keys from 200
JSON responses
- `headroom/proxy/server.py`: `/health` config block adds `mode`
- `headroom/cli/wrap.py`: generated commands export `default_mode` and
pass `openai_api_url`; new `_warn_proxy_mode_mismatch` on both
proxy-reuse paths
- `tests/test_cli/test_wrap_bob.py` (22 tests), including a
handler-level test that fails without the `openai.py` wiring

## Testing

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

### Test Output

```text
$ pytest tests/test_cli/ tests/test_provider_route_specs.py tests/test_agent_savings.py \
    tests/test_custom_base_passthrough_telemetry.py tests/test_compress_passthrough.py
878 passed, 1 skipped
$ pytest tests/test_cli/test_wrap_bob.py -k handler   # with openai.py reverted to the parent commit
1 failed  (upstream URL was not origin-rooted)       # -> the test guards the wiring
$ mypy headroom/cli/wrap.py headroom/providers/wrap_registry.py headroom/providers/route_specs.py
Success: no issues found in 3 source files
```

Locally, `tests/test_proxy_healthchecks.py` (where I added the `mode`
assertion) and two `tests/test_proxy_openai.py` cases fail identically
on `main`, because of a Starlette `TestClient` version mismatch in my
environment. So I checked `/health` separately through
`httpx.ASGITransport` from a loopback client:
`ProxyConfig(mode="token")` → `"mode": "token"`,
`ProxyConfig(mode="cache")` → `"mode": "cache"`.

## Real Behavior Proof

- Environment: macOS (darwin 25.6.0), Python 3.13, this branch; the real
IBM gateway, no Bob credentials
- Exact command / steps: a stub `bob` on PATH reads `/health` through
`BOB_GATEWAY_URL` and sends uncredentialed requests for Bob's three
paths; `headroom wrap bob --port 8911 -- run "fix it"` with
`HEADROOM_MODE` unset. For comparison, the same GETs sent straight to
IBM at the correct URLs and at the misrooted ones.
- Observed result: all three paths reach the correct IBM URLs.
- The child gets `BOB_GATEWAY_URL=http://127.0.0.1:8911/p/run` and
`argv=run fix it`. The proxy reports `mode: token`.
- The chat POST is logged as `outbound_request …
path=https://api.us-east.bob.ibm.com/inference/v1/chat/completions`.
Cloudflare rejects it with 403 because there are no credentials.
- `/admin/v1/profile` returns **401**, which matches the origin-rooted
URL (direct GET → 401). The misrooted `/inference/admin/v1/profile`
returns **403**.
- Not tested: a credentialed, live Bob session on this branch (it spends
IBM credits). That ran end to end on #3366, which shares these code
paths except for the removed overlay. `/inference/v1/model/info` can't
be told apart without credentials (403 either way); the handler and unit
tests cover it.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: two changes reach every proxy:
- The route `POST /inference/v1/chat/completions` is added. It
previously matched the catch-all.
- Catch-all passthrough changes only for requests whose OpenAI upstream
is the Bob gateway host.

  `/health` gains a `mode` field. Other clients behave the same.
- Kill switch / disable path: don't use `wrap bob`; the passthrough
rules only fire for the Bob gateway host
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR; no persisted state. What to monitor:
403s on `/inference` or `/admin` paths in the proxy log for Bob
sessions.

## Review Readiness

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

## Checklist

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

## Additional Notes

- Documentation: `headroom wrap bob --help` documents usage and the mode
default. There's no separate docs page, matching the other env-var wrap
targets.
- Known limitations, deliberate in this PR:
- The saved-`gatewayUrl` guard runs from `configure_launch`, after the
proxy is up, because it must see the actual port. A misconfigured
machine pays one proxy start/teardown (~2 s) before the abort; an
earlier requested-port check reintroduces the "rejected too early" case.
- Registry commands have no `--openai-api-url`; a non-us-east Bob
account needs a hand-started `headroom proxy --openai-api-url
https://api.<region>.bob.ibm.com/inference/v1` plus `--no-proxy`. The
passthrough rules now key on `.bob.ibm.com`, so that setup gets the same
path rooting and `region_domain` strip.
- `default_mode` is delivered through `HEADROOM_MODE` in the wrapper's
environment; that is the documented mode interface and what
`_start_proxy` already reads. It is also visible to the child process.
- `/inference/v1/chat/completions` is a static route on every proxy, not
gated on the upstream; no other upstream serves that path.
- After a persistent restart the mode warning queries the restarted
proxy's config; the "recovered but nothing listening" return stays
silent because there is no proxy to compare.
- Known limitation, unchanged by this PR: one proxy has one
OpenAI-family upstream and one mode. When Bob joins a shared proxy
started without the IBM upstream, wrap restarts it and repoints OpenAI
traffic for every attached client (kimi and vibe behave the same way).
Give Bob its own `--port` when running several harnesses.
- One of three PRs replacing #3366.

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

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

---

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

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-04 13:58:42 -07:00
bb1ab6afd3 fix(wrap): preserve pre-set ANTHROPIC_BASE_URL as proxy upstream (#1358)
## Description

Issue #1353: when the user already has `ANTHROPIC_BASE_URL` pointing at
a LiteLLM (or any custom Anthropic-compatible) gateway, `headroom wrap
claude` overwrote it with the local proxy URL and silently forwarded to
`api.anthropic.com`. `wrap claude` now treats a pre-existing
non-self-pointing `ANTHROPIC_BASE_URL` as the proxy's upstream (passed
as `ANTHROPIC_TARGET_API_URL`) so compression layers on top of the
user's gateway instead of replacing it. Explicit
`ANTHROPIC_TARGET_API_URL`, Foundry and Vertex paths still win.

Closes #1353

## Type of Change

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

## Changes Made

- Add `_detect_inbound_anthropic_upstream(proxy_port)` to
`headroom/cli/wrap.py`: returns a pre-set `ANTHROPIC_BASE_URL` as the
proxy upstream, ignoring unset/blank values and self-pointing localhost
URLs on the proxy port.
- Wire it into `wrap claude` so a user's custom gateway is preserved as
`ANTHROPIC_TARGET_API_URL` instead of being overwritten.
- Precedence unchanged: explicit `ANTHROPIC_TARGET_API_URL`, Foundry,
and Vertex still take priority.
- Add `tests/test_cli/test_wrap_claude_inbound_upstream.py` (8 cases)
covering detection, blank/unset, self-pointing URLs, and a
different-port upstream.

## Testing

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

### Test Output

```text
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_detects_custom_litellm_upstream PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_when_unset PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_when_blank PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://127.0.0.1:8787] PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://localhost:8787] PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://127.0.0.1:8787/] PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://LOCALHOST:8787/v1] PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_localhost_on_different_port PASSED

============================== 8 passed in 0.25s ===============================
```

## Real Behavior Proof

- Observed result: eight focused detection cases fail without the helper
and pass with it; custom non-self-pointing gateways are preserved while
blank or self-pointing values fall through safely.

- Environment: Python 3.13, local checkout, pytest 9.0.3
- Exact command / steps: `pytest
tests/test_cli/test_wrap_claude_inbound_upstream.py -v` on the patched
branch, then with the production fix reverted.
- Observed result (RED → GREEN):
- **RED** — with the fix reverted, all 8 tests fail: `AttributeError:
module 'headroom.cli.wrap' has no attribute
'_detect_inbound_anthropic_upstream'` (`8 failed in 0.37s`).
  - **GREEN** — with the fix applied, all 8 pass (`8 passed in 0.25s`).
- Not tested: end-to-end live LiteLLM gateway round-trip (covered
indirectly by the upstream-URL detection unit tests).

## Review Readiness

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

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Additional Notes

Docs/CHANGELOG checklist items left unchecked as N/A: this is a
behavioral bug fix to existing `wrap claude` upstream handling with no
new public surface to document.


## Real Behavior Proof

- Environment: headroom 0.28.0 dev checkout (branch `fix/issue-1353`),
`.venv`, proxy port 8787.
- Exact command / steps: invoked the real detection path used by `wrap
claude` (`_detect_inbound_anthropic_upstream`) across representative
`ANTHROPIC_BASE_URL` values:
  ```
python -c "from headroom.cli.wrap import
_detect_inbound_anthropic_upstream as d; ..."
  ```
- Observed result:
  ```
  custom LiteLLM gateway        -> 'https://litellm.mycorp.internal/v1'
  unset                         -> None
  blank                         -> None
  self-pointing localhost:8787  -> None
  self-pointing LOCALHOST/v1    -> None
  different port (real upstream)-> 'http://10.0.0.5:4000'
  ```
A pre-set, non-self-pointing `ANTHROPIC_BASE_URL` is returned as the
proxy upstream (wired to `ANTHROPIC_TARGET_API_URL`), so compression
layers on top of the user's gateway. Unset / blank / self-pointing
values fall through to `None`, so the proxy default applies and no
self-forwarding loop is created.
- Not tested: full `wrap claude` launch end-to-end against a live
LiteLLM gateway (needs the external gateway + Claude Code); the wiring
from `custom_upstream` to `ANTHROPIC_TARGET_API_URL` is covered by the
unit suite.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-01 22:32:38 -05:00
Sudhindra Desai 1982b3a773 fix(codex): explain why wrapped Codex runs without the shared server (#3899)
## Description

`headroom wrap codex` passes proxy routing as a `--config` override
(`openai_base_url=…`, or `model_providers.<id>.base_url=…` for custom
providers). This keeps routing scoped to the launched process and leaves
`~/.codex/config.toml` untouched, by design (#1507, #2160). Codex 0.159
runs any session that has command-line overrides in embedded mode, so
wrapped sessions always print `Running without the shared background
server` and never use Codex's shared background server.

Env-only routing can't replace the override. ChatGPT-subscription Codex
ignores `OPENAI_BASE_URL` (see 5c7a5b48 / d54c5b6a), so
`openai_base_url` has to come from config. A shared server also serves
every session at once, so a per-session base URL can't apply to it.

The issue accepts "explicit documentation of the limitation", so this PR
does that:

- `wrap codex` now prints a one-line note at launch that explains
embedded mode and points to the persistent alternative.
- The proxy docs describe the limitation and the alternative: `headroom
init codex` (project) or `headroom init -g codex` (user) writes the
routing to Codex's own config, so a plain `codex` launch keeps the
shared server.

Closes #3888

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

- `headroom/cli/wrap.py`: new `_CODEX_EMBEDDED_MODE_NOTE`.
`_codex_session_launch_settings` appends it to the launch display lines,
so it prints under `Launching CODEX…` for both the built-in `openai`
provider and custom providers.
- `docs/content/docs/proxy.mdx`: new paragraph under "Agent wrapping"
covering why wrapped Codex uses embedded mode, plus the `headroom init
codex` / `headroom init -g codex` alternative and its persistent scope.
- `tests/test_cli/test_wrap_codex.py`: asserts the note for both
provider paths.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`): not run successfully. My
local mypy stops on an unrelated numpy stub syntax error in this env
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ pytest tests/test_cli/test_wrap_codex.py -q
101 passed in 5.68s

$ pytest tests/test_cli -q -k codex
176 passed, 738 deselected in 6.84s

$ ruff check headroom/cli/wrap.py tests/test_cli/test_wrap_codex.py
All checks passed!
```

## Real Behavior Proof

- Environment: macOS, Python 3.12, branch head
- Exact command / steps: `python -c "import headroom.cli.wrap as w;
print(w._CODEX_EMBEDDED_MODE_NOTE)"`
- Observed result: the note prints as expected (below), and the codex
wrap tests assert it appears in the launch display for both the built-in
`openai` provider and custom providers:
  ```text
Note: session-scoped routing runs Codex without its shared background
server (embedded mode). To keep the shared server, route through Codex
config instead: run `headroom init codex` (or `headroom init -g codex`)
once, then start `codex` directly.
  ```
- Not tested: a live `headroom wrap codex` launch against Codex CLI
0.159.2 (Codex isn't installed on my machine). I also didn't verify end
to end that an `init`-configured plain `codex` launch keeps the shared
server, though that path passes no command-line overrides.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: No. Routing is unchanged; only one
extra banner line is printed.
- Kill switch / disable path: N/A
- Unsafe override required: No
- Qualification impact: None
- Rollback path: revert this PR

## Review Readiness

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

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [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

A follow-up could skip the `--config` override when Codex's effective
config already routes the selected provider to this proxy, for example
after `headroom init codex`. That would let `wrap codex` itself keep the
shared server. The trade-off is losing the per-project `/p/<project>`
URL prefix for those sessions, so I left it out of this PR. Happy to add
it if maintainers want that behavior.
2026-10-01 12:15:47 -05:00
8cfeb692ca fix(wrap): scope Serena's MCP registration to the wrapped project (#2787) (#2992)
## Description

Fixes #2787.

Scopes Headroom-installed Serena to the wrapped Claude project by
default, containing an upstream MCP failure to that project instead of
degrading every Claude Code session on the machine. `--code-memory-scope
user` / `HEADROOM_CODE_MEMORY_SCOPE=user` retains the prior machine-wide
behavior when explicitly requested.

The implementation completes ownership semantics across multiple wrapped
projects:

- Claude MCP registration, lookup, overwrite, and removal are
scope-aware.
- Legacy ledger-owned user entries migrate safely; user-managed global
Serena remains untouched.
- Each project gets an independent ledger ownership key, so wrapping
project B no longer overwrites project A's ownership.
- Unwrapping project A removes only A plus an independently-owned legacy
user entry; it cannot orphan B or delete an unowned global entry.
- The migration that retires a legacy machine-wide entry now clears the
ledger ownership record along with the config entry (see Changes Made) —
an ownership record can no longer outlive the entry it authorized.

## Type of Change

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

## Changes Made

- `headroom/mcp_registry/claude.py`: `ClaudeRegistrar` gained a `scope`
argument and reads/writes both `local` (project) and `user`
(machine-wide) Claude Code MCP scopes.
- `headroom/cli/wrap.py`: `_setup_serena_mcp` registers Serena at
`local` scope by default; `--code-memory-scope` (env
`HEADROOM_CODE_MEMORY_SCOPE`) restores `user` scope on request.
- `headroom/cli/wrap.py`: `_retire_user_scope_serena` migrates a
pre-#2787 machine-wide Serena entry on the next wrap, but only when the
ledger proves Headroom installed it.
- `headroom/cli/wrap.py`: fixed `_retire_user_scope_serena` to clear the
ledger's ownership record after removing the migrated entry — previously
the record survived the removal, so a user later installing the
identical Serena command globally themselves could collide with the
stale fingerprint and have their own entry deleted by a later wrap.
- `headroom/cli/wrap.py`: `_remove_headroom_installed_serena_mcp` now
also clears a scope's ownership record when that scope's live entry is
already absent, so a record can't outlive the entry it authorized.
- `headroom/mcp_registry/ledger.py`: ledger entries key off a
project-scoped `ownership_key` in addition to the legacy global key, so
multiple wrapped projects don't clobber each other's ownership records.
- Added/extended tests: `tests/test_cli/test_serena_scope.py`,
`tests/test_mcp_registry/test_claude_registrar.py`,
`tests/test_cli/test_unwrap_claude.py`.

## Testing

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

### Test Output

```text
pytest tests/test_cli/test_serena_scope.py -v
13 passed in 19.29s

pytest tests/test_mcp_registry/ tests/test_cli/test_unwrap_claude.py -q
137 passed, 2 failed in 2.16s
```

Both failures are pre-existing and unrelated to this change — they
reproduce identically with this PR's diff to `headroom/cli/wrap.py`
reverted, on a clean checkout of this branch.
`test_unwrap_claude_stops_claude_owned_persistent_deployment` was
already confirmed pre-existing on `main` by an independent reviewer on
this PR (comment from PrakharSrivastav, 2026-08-13).
`test_unwrap_claude_removes_mcp_purges_retired_hook_and_stops_proxy`
fails locally on Windows over a hook-config path-comparison mismatch
unrelated to Serena scoping; it is not exercised by this diff.

```text
ruff check .
All checks passed!

ruff format --check .
All files already formatted.

mypy headroom --ignore-missing-imports
Success: no issues found in 522 source files
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.13.11, project `.venv` (pytest
9.0.3, mypy 2.3.1, ruff).
- Exact command / steps: `pytest tests/test_cli/test_serena_scope.py
-v`, then re-ran the two new regression tests
(`test_rewrap_migration_clears_the_ledger_so_a_reinstall_is_never_deleted`,
`test_remove_serena_clears_a_stale_ownership_record_with_no_live_entry`)
with the `headroom/cli/wrap.py` fix reverted via `git stash`, to confirm
they fail on the old code and pass on the fix.
- Observed result: both new tests fail with `assert not True` (stale
ledger record still present) against the pre-fix code, and pass once the
`clear_install(...)` calls are added. Full `test_serena_scope.py` suite:
13/13 passed post-fix. `mypy headroom` and `ruff check .` both clean.
- Not tested: a real Claude Code installation end-to-end (these tests
drive `ClaudeRegistrar` against a `tmp_path` home directory, per the
existing pattern in this file); real macOS/Linux CI runners, which is
what the GitHub Actions matrix below covers.

## Runtime Rollout Safety

- Rollout-managed feature(s): `headroom wrap claude` Serena MCP
registration scope only.
- Minimum rollout channel: normal patch release; no staged feature flag
required.
- Stable/default behavior changed: Serena now registers at Claude Code's
`local` (project) scope by default instead of `user` (machine-wide)
scope; a pre-existing Headroom-installed machine-wide entry is migrated
(removed) on the next wrap, with its ledger record now also cleared.
- Kill switch / disable path: `--code-memory-scope user` (or
`HEADROOM_CODE_MEMORY_SCOPE=user`) restores the previous machine-wide
registration.
- Unsafe override required: none.
- Qualification impact: `tests/test_cli/test_serena_scope.py`,
`tests/test_mcp_registry/test_claude_registrar.py`, and
`tests/test_cli/test_unwrap_claude.py` must stay green (module to the
two pre-existing, environment-specific failures noted under Testing).
- Rollback path: human revert of this PR; `--code-memory-scope user`
provides an immediate operational fallback to the old registration scope
without a code rollback.

## 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 made corresponding changes to the documentation
(`README.md`, `docs/content/docs/proxy.mdx`)
- [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

## Additional Notes

Addresses the code-review finding from JerrettDavis (2026-08-14): the
ledger's stale ownership record after migration is now cleared, with a
regression test that reproduces the exact fingerprint-collision scenario
described in that review and fails on the pre-fix code.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-01 00:09:27 -05:00
rNozandJD Davis bd0296b5e7 fix(wrap): strip -dev from running proxy version in restart check (#3200)
## Description

`headroom wrap` is supposed to restart an already-running proxy whose
Headroom version differs from the CLI's. The check,
`_proxy_needs_version_restart`, strips the `-dev` suffix only from the
CLI's own version. A source-built proxy reporting e.g. `0.34.0-dev`
fails the `^v?\d+\.\d+\.\d+$` release regex, normalizes to `None`, and
the check silently never fires — so any stale dev-built proxy is reused
forever. The docstring already claims the opposite behavior ("a dev CLI
still restarts a stale proxy on a real version difference"); this PR
makes the code match it.

Observed in production on a maintainer machine: a 21-day-old
`0.34.0-dev` proxy (zero attached clients) was silently reused by a
`0.37.0-dev` wrap, which then also inherited its incompatible routing
config (see linked companion PR for the routing half).

Closes #3197

## Type of Change

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

## Changes Made

- `headroom/cli/wrap.py`: `_proxy_needs_version_restart` now strips
`-dev` from the *running* proxy version before normalization (mirroring
the CLI side), with a comment pinning the version scheme (`<base>-dev`
from `get_version`) so future suffix styles get stripped too.
- `tests/test_cli/test_wrap_persistent.py`: regression tests — dev proxy
vs dev CLI with different base releases restarts; same base does not;
release proxy vs dev CLI restarts; unparseable/missing versions still
never restart.

## Testing

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

### Test Output

```text
$ uv run pytest tests/test_cli/test_wrap_persistent.py -q
32 passed in 0.63s
$ uv run pytest tests/test_cli/test_wrap_persistent.py tests/test_cli/test_wrap_helpers.py -q
90 passed in 0.57s
$ uv run ruff format headroom/cli/wrap.py tests/test_cli/test_wrap_persistent.py
2 files left unchanged
$ uv run ruff check headroom/cli/wrap.py tests/test_cli/test_wrap_persistent.py
All checks passed!
$ uv run mypy headroom/cli/wrap.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS 26.5 arm64, Python 3.13, local source build
0.37.0-dev (integration overlay), live stale proxy: `headroom proxy
--port 8789` running 0.34.0-dev for 21 days with zero attached wrap
clients.
- Exact command / steps: `GET http://127.0.0.1:8789/health` before and
after; then from the fixed build, `python -c "from headroom.cli import
wrap as w; w._ensure_proxy(8789, False, agent_type='codex')"`.
- Observed result: before fix the same call printed "Proxy already
running" (reused). After fix: `/health` before = `version 0.34.0-dev,
pid 63454, augment_api_url set`; the call killed PID 63454 and started a
fresh proxy; `/health` after = `version 0.37.0-dev, pid 48365,
augment_api_url None`. Against a second stale proxy (port 8788) with one
live wrapper attached, the check correctly deferred ("Leaving it running
because 1 attached wrapper(s)") instead of killing a live session's
proxy.
- Not tested: the persistent-deployment variant of the version-restart
path (unit-tested only); Windows (code path is platform-independent
string handling).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: yes — wraps now actually restart
stale dev-built proxies instead of reusing them. Release-built proxies
(no `-dev` suffix) are byte-identical in behavior.
- Kill switch / disable path: none needed; stopping the old proxy
manually restores prior behavior.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit; reuse of stale dev proxies resumes.

## Review Readiness

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

## Checklist

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

## Additional Notes

Adversarially reviewed by a second model (glm-5.2, high reasoning)
before submission; verdict ready, one nit (version-scheme comment)
accepted and applied. Companion PRs (same incident): routing-config
reuse check, orphan-proxy watchdog.

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-09-30 11:19:38 -05:00
Bernardo GomesandJD Davis 08dda4cb0b fix(cli): strip unmarked headroom_memory TOML table before injecting (#3490)
## Description

`_inject_memory_mcp_config` (used by `headroom wrap codex`) only guards
against a duplicate `[mcp_servers.headroom_memory]` table via the
`_MEMORY_MCP_MARKER`/`_MEMORY_MCP_END` comment pair it writes. If that
table already exists in a user's `~/.codex/config.toml` **without**
those markers — e.g. hand-copied from the usage example in
`headroom/memory/mcp_server.py`, or left over from before this table
was marker-guarded — the injector appends a second
`[mcp_servers.headroom_memory]` table instead of replacing the
existing one. Two tables sharing the same key is invalid TOML, and
silently breaks Codex's MCP config parsing on startup.

This PR adds a helper that strips any unmarked
`[mcp_servers.headroom_memory]` table before the marker-wrapped
section is appended, mirroring the pattern already used for
`[model_providers.headroom]`.

No issue number to close (found while reviewing the Codex wrap flow).

## 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 `_strip_existing_codex_memory_mcp_table()` in
`headroom/cli/wrap.py`, mirroring the existing
`_strip_existing_codex_headroom_provider_table()` helper: it
regex-matches an unmarked `[mcp_servers.headroom_memory]` table and
removes it.
- Called this new helper from `_inject_memory_mcp_config()` right before
appending the marker-wrapped `headroom_memory` section, in the branch
that runs when no `_MEMORY_MCP_MARKER` is found in the existing config.
- Added a regression test, `test_inject_replaces_unmarked_memory_block`,
in `tests/test_cli/test_wrap_codex.py`.

## Testing

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

### Test Output

```text
$ .venv/bin/python -m pytest tests/test_cli/test_wrap_codex.py -q
============================= test session starts ==============================
platform linux -- Python 3.13.15, pytest-9.0.3, pluggy-1.6.0
rootdir: /home/bitter/development/oss/headroom
configfile: pyproject.toml
plugins: anyio-4.12.1, cov-7.0.0, langsmith-0.9.3, respx-0.23.1, asyncio-1.3.0
collected 93 items

tests/test_cli/test_wrap_codex.py ...................................... [ 40%]
.......................................................                  [100%]

======================== 93 passed in 66.82s (0:01:06) =========================

$ .venv/bin/python -m pytest tests/test_cli/ -q
[...]
734 passed, 4 skipped, 1 failed in 92.84s (0:01:32)

FAILED tests/test_cli/test_unwrap_claude.py::test_unwrap_claude_stops_claude_owned_persistent_deployment
```
This one failure is pre-existing on a clean `main` checkout (verified
via `git stash` + rerun before making any change here) and is
unrelated to this PR — it's an assertion on unwrap-claude output
messaging, not touched by this diff.

```text
$ .venv/bin/python -m ruff check headroom/cli/wrap.py tests/test_cli/test_wrap_codex.py
All checks passed!

$ .venv/bin/python -m mypy headroom/cli/wrap.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: local dev checkout, Python 3.13.15, `.venv` from repo
(`pytest 9.0.3`, `ruff`, `mypy`).
- Exact command / steps: Ran `.venv/bin/python -m pytest
tests/test_cli/test_wrap_codex.py::TestCodexMemoryMcpConfig::test_inject_replaces_unmarked_memory_block
-q`, which (1) seeds `~/.codex/config.toml` with an unmarked
`[mcp_servers.headroom_memory]` table plus `[profiles.default]` and an
unrelated `[mcp_servers.other]` table, (2) calls
`_inject_memory_mcp_config("codex-user")` — the same function `headroom
wrap codex` invokes — and (3) reads the resulting `config.toml` back and
parses it with `tomllib.loads`.
- Observed result: With the fix applied, the test passes — exactly one
`[mcp_servers.headroom_memory]` table remains in the file, wrapped in
the `_MEMORY_MCP_MARKER`/`_MEMORY_MCP_END` comments, with the updated
`--user codex-user` value; `[profiles.default]` and
`[mcp_servers.other]` are byte-for-byte untouched;
`tomllib.loads(content)` succeeds and
`parsed["mcp_servers"]["headroom_memory"]["args"][-1] == "codex-user"`.
I additionally reverted just `headroom/cli/wrap.py` to its pre-fix state
(`git checkout e67b3c8a -- headroom/cli/wrap.py`, keeping the new test)
and reran the same test to confirm it fails without the fix: `assert
content.count("[mcp_servers.headroom_memory]") == 1` fails with `assert
2 == 1`, because the injector left the old unmarked table in place and
appended a second, marker-wrapped `[mcp_servers.headroom_memory]` table
below it. Separately, I fed that exact two-table content through
`tomllib.loads()` directly and confirmed it raises
`tomllib.TOMLDecodeError: Cannot declare ('mcp_servers',
'headroom_memory') twice (at line 14, column 29)` — reproducing the
exact failure mode Codex's TOML parser hits on startup. I then restored
the fixed `wrap.py` and reran the test to confirm it passes again.
- Not tested: real `codex` binary startup against the patched config (no
local Codex CLI install in this environment) — covered instead by the
`tomllib.loads` validity assertion, which is what actually breaks
Codex's parser today.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — this only affects the `headroom
wrap codex` CLI subcommand's local config-file writer, not any
server-side or rollout-gated runtime behavior.
- Minimum rollout channel: N/A (CLI-only, no feature flag).
- Stable/default behavior changed: no. Behavior only changes for the
edge case where an unmarked `[mcp_servers.headroom_memory]` table
already exists (previously produced broken/invalid TOML); the normal
marker-found and no-table-at-all paths are unchanged.
- Kill switch / disable path: N/A — no runtime toggle; users can simply
not run `headroom wrap codex` or manually edit `~/.codex/config.toml`.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert this commit; the prior (buggy) behavior only
manifested for a narrow, previously-broken edge case, so reverting is
safe.

## 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 (N/A —
internal helper, no user-facing docs describe this edge case)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A — CLI/config-file fix, no UI.

## Additional Notes

- "Manual testing performed" is unchecked because I did not run the real
`codex` binary against the patched config in this environment (no Codex
CLI installed here); the regression test's `tomllib.loads` round-trip is
the direct proof that the generated config is valid TOML, which is the
actual failure mode this PR fixes.
- The pre-existing
`test_unwrap_claude_stops_claude_owned_persistent_deployment` failure on
`tests/test_cli/` is unrelated to this change and reproduces identically
on a clean `main` checkout.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-09-30 11:15:04 -05:00
b1b005a9a8 fix(memory): align project routing with wrap headers (#3603)
## Description

When `headroom wrap claude` runs from two directories named `api`, both
requests currently send `X-Headroom-Project: api`. Using that label as a
memory or CCR identity can make the two workspaces share history.

This keeps `X-Headroom-Project` as the human-readable savings label and
adds `X-Headroom-Cwd`, derived from the canonical launch directory, for
routing. The resolver now ignores the label when it is the only project
signal.

Closes #3597

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

- Keep `X-Headroom-Project` for savings attribution only.
- Add a percent-encoded `X-Headroom-Cwd` header containing the canonical
launch directory.
- Hash the decoded cwd for memory and CCR routing, while retaining the
basename as the display label.
- Preserve user-supplied project and cwd headers without duplicating or
overwriting them.
- Add regressions for same-basename directories, label-only fail-closed
behavior, and an explicit user-supplied label collision.

## 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
216 passed, 1 warning in 4.80s
7 files already formatted
All checks passed!
git diff --check: clean
```

## Real Behavior Proof

- Environment: Ubuntu 24.04 VPS, Python 3.12.3, Rust extension built in
the test environment.
- Exact command / steps: Wrapped two temporary directories with the same
basename (`api`), using the same explicit `X-Headroom-Project` value,
then resolved both memory and CCR workspaces.
- Observed result: Both requests retained the same display label but
produced different cwd headers and different memory and CCR keys. A
request containing only the display label returned the fail-closed
result.
- Not tested: A live request to an external Claude provider.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Stable.
- Stable/default behavior changed: `headroom wrap claude` now sends a
second `X-Headroom-Cwd` routing header; `X-Headroom-Project` remains a
savings label.
- Kill switch / disable path: Remove the generated routing header or
disable project-scoped memory/CCR using the existing configuration.
- Unsafe override required: No.
- Qualification impact: Requests with only the savings label remain
unscoped and fail closed; requests with a cwd identity retain
project-scoped memory and CCR.
- Rollback path: Revert commit `101b332`.

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

---------

Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-09-29 15:33:17 -05:00
trs-80andClaude Opus 5.5 3ffa57ec25 fix(wrap): never reuse a non-Headroom listener on the proxy port (#3799)
## Description

`headroom wrap` decided a proxy was running with `_check_proxy`, which
is a bare TCP connect. Any service listening on the wrap port passed
that check. When something other than Headroom held the port (seen in
practice: a caveman gateway on 8787), wrap would:

- reuse it and route the tool at it
- wait on it as a persistent deployment
- treat it as a live session in the dead-marker self-heal

A listener now counts as Headroom only if its `/health` payload carries
Headroom identity: `service: "headroom-proxy"` (reported by both the
Python and Rust proxies) or a `config` block. Generic JSON such as
`{"status": "ok"}` is foreign. Otherwise wrap uses the existing port
search.

Split out of #3366. These fixes apply to every harness and don't depend
on the wrap-target registry.

Closes #

## Type of Change

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

## Changes Made

- `headroom/cli/wrap.py`:
  - `_is_headroom_health(payload)`: the identity rule above.
- `_foreign_listener(port)`: TCP accepts, but `/health` does not
identify Headroom.
- `_ensure_proxy_unlocked`: a foreign listener is never reused. The port
search takes over, and a persistent manifest on a foreign-held port
falls through to a fresh proxy instead of raising "not healthy".
- `_check_and_clear_dead_wrap_marker`: a foreign listener on a dead
wrapper's port no longer counts as a live session (the marker is kept
while the writer PID is alive).
- `_launch_tool`: on port fallback the launch banner is rewritten too,
so it shows the URL the child actually got (the env already was).
- `wrap claude`: the marker/owner claim records `actual_port` instead of
the requested port.
- `_ensure_claude_wrap_selfheal_hook`: a marker-bearing hook whose
command drifted (hand edit, moved binary) is rewritten in place instead
of skipped.
- `tests/test_cli/test_wrap_claude_vertex_proxy_env.py`: runs in an
isolated cwd so it can't write a selfheal hook into the repo's
`.claude/settings.local.json`. Also gitignored
`.claude/.headroom_wrap_*.json`.

## Testing

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

### Test Output

```text
$ pytest tests/test_cli/
792 passed, 1 skipped
$ ruff check headroom/cli/wrap.py tests/test_cli/ && ruff format --check headroom/cli/wrap.py tests/test_cli/
All checks passed!
$ mypy headroom/cli/wrap.py
Success: no issues found in 1 source file
```

New: `tests/test_cli/test_wrap_foreign_listener.py` (12 tests, including
a generic-JSON `/health` server and the Rust-proxy `/health` shape),
`test_wrap_selfheal_hook_repairs_stale_command`. Updated:
`test_wrap_kimi.py::test_non_kimi_fallback_display_follows_actual_port`
(asserted the old stale banner), plus two `test_wrap_persistent.py`
tests that now identify the listener as Headroom via `/health`.

## Real Behavior Proof

- Environment: macOS (darwin 25.6.0), Python 3.13, this branch vs `main`
at 3aa50128
- Exact command / steps: `python3 -m http.server 8899` as a foreign
listener (its `/health` returns 404); a stub `goose` on PATH that prints
`OPENAI_BASE_URL` and curls `$ANTHROPIC_BASE_URL/health`; then `headroom
wrap goose --port 8899`
- Observed result: main hands the tool the squatter; this branch starts
a real proxy on the next port.
- main: `Proxy already running on port 8899` → child gets
`http://127.0.0.1:8899/v1`, and its `/health` → **404** (the tool is
talking to the squatter)
- this branch: `Port 8899 is in use by a non-Headroom service; selecting
another port...` → proxy starts on 8900, banner and child both show
`http://127.0.0.1:8900/v1`, `/health` → **200**
- Not tested: Windows; a live persistent (`headroom install`) deployment
whose port was taken over (covered by
`test_persistent_manifest_on_foreign_port_falls_through`)

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only when a non-Headroom service
holds the wrap port. Wrap used to hand the tool that service; now it
starts a Headroom proxy on the next free port. A real Headroom proxy is
identified by `/health` and reused exactly as before.
- Kill switch / disable path: none needed; pass `--port` to choose a
free port explicitly
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR; no persisted state or format 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
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

- Documentation: N/A, no user-facing docs describe port reuse.
- One of three PRs replacing #3366 (see that PR for the split
rationale). Independent of the other two; merges cleanly with them in
either order.

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

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 15:30:56 -05:00
JD Davis 5bf6612326 fix(cli): honor CODEX_HOME and align wrap/init/doctor with the live proxy port (#3855)
## Description

Closes several CLI usability gaps where `wrap`, `init` and `doctor`
disagreed about *where* things are:

1. **CODEX_HOME was ignored by `doctor` / `install` / `init -g codex`
hooks.** `codex_config_path()` hardcoded `~/.codex/config.toml`, while
`wrap` and the MCP registrar honored `CODEX_HOME`. With a relocated
Codex home, `doctor` reported "not routed" for a correctly wrapped Codex
(and `install apply` edited the wrong file).
2. **Hard-coded 8787.** `wrap <tool> --port` (~20 subcommands) and `init
--port` ignored `HEADROOM_PORT` and never noticed a proxy already
running on another port, so they would start a second proxy or point the
agent at a dead port.
3. **`init hook ensure` output was fully suppressed**, so an agent whose
`base_url` drifted from the managed proxy's port failed silently every
session.
4. **`doctor`** only probed `/livez`, did not check the hooks `init`
installs, and did not notice a live proxy on another port.

## Type of Change

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

## Changes Made

**CODEX_HOME (one helper, reused everywhere)**
- `headroom.install.paths`: new `codex_home_dir()` (`CODEX_HOME`,
blank-safe, else `~/.codex`), `codex_hooks_path()`,
`codex_project_config_path()`; `codex_config_path()` now goes through
it.
- Reused by `wrap._codex_home_dir`, `CodexRegistrar`, `recover codex`,
`init` (`-g` config **and** `hooks.json`), `install` (via
`codex_config_path`), and `doctor`.
- `doctor`'s `codex` check consults the project `.codex/config.toml`
first (Codex layers it over the user config; `init codex` without `-g`
writes there), then `$CODEX_HOME/config.toml`, and names the file that
supplied the routing. The "no config" summary now names the real path
instead of `~/.codex/config.toml`.

**Port resolution (`headroom/cli/port_discovery.py`)**
- Every `wrap` subcommand's `--port` / `--proxy-port` (shared
`proxy_port_option`) and `init --port`:
  - explicit `--port` -> honored as-is, no discovery;
  - `HEADROOM_PORT` -> honored as-is, no discovery;
- otherwise default 8787 **plus** cheap discovery: candidates are the
requested port, `HEADROOM_PORT`, 8787, deployment-manifest ports and the
project's wrap marker (max 8, de-duplicated), probed **concurrently** on
loopback `/livez` with a 0.5 s timeout. A port counts only if `/livez`
identifies `service: headroom-proxy` (unrelated local servers are
ignored). No port-range scanning.
- If the requested port has no Headroom proxy but another candidate
does:
- **TTY (stdin and stdout)**: prompt `Connect to the running proxy on N
[c], keep port 8787 [k], or abort [a]?` (default `c`);
- **non-interactive**: keep the requested port (nothing is adopted
silently) and print to stderr the live port and the exact `--port N` /
`HEADROOM_PORT=N` to use it.
  - `init hook ...` never runs discovery (hooks must stay silent/fast).
  - Kill switch: `HEADROOM_PORT_DISCOVERY=0`.
- Before `wrap codex` / `init codex` rewrite an existing
`[model_providers.headroom]` whose loopback `base_url` port differs, a
warning names the old and new port and how to keep the old one.

**`init hook ensure` alignment warning**
- After the (still suppressed) ensure step, for Claude/Codex hooks on
**SessionStart only** (event read from the hook's stdin JSON with a 0.5
s bound), compare the agent's configured base URL port -- Claude:
`settings.local.json` > `settings.json` > `~/.claude/settings.json` >
env; Codex: project `.codex/config.toml` > `$CODEX_HOME/config.toml` --
with the managed manifest's port. On mismatch it prints hook JSON:
`systemMessage` (user) + `hookSpecificOutput.additionalContext` (agent),
including the fix command (`headroom init [-g] --port N <agent>`; N =
the configured port if a Headroom proxy is live there, else the managed
port). PreToolUse / Copilot stay silent. Wrapped in a catch-all: never
raises, never blocks.

**`doctor`**
- New `readiness` row: probes `/readyz` (3 s) when `/livez` answered;
live-but-not-ready is a WARN.
- New `hooks` row: for each `init` manifest in scope (`init-user`, or
this project's profile), checks the Claude settings / Codex `hooks.json`
(CODEX_HOME-aware) still contain the Headroom hook and that the hook's
program still resolves; WARN with the exact `headroom init ...`
re-install command. SKIP when no init hooks are expected.
- When the probed port is down, discovery (same bounded candidates)
names a live proxy on another port in the `proxy` row with `headroom
doctor --port N` and the matching `wrap`/`init --port N` commands.
Exit-code semantics unchanged (still 2 when the probed proxy is down).

**`wrap selfheal`**
- After clearing a dead wrap route, if a live Headroom proxy exists
elsewhere it prints `headroom wrap claude --port N` to stderr.
Deliberately **warn-only** (no automatic repoint): adopting another
session's proxy could silently change backend/mode/owner.

**Tests**
- `tests/test_cli/test_port_alignment.py` (47 tests): CODEX_HOME helpers
+ consumers, doctor CODEX_HOME/project precedence, port
candidates/bounds/identity/disable switch, TTY prompt c/k/a, non-TTY
warning, click option source handling (default vs `--port` vs
`HEADROOM_PORT`), all wrap subcommands wired to the shared option, init
port resolution (incl. hook skip), Codex provider repoint warning, hook
JSON on SessionStart / silent on PreToolUse / never raises, doctor
readiness/hooks/live-elsewhere, selfheal warning. All
homes/cwd/workspace under `tmp_path`, probes injected -- no real
`~/.codex`, `~/.headroom`, or proxy.
- `tests/conftest.py`: autouse sets `HEADROOM_PORT_DISCOVERY=0` and
unsets `CODEX_HOME` so a developer's running proxy / Codex home can't
leak into CLI tests (tests that need discovery re-enable it).

## Testing

- [x] Unit tests pass (`pytest`) -- affected suites, see below
- [x] Linting passes (`ruff check .`, `ruff format --check`)
- [x] Type checking passes (`mypy headroom`) -- no new errors
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ python -m pytest tests/test_cli/test_port_alignment.py -q
47 passed in 1.61s

$ python -m pytest tests/test_cli tests/test_cli_doctor.py tests/test_install tests/test_mcp_registry tests/test_provider_codex_runtime.py -q
2 failed, 1314 passed, 8 skipped
FAILED tests/test_cli/test_unwrap_claude.py::test_unwrap_claude_removes_mcp_purges_retired_hook_and_stops_proxy
FAILED tests/test_cli/test_wrap_stale_marker.py::test_signal_handler_unwinds_so_the_restore_can_run
# both fail identically on unmodified upstream/main on Windows (signal.SIGHUP missing; retired rtk hook cleanup) -- pre-existing, unrelated

$ ruff check headroom tests/... && ruff format --check ...
All checks passed!

$ mypy headroom
headroom/fileperms.py:71 (os.fchmod on Windows) and headroom/integrations/langchain/chat_model.py:394 -- both pre-existing, files untouched
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12.13, worktree checkout. Fully
sandboxed: `HOME`/`USERPROFILE`/`APPDATA`, `CODEX_HOME` and
`HEADROOM_WORKSPACE_DIR` pointed at a scratch dir; a stand-in server
answering only `/livez` with `service: headroom-proxy` on port 47311; a
hand-written deployment manifest on 47311 and an `init-user` manifest on
8787; Claude settings and `$CODEX_HOME/config.toml` routed to 47311.
- Exact command / steps: run each `$` command below in the sandboxed
environment (doctor, init hook alignment, port reconcile, codex provider
repoint).
- Observed result: each command's output is shown directly beneath it;
doctor names the live proxy on 47311 and honors CODEX_HOME, the hook
warns on port mismatch, and non-interactive reconcile keeps the
requested port.

```text
$ headroom doctor --port 47399 --json   (rows)
proxy fail | not reachable at http://127.0.0.1:47399; a Headroom proxy IS running on port 47311 | re-run with: headroom doctor --port 47311 (or export HEADROOM_PORT=47311); to use port 47311 from agents, re-run `headroom wrap <agent> --port 47311` / `headroom init --port 47311 <agent>`
codex warn | routed to port 47311, but doctor probed port 47399 (<scratch>\codex\config.toml) | re-run with: headroom doctor --port 47311

$ headroom doctor --port 47311 --json   (rows)
proxy pass | running at http://127.0.0.1:47311 (up, demo)
readiness warn | proxy is live but /readyz is not ready (upstream unreachable or still starting)
codex pass | routed via <scratch>\codex\config.toml          <- CODEX_HOME honored
hooks warn | claude (user): no Headroom hook in <scratch>\home\.claude\settings.json; codex (user): no Headroom hook in <scratch>\codex\hooks.json | re-install with: headroom init -g claude && headroom init -g codex

$ echo '{"hook_event_name":"SessionStart"}' | <init hook alignment, marker headroom-init-claude, profile init-user>
{"systemMessage": "Headroom: Claude Code is configured for http://127.0.0.1:47311 but the Headroom proxy managed by `headroom init` (init-user) uses port 8787; a Headroom proxy is running on 47311, not the managed one. Fix: headroom init -g --port 47311 claude", "hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "..."}}
(same for codex via CODEX_HOME; PreToolUse -> no output)

$ non-interactive default-port reconcile (requested 47398)
headroom: no Headroom proxy on port 47398, but one is running on port 47311.
headroom: continuing with port 47398. To use the running proxy, pass --port 47311 (or set HEADROOM_PORT=47311).

$ codex provider repoint
headroom: warning: cfg.toml routes Codex's [model_providers.headroom] to port 47311; repointing it to port 8787. Pass --port 47311 to keep the existing route.
```

- Not tested: the interactive TTY prompt end-to-end in a real terminal
(covered by unit tests with a stubbed prompt); a full `wrap <agent>`
launch against a real proxy; the hook JSON as rendered inside a live
Claude Code / Codex session (Codex's acceptance of
`hookSpecificOutput.additionalContext` for SessionStart is assumed to
mirror Claude's schema); Linux/macOS.

## Runtime Rollout Safety

- Rollout-managed feature(s): none (CLI only; proxy runtime untouched).
- Minimum rollout channel: Stable.
- Stable/default behavior changed: default `wrap`/`init` port now
follows `HEADROOM_PORT`; discovery only warns or prompts, never switches
ports non-interactively.
- Kill switch / disable path: `HEADROOM_PORT_DISCOVERY=0`; explicit
`--port` bypasses discovery.
- Unsafe override required: No.
- Qualification impact: None (CLI only; no proxy runtime or
qualification-gated behavior touched).
- Rollback path: revert this PR.

## Review Readiness

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

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation (CLI help
text updated; no docs pages changed)
- [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 (2
pre-existing Windows-only failures noted above)
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

Design points for review:
- `HEADROOM_PORT` is treated as an explicit choice (no
discovery/prompt), same as `--port`.
- The TTY prompt defaults to *connect* to the live proxy; non-TTY never
adopts.
- `unwrap` commands were intentionally left on their old `--port`
default: discovering a port there could stop a proxy the user did not
target.
- `wrap` subcommand `--port` now also reads `HEADROOM_PORT` via Click's
envvar, so an invalid `HEADROOM_PORT` is a usage error for `wrap`
(init/hook ignore invalid values).
- The hook reads stdin for `hook_event_name` in a daemon thread bounded
to 0.5 s so a host that never closes stdin cannot stall session start.
2026-09-29 15:02:20 -05:00