sprag-cli 3.40.0

package/src/brief.js

@@ -0,0 +1,264 @@
+/**
+ * brief — UserPromptSubmit hook: per-session, change-triggered briefing.
+ *
+ * The statusline can only show chips (`ctx 82%`, `route? R1`, `rule-health`),
+ * and the model cannot see the statusline at all — so a mid-session state
+ * change is invisible to the conversation unless a hook injects it. This
+ * module runs on every prompt submit, compares the CURRENT session's state
+ * against what was already briefed for that session, and emits a short
+ * briefing instruction only when something NEW crossed a threshold. No
+ * change → completely silent (zero context cost).
+ *
+ * Per-session by design (user requirement): context size is a property of
+ * one session's transcript, so both the measurement (from this session's
+ * transcript_path) and the "already briefed" markers are keyed by session_id.
+ *
+ * State: <stateDir>/brief-state.json
+ *   { sessions: { [session_id]: { ts, ctxTier, briefed: [signature] } } }
+ * Sessions untouched for 7 days are pruned on every write.
+ *
+ * Division of labor with the SessionStart hook: SessionStart prints the
+ * session-start snapshot and records the signatures it actually briefed via
+ * seedSessionBriefed(); this hook emits anything NOT in that record. A
+ * candidate that lands after the SessionStart read (e.g. the detached rescan
+ * finishing between session start and the first prompt) is therefore briefed
+ * on the next prompt instead of being lost for the whole session.
+ */
+
+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
+// ever hears about each tier once, and only on upward crossings.
+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. 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;
+
+// See the note in route-scan.js — paths.js is the only place that resolves
+// this, so an XDG_CONFIG_HOME override moves every state file together.
+const stateDir = userDataDir;
+
+export function briefStatePath() {
+  return join(stateDir(), 'brief-state.json');
+}
+
+function loadState() {
+  try {
+    const s = JSON.parse(readFileSync(briefStatePath(), 'utf8'));
+    return s && typeof s.sessions === 'object' ? s : { sessions: {} };
+  } catch {
+    return { sessions: {} };
+  }
+}
+
+function saveState(state, now) {
+  for (const [id, s] of Object.entries(state.sessions)) {
+    if (!s?.ts || now - s.ts > PRUNE_MS) delete state.sessions[id];
+  }
+  const dir = stateDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  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 modelWindow = observedMax > WINDOW_1M_MIN_INPUT ? 1_000_000 : 200_000;
+  let window = modelWindow;
+  let compactCapped = false;
+  try {
+    const { model } = resolveModelId(root);
+    if (isOneMillionModel(model)) modelWindow = 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, modelWindow, 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, { root = process.cwd() } = {}) {
+  let size;
+  try { size = statSync(transcriptPath).size; } catch { return null; }
+  const start = Math.max(0, size - TAIL_BYTES);
+  const buf = Buffer.alloc(size - start);
+  let fd;
+  try {
+    fd = openSync(transcriptPath, 'r');
+    readSync(fd, buf, 0, buf.length, start);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) try { closeSync(fd); } catch { /* already closed */ }
+  }
+  const lines = buf.toString('utf8').split('\n');
+  let input = null;
+  let maxInput = 0;
+  for (const line of lines) {
+    if (!line.includes('"usage"')) continue;
+    let e; try { e = JSON.parse(line); } catch { continue; }
+    const u = e?.message?.usage;
+    if (!u) continue;
+    const total = (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
+    if (total > 0) { input = total; maxInput = Math.max(maxInput, total); }
+  }
+  if (input == null) return null;
+  const { window, modelWindow, compactCapped } = ctxWindowFor(maxInput, root);
+  return { input, window, modelWindow, compactCapped, pct: input / window };
+}
+
+function ctxTierOf(pct) {
+  let t = 0;
+  for (const { tier, pct: p } of CTX_TIERS) if (pct >= p) t = tier;
+  return t;
+}
+
+const fmtK = (n) => `${Math.round(n / 1000)}k`;
+
+/**
+ * Called by the SessionStart hook after it prints the session-start snapshot:
+ * records the signatures it actually briefed so runBrief suppresses exactly
+ * those and nothing more. Signature format matches runBrief:
+ * `route|<sig>` / `health|<sig>|<scope>`.
+ */
+export function seedSessionBriefed(sessionId, signatures, now = Date.now()) {
+  if (!sessionId || !Array.isArray(signatures) || signatures.length === 0) return;
+  const state = loadState();
+  const s = state.sessions[sessionId] || { ctxTier: 0, briefed: [] };
+  s.briefed = [...new Set([...(s.briefed || []), ...signatures])];
+  s.ts = now;
+  state.sessions[sessionId] = s;
+  saveState(state, now);
+}
+
+/**
+ * Compute the briefing for one prompt-submit event. Returns the text to
+ * inject, or null when nothing new happened. Mutates + persists state.
+ *
+ * Route/rule-health signatures already briefed by the SessionStart hook
+ * (recorded via seedSessionBriefed) are skipped; every other fresh signature
+ * is emitted, including on the session's first event.
+ */
+export async function runBrief({ sessionId, transcriptPath, now = Date.now() }) {
+  if (!sessionId) return null;
+  const state = loadState();
+  const s = state.sessions[sessionId] || { ctxTier: 0, briefed: [] };
+  const items = [];
+
+  // ── context tier crossing (per-session) ──
+  const ctx = transcriptPath ? sessionCtx(transcriptPath) : null;
+  if (ctx) {
+    const tier = ctxTierOf(ctx.pct);
+    // The tier is not monotonic: auto-compaction drops the live context back to
+    // a fraction of the window, which starts a new fill cycle. Holding the old
+    // high-water tier meant a session that compacted at 80% was never warned
+    // again — it silently refilled to the cap with no signal at all.
+    if (tier < (s.ctxTier || 0)) s.ctxTier = tier;
+    if (tier > (s.ctxTier || 0)) {
+      // Name both denominators when they differ. Claude Code's own UI counts
+      // against the model window, so a bare "400k 창의 80%" reads as wrong to
+      // anyone looking at a statusline that says 32% of 1M — same session,
+      // two different windows, no way to reconcile them from the text alone.
+      const winLabel = ctx.window >= 1_000_000 ? '1M' : fmtK(ctx.window);
+      const modelPct = Math.round((ctx.input / ctx.modelWindow) * 100);
+      const modelLabel = ctx.modelWindow >= 1_000_000 ? '1M' : fmtK(ctx.modelWindow);
+      const capNote = ctx.compactCapped ? `, 화면의 ${modelLabel} 창 기준으로는 ${modelPct}%` : '';
+      // With autoCompactWindow set, crossing the threshold means compaction is
+      // about to run on its own. Telling the user to start a new session there
+      // would be advice for a problem the setting already handles.
+      items.push(tier === 2
+        ? (ctx.compactCapped
+            ? `이 세션의 컨텍스트가 자동 압축 창(${winLabel})의 95%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}${capNote}). 곧 자동 압축이 돌아 이전 대화가 요약으로 바뀝니다 — 지금 단계를 마무리하고 이어서 할 일은 파일에 적어두면 압축 뒤에도 안전합니다.`
+            : `이 세션의 컨텍스트가 ${winLabel} 창의 95%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 곧 자동 압축으로 맥락 손실이 생길 수 있으니, 진행 중인 작업을 일단락하고 새 세션을 시작하는 편이 좋습니다.`)
+        : (ctx.compactCapped
+            ? `이 세션의 컨텍스트가 자동 압축 창(${winLabel})의 80%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}${capNote}). 설정해 둔 압축 지점이 가까워졌습니다 — 압축은 알아서 돌아가니 새 세션을 서두를 필요는 없고, 여기까지의 결정과 다음 할 일만 파일에 남겨두면 됩니다.`
+            : `이 세션의 컨텍스트가 ${winLabel} 창의 80%를 넘었습니다(직전 요청 입력 ${fmtK(ctx.input)}). 이후 요청은 비용이 커지는 구간입니다 — 작업이 일단락되면 새 세션 시작을 권합니다.`));
+      s.ctxTier = tier;
+    }
+  }
+
+  // ── mid-session route-scan / rule-health changes (global state, briefed
+  //    at most once per session per signature) ──
+  try {
+    const rs = await import('./route-scan.js');
+    const mr = await import('./model-rules.js');
+    const briefed = new Set(s.briefed || []);
+    const fresh = [];
+    for (const c of rs.openCandidates(rs.readRouteScan())) {
+      const sig = `route|${c.signature}`;
+      if (briefed.has(sig)) continue;
+      briefed.add(sig);
+      fresh.push(['route', c]);
+    }
+    for (const r of mr.loadModelRules().rules) {
+      if (r.status !== 'review') continue;
+      const sig = `health|${r.signature}|${r.scope}`;
+      if (briefed.has(sig)) continue;
+      briefed.add(sig);
+      fresh.push(['health', r]);
+    }
+    for (const [kind, x] of fresh) {
+      items.push(kind === 'route'
+        ? `새 위임 후보가 감지되었습니다 — "${x.label}" 유형 ${x.count}회 반복(statusline의 route? R${x.id} 칩). 등록: claude-token-saver harness promote R${x.id} --project|--global (적용 범위는 사용자에게 확인) / 무시: route-scan dismiss ${x.id}`
+        : `승인된 위임 룰의 최근 에러율이 기준(20%)을 넘었습니다 — "${x.label}" (${x.healthSource === 'delegated' ? `위임 실행 ${x.delegatedRuns}건 중 에러율 ${Math.round((x.delegatedErrRate || 0) * 100)}%` : `유사 에피소드 기준 에러율 ${Math.round((x.errRate || 0) * 100)}%`}, statusline의 rule-health 칩). 조건 좁히기/제거를 사용자와 상의하세요: claude-token-saver route-scan rules`);
+    }
+    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만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmtK(st.recommendedMin)}~${fmtK(st.recommendedMax)} 범위를 권장합니다(그 범위 안이면 경고하지 않습니다). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다. 등록: claude-token-saver compact-window set --global|--project [--value ${fmtK(st.recommendedMax)}] (기본 ${fmtK(st.recommended)}, 적용 범위는 사용자에게 확인) / 끄기: compact-window off`);
+      }
+    }
+  } catch { /* settings unreadable — other briefings above still apply */ }
+
+  s.ts = now;
+  state.sessions[sessionId] = s;
+  saveState(state, now);
+
+  if (items.length === 0) return null;
+  const lines = [
+    '[claude-token-saver 브리핑] 아래 상태 변화를 사용자에게 알려주세요. 진행 중인 답변 흐름을 끊지 말고, 답변 말미에 `※ [claude-token-saver]` 라벨을 달아 각 항목을 1~2줄로 요약해 전달하면 됩니다 (이 브리핑은 항목당 한 번만 주입됩니다):',
+  ];
+  for (const it of items) lines.push(`- ${it}`);
+  return lines.join('\n');
+}

package/src/caps-cache.js

@@ -0,0 +1,84 @@
+/**
+ * Statusline snapshot cache — the rate-limit numbers and model name only flow
+ * through stdin from Claude Code's statusline contract, but we want the table
+ * view (`claude-token-saver --days N`) to surface the same data. So
+ * whenever the statusline path sees them it writes them here, and the table
+ * path reads them back if its own stdin was empty.
+ *
+ * Stale data is worse than missing data — if the saved snapshot is older
+ * than `maxAgeMs` the loader returns null and the table view stays quiet.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+
+const CACHE_PATH = join(userDataDir(), 'last-caps.json');
+
+function ensureDir() {
+  const dir = userDataDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Persist whatever subset of statusline state we have right now. A null/empty
+ * snapshot is a no-op so callers don't have to guard.
+ *
+ * @param {{ caps?: object|null, model?: string|null }|null} snapshot
+ */
+export function persistSnapshot(snapshot) {
+  if (!snapshot) return;
+  const hasCaps = !!snapshot.caps;
+  const hasModel = typeof snapshot.model === 'string' && snapshot.model.length > 0;
+  if (!hasCaps && !hasModel) return;
+  try {
+    ensureDir();
+    const payload = {
+      capturedAt: Date.now(),
+      caps: snapshot.caps || null,
+      model: snapshot.model || null,
+    };
+    writeFileSync(CACHE_PATH, JSON.stringify(payload) + '\n');
+  } catch {
+    // best-effort cache, never blocks the statusline
+  }
+}
+
+/**
+ * v2.3 wrote `caps` as `{ fiveHour, sevenDay }`; v2.4+ writes `{ windows: [...] }`.
+ * Convert on read so a returning user's stale snapshot still feeds the table view
+ * until the next statusline refresh overwrites it.
+ */
+function normalizeCaps(caps) {
+  if (!caps || typeof caps !== 'object') return null;
+  if (Array.isArray(caps.windows)) return caps;
+  const windows = [];
+  if (caps.fiveHour && typeof caps.fiveHour === 'object') {
+    windows.push({ key: 'five_hour', usedPct: caps.fiveHour.usedPct, resetsAt: caps.fiveHour.resetsAt ?? null });
+  }
+  if (caps.sevenDay && typeof caps.sevenDay === 'object') {
+    windows.push({ key: 'seven_day', usedPct: caps.sevenDay.usedPct, resetsAt: caps.sevenDay.resetsAt ?? null });
+  }
+  return windows.length ? { windows } : null;
+}
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.maxAgeMs=5*60*1000] - drop snapshots older than this.
+ * @returns {{ caps: object|null, model: string|null }|null}
+ */
+export function loadRecentSnapshot({ maxAgeMs = 5 * 60 * 1000 } = {}) {
+  try {
+    if (!existsSync(CACHE_PATH)) return null;
+    const raw = readFileSync(CACHE_PATH, 'utf8');
+    const data = JSON.parse(raw);
+    if (!data || typeof data.capturedAt !== 'number') return null;
+    if (Date.now() - data.capturedAt > maxAgeMs) return null;
+    return {
+      caps: normalizeCaps(data.caps),
+      model: data.model || null,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/cli-args.js

@@ -0,0 +1,51 @@
+/**
+ * argv accessors shared by every subcommand.
+ *
+ * `createArgs(argv)` binds them to one argument list, so a subcommand module
+ * takes them as a parameter instead of reaching for a module-level global —
+ * which also makes them directly testable.
+ */
+
+export function createArgs(argv) {
+  const args = argv;
+
+  function getArg(name) {
+    const idx = args.indexOf(name);
+    if (idx !== -1) return args[idx + 1];
+    const prefix = `${name}=`;
+    const eq = args.find((a) => a.startsWith(prefix));
+    if (eq) return eq.slice(prefix.length);
+    return undefined;
+  }
+
+  function hasFlag(name) {
+    return args.includes(name);
+  }
+
+  /**
+   * Read a numeric option, rejecting garbage instead of letting NaN flow into
+   * the report window. `--days abc` used to render as `NaNd` on the statusline
+   * and as a bare "no session data" in the table view — a typo that looked
+   * exactly like "you have no logs".
+   *
+   * @param {string} name flag name, e.g. '--days'
+   * @param {object} [opts]
+   * @param {number} [opts.dflt] value when the flag is absent
+   * @param {number} [opts.min] inclusive lower bound
+   * @param {number} [opts.max] inclusive upper bound
+   * @throws {Error} on a non-numeric or out-of-range value
+   */
+  function numArg(name, { dflt, min, max } = {}) {
+    const raw = getArg(name);
+    if (raw === undefined) return dflt;
+    const n = parseFloat(raw);
+    if (!Number.isFinite(n)) {
+      throw new Error(`${name} expects a number, got "${raw}"`);
+    }
+    if (min !== undefined && n < min) throw new Error(`${name} must be >= ${min}, got ${n}`);
+    if (max !== undefined && n > max) throw new Error(`${name} must be <= ${max}, got ${n}`);
+    return n;
+  }
+
+  return { args, getArg, hasFlag, numArg };
+}

package/src/cohesion.js

@@ -0,0 +1,70 @@
+/**
+ * cohesion — English sentence-connection guidance injected at session start.
+ *
+ * The Korean supplement's cohesion section turned out to be language-neutral:
+ * given-before-new ordering, one referent per pronoun, subject consistency,
+ * bridging instead of leaping, merging choppy sentences. English-only users
+ * never run `korean on`, so those rules never reached them. This module ships
+ * the same principles as a standalone English block.
+ *
+ * Off by default for the same reason the Korean guidance is opt-in: a
+ * token-saving tool has no business silently billing ~0.5k tokens a session.
+ * Enable with `claude-token-saver cohesion on`.
+ *
+ * When the Korean guidance is enabled, this block is NOT injected even if
+ * enabled: the Korean supplement already carries the cohesion rules, and
+ * injecting the same principles twice bills them twice.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig, saveConfig } from './config.js';
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const COHESION_PATH = join(packageRoot, 'presets', 'cohesion', 'cohesion-en.md');
+
+/** Whether session-start injection is enabled. Off unless the user asked. */
+export function cohesionEnabled(cfg = loadConfig()) {
+  return cfg?.cohesion?.enabled === true;
+}
+
+export function setCohesionEnabled(enabled) {
+  const cfg = loadConfig();
+  cfg.cohesion = { ...(cfg.cohesion || {}), enabled: !!enabled };
+  saveConfig(cfg);
+  return cfg.cohesion;
+}
+
+/** The guidance text with the provenance comment stripped, or null. */
+export function cohesionText() {
+  try {
+    if (!existsSync(COHESION_PATH)) return null;
+    const raw = readFileSync(COHESION_PATH, 'utf8');
+    const body = raw.replace(/^<!--[\s\S]*?-->\s*/, '').trim();
+    return body || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Block to inject at session start, or null when disabled, unavailable, or
+ * redundant (Korean guidance on — its supplement already carries these rules).
+ */
+export async function cohesionInjection({ cfg = loadConfig() } = {}) {
+  if (!cohesionEnabled(cfg)) return null;
+  try {
+    const { koreanStyleEnabled } = await import('./korean-style.js');
+    if (koreanStyleEnabled(cfg)) return null;
+  } catch { /* korean module unavailable: inject normally */ }
+  const text = cohesionText();
+  if (!text) return null;
+  return [
+    '[claude-token-saver cohesion] Follow this guidance for English prose in this session.',
+    'The user enabled it in claude-token-saver.',
+    '',
+    text,
+  ].join('\n');
+}

package/src/commands/brief.js

@@ -0,0 +1,31 @@
+/**
+ * Subcommand: route-scan — detect recurring easy work on expensive models
+ * and propose model-delegation ratchet rules. Zero token cost, fully local.
+ *   claude-token-saver route-scan                 # scan (24h cache) + print candidates
+ *   claude-token-saver route-scan --refresh       # force rescan
+ *   claude-token-saver route-scan --days 30       # wider lookback
+ *   claude-token-saver route-scan --hook          # SessionStart hook mode (context injection)
+ *   claude-token-saver route-scan dismiss <N>     # mute candidate R<N>
+ * Promote a candidate to a ratchet rule (scope is always explicit):
+ *   claude-token-saver harness promote R<N> --project|--global
+ * brief --hook — UserPromptSubmit hook mode: per-session, change-triggered
+ * briefing of state the statusline can only chip (ctx tier crossings,
+ * mid-session route/rule-health changes). Silent when nothing changed.
+ */
+
+import { readStdinJson } from '../stdin-payload.js';
+import { debug } from '../debug.js';
+
+export async function run({ hasFlag }) {
+    if (!hasFlag('--hook')) {
+      console.error('Usage: claude-token-saver brief --hook   (UserPromptSubmit hook mode)');
+      process.exit(1);
+    }
+    const ctx = readStdinJson() || {};
+    try {
+      const { runBrief } = await import('../brief.js');
+      const out = await runBrief({ sessionId: ctx.session_id, transcriptPath: ctx.transcript_path });
+      if (out) console.log(out);
+    } catch (e) { debug('brief:hook', e); /* briefing is best-effort — never block a prompt */ }
+    return;
+}

package/src/commands/cohesion.js

@@ -0,0 +1,59 @@
+/**
+ * Subcommand: cohesion — English sentence-connection guidance for every session.
+ *   claude-token-saver cohesion on       # inject at session start, all projects
+ *   claude-token-saver cohesion off      # stop injecting
+ *   claude-token-saver cohesion status   # current state and cost
+ *   claude-token-saver cohesion show     # print the guidance itself
+ *
+ * The English sibling of `korean on`, carrying only the language-neutral
+ * cohesion rules (given-before-new, one referent per pronoun, subject
+ * consistency, bridging, merging choppy sentences). No lint: every clause
+ * needs judgement, so nothing here is machine-checkable.
+ */
+
+export async function run({ args }) {
+  const sub = args[1] || 'status';
+  const co = await import('../cohesion.js');
+  const { userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+
+  if (sub === 'on' || sub === 'off') {
+    co.setCohesionEnabled(sub === 'on');
+    if (sub === 'on') {
+      console.log(lang === 'ko'
+        ? '✍️ cohesion on: 다음 세션부터 영어 문장 연결 지침이 주입됩니다 (약 0.5k 토큰/세션, 세션 시작 1회).'
+        : '✍️ cohesion on — English cohesion guidance will be injected from the next session (~0.5k tokens per session, once at session start).');
+      const { koreanStyleEnabled } = await import('../korean-style.js');
+      if (koreanStyleEnabled()) {
+        console.log(lang === 'ko'
+          ? '참고: korean 지침이 켜져 있는 동안에는 같은 원칙이 이미 들어가므로 이 블록은 주입되지 않습니다.'
+          : 'Note: while the Korean guidance is on, its supplement already carries these rules, so this block is not injected.');
+      }
+    } else {
+      console.log(lang === 'ko' ? 'cohesion off: 더 이상 주입하지 않습니다.' : 'cohesion off — no longer injected.');
+    }
+    return;
+  }
+
+  if (sub === 'show') {
+    const text = co.cohesionText();
+    if (!text) {
+      console.error('cohesion guidance file missing: ' + co.COHESION_PATH);
+      process.exit(1);
+    }
+    console.log(text);
+    return;
+  }
+
+  // status (default)
+  const enabled = co.cohesionEnabled();
+  const { koreanStyleEnabled } = await import('../korean-style.js');
+  const suppressed = enabled && koreanStyleEnabled();
+  if (lang === 'ko') {
+    console.log(`cohesion: ${enabled ? 'on' : 'off'}${suppressed ? ' (korean 지침이 켜져 있어 주입은 생략됨)' : ''}`);
+    console.log('영어 산문의 문장 연결 지침을 세션 시작에 주입합니다. 켜기: claude-token-saver cohesion on');
+  } else {
+    console.log(`cohesion: ${enabled ? 'on' : 'off'}${suppressed ? ' (suppressed while the Korean guidance is on — it already carries these rules)' : ''}`);
+    console.log('Injects English cohesion guidance at session start. Enable with: claude-token-saver cohesion on');
+  }
+}

package/src/commands/compact-window.js

@@ -0,0 +1,93 @@
+/**
+ * Subcommand: compact-window — audit / pin Claude Code's `autoCompactWindow`.
+ *   claude-token-saver compact-window                      # status
+ *   claude-token-saver compact-window set --global         # pin 500k in ~/.claude/settings.json
+ *   claude-token-saver compact-window set --project        # pin 500k in <root>/.claude/settings.json
+ *   claude-token-saver compact-window set --global --value 600k
+ *   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✅ 압축 창이 권장 범위(${fmt(s.recommendedMin)}~${fmt(s.recommendedMax)}) 상한 이하입니다.`
+        : `\n✅ Compaction window is at or below the top of the recommended ${fmt(s.recommendedMin)}–${fmt(s.recommendedMax)} band.`);
+      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
+      ? `  그 전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmt(s.recommendedMin)}~${fmt(s.recommendedMax)} 범위를 권장합니다 (기본값 ${fmt(s.recommended)}, --value로 조절). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다.`
+      : `  Until then every request re-bills the whole context. 1M is too large — pick something in ${fmt(s.recommendedMin)}–${fmt(s.recommendedMax)} (default ${fmt(s.recommended)}, override with --value). The 1M window itself stays.`);
+    console.log(`\n  claude-token-saver compact-window set --global     (~/.claude/settings.json, ${fmt(s.recommended)})`);
+    console.log(`  claude-token-saver compact-window set --project    (<root>/.claude/settings.json, ${fmt(s.recommended)})`);
+    console.log(`  claude-token-saver compact-window set --global --value ${fmt(s.recommendedMax)}`);
+    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 500k]|off|on]');
+  process.exit(1);
+}