headroom-desktop: Instructions file for Claude Code

CLAUDE.md - headroom-desktop

This file holds only what the model cannot derive: project invariants, environment quirks, and concrete commands. Generic coding-style coaching (write simply, read before editing, state the bug and stop) was removed on 2026-08-03 — modern models do it unprompted and the harness enforces the rest. Do not re-add it.

Testing Rules

• After any code change, run the relevant tests/checks before declaring the task done. Do not ask the user to verify.
• Rust changes: cargo test --manifest-path src-tauri/Cargo.toml --lib <filter> for the affected module, plus cargo check --manifest-path src-tauri/Cargo.toml if the change crosses module boundaries.
• Frontend changes: npx tsc --noEmit and any relevant Vitest suite. For visual changes, see Styling Rules.
• If a test cannot be run in this environment, say so explicitly rather than skipping silently.

Wheel Bump Rules

• Before changing HEADROOM_PINNED_VERSION: diff upstream savings_tracker.py, prometheus_metrics.py, and server.py between the old and new pins, and check every consumed field against stats_contract_pins_every_consumed_path in state.rs. Upstream has silently redefined persisted savings fields before (0.36.0 widened compression_savings_usd); the savings-rate canary in state.rs is the runtime tripwire, this diff is the compile-time one.
• Re-pick every platform's wheel URL/sha256 when bumping (see the pin comment in tool_manager.rs).
• Diff rollout.py's FEATURES registry between the old and new pins. The app declares HEADROOM_ROLLOUT_CHANNEL=beta (tool_manager.rs), so any new feature with default_enabled_in at or below beta auto-enables for every user on the bump; any feature the app requests whose available_in moved above beta silently turns off (this is how 0.37.0 disabled the output shaper on stable).
• Diff headroom/transforms/ between the pins. This is the compression ENGINE and nothing else in these rules covers it; the 0.35.0 -> 0.37.0 bump changed it by +421 lines and shipped unexamined. Diff it, but do NOT assume a diff means a behaviour change. Bisected 2026-09-02 with a fixed workload replayed on both wheels installed from PyPI (uv venv + uv pip install headroom-ai==<v>, about 3s per version): ContentRouter.compress() AND the full ContentRouter.apply() path returned BYTE-IDENTICAL output on 0.35.0 and 0.37.0 (tok_before 62,384 -> tok_after 57,068, identical transforms list, on both). The engine is EXONERATED. The real production drop (fable-5 500k+: 4.64% / 25,631 tokens per request down to 0.45% / 2,463 at matched model and size) is therefore caused by the INPUT reaching the compressor, not the compressor. Six hypotheses are refuted and must not be restated as fact: the prefix-replay guard (identical on full-replay and floor builds), workload/model mix (matched), the TTL-aware net-cost gate (flag-gated behind HEADROOM_NET_COST_POLICY=1, not set, zero netcost:skip markers across 925 requests), protection rate (0.35 vs 0.32 per request), router acceptance thresholds (min_ratio_* identical), and content granularity (today's messages are BIGGER, 3,053 vs 1,982 tok/msg, which should compress better). What the router logs do show: more messages compressed per request (4.0 -> 5.1) each yielding far less, at an unchanged frozen fraction (86.8% -> 85.2%). Investigate session shape next, not the wheel.
• The #3380 prefix-floor vendor is exact-pin gated to wheel 0.37.0. Any bump makes it INERT, silently: replay falls back to the full-replay guard, compression drops by roughly half (measured 13,568 -> 6,831 tokens/request on the 0.9.4->0.9.5 swap), and nothing errors. So on every bump, check whether the new wheel actually carries #3380: if it does, delete the vendor; if it does not, re-pin the vendor to the new version and re-run cargo test --manifest-path src-tauri/Cargo.toml --lib vendored_prefix_floor against the installed runtime. That test self-skips when the vendor does not bind, so a green suite is NOT evidence the floor still works after a bump.
• Three more 0.37.0-pinned vendors live in the same sitecustomize (upstream PRs #3482 thinking signatures, #3483 fresh cache_control, #3484 Kompress marker gate; kill switches HEADROOM_THINKING_SIG_TOKENS, HEADROOM_FRESH_CC_COMPRESS, HEADROOM_KOMPRESS_MARKER_GATE; probe scripts/verify-compression-vendors.py, test compression_vendors_behave_against_the_installed_wheel). On a bump, diff tokenizers/base.py (thinking branch), the router's cache_control skip, and the Kompress marker gate against the new wheel: drop each vendor the wheel carries, re-pin the rest. The probe self-skips when a vendor does not bind, so green is not evidence.
• When a wheel ships upstream #3460 (conversation clusters in the output-savings ledger), purge BOTH ledger arms once on that bump: extend ledger_bytes_without_control (tool_manager.rs) to treatment under a new stamp. Legacy accumulators carry no clusters so they cannot clear the 5-conversation gate, but the moment new records add clusters the whole accumulator, old requests included, re-enters the mean. Treatment has also accrued since 2026-07 while control was purged 2026-08-19, so the arms describe different months until both restart together. Also drop the holdout boost (output_holdout_for) back to a flat 3% only if the fleet's measured coverage says so; it is evidence-gated per machine on purpose.