claude-token-saver 3.5.3 → 3.6.0

package/src/commands/last.js

@@ -0,0 +1,151 @@
+/**
+ * Subcommand: last — print the most recent warning + how to handle it.
+ * Designed for the auto-trigger skill so the user immediately sees
+ * "what just fired and how to fix it" without having to read the whole
+ * history file.
+ *   claude-token-saver last           # search last 1 day
+ *   claude-token-saver last --days 7  # widen the lookback
+ */
+
+
+/**
+ * Scan recent history file contents (newest day first) and return the most
+ * recent warning event — `{ time, chip, detail, codes, isCap, capLabel, capPct }`.
+ * Returns null when no warning is found in the window.
+ *
+ * Recognized event lines (from history.js appendDayLine output):
+ *   - HH:MM:SS ⚠ Cache miss — session abc1: LOW_HIT_RATE
+ *   - HH:MM:SS ⚠ A → ⚠ B — detail
+ *   - HH:MM:SS 🚨 5H 94% cap warning (resets in ...)
+ *   - HH:MM:SS ✓ resolved (was ...)        ← skip
+ *   - HH:MM:SS ✓ 5H cap warning resolved   ← skip
+ *   - HH:MM:SS 📝 handoff written: ...     ← skip
+ */
+function findLatestWarning(historyEntries, chipToCodes) {
+  const warnings = [];
+  for (const { date, content } of historyEntries) {
+    const lines = content.split('\n');
+    for (const line of lines) {
+      // Skip non-event lines
+      const m = line.match(/^- (\d{2}:\d{2}:\d{2})\s+(.+)$/);
+      if (!m) continue;
+      const time = m[1];
+      const rest = m[2];
+      // Skip resolutions and handoff entries
+      if (rest.startsWith('✓ ') || rest.startsWith('📝 ')) continue;
+      // Cap-warn line: `🚨 5H 94% cap warning (...)`
+      const cap = rest.match(/^🚨\s+(\S+)\s+(\d+)%\s+cap warning(?:\s*\((.+)\))?$/);
+      if (cap) {
+        warnings.push({
+          date,
+          time,
+          chip: `🚨 ${cap[1]} ${cap[2]}%`,
+          isCap: true,
+          capLabel: cap[1],
+          capPct: parseInt(cap[2], 10),
+          capReset: cap[3] || null,
+          codes: [],
+          detail: null,
+        });
+        continue;
+      }
+      // Chip line — last token after the chip is `— detail` (optional). The
+      // chip itself can be a plain `⚠ X` or a `⚠ A → ⚠ B` transition; we want
+      // the *current* chip (right side of the arrow if present).
+      const arrowMatch = rest.match(/^(.+?)\s+→\s+(.+?)(?:\s+—\s+(.+))?$/);
+      let chip;
+      let detail = null;
+      if (arrowMatch) {
+        chip = arrowMatch[2].trim();
+        detail = arrowMatch[3] || null;
+      } else {
+        const plain = rest.match(/^(\S+(?:\s+\S+)*?)(?:\s+—\s+(.+))?$/);
+        if (!plain) continue;
+        chip = plain[1].trim();
+        detail = plain[2] || null;
+      }
+      // Resolve codes: detail "session ID: A, B" → codes; else CHIP_TO_CODES.
+      const codes = [];
+      if (detail) {
+        const dm = detail.match(/^session [^:]+:\s*(.+)$/);
+        if (dm) {
+          for (const c of dm[1].split(',').map((s) => s.trim()).filter(Boolean)) {
+            if (!codes.includes(c)) codes.push(c);
+          }
+        }
+      }
+      if (chipToCodes[chip]) {
+        for (const c of chipToCodes[chip]) if (!codes.includes(c)) codes.push(c);
+      }
+      warnings.push({ date, time, chip, isCap: false, codes, detail });
+    }
+  }
+  return warnings.length ? warnings[warnings.length - 1] : null;
+}
+
+export async function run({ numArg }) {
+    const { readRecent, historyDir } = await import('../history.js');
+    const { ISSUE_MESSAGES, CHIP_TO_CODES, CAP_TIPS } = await import('../advice.js');
+    const { userLanguage } = await import('../config.js');
+    const lang = userLanguage();
+    const days = numArg('--days', { dflt: 1, min: 0 });
+    const recent = readRecent(days);
+    const latest = findLatestWarning(recent, CHIP_TO_CODES);
+    if (!latest) {
+      if (lang === 'ko') {
+        console.log(`최근 ${days}일 내 경고가 없습니다.`);
+        console.log(`(히스토리 디렉터리: ${historyDir()})`);
+      } else {
+        console.log(`No warnings in the last ${days} day${days === 1 ? '' : 's'}.`);
+        console.log(`(History dir: ${historyDir()})`);
+      }
+      return;
+    }
+    // Header
+    console.log(`Most recent warning — ${latest.date} ${latest.time}`);
+    console.log(`  ${latest.chip}${latest.detail ? `  — ${latest.detail}` : ''}`);
+    console.log('');
+    // Cap-warn path: handoff is the recommendation. Print the bilingual tip
+    // and a one-line "how to back up" pointer.
+    if (latest.isCap) {
+      if (latest.capReset) console.log(`  Cap window: ${latest.capReset}`);
+      console.log('');
+      console.log('💡 ' + (lang === 'ko' ? CAP_TIPS.ko : CAP_TIPS.en));
+      console.log('');
+      console.log(lang === 'ko' ? '실행:' : 'Run:');
+      console.log('  claude-token-saver handoff');
+      return;
+    }
+    // Chip warning path: render full ISSUE_MESSAGES advice for each code,
+    // bilingual (English first, `└ Korean` continuation per line — matches
+    // the history.md format).
+    if (latest.codes.length === 0) {
+      console.log(lang === 'ko'
+        ? '(진단 코드 없음 — 표 뷰를 열어보세요: `claude-token-saver --days 1`)'
+        : '(No diagnostic code attached — open the table view: `claude-token-saver --days 1`)');
+      return;
+    }
+    // Pick a single language per field; fall back to EN when KO is missing.
+    const pick = (en, ko) => (lang === 'ko' && ko ? ko : en);
+    for (const code of latest.codes) {
+      const msg = ISSUE_MESSAGES[code];
+      if (!msg) {
+        console.log(`Code: ${code} (no advice registered)`);
+        continue;
+      }
+      console.log(`▎ ${pick(msg.title, msg.titleKo)}`);
+      console.log(`  ${pick(msg.explain, msg.explainKo)}`);
+      const actions = typeof msg.actions === 'function' ? msg.actions() : msg.actions || [];
+      for (const a of actions) {
+        console.log('');
+        console.log(`  ${pick(a.label, a.labelKo)}:`);
+        const cmds = a.commands || [];
+        const cmdsKo = a.commandsKo || [];
+        for (let i = 0; i < cmds.length; i++) {
+          console.log(`    - ${pick(cmds[i], cmdsKo[i])}`);
+        }
+      }
+      console.log('');
+    }
+    return;
+}

package/src/commands/mode.js

@@ -0,0 +1,45 @@
+/**
+ * Subcommand: mode — persist statusline preferences so future runs pick
+ * them up without flags or wrapper edits.
+ *   claude-token-saver mode                    # show current config
+ *   claude-token-saver mode icon verbose       # set icon + verbose
+ *   claude-token-saver mode reset              # clear back to defaults
+ */
+
+
+export async function run({ args }) {
+    const { applyMode, loadConfig, configPath, statuslineDefaults, userLanguage, VALID_KEYWORDS } =
+      await import('../config.js');
+    const words = args.slice(1);
+    if (words.length === 0) {
+      const eff = statuslineDefaults();
+      const raw = loadConfig();
+      console.log('Statusline (effective):');
+      console.log(`  icon:    ${eff.icon}`);
+      console.log(`  verbose: ${eff.verbose}`);
+      console.log(`  timer:   ${eff.timer}`);
+      console.log(`  color:   ${eff.color}`);
+      console.log(`  window:  ${eff.windowLabel} (${eff.windowHours}h)`);
+      console.log('');
+      console.log('Output language (advice / history / last):');
+      console.log(`  language: ${userLanguage()}`);
+      console.log('');
+      console.log(`Stored config file (${configPath()}):`);
+      console.log(`  ${Object.keys(raw).length === 0 ? '(none — using defaults)' : JSON.stringify(raw)}`);
+      console.log('');
+      console.log('Change with: claude-token-saver mode <keywords...>');
+      console.log(`Keywords: ${VALID_KEYWORDS.join(', ')}`);
+      return;
+    }
+    const { applied, unknown } = applyMode(words);
+    if (unknown.length) {
+      console.error(`Unknown keyword${unknown.length > 1 ? 's' : ''}: ${unknown.join(', ')}`);
+      console.error(`Valid: ${VALID_KEYWORDS.join(', ')}`);
+      process.exit(1);
+    }
+    const eff = statuslineDefaults();
+    console.log(`Updated: ${applied.join(', ')}`);
+    console.log(`Now: icon=${eff.icon} verbose=${eff.verbose} timer=${eff.timer} color=${eff.color} window=${eff.windowLabel} language=${userLanguage()}`);
+    console.log('Statusline picks up the change on the next refresh (~1s).');
+    return;
+}

package/src/commands/route-scan.js

@@ -0,0 +1,201 @@
+/**
+
+ */
+
+import { readStdinJson } from '../stdin-payload.js';
+import { debug } from '../debug.js';
+
+export async function run({ args, hasFlag, numArg }) {
+    const rs = await import('../route-scan.js');
+    const { userLanguage } = await import('../config.js');
+    const lang = userLanguage();
+
+    // route-scan rules [rm <N>] — the model-fitting rule registry (rules
+    // promoted from candidates; auto-refreshed from logs on every rescan).
+    if (args[1] === 'rules') {
+      const mr = await import('../model-rules.js');
+      if (args[2] === 'rm') {
+        const n = parseInt(args[3], 10);
+        const removed = Number.isFinite(n) ? mr.removeModelRule(n) : null;
+        if (!removed) {
+          console.error('Usage: claude-token-saver route-scan rules rm <N>   # N from `route-scan rules`');
+          process.exit(1);
+        }
+        // A target whose last rule was removed gets its (tool-owned) file deleted.
+        mr.syncAllFiles({ previousPaths: [mr.modelRatchetPathFor(removed.scope, removed.targetRoot)] });
+        console.log(`Removed model-fitting rule #${n}: ${removed.rule}`);
+        return;
+      }
+      const { rules } = mr.loadModelRules();
+      if (rules.length === 0) {
+        console.log(lang === 'ko' ? '등록된 모델 피팅 룰 없음.' : 'No model-fitting rules registered.');
+        return;
+      }
+      console.log(lang === 'ko' ? '📐 모델 피팅 룰 (로그 기반 자동 갱신):' : '📐 Model-fitting rules (auto-refreshed from logs):');
+      rules.forEach((r, i) => {
+        const health = r.status === 'review'
+          ? (lang === 'ko' ? '  ⚠ 에러율 초과 — 재검토 필요' : '  ⚠ error rate over threshold — needs review')
+          : '';
+        const stat = lang === 'ko'
+          ? `${r.tier} (${rs.tierLabel(r.tier)}) · ${rs.scopeLabel(r.scope)} · 반복 ${r.count || 0}회 · 에러율 ${Math.round((r.errRate || 0) * 100)}%`
+          : `${r.tier} (${rs.tierLabel(r.tier, 'en')}) · ${rs.scopeLabel(r.scope, 'en')} · seen ×${r.count || 0} · err ${Math.round((r.errRate || 0) * 100)}%`;
+        console.log(`  #${i + 1} ${stat}${health}`);
+        console.log(`      ${r.rule}`);
+      });
+      console.log(lang === 'ko'
+        ? '\n제거: claude-token-saver route-scan rules rm <N>'
+        : '\nRemove with: claude-token-saver route-scan rules rm <N>');
+      return;
+    }
+
+    if (args[1] === 'dismiss') {
+      const n = parseInt(args[2], 10);
+      if (!Number.isFinite(n)) {
+        console.error('Usage: claude-token-saver route-scan dismiss <N>   # N from `route? R<N>`');
+        process.exit(1);
+      }
+      const cand = rs.resolveCandidate(n);
+      if (!cand) {
+        console.error(`No route candidate R${n}. Run: claude-token-saver route-scan`);
+        process.exit(1);
+      }
+      console.log(lang === 'ko'
+        ? `R${n} 무시 처리: ${cand.label} (${cand.project}) — 재스캔에도 다시 뜨지 않습니다.`
+        : `Dismissed R${n}: ${cand.label} (${cand.project}) — won't resurface on rescans.`);
+      return;
+    }
+
+    // --hook: SessionStart hook mode. Never scans inline (session start must
+    // stay fast) — reads the cache, kicks a detached refresh when stale, and
+    // prints delegation-candidate context for the new session.
+    if (hasFlag('--hook')) {
+      const hookCtx = readStdinJson() || {};
+      let cache = rs.readRouteScan();
+      if (await rs.shouldRescan(cache)) {
+        try {
+          const { spawn } = await import('node:child_process');
+          spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet'],
+            { detached: true, stdio: 'ignore' }).unref();
+        } catch (e) { debug('route-scan:spawn-refresh', e); /* stale cache is still usable below */ }
+      }
+      const open = rs.openCandidates(cache);
+      // Registered rules whose delegated-category error rate crossed the
+      // health threshold since promotion — the user approved these, so a
+      // status change must be briefed, not just written into the md file.
+      let reviewRules = [];
+      try {
+        const mr = await import('../model-rules.js');
+        reviewRules = mr.loadModelRules().rules
+          .map((r, i) => ({ ...r, n: i + 1 }))
+          .filter((r) => r.status === 'review');
+      } catch (e) { debug('route-scan:load-rules', e); /* candidate briefing still goes out */ }
+      if (open.length === 0 && reviewRules.length === 0) return; // silent — nothing to inject
+      // This text is injected straight into the model's context, so it must
+      // follow the user's configured language — a Korean-only briefing in an
+      // English session steers the whole first response into Korean.
+      const lines = [];
+      if (open.length > 0) {
+        if (lang === 'ko') {
+          lines.push(`[claude-token-saver route-scan] 최근 ${cache.days}일 세션에서 비싼 모델(opus/fable)이 반복 처리해 온, 더 싼 모델로 넘겨도 되는 작업이 감지되었습니다.`);
+          lines.push('(R<N>은 후보 번호, T2/T1은 난이도 등급입니다 — 사용자에게 전달할 때는 코드가 아니라 아래 풀어쓴 설명으로 브리핑하세요)');
+        } else {
+          lines.push(`[claude-token-saver route-scan] Over the last ${cache.days} days, expensive models (opus/fable) repeatedly handled work that a cheaper model could take.`);
+          lines.push('(R<N> is the candidate id, T2/T1 the difficulty tier — brief the user with the spelled-out wording below, not the codes.)');
+        }
+        for (const c of open) {
+          const tier = c.tier || 'T2';
+          const label = lang === 'ko' ? c.label : (c.labelEn || c.label);
+          const rule = lang === 'ko' ? c.rule : (c.ruleEn || c.rule);
+          if (lang === 'ko') {
+            lines.push(`  후보 R${c.id} — "${label}" 유형, ${c.count}회 반복 (프로젝트: ${c.project})`);
+            lines.push(`      판정: ${tier} (${rs.tierLabel(tier)}) → ${c.agent} 서브에이전트 위임 권장 · 적용 범위 제안: ${rs.scopeLabel(c.suggestedScope)}`);
+            lines.push(`      예시 요청: "${c.example}"`);
+            lines.push(`      등록 시 ratchet-model.md에 기록될 룰: "${rule}"`);
+          } else {
+            lines.push(`  Candidate R${c.id} — "${label}", seen ×${c.count} (project: ${c.project})`);
+            lines.push(`      verdict: ${tier} (${rs.tierLabel(tier, 'en')}) → delegate to the ${c.agent} subagent · suggested scope: ${rs.scopeLabel(c.suggestedScope, 'en')}`);
+            lines.push(`      example request: "${c.example}"`);
+            lines.push(`      rule that would be written to ratchet-model.md: "${rule}"`);
+          }
+        }
+        if (lang === 'ko') {
+          lines.push('등록하면 다음 세션부터 자동 위임됩니다. 사용자에게 등록 여부를 물을 때 위 룰 원문을 그대로 보여주고, 적용 범위까지 확인한 뒤 실행하세요:');
+          lines.push('  claude-token-saver harness promote R<N> --project|--global   # 적용 범위는 반드시 사용자에게 확인');
+          lines.push('  claude-token-saver route-scan dismiss <N>                    # 사용자가 원치 않으면');
+        } else {
+          lines.push('Once registered, delegation happens automatically from the next session. Show the user the rule text verbatim, confirm the scope with them, then run:');
+          lines.push('  claude-token-saver harness promote R<N> --project|--global   # ALWAYS confirm the scope with the user first');
+          lines.push('  claude-token-saver route-scan dismiss <N>                    # if they do not want it');
+        }
+      }
+      if (reviewRules.length > 0) {
+        lines.push(lang === 'ko'
+          ? '[claude-token-saver rule-health] 사용자가 승인한 위임 룰 중, 위임 대상 유형의 최근 에러율이 기준(20%)을 넘어 재검토가 필요한 룰이 있습니다 — 사용자에게 브리핑하고 조건 좁히기/제거를 상의하세요:'
+          : '[claude-token-saver rule-health] Some user-approved delegation rules now exceed the 20% error-rate threshold for their delegated category — brief the user and discuss narrowing or removing them:');
+        for (const r of reviewRules) {
+          lines.push(lang === 'ko'
+            ? `  룰 #${r.n} (${r.tier} ${rs.tierLabel(r.tier)} · ${rs.scopeLabel(r.scope)}) — 최근 에러율 ${Math.round((r.errRate || 0) * 100)}%`
+            : `  rule #${r.n} (${r.tier} ${rs.tierLabel(r.tier, 'en')} · ${rs.scopeLabel(r.scope, 'en')}) — recent error rate ${Math.round((r.errRate || 0) * 100)}%`);
+          lines.push(`      "${r.rule}"`);
+        }
+        lines.push(lang === 'ko'
+          ? '  제거: claude-token-saver route-scan rules rm <N>'
+          : '  remove with: claude-token-saver route-scan rules rm <N>');
+      }
+      lines.push(lang === 'ko'
+        ? '위 내용은 사용자의 첫 메시지 주제와 무관하더라도(단순 인사여도) 첫 응답 말미에 `※ [claude-token-saver]` 라벨을 달아 요약 브리핑하세요 — 사용자가 물어볼 때까지 기다리지 말 것.'
+        : 'Summarize the above at the end of your first response under a `※ [claude-token-saver]` label, even if the user\'s first message is unrelated (a bare greeting counts) — do not wait to be asked.');
+      console.log(lines.join('\n'));
+      // Record what was actually briefed so the UserPromptSubmit brief hook
+      // suppresses exactly these — a candidate landing after this read (e.g.
+      // the detached rescan above finishing) still gets briefed next prompt.
+      try {
+        const { seedSessionBriefed } = await import('../brief.js');
+        seedSessionBriefed(hookCtx.session_id, [
+          ...open.map((c) => `route|${c.signature}`),
+          ...reviewRules.map((r) => `health|${r.signature}|${r.scope}`),
+        ]);
+      } catch (e) { debug('route-scan:seed-briefed', e); /* worst case is one duplicate brief */ }
+      return;
+    }
+
+    const days = numArg('--days', { dflt: 14, min: 0 });
+    let cache = rs.readRouteScan();
+    if (hasFlag('--refresh') || (cache && cache.days !== days) || await rs.shouldRescan(cache, { days })) {
+      cache = await rs.runRouteScan({ days });
+    }
+    if (hasFlag('--quiet')) return;
+    if (hasFlag('--json')) {
+      console.log(JSON.stringify(cache, null, 2));
+      return;
+    }
+    const easyPct = cache.totalEpisodes ? Math.round(cache.easyEpisodes / cache.totalEpisodes * 100) : 0;
+    console.log(lang === 'ko'
+      ? `route-scan — 최근 ${cache.days}일: 에피소드 ${cache.totalEpisodes}건 중 easy ${cache.easyEpisodes}건 (${easyPct}%)  [스캔: ${cache.scannedAt}]`
+      : `route-scan — last ${cache.days}d: ${cache.easyEpisodes}/${cache.totalEpisodes} episodes easy (${easyPct}%)  [scanned: ${cache.scannedAt}]`);
+    const open = rs.openCandidates(cache);
+    if (open.length === 0) {
+      console.log(lang === 'ko'
+        ? '위임 후보 없음 (반복 3회 미만이거나 이미 처리됨).'
+        : 'No delegation candidates (below recurrence threshold or already resolved).');
+      return;
+    }
+    console.log(lang === 'ko' ? '\n위임 후보 (R<N>=후보 번호, T2/T1=난이도 등급):' : '\nDelegation candidates (R<N> = candidate id, T2/T1 = difficulty tier):');
+    for (const c of open) {
+      const tier = c.tier || 'T2';
+      if (lang === 'ko') {
+        console.log(`  R${c.id}  "${c.label}" ×${c.count}회 [${c.project}]`);
+        console.log(`       판정: ${tier} (${rs.tierLabel(tier)}) → ${c.agent} 위임 권장 · 적용 범위 제안: ${rs.scopeLabel(c.suggestedScope)}`);
+      } else {
+        console.log(`  R${c.id}  "${c.labelEn || c.label}" ×${c.count} [${c.project}]`);
+        console.log(`       verdict: ${tier} (${rs.tierLabel(tier, 'en')}) → delegate to ${c.agent} · suggested scope: ${rs.scopeLabel(c.suggestedScope, 'en')}`);
+      }
+      console.log(`       ${lang === 'ko' ? '예시' : 'example'}: "${c.example}"`);
+      console.log(`       ${lang === 'ko' ? '룰' : 'rule'}: ${lang === 'ko' ? c.rule : (c.ruleEn || c.rule)}`);
+    }
+    console.log('');
+    console.log(lang === 'ko' ? '등록 / 무시:' : 'Promote / dismiss:');
+    console.log('  claude-token-saver harness promote R<N> --project|--global');
+    console.log('  claude-token-saver route-scan dismiss <N>');
+    return;
+}

package/src/debug.js

@@ -0,0 +1,29 @@
+/**
+ * Opt-in diagnostics for the tool's deliberately silent paths.
+ *
+ * Most catches here are best-effort by design: a failed history append or
+ * cache write must never break a statusline that renders every few seconds,
+ * and a hook that throws would disrupt the user's session. The cost is that
+ * a genuinely broken path (bad permissions on the state dir, a corrupt hook
+ * payload) is indistinguishable from "nothing to do".
+ *
+ * `CTS_DEBUG=1` makes those swallowed failures visible on stderr — which the
+ * statusline contract discards and hooks surface in Claude Code's debug
+ * output — without changing behavior in any way.
+ */
+
+const ENABLED = !!process.env.CTS_DEBUG;
+
+/**
+ * @param {string} scope short label for where the failure happened
+ * @param {unknown} err the swallowed error
+ */
+export function debug(scope, err) {
+  if (!ENABLED) return;
+  const msg = err && err.stack ? err.stack : String(err);
+  process.stderr.write(`[cts:${scope}] ${msg}\n`);
+}
+
+export function debugEnabled() {
+  return ENABLED;
+}

package/src/model-rules.js

@@ -16,7 +16,7 @@
  *      (rule-health, per docs/TIER_CRITERIA.md).
  *
  * Registry file (source of truth): <stateDir>/model-rules.json
- *   { rules: [ { signature, tier, category, label, agent, scope,   // 'project'|'global'
+ *   { rules: [ { signature, tier, category, label, labelEn, agent, scope,  // 'project'|'global'
  *                targetRoot,           // project root path (project scope)
  *                rule, example, count, errRate, promotedAt, lastSeen,
  *                status } ] }          // 'active' | 'review'
@@ -31,6 +31,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
+import { userLanguage } from './config.js';
 
 // Post-promotion delegated-category error rate above this flags the rule
 // for review (rule-health). Calibrated against local T0 avg error incidence.
@@ -93,9 +94,16 @@ export function removeModelRule(index1) {
   return removed;
 }
 
-/** Render the full ratchet-model.md for one target (scope+root). */
-export function renderModelRatchet(rules) {
-  const lines = [
+/**
+ * Render the full ratchet-model.md for one target (scope+root).
+ *
+ * The LLM reads this file as instructions, so it is written in the user's
+ * configured language — a Korean-only file would pull an English session's
+ * responses into Korean.
+ */
+export function renderModelRatchet(rules, lang = userLanguage()) {
+  const ko = lang === 'ko';
+  const lines = ko ? [
     '# Model-Fitting Ratchet (claude-token-saver 자동 관리)',
     '',
     '로그 기반 티어 위임 룰. 이 파일은 route-scan이 매 스캔마다 통째로 재생성하므로',
@@ -107,10 +115,23 @@ export function renderModelRatchet(rules) {
     '',
     '## Rules',
     '',
+  ] : [
+    '# Model-Fitting Ratchet (managed by claude-token-saver)',
+    '',
+    'Log-derived tier delegation rules. route-scan regenerates this file in full',
+    'on every scan — do not edit it by hand. List / remove with:',
+    '`claude-token-saver route-scan rules [rm <N>]`.',
+    '',
+    'When delegating under a rule below, show the user this line first so it is',
+    'visible which tool is saving tokens:',
+    '`🔀 [claude-token-saver] model fitting: "<category>" → delegated to <agent>`',
+    '',
+    '## Rules',
+    '',
   ];
-  const healthOf = (r) => r.status === 'review'
+  const healthOf = (r) => r.status !== 'review' ? '' : (ko
     ? ` ⚠ rule-health: 최근 위임 대상 에러율 ${Math.round((r.errRate || 0) * 100)}% — 조건을 좁히거나 제거 검토`
-    : '';
+    : ` ⚠ rule-health: recent error rate ${Math.round((r.errRate || 0) * 100)}% for the delegated category — narrow the condition or remove`);
   const statsOf = (r) => `×${r.count || 0}, err ${Math.round((r.errRate || 0) * 100)}%, seen ${r.lastSeen || r.promotedAt}`;
 
   // A category can carry both a T2 (haiku) and a T1 (sonnet) rule. Tier is
@@ -128,10 +149,13 @@ export function renderModelRatchet(rules) {
     const t2 = group.find((r) => r.tier === 'T2');
     const t1 = group.find((r) => r.tier === 'T1');
     if (t2 && t1) {
-      const rule =
-        `"${t2.label}" 유형 요청은 기본적으로 ${t2.agent}(haiku) 서브에이전트로 위임한다(예: "${t2.example}"). ` +
-        `여러 단계·여러 파일 수정이 얽힌 중간 난도 요청(예: "${t1.example}")은 model: sonnet 서브에이전트로 위임한다. ` +
-        `설계 판단·배포·스토어 제출 같은 비가역 작업이 섞이거나 위임 중 에러가 반복되면 위임하지 말고 메인 모델이 직접 처리한다`;
+      const rule = ko
+        ? `"${t2.label}" 유형 요청은 기본적으로 ${t2.agent}(haiku) 서브에이전트로 위임한다(예: "${t2.example}"). ` +
+          `여러 단계·여러 파일 수정이 얽힌 중간 난도 요청(예: "${t1.example}")은 model: sonnet 서브에이전트로 위임한다. ` +
+          `설계 판단·배포·스토어 제출 같은 비가역 작업이 섞이거나 위임 중 에러가 반복되면 위임하지 말고 메인 모델이 직접 처리한다`
+        : `Delegate "${t2.labelEn || t2.label}" requests to the ${t2.agent} (haiku) subagent by default (e.g. "${t2.example}"). ` +
+          `Escalate moderate ones that span multiple steps or file edits (e.g. "${t1.example}") to a model: sonnet subagent. ` +
+          `Do not delegate at all — handle it on the main model — when the request mixes in design judgement or irreversible work (deploy, release, store submission), or when errors repeat during delegation`;
       lines.push(`- ${rule}${healthOf(t2)}${healthOf(t1)} <!-- T2 ${statsOf(t2)} / T1 ${statsOf(t1)} -->`);
       for (const r of group) {
         if (r !== t2 && r !== t1) lines.push(`- ${r.rule}${healthOf(r)} <!-- ${statsOf(r)} -->`);

package/src/parser.js

@@ -3,6 +3,7 @@ import { readdir, stat } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
 import { join, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
+import { loadCache, getCached, putCached, saveCache } from './session-cache.js';
 
 const CLAUDE_DIR = join(homedir(), '.claude', 'projects');
 
@@ -158,7 +159,9 @@ export async function discoverSessionFiles(options = {}) {
       try {
         const s = await stat(fp);
         if (s.mtimeMs >= cutoff) {
-          files.push({ path: fp, projectDir: projDir, mtime: s.mtimeMs });
+          // `size` pairs with `mtime` as the session-cache key — transcripts
+          // are append-only, so the pair identifies a parse result exactly.
+          files.push({ path: fp, projectDir: projDir, mtime: s.mtimeMs, size: s.size });
         }
       } catch {
         continue;
@@ -170,21 +173,43 @@ export async function discoverSessionFiles(options = {}) {
 }
 
 /**
- * Parse all sessions with concurrency control
+ * Parse all sessions with concurrency control, backed by the (path, mtime,
+ * size) session cache so repeated runs — above all the statusline, which
+ * re-runs this every few seconds — only touch transcripts that changed.
+ *
+ * The returned sessions carry the aggregate summary WITHOUT the per-request
+ * array: it is an aggregation detail no consumer reads, and omitting it on
+ * both the cache-hit and fresh-parse paths keeps the two shapes identical.
+ * Call `parseSessionFile` directly if you need the raw requests.
+ *
+ * @param {object} [options] forwarded to discoverSessionFiles
+ * @param {boolean} [options.noCache=false] bypass the cache entirely
  */
 export async function parseAllSessions(options = {}) {
   const files = await discoverSessionFiles(options);
   const concurrency = 10;
   const results = [];
+  const useCache = !options.noCache;
+  const cache = useCache ? loadCache() : { entries: {} };
+  let misses = 0;
 
   for (let i = 0; i < files.length; i += concurrency) {
     const batch = files.slice(i, i + concurrency);
     const parsed = await Promise.all(
       batch.map(async (f) => {
+        if (useCache) {
+          const hit = getCached(cache, f);
+          if (hit) return hit;
+        }
         try {
           const session = await parseSessionFile(f.path);
           session.projectDir = f.projectDir;
-          return session;
+          const { requests, ...summary } = session;
+          if (useCache) {
+            putCached(cache, f, session);
+            misses++;
+          }
+          return summary;
         } catch {
           return null;
         }
@@ -193,5 +218,7 @@ export async function parseAllSessions(options = {}) {
     results.push(...parsed.filter(Boolean));
   }
 
+  if (useCache && misses > 0) saveCache(cache);
+
   return results.filter((s) => s.requestCount > 0);
 }

package/src/route-scan.js

@@ -68,36 +68,42 @@ const CATEGORIES = [
   {
     id: 'paste',
     label: '붙여넣은 화면·로그 질문',
+    labelEn: 'questions about pasted screens/logs',
     agent: 'haiku-explore',
     kw: null, // matched by length, see categorize()
   },
   {
     id: 'translate',
     label: '배치 번역·정형 텍스트 변환',
+    labelEn: 'batch translation / mechanical text transforms',
     agent: 'haiku-translate',
     kw: [[/번역|translate/i, 2], [/변환해|표로 정리|포맷팅/i, 1]],
   },
   {
     id: 'explore',
     label: '탐색·조회 (파일/값 찾기)',
+    labelEn: 'lookup (finding files/values)',
     agent: 'haiku-explore',
     kw: [[/grep|검색|search|find/i, 2], [/찾아|어디|위치|목록|살펴/i, 1]],
   },
   {
     id: 'read',
     label: '읽기·요약·설명',
+    labelEn: 'reading / summarizing / explaining',
     agent: 'haiku-explore',
     kw: [[/요약|summar|explain/i, 2], [/읽어|설명|정리해|보여줘|알려줘|뭐야|what/i, 1]],
   },
   {
     id: 'check',
     label: '상태 확인·검증',
+    labelEn: 'status checks / verification',
     agent: 'haiku-explore',
     kw: [[/확인|검증|verify|점검/i, 2], [/맞아\?|되나|됐나|됐어|되는지|괜찮|체크|check|status/i, 1]],
   },
   {
     id: 'run',
     label: '명령 실행 (빌드·테스트·git)',
+    labelEn: 'running commands (build/test/git)',
     agent: 'haiku-runner',
     kw: [[/git |commit|push|npm |pip|빌드해|빌드 돌/i, 2], [/실행|돌려|run |build|빌드|테스트|설치/i, 1]],
   },
@@ -335,6 +341,7 @@ export async function runRouteScan({ days = 14 } = {}) {
       tier,
       category: cat.id,
       label: cat.label,
+      labelEn: cat.labelEn,
       agent: tier === 'T2' ? cat.agent : 'sonnet',
       project: projectDir,
       projectPath: '',
@@ -368,9 +375,15 @@ export async function runRouteScan({ days = 14 } = {}) {
     r.tier === g.tier && r.category === g.category &&
     (r.scope === 'global' || r.project === g.project));
 
+  // Both languages are computed at scan time and stored on the candidate, so
+  // switching `language` later re-renders (and promotes) correctly without
+  // waiting for a rescan.
   const ruleText = (g) => g.tier === 'T2'
     ? `"${g.label}" 유형의 단순 요청(예: "${g.example}")은 ${g.agent}(haiku) 서브에이전트로 위임한다 (설계 판단·배포·스토어 제출 같은 비가역 작업이 섞이면 위임하지 않음)`
     : `"${g.label}" 유형의 중간 난도 요청(예: "${g.example}")은 model: sonnet 서브에이전트로 위임한다 (설계 판단·비가역 작업·반복 에러 발생 시 메인 모델이 이어받음)`;
+  const ruleTextEn = (g) => g.tier === 'T2'
+    ? `Delegate simple "${g.labelEn}" requests (e.g. "${g.example}") to the ${g.agent} (haiku) subagent — never when the request mixes in design judgement or irreversible work like deploy/release/submission`
+    : `Delegate moderate "${g.labelEn}" requests (e.g. "${g.example}") to a model: sonnet subagent — hand back to the main model on design judgement, irreversible work, or repeated errors`;
 
   const candidates = [...groups.values()]
     .filter((g) => g.count >= MIN_RECURRENCE && !hasRule(g))
@@ -382,6 +395,7 @@ export async function runRouteScan({ days = 14 } = {}) {
       tier: g.tier,
       category: g.category,
       label: g.label,
+      labelEn: g.labelEn,
       agent: g.agent,
       project: g.project,
       // Real session cwd for the project (munged `project` is lossy) — lets
@@ -396,6 +410,7 @@ export async function runRouteScan({ days = 14 } = {}) {
       // the same category recurs across 2+ projects (then 'global').
       suggestedScope: 'project',
       rule: ruleText(g),
+      ruleEn: ruleTextEn(g),
     }));
 
   // Same category appearing in 2+ projects → suggest global for each.