claude-token-saver 3.7.0 → 3.8.1

package/README.en.md

@@ -86,6 +86,7 @@ Run these in your shell (inside Claude Code, the `/claude-token-saver` Skill is
 | `claude-token-saver mode [keywords...]` | Output config (`icon`/`text`, `en`/`ko`, `1h`–`30d` window, …) |
 | `claude-token-saver harness ...` | 🅷 Harness management (below) |
 | `claude-token-saver route-scan` | Detect recurring easy work on expensive models → propose haiku-delegation ratchet rules (below) |
+| `claude-token-saver compact-window` | Warn when a 1M-context session has no auto-compact cap → pin 400k with `set` (below) |
 | `claude-token-saver install` | Manually register Skill + statusline |
 
 Switch output language with `mode ko` / `mode en` (English default; statusline chips stay symbolic).
@@ -141,6 +142,25 @@ An auto `.bak` is kept, but **the session context that earned the rule its place
 </details>
 
 
+## 📦 compact-window — pin where a 1M session compacts
+
+Claude Code compacts when usage approaches `min(autoCompactWindow, model max context)`. On a 1M window, with that value unset, compaction only fires near 800k — and until then every request re-bills the whole context. Pinning 400k keeps twice a 200k session's headroom for the genuinely large pastes while cutting off the runaway tail.
+
+**200k sessions are never warned** — their window is already at or below 200k, so the setting cannot change anything.
+
+```bash
+claude-token-saver compact-window                       # status (model, window, value, source)
+claude-token-saver compact-window set --global          # pin 400k in ~/.claude/settings.json
+claude-token-saver compact-window set --project         # pin it in <root>/.claude/settings.json
+claude-token-saver compact-window set --global --value 250k   # explicit value (100k–1M)
+claude-token-saver compact-window off | on              # toggle the warning
+```
+
+- On a 1M model with the value unset or above 400k, the statusline shows `🅷⚠ compact-window?` and the session briefing hands the model the exact registration command.
+- Scope (`--global`/`--project`) is **required** for `set` — a global settings file is never edited on a guess.
+- Every other key in `settings.json` is preserved and a `.bak` is written first. Malformed JSON aborts the write untouched.
+- An exported `CLAUDE_CODE_AUTO_COMPACT_WINDOW` beats settings.json; `set` detects that and says so.
+
 ## 🔀 route-scan — "this recurring task could run on a cheaper tier"
 
 Finds the easy work your expensive model (opus/fable) keeps redoing in your session logs and proposes **haiku/sonnet delegation rules**. Fully local, zero token cost.
@@ -243,6 +263,12 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.8.1 (2026-07-31)
+- **Fixed: 1M sessions were judged against a 200k window** — the briefing inferred the window from the largest request seen so far, so a 1M session counted as 200k until it had already grown past 250k. At 160k of input it announced "past 80% of the 200k window" — really 16%. The window now comes from the configured model id, and when `autoCompactWindow` is set that is where the session actually turns over, so the percentage is measured against it (the text says `(autoCompactWindow 기준)`). The observed-size heuristic remains only as the fallback for an unreadable model id.
+
+### v3.8.0 (2026-07-31)
+- **New `compact-window` — 1M sessions had no compaction cap** — Claude Code compacts near `min(autoCompactWindow, model max context)`. On a 1M window with that value unset, compaction only fires around 800k, and every request until then re-bills the entire context. A 1M model with the value unset or above 400k now raises `🅷⚠ compact-window?` on the statusline plus a session briefing, and `compact-window set --global|--project` pins 400k. 200k sessions are exempt — the setting cannot change anything for them.
+
 ### v3.7.0 (2026-07-29)
 - **Fixed: delegation rules named subagents that may not exist** — generated T2 rules hard-coded preset names like `haiku-explore` / `haiku-runner`, which live in each user's own `~/.claude/agents/` and are not shipped by this package. On a machine without them, the rule told the model to delegate to a nonexistent agent. The default phrasing is now `model: haiku` (matching T1's `model: sonnet`), and the name is added only when the agent file is really present, e.g. `haiku-explore(model: haiku)`. Project-level `.claude/agents/` counts too. `ratchet-model.md` re-renders with the new phrasing on the next `route-scan`.
 

package/README.md

@@ -86,6 +86,7 @@ Claude 안에서 `/claude-token-saver` Skill을 실행하거나 칩 문구를
 | `claude-token-saver mode [keywords...]` | 출력 설정 (`icon`/`text`, `ko`/`en`, `1h`~`30d` 윈도 등) |
 | `claude-token-saver harness ...` | 🅷 Harness 관리 (아래 참고) |
 | `claude-token-saver route-scan` | 상위 모델이 반복 처리한 easy 작업 감지 → haiku 위임 랫쳇 룰 제안 (아래 참고) |
+| `claude-token-saver compact-window` | 1M 컨텍스트인데 자동 압축 창이 안 잡혀 있으면 경고 → `set`으로 40만 고정 (아래 참고) |
 | `claude-token-saver install` | Skill·statusline 수동 등록 |
 
 출력 언어는 `mode ko` / `mode en`으로 전환합니다 (기본 영어, statusline 칩은 항상 기호). 전체 옵션은 [영문 README](./README.en.md#options) 참고.
@@ -122,6 +123,25 @@ ratchet의 가치는 **한 방향 누적**에 있습니다. 룰을 가볍게 지
 </details>
 
 
+## 📦 compact-window — 1M 컨텍스트의 자동 압축 지점 고정
+
+Claude Code는 `min(autoCompactWindow, 모델 최대 창)`에 가까워지면 대화를 자동 압축합니다. 1M 창을 쓰면 이 값이 잡혀 있지 않은 한 80만 토큰 근처까지 가서야 압축이 걸리고, 그전까지 모든 요청이 전체 컨텍스트를 통째로 재과금합니다. 40만으로 고정하면 큰 붙여넣기용 여유는 200k 세션의 두 배로 남기면서 꼬리만 잘라냅니다.
+
+**200k 컨텍스트는 경고 대상이 아닙니다** — 창이 이미 200k 이하라 이 설정이 바꿀 게 없습니다.
+
+```bash
+claude-token-saver compact-window                       # 현재 상태 (모델·창·설정값·출처)
+claude-token-saver compact-window set --global          # ~/.claude/settings.json 에 40만 고정
+claude-token-saver compact-window set --project         # <root>/.claude/settings.json 에 고정
+claude-token-saver compact-window set --global --value 250k   # 값 직접 지정 (10만~1M)
+claude-token-saver compact-window off | on              # 경고 표시 토글
+```
+
+- 1M 모델인데 미설정이거나 40만을 넘으면 statusline에 `🅷⚠ compact-window?`가 뜨고, 세션 브리핑이 등록 명령까지 알려줍니다.
+- 스코프(`--global`/`--project`)는 `set`에서 **필수** — 글로벌 설정 파일을 묻지 않고 고치지 않기 위한 설계입니다.
+- 기존 `settings.json`의 다른 키는 그대로 보존하고 `.bak`을 남깁니다. JSON이 깨져 있으면 아무것도 쓰지 않고 중단합니다.
+- 셸에 `CLAUDE_CODE_AUTO_COMPACT_WINDOW`가 export돼 있으면 그쪽이 settings.json보다 우선합니다 (`set`이 이 경우를 감지해 알려줍니다).
+
 ## 🔀 route-scan — "이 반복 작업, 더 싼 티어로 내려도 됩니다"
 
 세션 로그에서 상위 모델(opus/fable)이 반복 처리해 온 쉬운 작업을 찾아 **haiku/sonnet 위임 룰로 승격**을 제안합니다. 전 과정 로컬, 토큰 비용 0.
@@ -200,6 +220,12 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.8.1 (2026-07-31)
+- **1M 세션을 200k 창으로 오판하던 브리핑 버그 수정** — 세션 창을 "지금까지 본 가장 큰 요청"으로 추정해서, 1M 세션이라도 25만 토큰을 넘기 전까지는 200k로 취급했습니다. 그래서 입력 160k에서 "200k 창의 80%를 넘었습니다" 경고가 떴습니다(실제로는 16%). 이제 설정된 모델 ID로 창을 판정하고, `autoCompactWindow`가 잡혀 있으면 그 값이 실제로 세션이 넘어가는 지점이므로 그쪽을 기준으로 %를 계산합니다(문구에도 `(autoCompactWindow 기준)` 표기). 모델 ID를 못 읽는 경우에만 기존 관측치 추정으로 되돌아갑니다.
+
+### v3.8.0 (2026-07-31)
+- **`compact-window` 추가 — 1M 컨텍스트에서 자동 압축 지점이 방치되던 문제** — Claude Code는 `min(autoCompactWindow, 모델 최대 창)` 근처에서 압축합니다. 1M 창을 쓰면 이 값을 안 잡는 한 80만 토큰까지 커진 뒤에야 압축이 걸리고, 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 이제 1M 모델인데 미설정이거나 40만 초과면 statusline `🅷⚠ compact-window?` + 세션 브리핑으로 알리고, `compact-window set --global|--project`로 40만을 고정합니다. 200k 컨텍스트는 설정이 영향을 주지 않으므로 경고 대상에서 제외합니다.
+
 ### v3.7.0 (2026-07-29)
 - **위임 룰이 없는 서브에이전트를 가리키던 문제 수정** — 생성되는 T2 룰이 `haiku-explore`·`haiku-runner` 같은 이름을 직접 적었는데, 이 preset 에이전트들은 각자의 `~/.claude/agents/`에 있는 것이라 패키지가 배포하지 않습니다. 그래서 해당 파일이 없는 환경에서는 "존재하지 않는 에이전트로 위임하라"는 룰이 자동 생성됐습니다. 이제 기본 표현은 `model: haiku`(T1의 `model: sonnet`과 통일)이고, 에이전트 파일이 실제로 있을 때만 `haiku-explore(model: haiku)`처럼 이름을 병기합니다. 프로젝트 `.claude/agents/`도 인식합니다. 다음 `route-scan` 때 `ratchet-model.md`가 새 표현으로 다시 렌더됩니다.
 

package/bin/cli.js

@@ -145,6 +145,17 @@ async function main() {
     return (await import('../src/commands/harness.js')).run({ args, hasFlag });
   }
 
+  // Subcommand: compact-window — audit / pin Claude Code's autoCompactWindow.
+  // On a 1M-context model, compaction only fires near 800k unless the window is
+  // capped; 200k sessions are exempt.
+  //   claude-token-saver compact-window                  # status
+  //   claude-token-saver compact-window set --global     # pin 200k (~/.claude/settings.json)
+  //   claude-token-saver compact-window set --project    # pin 200k (<root>/.claude/settings.json)
+  //   claude-token-saver compact-window off | on         # toggle the statusline warning
+  if (args[0] === 'compact-window') {
+    return (await import('../src/commands/compact-window.js')).run({ args, hasFlag });
+  }
+
   // Hook management
   if (hasFlag('--install-hook')) {
     const { installHook } = await import('../src/hook-manager.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {

package/src/brief.js

@@ -28,6 +28,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
+import { resolveModelId, isOneMillionModel, effectiveWindow } from './compact-window.js';
 
 // Context tiers as a fraction of the session's context window. Tier 1 warns
 // (compaction/cost territory ahead), tier 2 urges wrapping up. A session only
@@ -36,7 +37,9 @@ export const CTX_TIERS = [
   { tier: 1, pct: 0.8 },
   { tier: 2, pct: 0.95 },
 ];
-// Requests above this input size can only exist on a 1M window.
+// Requests above this input size can only exist on a 1M window. Used as a
+// fallback signal only — a 1M session that has not yet grown past 250k is
+// still a 1M session, so the configured model decides first (see sessionCtx).
 const WINDOW_1M_MIN_INPUT = 250_000;
 const PRUNE_MS = 7 * 24 * 60 * 60 * 1000;
 const TAIL_BYTES = 256 * 1024;
@@ -67,11 +70,40 @@ function saveState(state, now) {
   writeFileSync(briefStatePath(), JSON.stringify(state) + '\n');
 }
 
+/**
+ * The window a tier crossing should be measured against.
+ *
+ * Two corrections over "infer from the biggest request seen":
+ *  - The configured model decides the ceiling. A 1M session that has not yet
+ *    grown past 250k is still a 1M session; judging it against 200k fired the
+ *    80% warning at 160k, less than a fifth of the real window.
+ *  - `autoCompactWindow` lowers that ceiling. Once compaction is pinned at
+ *    400k, 400k — not 1M — is where the session actually turns over, so that
+ *    is the number a "you are at 80%" warning has to mean.
+ *
+ * `observedMax` stays as a floor: it proves a 1M window even when the model id
+ * is unreadable (env override, settings we do not resolve).
+ */
+export function ctxWindowFor(observedMax = 0, root = process.cwd()) {
+  let window = observedMax > WINDOW_1M_MIN_INPUT ? 1_000_000 : 200_000;
+  let compactCapped = false;
+  try {
+    const { model } = resolveModelId(root);
+    if (isOneMillionModel(model)) window = 1_000_000;
+    const cap = effectiveWindow(root).value;
+    if (cap !== null && cap < window) {
+      window = cap;
+      compactCapped = true;
+    }
+  } catch { /* settings unreadable — the observed-size fallback still holds */ }
+  return { window, compactCapped };
+}
+
 /**
  * Last request's input size for THIS session, from the transcript tail.
  * Reads at most TAIL_BYTES — prompt-submit hooks must stay fast.
  */
-export function sessionCtx(transcriptPath) {
+export function sessionCtx(transcriptPath, { root = process.cwd() } = {}) {
   let size;
   try { size = statSync(transcriptPath).size; } catch { return null; }
   const start = Math.max(0, size - TAIL_BYTES);
@@ -97,8 +129,8 @@ export function sessionCtx(transcriptPath) {
     if (total > 0) { input = total; maxInput = Math.max(maxInput, total); }
   }
   if (input == null) return null;
-  const window = maxInput > WINDOW_1M_MIN_INPUT ? 1_000_000 : 200_000;
-  return { input, window, pct: input / window };
+  const { window, compactCapped } = ctxWindowFor(maxInput, root);
+  return { input, window, compactCapped, pct: input / window };
 }
 
 function ctxTierOf(pct) {
@@ -144,10 +176,14 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
   if (ctx) {
     const tier = ctxTierOf(ctx.pct);
     if (tier > (s.ctxTier || 0)) {
-      const winLabel = ctx.window >= 1_000_000 ? '1M' : '200k';
+      // Name the window the percentage was actually computed against — when
+      // autoCompactWindow caps a 1M model at 400k, "1M 창의 80%" would be a
+      // number the user cannot reconcile with anything they configured.
+      const winLabel = ctx.window >= 1_000_000 ? '1M' : fmtK(ctx.window);
+      const capNote = ctx.compactCapped ? ' (autoCompactWindow 기준)' : '';
       items.push(tier === 2
-        ? `이 세션의 컨텍스트가 ${winLabel} 창의 95%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 곧 자동 압축으로 맥락 손실이 생길 수 있으니, 진행 중인 작업을 일단락하고 새 세션을 시작하는 편이 좋습니다.`
-        : `이 세션의 컨텍스트가 ${winLabel} 창의 80%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 이후 요청은 비용이 커지는 구간입니다 — 작업이 일단락되면 새 세션 시작을 권합니다.`);
+        ? `이 세션의 컨텍스트가 ${winLabel} 창${capNote}의 95%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 곧 자동 압축으로 맥락 손실이 생길 수 있으니, 진행 중인 작업을 일단락하고 새 세션을 시작하는 편이 좋습니다.`
+        : `이 세션의 컨텍스트가 ${winLabel} 창${capNote}의 80%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 이후 요청은 비용이 커지는 구간입니다 — 작업이 일단락되면 새 세션 시작을 권합니다.`);
       s.ctxTier = tier;
     }
   }
@@ -180,6 +216,25 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
     s.briefed = [...briefed];
   } catch { /* caches unreadable — ctx briefing above still applies */ }
 
+  // ── auto-compact window misconfigured on a 1M model (once per session) ──
+  // Config defect, not a usage trend: on a 1M window compaction only fires
+  // past ~800k, so every request until then re-bills a context the session
+  // never needed. 200k sessions are exempt (their window is already <= 200k).
+  try {
+    const cw = await import('./compact-window.js');
+    const st = cw.compactWindowStatus({ root: process.cwd() });
+    if (!st.ok) {
+      const sig = `compact-window|${st.reason}`;
+      const briefed = new Set(s.briefed || []);
+      if (!briefed.has(sig)) {
+        briefed.add(sig);
+        s.briefed = [...briefed];
+        const now = st.window ? `현재 ${fmtK(st.window)}` : '현재 미설정';
+        items.push(`1M 컨텍스트 모델(${st.model})인데 autoCompactWindow가 ${now}입니다 — 자동 압축이 80만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 40만으로 고정하면 1M 창은 그대로 두고 압축 시점만 앞당깁니다. 등록: claude-token-saver compact-window set --global|--project (적용 범위는 사용자에게 확인) / 끄기: compact-window off`);
+      }
+    }
+  } catch { /* settings unreadable — other briefings above still apply */ }
+
   s.ts = now;
   state.sessions[sessionId] = s;
   saveState(state, now);

package/src/commands/compact-window.js

@@ -0,0 +1,90 @@
+/**
+ * Subcommand: compact-window — audit / pin Claude Code's `autoCompactWindow`.
+ *   claude-token-saver compact-window                      # status
+ *   claude-token-saver compact-window set --global         # pin 400k in ~/.claude/settings.json
+ *   claude-token-saver compact-window set --project        # pin 400k in <root>/.claude/settings.json
+ *   claude-token-saver compact-window set --global --value 250k
+ *   claude-token-saver compact-window off | on             # toggle the statusline warning
+ *
+ * Scope is deliberately explicit for `set`: writing a global settings.json is
+ * not something to guess at, and the non-TTY hook environment cannot prompt.
+ */
+
+export async function run({ args, hasFlag }) {
+  const sub = args[1];
+  const cw = await import('../compact-window.js');
+  const { findProjectRoot } = await import('../harness.js');
+  const { loadConfig, saveConfig, userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+  const root = findProjectRoot();
+  const ko = lang === 'ko';
+  const fmt = (n) => (n === null || n === undefined ? '-' : `${Math.round(n / 1000)}k`);
+
+  if (sub === 'off' || sub === 'on') {
+    const cfg = loadConfig();
+    cfg.compactWindow = cfg.compactWindow || {};
+    cfg.compactWindow.enabled = sub === 'on';
+    saveConfig(cfg);
+    console.log(`Statusline compact-window warning: ${sub}`);
+    return;
+  }
+
+  if (sub === 'set') {
+    const scope = hasFlag('--global') ? 'global' : hasFlag('--project') ? 'project' : null;
+    if (!scope) {
+      console.error(ko
+        ? '적용 범위를 명시하세요 (사용자에게 먼저 확인): --global (~/.claude/settings.json) 또는 --project (<root>/.claude/settings.json)'
+        : 'Scope required: --global (~/.claude/settings.json) or --project (<root>/.claude/settings.json)');
+      process.exit(1);
+    }
+    const argv = args.slice(2);
+    const i = argv.indexOf('--value');
+    const eq = argv.find((a) => a.startsWith('--value='));
+    const raw = i !== -1 && argv[i + 1] ? argv[i + 1] : (eq ? eq.slice('--value='.length) : null);
+    const r = cw.setAutoCompactWindow({ root, scope, value: raw ?? cw.RECOMMENDED_WINDOW });
+    if (!r.ok) { console.error(`❌ ${r.error}`); process.exit(1); }
+    console.log(`✅ autoCompactWindow = ${r.value} (${fmt(r.value)}) → ${r.path} [${r.scope}]`);
+    if (r.previous !== null && r.previous !== undefined) console.log(`   previous: ${r.previous}`);
+    if (r.backup) console.log(`   backup:   ${r.backup}`);
+    // The env var beats settings.json, so a stale export silently defeats the
+    // write we just made — say so instead of letting the user wonder.
+    if (process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW) {
+      console.log(ko
+        ? `\n⚠ 셸에 CLAUDE_CODE_AUTO_COMPACT_WINDOW=${process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW} 가 설정돼 있어 settings.json보다 우선합니다. unset 하세요.`
+        : `\n⚠ CLAUDE_CODE_AUTO_COMPACT_WINDOW=${process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW} is exported and takes precedence over settings.json. Unset it.`);
+    }
+    console.log(ko ? '\n새 세션부터 적용됩니다.' : '\nApplies from the next session.');
+    return;
+  }
+
+  if (!sub || sub === 'status' || sub === 'check') {
+    const s = cw.compactWindowStatus({ root });
+    console.log(`model:  ${s.model || '(not set — Claude Code default)'}${s.modelSource ? ` [${s.modelSource}]` : ''}`);
+    console.log(`window: ${s.is1m ? '1M context' : '200k context'}`);
+    console.log(`autoCompactWindow: ${s.window === null ? '(unset)' : `${s.window} (${fmt(s.window)})`}${s.windowSource ? ` [${s.windowSource}${s.windowPath ? ` → ${s.windowPath}` : ''}]` : ''}`);
+    if (s.ok && s.reason === 'not-1m') {
+      console.log(ko
+        ? '\n✅ 200k 컨텍스트라 이 설정은 영향이 없습니다 (워닝 대상 아님).'
+        : '\n✅ 200k context — this setting changes nothing here (not warned).');
+      return;
+    }
+    if (s.ok) {
+      console.log(ko ? '\n✅ 압축 창이 400k 이하로 고정돼 있습니다.' : '\n✅ Compaction window is pinned at or below 400k.');
+      return;
+    }
+    console.log(ko
+      ? `\n⚠ 1M 컨텍스트인데 autoCompactWindow가 ${s.reason === 'unset' ? '설정되지 않았습니다' : `${fmt(s.window)}로 너무 큽니다`} — 자동 압축이 80만 토큰 근처에서야 걸립니다.`
+      : `\n⚠ 1M context with autoCompactWindow ${s.reason === 'unset' ? 'unset' : `at ${fmt(s.window)}`} — compaction only fires near 800k.`);
+    console.log(ko
+      ? '  그 전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 40만으로 고정하면 1M 창은 유지하면서 압축 시점만 앞당깁니다.'
+      : '  Until then every request re-bills the whole context. Pinning 400k keeps the 1M window while capping the runaway tail.');
+    console.log('\n  claude-token-saver compact-window set --global     (~/.claude/settings.json)');
+    console.log('  claude-token-saver compact-window set --project    (<root>/.claude/settings.json)');
+    console.log(ko ? '  (적용 범위는 사용자에게 먼저 확인할 것)' : '  (confirm the scope with the user first)');
+    return;
+  }
+
+  console.error(`Unknown compact-window subcommand: ${sub}`);
+  console.error('Usage: claude-token-saver compact-window [status|set --global|--project [--value 400k]|off|on]');
+  process.exit(1);
+}

package/src/compact-window.js

@@ -0,0 +1,192 @@
+/**
+ * compact-window — auto-compact window audit for 1M-context sessions.
+ *
+ * Claude Code compacts when context usage approaches
+ * `min(settings.autoCompactWindow, model max context)`. On a 1M window the
+ * default lets a session grow past 800k before compaction ever fires, so every
+ * later request re-bills a context most sessions never needed. Pinning
+ * `autoCompactWindow: 400000` keeps twice the headroom of a 200k session for
+ * the genuinely large ones while capping the runaway tail.
+ *
+ * 200k sessions are exempt by design: their window is already <= 200k, so the
+ * setting changes nothing and a warning would be pure noise.
+ *
+ * Sources, highest precedence first (mirrors Claude Code's own resolution):
+ *   1. env CLAUDE_CODE_AUTO_COMPACT_WINDOW  ("200000" | "200k" | "200")
+ *   2. <root>/.claude/settings.local.json
+ *   3. <root>/.claude/settings.json
+ *   4. ~/.claude/settings.json
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { debug } from './debug.js';
+
+// Claude Code clamps autoCompactWindow to [100k, 1M] (settings schema:
+// `.int().min(1e5).max(1e6)`), so anything outside that range is not a value
+// the app would honor.
+export const MIN_WINDOW = 100_000;
+export const MAX_WINDOW = 1_000_000;
+export const RECOMMENDED_WINDOW = 400_000;
+
+// A model id whose context is the 1M variant. Claude Code spells it as a
+// suffix on the model id (`claude-opus-5[1m]`); the beta header form
+// (`context-1m`) shows up in SDK/env configs.
+const ONE_M_RE = /\[1m\]|context-1m|1m-context/i;
+
+export function userSettingsPath() {
+  return join(homedir(), '.claude', 'settings.json');
+}
+
+export function projectSettingsPaths(root) {
+  return [
+    join(root, '.claude', 'settings.local.json'),
+    join(root, '.claude', 'settings.json'),
+  ];
+}
+
+function readJson(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    debug('compact-window:read', e);
+    return null; // malformed settings — treat as "nothing configured"
+  }
+}
+
+/**
+ * Parse the value forms Claude Code accepts for a window size: a plain token
+ * count, a `200k`/`1M` shorthand, or the bare-hundreds shorthand (`200` = 200k)
+ * its /config parser documents. Returns null when unparseable.
+ */
+export function parseWindow(raw) {
+  if (typeof raw === 'number') return Number.isFinite(raw) ? Math.round(raw) : null;
+  if (typeof raw !== 'string') return null;
+  const s = raw.trim().toLowerCase();
+  const m = s.match(/^(\d+(?:\.\d+)?)\s*([km]?)$/);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  if (!Number.isFinite(n)) return null;
+  if (m[2] === 'k') return Math.round(n * 1_000);
+  if (m[2] === 'm') return Math.round(n * 1_000_000);
+  // Bare number: below the legal minimum it can only be the `200` = 200k form.
+  return n < MIN_WINDOW ? Math.round(n * 1_000) : Math.round(n);
+}
+
+/**
+ * The model id this project would launch with. Same precedence as the settings
+ * lookup, with ANTHROPIC_MODEL on top (Claude Code reads it as an override).
+ */
+export function resolveModelId(root) {
+  if (process.env.ANTHROPIC_MODEL) return { model: process.env.ANTHROPIC_MODEL, source: 'env' };
+  for (const p of projectSettingsPaths(root)) {
+    const j = readJson(p);
+    if (j && typeof j.model === 'string') return { model: j.model, source: 'project', path: p };
+  }
+  const g = readJson(userSettingsPath());
+  if (g && typeof g.model === 'string') return { model: g.model, source: 'global', path: userSettingsPath() };
+  return { model: null, source: null };
+}
+
+export function isOneMillionModel(model) {
+  return typeof model === 'string' && ONE_M_RE.test(model);
+}
+
+/** Effective autoCompactWindow, with the source that won. */
+export function effectiveWindow(root) {
+  const env = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW;
+  if (env) {
+    const v = parseWindow(env);
+    if (v !== null) return { value: v, source: 'env' };
+  }
+  for (const p of projectSettingsPaths(root)) {
+    const j = readJson(p);
+    const v = j ? parseWindow(j.autoCompactWindow) : null;
+    if (v !== null) return { value: v, source: 'project', path: p };
+  }
+  const gp = userSettingsPath();
+  const g = readJson(gp);
+  const gv = g ? parseWindow(g.autoCompactWindow) : null;
+  if (gv !== null) return { value: gv, source: 'global', path: gp };
+  return { value: null, source: null };
+}
+
+/**
+ * Full audit result. `ok` is true when there is nothing to warn about — either
+ * the session is not on a 1M model (exempt), or the window is already pinned at
+ * or below the recommended 400k.
+ *
+ * `reason` names why it is not ok: 'unset' (no autoCompactWindow anywhere) or
+ * 'too-large' (set, but above 400k — still lets context run away).
+ */
+export function compactWindowStatus({ root = process.cwd() } = {}) {
+  const { model, source: modelSource } = resolveModelId(root);
+  const is1m = isOneMillionModel(model);
+  const win = effectiveWindow(root);
+  const base = {
+    model,
+    modelSource,
+    is1m,
+    window: win.value,
+    windowSource: win.source,
+    windowPath: win.path || null,
+    recommended: RECOMMENDED_WINDOW,
+  };
+  if (!is1m) return { ...base, ok: true, reason: 'not-1m' };
+  if (win.value === null) return { ...base, ok: false, reason: 'unset' };
+  if (win.value > RECOMMENDED_WINDOW) return { ...base, ok: false, reason: 'too-large' };
+  return { ...base, ok: true, reason: 'configured' };
+}
+
+/**
+ * Statusline chip text, or null when there is nothing to say. Kept to the same
+ * short shape as the other 🅷⚠ warnings so the line stays single-width.
+ */
+export function compactWindowWarningForStatusline(root = process.cwd(), cfg = null) {
+  if (cfg && cfg.compactWindow && cfg.compactWindow.enabled === false) return null;
+  try {
+    const s = compactWindowStatus({ root });
+    return s.ok ? null : 'compact-window?';
+  } catch (e) {
+    debug('compact-window:statusline', e);
+    return null;
+  }
+}
+
+/**
+ * Write `autoCompactWindow` into a settings.json, preserving every other key.
+ * Scope 'global' → ~/.claude/settings.json, 'project' → <root>/.claude/settings.json.
+ * A `.bak` is written first whenever the file already exists.
+ *
+ * Returns { path, scope, value, previous, backup }.
+ */
+export function setAutoCompactWindow({ root = process.cwd(), scope = 'global', value = RECOMMENDED_WINDOW } = {}) {
+  const v = parseWindow(value);
+  if (v === null || v < MIN_WINDOW || v > MAX_WINDOW) {
+    return { ok: false, error: `Invalid window: ${value} (expected ${MIN_WINDOW}–${MAX_WINDOW} tokens, e.g. 400000 or 400k)` };
+  }
+  const path = scope === 'global' ? userSettingsPath() : join(root, '.claude', 'settings.json');
+  let json = {};
+  let backup = null;
+  if (existsSync(path)) {
+    const raw = readFileSync(path, 'utf8');
+    try {
+      json = JSON.parse(raw);
+    } catch (e) {
+      debug('compact-window:parse', e);
+      // Refuse to overwrite a file we cannot parse — silently replacing a
+      // malformed settings.json would drop every other setting in it.
+      return { ok: false, error: `${path} is not valid JSON — fix it first (nothing was written).` };
+    }
+    backup = `${path}.bak`;
+    writeFileSync(backup, raw);
+  } else {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+  const previous = parseWindow(json.autoCompactWindow);
+  json.autoCompactWindow = v;
+  writeFileSync(path, JSON.stringify(json, null, 2) + '\n');
+  return { ok: true, path, scope, value: v, previous, backup };
+}

package/src/harness.js

@@ -23,6 +23,7 @@ import {
 } from './harness-templates.js';
 import { routeWarningForStatusline } from './route-scan.js';
 import { ruleHealthWarningForStatusline, modelRatchetPathFor, renderModelRatchet } from './model-rules.js';
+import { compactWindowWarningForStatusline } from './compact-window.js';
 
 const require = createRequire(import.meta.url);
 function readHarnessState() {
@@ -533,6 +534,15 @@ export function harnessStatusForStatusline(cfg, { root } = {}) {
   // but carries no `@` import, so every promoted ratchet rule is dead weight.
   // One `harness init` re-run fixes it and the warning goes away for good.
   if (!warning && status.hasBlock && !(status.hasRatchetImport && status.hasModelRatchetImport)) warning = 'ratchet-unloaded';
+  // Same class of defect, one notch lower: the session runs on a 1M-context
+  // model with no `autoCompactWindow` cap, so compaction only fires past 800k
+  // and every request until then re-bills the whole context. 200k sessions are
+  // exempt — the setting cannot change anything for them.
+  if (!warning) {
+    try {
+      warning = compactWindowWarningForStatusline(projectRoot, cfg);
+    } catch { /* settings unreadable — stay silent */ }
+  }
   // Below session-quality warnings: a promoted delegation rule whose
   // category started failing (`rule-health R<N>`) — the user approved that
   // rule, so its degradation outranks a mere new-candidate nudge.