fix: remove rtk and lean-ctx CLI context tools (#2677)

## Description

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

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

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

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

## Type of Change

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

## Changes Made

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

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

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

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

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

## Testing

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

### Test Output

```text
$ ruff check headroom/ tests/ e2e/ --exclude headroom/dashboard/templates
All checks passed!

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

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

$ pytest tests/test_context_tool_cleanup.py -q
11 passed

$ pytest tests/test_fsutil.py -q
12 passed

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

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

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

## Real Behavior Proof

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

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

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

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

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

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

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

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

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

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

## Review Readiness

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

## Checklist

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

## Additional Notes

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

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

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

**Follow-ups not in scope:** `_emit_wrap_interrupted` was deleted as
dead code — its only caller was the `except KeyboardInterrupt` guarding
the binary download, so with no download there is nothing slow left to
interrupt.
This commit is contained in:
Tejas Chopra 2026-07-30 22:59:41 -07:00 committed by GitHub
parent 759209cff3
commit e0ce4b1d48
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
101 changed files with 1546 additions and 8746 deletions

View file

@ -87,11 +87,6 @@ function Require-Command {
}
}
function Get-RtkTarget {
$arch = if ($env:PROCESSOR_ARCHITECTURE -match 'ARM64') { 'aarch64' } else { 'x86_64' }
return "${arch}-pc-windows-msvc"
}
function Ensure-HostDirs {
foreach ($dir in @(
(Join-Path $HostHome '.headroom'),
@ -825,52 +820,6 @@ function Parse-InstallProfileArgs {
return $profile
}
function Invoke-ClaudeRtkInit {
$rtkPath = Join-Path $HostHome '.headroom\bin\rtk.exe'
if (-not (Test-Path $rtkPath)) {
Write-Warning "rtk was not installed at $rtkPath; Claude hooks were not registered"
return
}
try {
& $rtkPath init --global --auto-patch | Out-Null
} catch {
Write-Warning "Failed to register Claude hooks with rtk; continuing without hook registration"
}
}
function Get-ContextTool {
$value = $env:HEADROOM_CONTEXT_TOOL
if ([string]::IsNullOrWhiteSpace($value)) {
return 'rtk'
}
$value = $value.Trim().ToLowerInvariant().Replace('_', '-')
if ($value -eq 'leanctx') {
return 'lean-ctx'
}
if ($value -ne 'rtk' -and $value -ne 'lean-ctx') {
Fail 'HEADROOM_CONTEXT_TOOL must be one of: lean-ctx, rtk'
}
return $value
}
function Invoke-LeanCtxInit {
param([string]$Agent)
$cmd = Get-Command lean-ctx -ErrorAction SilentlyContinue
if (-not $cmd) {
Write-Warning "lean-ctx is not installed on PATH; $Agent lean-ctx setup was skipped"
return
}
try {
& $cmd.Source init --agent $Agent | Out-Null
} catch {
Write-Warning "Failed to initialize lean-ctx for $Agent; continuing without lean-ctx setup"
}
}
function Invoke-WithTemporaryEnv {
param(
[hashtable]$Environment,
@ -1399,7 +1348,6 @@ function Parse-WrapArgs {
$known = New-Object System.Collections.Generic.List[string]
$hostArgs = New-Object System.Collections.Generic.List[string]
$port = 8787
$noRtk = $false
$noProxy = $false
$learn = $false
$backend = $null
@ -1431,12 +1379,6 @@ function Parse-WrapArgs {
$i += 1
continue
}
'^--no-rtk$' {
$noRtk = $true
$known.Add($arg)
$i += 1
continue
}
'^--no-proxy$' {
$noProxy = $true
$known.Add($arg)
@ -1496,6 +1438,13 @@ function Parse-WrapArgs {
$i += 1
continue
}
'^--rtk$|^--no-rtk$|^--no-project-rtk$|^--keep-rtk$|^--context-tool$|^--context-tool=|^--no-context-tool$' {
# Retired CLI context tools (rtk, lean-ctx). Reject explicitly: the
# default branch below forwards the first unknown flag AND everything
# after it to the wrapped tool, so a leftover --no-rtk in a script
# would silently swallow a following --port and be ignored downstream.
Fail "CLI context tools (rtk, lean-ctx) have been removed from Headroom. Drop $arg and unset HEADROOM_CONTEXT_TOOL; 'headroom wrap' uninstalls what they left behind on first run."
}
default {
for ($j = $i; $j -lt $Arguments.Count; $j++) {
$hostArgs.Add($Arguments[$j])
@ -1509,7 +1458,6 @@ function Parse-WrapArgs {
KnownArgs = $known.ToArray()
HostArgs = $hostArgs.ToArray()
Port = $port
NoRtk = $noRtk
NoProxy = $noProxy
Learn = $learn
Backend = $backend
@ -1528,8 +1476,6 @@ function Invoke-PrepareOnly {
$dockerArgs.AddRange([string[]]@('run','--rm'))
Add-TtyArgs -ArgsList $dockerArgs
$dockerArgs.AddRange((Get-SharedDockerArgs))
$dockerArgs.Add('--env')
$dockerArgs.Add("HEADROOM_RTK_TARGET=$(Get-RtkTarget)")
$dockerArgs.Add('--entrypoint')
$dockerArgs.Add('headroom')
$dockerArgs.Add($HeadroomImage)
@ -1647,7 +1593,6 @@ switch ($args[0]) {
}
$parsed = Parse-WrapArgs -Arguments $wrapArgs
$contextTool = Get-ContextTool
$proxyArgs = New-Object System.Collections.Generic.List[string]
if ($parsed.Learn) { $proxyArgs.Add('--learn') }
if ($parsed.Backend) { $proxyArgs.AddRange([string[]]@('--backend', $parsed.Backend)) }
@ -1667,20 +1612,10 @@ switch ($args[0]) {
if (-not $parsed.NoProxy) {
$prepareArgs.Add('--no-proxy')
}
if ((-not $parsed.NoRtk) -and $contextTool -eq 'lean-ctx') {
$prepareArgs.Add('--no-rtk')
}
Invoke-PrepareOnly -Tool $tool -KnownArgs $prepareArgs.ToArray()
if ((-not $parsed.NoRtk) -and $contextTool -eq 'lean-ctx') {
Invoke-LeanCtxInit -Agent $tool
}
switch ($tool) {
'claude' {
if ((-not $parsed.NoRtk) -and $contextTool -eq 'rtk') {
Invoke-ClaudeRtkInit
}
$exitCode = Invoke-WithTemporaryEnv -Environment @{ ANTHROPIC_BASE_URL = "http://127.0.0.1:$($parsed.Port)" } -Command 'claude' -Arguments $parsed.HostArgs
exit $exitCode
}

View file

@ -82,33 +82,6 @@ require_cmd() {
command -v "$1" >/dev/null 2>&1 || die "Missing required command: $1"
}
detect_rtk_target() {
local system
local machine
system="$(uname -s)"
machine="$(uname -m)"
case "${system}" in
Darwin)
if [[ "${machine}" == "arm64" ]]; then
printf 'aarch64-apple-darwin'
else
printf 'x86_64-apple-darwin'
fi
;;
Linux)
if [[ "${machine}" == "aarch64" ]]; then
printf 'aarch64-unknown-linux-gnu'
else
printf 'x86_64-unknown-linux-musl'
fi
;;
*)
die "Unsupported host platform for Docker-native wrapper: ${system}/${machine}"
;;
esac
}
ensure_host_dirs() {
mkdir -p \
"${HEADROOM_HOST_HOME}/.headroom" \
@ -785,66 +758,20 @@ parse_install_profile_arg() {
done
}
run_claude_rtk_init() {
local rtk_bin="${HEADROOM_HOST_HOME}/.headroom/bin/rtk"
if [[ ! -x "${rtk_bin}" ]]; then
warn "rtk was not installed at ${rtk_bin}; Claude hooks were not registered"
return
fi
if ! "${rtk_bin}" init --global --auto-patch >/dev/null 2>&1; then
warn "Failed to register Claude hooks with rtk; continuing without hook registration"
fi
}
selected_context_tool() {
local value="${HEADROOM_CONTEXT_TOOL:-rtk}"
value="${value,,}"
value="${value//_/-}"
if [[ -z "${value}" ]]; then
value="rtk"
elif [[ "${value}" == "leanctx" ]]; then
value="lean-ctx"
fi
case "${value}" in
rtk|lean-ctx)
printf '%s\n' "${value}"
;;
*)
die "HEADROOM_CONTEXT_TOOL must be one of: lean-ctx, rtk"
;;
esac
}
run_lean_ctx_init() {
local agent="$1"
if ! command -v lean-ctx >/dev/null 2>&1; then
warn "lean-ctx is not installed on PATH; ${agent} lean-ctx setup was skipped"
return
fi
if ! lean-ctx init --agent "${agent}" >/dev/null 2>&1; then
warn "Failed to initialize lean-ctx for ${agent}; continuing without lean-ctx setup"
fi
}
parse_wrap_args() {
local -n out_known=$1
local -n out_host=$2
local -n out_port=$3
local -n out_no_rtk=$4
local -n out_no_proxy=$5
local -n out_learn=$6
local -n out_backend=$7
local -n out_anyllm=$8
local -n out_region=$9
shift 9
local -n out_no_proxy=$4
local -n out_learn=$5
local -n out_backend=$6
local -n out_anyllm=$7
local -n out_region=$8
shift 8
out_known=()
out_host=()
out_port=8787
out_no_rtk=0
out_no_proxy=0
out_learn=0
out_backend=""
@ -871,11 +798,6 @@ parse_wrap_args() {
out_known+=("$1")
shift
;;
--no-rtk)
out_no_rtk=1
out_known+=("$1")
shift
;;
--no-proxy)
out_no_proxy=1
out_known+=("$1")
@ -923,6 +845,13 @@ parse_wrap_args() {
out_known+=("$1")
shift
;;
--rtk|--no-rtk|--no-project-rtk|--keep-rtk|--context-tool|--no-context-tool|--context-tool=*)
# Retired CLI context tools (rtk, lean-ctx). Reject explicitly: the
# catch-all below forwards the first unknown flag AND everything after it
# to the wrapped tool, so a leftover --no-rtk in a script would silently
# swallow a following --port and be ignored by the wrapped CLI.
die "CLI context tools (rtk, lean-ctx) have been removed from Headroom. Drop $1 and unset HEADROOM_CONTEXT_TOOL; 'headroom wrap' uninstalls what they left behind on first run."
;;
*)
out_host+=("$@")
break
@ -939,7 +868,6 @@ run_prepare_only() {
args=(docker run --rm)
append_tty_args args
append_common_container_args args
args+=(--env "HEADROOM_RTK_TARGET=$(detect_rtk_target)")
args+=(--entrypoint headroom "${HEADROOM_IMAGE}" wrap "${tool}" --prepare-only "$@")
"${args[@]}"
}
@ -1502,9 +1430,8 @@ main() {
return
fi
local known_args host_args port no_rtk no_proxy learn backend anyllm region context_tool
parse_wrap_args known_args host_args port no_rtk no_proxy learn backend anyllm region "$@"
context_tool="$(selected_context_tool)"
local known_args host_args port no_proxy learn backend anyllm region
parse_wrap_args known_args host_args port no_proxy learn backend anyllm region "$@"
local proxy_args=()
if [[ "${learn}" -eq 1 ]]; then
@ -1530,20 +1457,10 @@ main() {
if [[ "${no_proxy}" -eq 0 ]]; then
prep_args+=(--no-proxy)
fi
if [[ "${no_rtk}" -eq 0 && "${context_tool}" == "lean-ctx" ]]; then
prep_args+=(--no-rtk)
fi
run_prepare_only "${tool}" "${prep_args[@]}"
if [[ "${no_rtk}" -eq 0 && "${context_tool}" == "lean-ctx" ]]; then
run_lean_ctx_init "${tool}"
fi
case "${tool}" in
claude)
if [[ "${no_rtk}" -eq 0 && "${context_tool}" == "rtk" ]]; then
run_claude_rtk_init
fi
ANTHROPIC_BASE_URL="http://127.0.0.1:${port}" run_host_tool claude "${host_args[@]}"
;;
codex)