fix(grok): preserve business-seat auth while routing only inference (#2514)

## Description

`headroom wrap grok` currently routes the whole session through
`GROK_CLI_CHAT_PROXY_BASE_URL`. xAI's July 21, 2026 enterprise docs say
that host carries both inference and settings, so the wrap displaces the
native settings/auth path along with inference. A Grok account whose
SuperGrok entitlement lives on a business account can then no longer
resolve that seat and falls back to a login screen, even though native
`grok` works for the same account.

This change retargets the Grok provider slice to the narrower
inference-only key, `GROK_MODELS_BASE_URL`, and leaves
`GROK_CLI_CHAT_PROXY_BASE_URL` unset. Headroom still intercepts
inference and model discovery through the existing `/v1/models` and
chat-completions proxy paths, while the native `cli-chat-proxy.grok.com`
settings host and `auth.x.ai` auth path stay intact. Closes #2489.

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

- switch the Grok provider env authority from
`GROK_CLI_CHAT_PROXY_BASE_URL` to `GROK_MODELS_BASE_URL`
- update the Grok wrap and unwrap docstrings to describe inference-only
routing and the preserved native settings/auth path
- update the compatibility matrix entry in `README.md` so the public
docs match the new Grok routing key
- add focused provider and wrap tests that assert the old chat-proxy key
is absent and the project-prefixed inference URL is preserved
- keep `grok_build` and the existing `/v1/models` proxy route unchanged,
using them as preservation boundaries

## Testing

- [x] Unit tests pass (`uv run pytest tests/test_provider_grok.py
tests/test_cli/test_wrap_grok.py tests/test_provider_grok_build.py -q`)
- [x] Linting passes (`uv run ruff check
headroom/providers/grok/runtime.py headroom/cli/wrap.py
tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py`)
- [ ] Type checking passes (`uv run mypy headroom`)
- [x] New tests added for new functionality when applicable
- [ ] Manual testing performed

### Test Output

```text
uv run pytest tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py tests/test_provider_grok_build.py -q
uv run ruff check headroom/providers/grok/runtime.py headroom/cli/wrap.py tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py
uv run ruff format headroom/providers/grok/runtime.py headroom/cli/wrap.py tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py --check
```

## Real Behavior Proof

- Environment: current Grok CLI plus a focused Headroom worktree
- Exact command / steps: capture `grok --version`, re-check xAI's
documented Grok env contract, run the focused Grok provider and wrap
tests, and if a business-seat account is available locally launch
`headroom wrap grok` to confirm the wrapped session no longer falls back
to login
- Observed result: Headroom emits only the inference-routing key, the
old settings/auth key is absent, project prefixing still works, and the
focused Grok tests pass
- Not tested: local business-seat account on this host

## Review Readiness

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

## Checklist

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

## Screenshots (if applicable)

N/A - CLI and provider-routing change only.

## Additional Notes

- `CHANGELOG.md` stays untouched because Headroom's release automation
generates it from conventional commits.
- The issue is reporter-only today, so the proof report records the
validated `grok --version` and whether a real business-seat retest was
reached locally or remains for the reporter.

README.md

@@ -227,7 +227,7 @@ shows an **Output Tokens Saved** card next to input compression, labelled
 |--------------|:---------------:|----------------------------------|
 | Claude Code  | ✅              | `--memory` · `--code-graph` · `--1m` · `--tool-search` |
 | Codex        | ✅              | shares memory with Claude        |
-| Grok CLI     | ✅              | routes via `GROK_CLI_CHAT_PROXY_BASE_URL` |
+| Grok CLI     | ✅              | routes via `GROK_MODELS_BASE_URL` |
 | Cursor       | Manual setup    | starts proxy and prints base URLs for Cursor settings |
 | Aider        | ✅              | starts proxy + launches          |
 | Copilot CLI  | ✅              | starts proxy + launches          |

headroom/cli/wrap.py

@@ -6381,9 +6381,10 @@ def grok(
     """Launch Grok CLI through Headroom proxy.
 
     \b
-    Sets ``GROK_CLI_CHAT_PROXY_BASE_URL`` so Grok routes inference traffic
-    through Headroom. Registers the headroom MCP server in ``~/.grok/config.toml``
-    so Grok can call ``headroom_retrieve`` on compression markers.
+    Sets ``GROK_MODELS_BASE_URL`` so Grok routes inference traffic through
+    Headroom while preserving native settings and authentication routing.
+    Registers the headroom MCP server in ``~/.grok/config.toml`` so Grok can
+    call ``headroom_retrieve`` on compression markers.
 
     \b
     Examples:
@@ -8210,10 +8211,11 @@ def unwrap_omp(port: int, no_stop_proxy: bool) -> None:
 def unwrap_grok(port: int, no_stop_proxy: bool) -> None:
     """Undo durable ``headroom wrap grok`` MCP and guidance edits.
 
-    Grok API routing is session-scoped via ``GROK_CLI_CHAT_PROXY_BASE_URL`` and
-    does not require config restoration. This command removes Headroom MCP
-    servers from ``~/.grok/config.toml`` and strips injected RTK guidance from
-    the project ``AGENTS.md``.
+    Grok inference routing is session-scoped via ``GROK_MODELS_BASE_URL`` and
+    does not require config restoration. Native settings and authentication
+    routing stay unchanged. This command removes Headroom MCP servers from
+    ``~/.grok/config.toml`` and strips injected RTK guidance from the project
+    ``AGENTS.md``.
     """
     click.echo()
     click.echo("  ╔═══════════════════════════════════════════════╗")

headroom/providers/grok/runtime.py

@@ -8,7 +8,7 @@ from collections.abc import Mapping
 from headroom.proxy.project_context import with_project_prefix
 
 DEFAULT_API_URL = "https://api.x.ai"
-PROXY_ENV_KEY = "GROK_CLI_CHAT_PROXY_BASE_URL"
+PROXY_ENV_KEY = "GROK_MODELS_BASE_URL"
 
 
 def proxy_base_url(port: int) -> str:
@@ -23,9 +23,9 @@ def build_launch_env(
 ) -> tuple[dict[str, str], list[str]]:
     """Build environment variables for Grok CLI through the local proxy.
 
-    Grok routes inference traffic through ``GROK_CLI_CHAT_PROXY_BASE_URL``
-    when set (see Grok CLI auth/custom-models docs). The proxy forwards
-    OpenAI-compatible chat requests upstream to xAI.
+    Grok routes inference traffic through ``GROK_MODELS_BASE_URL`` when set.
+    The proxy forwards OpenAI-compatible chat requests upstream to xAI while
+    Grok keeps its native settings and authentication routing.
 
     ``project`` (the wrap launch directory) is encoded as a ``/p/<name>``
     base-URL prefix because Grok cannot send custom attribution headers;

tests/test_cli/test_wrap_grok.py

@@ -44,6 +44,7 @@ def test_wrap_grok_sets_proxy_env(
     env = captured["env"]
     assert isinstance(env, dict)
     assert env[PROXY_ENV_KEY] == f"http://127.0.0.1:8787{_expected_project_prefix()}/v1"
+    assert "GROK_CLI_CHAT_PROXY_BASE_URL" not in env
     assert captured["tool_label"] == "GROK"
     assert captured["agent_type"] == "grok"
     assert captured["args"] == ("-p", "hello")

tests/test_provider_grok.py

@@ -8,10 +8,11 @@ def test_grok_proxy_base_url_uses_local_headroom_proxy() -> None:
     assert proxy_base_url(8787) == "http://127.0.0.1:8787/v1"
 
 
-def test_grok_build_launch_env_sets_chat_proxy_base_url() -> None:
+def test_grok_build_launch_env_sets_models_base_url() -> None:
     env, display = build_launch_env(9999, environ={})
 
     assert env[PROXY_ENV_KEY] == "http://127.0.0.1:9999/v1"
+    assert "GROK_CLI_CHAT_PROXY_BASE_URL" not in env
     assert display == [f"{PROXY_ENV_KEY}=http://127.0.0.1:9999/v1"]
 
 
@@ -19,6 +20,7 @@ def test_grok_build_launch_env_applies_project_prefix() -> None:
     env, _display = build_launch_env(8787, environ={}, project="frontend")
 
     assert env[PROXY_ENV_KEY] == "http://127.0.0.1:8787/p/frontend/v1"
+    assert "GROK_CLI_CHAT_PROXY_BASE_URL" not in env
 
 
 def test_grok_build_install_env_returns_proxy_url() -> None: