Autocompact window guidance is wrong for 1M-context models (3 harness layers)

[BaseInfinity]

What happened

Global ~/.claude/settings.json carried CLAUDE_CODE_AUTO_COMPACT_WINDOW: "350000" (itself a replacement for an older CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "35"). On Opus 5's 1M window this made the status line report two numbers that look contradictory but are both correct:

ctx:11% (890k left)        <- measured against the real 1M window
4% until auto-compact      <- measured against the artificial 350k window

Net effect: auto-compact fires with ~650k of usable context unused. Both knobs only ever move compaction earlier — neither raises real capacity. Removed from layer 1 on 2026-08-08.

The three layers need three different answers

Layer 1 — user global (~/.claude/settings.json) — RESOLVED. Override removed; auto-compact now uses the model's real window.

Layer 2 — this meta-repo (.claude/settings.json) — OPEN. This repo has no env block at all today. Question: does a repo whose sessions routinely hold a Codex review, a Fable review, a full diff, and a 73-suite sweep want an explicit setting? Note the only available direction is earlier compaction, so the answer is plausibly "still nothing" — but it should be a decision, not an accident.

Layer 3 — what the wizard ships (CLAUDE_CODE_SDLC_WIZARD.md) — OPEN, and the real defect. Lines ~1044-1049 and ~1118 document both env vars and correctly warn "Do NOT set both." What they do NOT say is that on a 1M-context model you should set neither — the guidance reads as if picking one is the right move. A consumer following it on Opus 5 reproduces exactly the misconfiguration above. skills/sdlc/SKILL.md also pairs CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30 with a claude-opus-4-6 pin, same trap.

Proposed fix (layer 3)

Add an explicit "on a 1M-context model, set neither" line, and reframe the existing text so the vars are presented as narrowing tools for small-window pins (e.g. opusplan at 200K), never as tuning for large windows.

Constraints

• Layer 3 is a shipped-doc change: TDD RED/GREEN + full cross-model round required.
• skills/sdlc/SKILL.md is at 19,356 / 20,000 bytes — any addition there needs an equal-or-greater trim.

[BaseInfinity]

Live reproduction on 2026-08-08 — the two knobs multiply, and that is the part the wizard doc never says.

Observed in-session env:

CLAUDE_CODE_AUTO_COMPACT_WINDOW=350000
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=35

WINDOW replaces the real 1M window with a fake 350k one; PCT_OVERRIDE then fires at 35% of that fake window — 350,000 × 0.35 = 122,500 tokens. The statusline reads the real window (ctx:11%, 890k left) while autocompact measures the overridden one, so the user sees compaction fire with 890k free. Two correct numbers on different denominators.

Consequences for this issue:

1. Neither var raises capacity. Both only ever move compaction earlier. On a 1M-context model the correct setting for both is unset (default ≈95% of the real window).
2. Removing one is not a fix. That mistake was already made here — PCT_OVERRIDE was swapped for WINDOW, i.e. one early-compaction knob for the documented version of the same knob. Layer-2/3 guidance must say set neither, not tune one.
3. Env is read into the process at launch. Editing settings.json mid-session changes nothing; the fix requires a new process (claude --resume preserves the transcript). Any guidance we ship needs that caveat or people will edit the file, see no change, and conclude the setting does not work.
4. Diagnosis order (settings file is NOT the authority — the live env is): env | grep -iE "compact|CLAUDE_CODE" → ~/.claude/settings.json env block → settings.local.json / ~/.claude.json → shell rc → launchctl getenv.

The existing skills/sdlc/SKILL.md line pairing CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30 with a claude-opus-4-6 pin is the only place either var is mentioned, and it is silent on the multiplication and on the launch-time read. Both belong in whatever this issue ships.

[BaseInfinity]

Verified against decompiled Claude Code v2.1.221 — corrects my earlier comment

Fable disassembled the installed binary (~/.local/share/claude/versions/2.1.221), functions EX, CCo, F0s, fEe, ZJu, VJu, kO. This replaces the behaviour-inferred version above.

Mechanism confirmed, arithmetic corrected. EX(): window = min(model_window, clamp(WINDOW_env, 100k..1M)). CCo(): threshold = min(floor(window × pct/100), window − 13000). fEe() subtracts up to 20k system overhead first, so with WINDOW=350000 + PCT_OVERRIDE=35 the real trigger is floor((350000−20000) × 0.35) ≈ 115,500, not the 122,500 I stated. PCT_OVERRIDE is unambiguously % used (Math.floor(e*(n/100)) compared against tokens used).

Three corrections that matter for what we ship to consumers:

1. WINDOW in the 100k–199k range silently disables autocompact entirely. ZJu returns false unconditionally for any non-auto window below bIe = 200000. This is a live footgun — a consumer trying to be conservative by setting a small window gets no autocompact at all. Any guidance we ship must name this range explicitly.

2. "Env can only lower capacity" is not absolute. VJu gives claude-sonnet-5 an auto default of 967,000 (and 500,000 on remote-cowork / local-agent surfaces). So WINDOW=1000000 genuinely raises it by 33k on Sonnet 5, and by 500k on the cowork surface. Tuning is real there and pointless on a 1M Opus — which is exactly the layer-2 vs layer-3 distinction this issue is about. Per-surface, not one number.

3. Drop the "~95% default" figure. Hard compact is window − 13000 (~98.7%); the precompute arm F0s fires at window × 0.8 via constant $0s = 0.2, which is experiment-tunable and therefore not safe to document as a fixed number.

Mid-session recovery — new and useful. Env vars cannot be unset in a live process (removing the key from settings.json has no unset mechanism; the /config screen hard-codes "CLAUDE_CODE_AUTO_COMPACT_WINDOW is set and takes precedence. Unset it to change this setting here"). But kO() reads autoCompactEnabled live, so autoCompactEnabled: false — via settings.json, /config, or DISABLE_AUTO_COMPACT=1 — stops premature compaction without a restart. Cost: the session runs to the hard blocking limit instead of compacting. Interim only; claude --resume remains the real fix.

Implication for layers 2 and 3: we should ship no WINDOW value at all as a default, plus a named warning about the sub-200k trap, plus the autoCompactEnabled escape hatch for the stuck-session case. A single recommended number is wrong because the auto default is already per-model and per-surface.

Caveat carried honestly: "statusline reads the real window" is consistent with the observation but the statusline code path was not traced.