claude-token-saver 3.13.0 → 3.14.0

package/README.en.md

@@ -199,6 +199,7 @@ claude-token-saver route-scan                    # scan (24h cache) + tiered can
 claude-token-saver harness promote R1 --project  # promote candidate R1 to a model-fitting rule
 claude-token-saver route-scan dismiss 1          # not interested — won't resurface
 claude-token-saver route-scan rules              # list model-fitting rules (rm <N> to remove)
+claude-token-saver route-scan savings            # the savings ledger — which rule moved work off which model, onto which
 ```
 
 Dig deeper: **tier criteria & research evidence** → [docs/TIER_CRITERIA.md](./docs/TIER_CRITERIA.md) (Korean) · **rule-file mechanics, scan triggers, subagent setup** → [docs/ROUTE_SCAN.md](./docs/ROUTE_SCAN.md) (Korean + English)
@@ -305,6 +306,12 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.14.0 (2026-08-22)
+- **The statusline headline names the model changes behind the total** — `🔀 Routing saved weekly $1.4 · monthly $2.1 · total $2.1 | fable→sonnet 1× $0.72 · opus→haiku 1× $0.57 …`. Versions are dropped (`claude-opus-4-5-20251101-v1:0` → `opus`) since they bump constantly and add nothing here. **Every** pair is listed rather than a top-N: the amounts sit next to a total, so a truncated list misstates what that total is made of. Families collapse the list on their own, so it stays short without being cut.
+- **New `route-scan savings`** — the evidence behind the headline: a per-model-change rollup (from, to, runs, dollars) and the per-run log (date, amount, model change, the rule that caused it).
+- **Baselines are the model that handled a category most, not the priciest seen** — transcripts routinely carry more than one model (a mid-session switch), and taking the priciest let a single Fable record set the baseline for a category Opus had handled thirty times, inflating every later saving. Ties break toward the pricier model. Baselines written under the old definition are recomputed once.
+- **The ledger is written after the rule refresh** — writing it first made a changed baseline take two scans to settle: the first stored the new baseline but billed against the old one.
+
 ### v3.13.0 (2026-08-22)
 - **Routing savings are now priced "model before the rule → model that ran it"** — previously the counterfactual was the session's priciest model, which booked a saving even when that model had never handled work of this shape. Each rule now remembers the **model that handled its category before promotion** (its baseline) and prices only against that. The baseline is sticky once set: as a rule takes effect fewer episodes stay on the expensive model, so a recomputed baseline would drift down and shrink the very saving the rule produces.
 - **Delegations no rule covers are excluded** — `Explore`, hand-written agents, and plugin subagents were all being counted, crediting this tool for routing it never did. Ledger events now carry `rule` / `from` / `to`, so every dollar is traceable to the rule and model change behind it.

package/README.md

@@ -179,6 +179,17 @@ claude-token-saver route-scan                    # 스캔 (24h 캐시) + 티어
 claude-token-saver harness promote R1 --project  # 후보 R1을 모델 피팅 룰로 등록
 claude-token-saver route-scan dismiss 1          # 관심 없으면 무시 (재스캔에도 안 뜸)
 claude-token-saver route-scan rules              # 등록된 모델 피팅 룰 목록 (rm <N>으로 제거)
+claude-token-saver route-scan savings            # 절감 원장 — 어느 룰이 어떤 모델에서 어떤 모델로 옮겼는지
+```
+
+`route-scan savings`는 statusline의 `🔀 Routing saved` 한 줄 뒤에 있는 근거를 그대로 보여줍니다. 모델 이동별 합계와 실행별 내역이 함께 나오므로, 금액이 어디서 나왔는지 추적할 수 있습니다.
+
+```
+🔀 라우팅 절감 — 주간 $1.40 · 월간 $2.09 · 누적 $2.09
+
+모델 이동별:
+  claude-fable-5 → claude-sonnet-5  —  1회, $0.72
+  claude-opus-5 → claude-haiku-4-5  —  1회, $0.57
 ```
 
 더 알아보기: **티어 기준·리서치 근거** → [docs/TIER_CRITERIA.md](./docs/TIER_CRITERIA.md) · **룰 파일 구조·스캔 트리거·서브에이전트 준비** → [docs/ROUTE_SCAN.md](./docs/ROUTE_SCAN.md)
@@ -261,6 +272,12 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.14.0 (2026-08-22)
+- **statusline 헤드라인이 모델 이동을 함께 보여줍니다** — `🔀 Routing saved weekly $1.4 · monthly $2.1 · total $2.1 | fable→sonnet 1× $0.72 · opus→haiku 1× $0.57 …`. 버전 숫자는 계속 올라가고 statusline에서는 잡음이라 계열명만 남깁니다(`claude-opus-4-5-20251101-v1:0` → `opus`). 이동 목록은 **자르지 않고 전부** 표시합니다 — 금액이 `total` 옆에 붙어 있어서 일부만 보이면 합계를 잘못 말하게 됩니다. 계열 단위로 접히면 조합 수가 원래 많지 않아 줄은 짧게 유지됩니다.
+- **`route-scan savings` 추가** — 헤드라인 뒤에 있는 근거를 그대로 조회합니다. 모델 이동별 합계(어느 모델에서 어느 모델로 몇 회, 얼마)와 실행별 내역(날짜·금액·모델 이동·해당 룰)이 함께 나옵니다.
+- **기준 모델을 최고가가 아니라 '가장 많이 처리한 모델'로 정합니다** — 한 트랜스크립트에 모델이 섞이는 일이 흔한데(세션 중 모델 전환 등) 최고가를 고르면 Fable 기록 한 건이 Opus가 서른 번 처리한 카테고리의 기준을 차지해 이후 절감액을 전부 부풀렸습니다. 동수일 때만 비싼 쪽으로 기웁니다. 옛 정의로 굳은 기준은 1회 재계산됩니다.
+- **원장 기록을 룰 갱신 뒤로 옮겼습니다** — 앞서 기록하면 기준이 바뀐 스캔이 새 기준을 저장하면서 청구는 옛 기준으로 해, 합계가 두 번째 스캔에야 맞았습니다.
+
 ### v3.13.0 (2026-08-22)
 - **라우팅 절감액의 기준을 '승격 전 모델 → 위임 모델' 차액으로 바꿨습니다** — 이전에는 세션의 최상위 모델을 반사실로 잡아, 그 모델이 해당 유형을 실제로 처리한 적이 없어도 차액을 절감으로 기록했습니다. 이제 각 룰이 **승격 전 그 유형을 직접 처리하던 모델**(baseline)을 기억하고, 그 기준 대비로만 계산합니다. baseline은 한 번 정해지면 고정됩니다 — 룰이 효력을 낼수록 직접 처리 사례가 줄어 기준이 흘러내리고, 그러면 룰이 만든 절감이 스스로 작아지기 때문입니다.
 - **룰이 커버하지 않는 위임은 집계에서 뺐습니다** — `Explore`, 직접 만든 에이전트, 플러그인 에이전트처럼 이 도구와 무관하게 돌던 서브에이전트 실행까지 절감으로 잡히고 있었습니다. 도구가 라우팅하지 않은 작업의 절감을 도구 성과로 표시하면 안 됩니다. 원장 이벤트에 `rule`/`from`/`to`를 남겨 어느 룰이 어떤 모델 차이를 만들었는지 추적할 수 있습니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/src/commands/route-scan.js

@@ -10,6 +10,58 @@ export async function run({ args, hasFlag, numArg }) {
     const { userLanguage } = await import('../config.js');
     const lang = userLanguage();
 
+    // route-scan savings — the delegation ledger behind the statusline's
+    // "Routing saved" headline. The headline is one number; this is the
+    // evidence for it: which rule fired, which model the work moved off, and
+    // which model actually ran it.
+    if (args[1] === 'savings') {
+      const { loadLedger, delegationSavedTotals } = await import('../savings-ledger.js');
+      const events = Object.entries(loadLedger().events)
+        .map(([key, e]) => ({ key, ...e }))
+        .sort((a, b) => b.ts - a.ts);
+      if (events.length === 0) {
+        console.log(lang === 'ko'
+          ? '기록된 라우팅 절감 없음. 승격된 룰이 실제로 위임을 일으킨 뒤 `route-scan --refresh` 를 돌리면 채워집니다.'
+          : 'No routing savings recorded yet. Promote a rule, let it delegate, then run `route-scan --refresh`.');
+        return;
+      }
+      const t = delegationSavedTotals();
+      const money = (v) => `$${v.toFixed(2)}`;
+      console.log(lang === 'ko'
+        ? `🔀 라우팅 절감 — 주간 ${money(t.week)} · 월간 ${money(t.month)} · 누적 ${money(t.total)}`
+        : `🔀 Routing saved — weekly ${money(t.week)} · monthly ${money(t.month)} · total ${money(t.total)}`);
+
+      // Per model-pair rollup first: the "what moved where" question is what
+      // this view exists to answer, and it is easier to read than the log.
+      const pairs = new Map();
+      for (const e of events) {
+        const k = `${e.from || '?'} → ${e.to || '?'}`;
+        const p = pairs.get(k) || { runs: 0, usd: 0 };
+        p.runs += 1;
+        p.usd += Number(e.usd) || 0;
+        pairs.set(k, p);
+      }
+      console.log('');
+      console.log(lang === 'ko' ? '모델 이동별:' : 'By model change:');
+      for (const [k, p] of [...pairs].sort((a, b) => b[1].usd - a[1].usd)) {
+        const runs = lang === 'ko' ? `${p.runs}회` : `${p.runs} run${p.runs === 1 ? '' : 's'}`;
+        console.log(`  ${k}  —  ${runs}, ${money(p.usd)}`);
+      }
+
+      console.log('');
+      console.log(lang === 'ko' ? '실행별 (최근순):' : 'By run (newest first):');
+      for (const e of events) {
+        const when = new Date(e.ts).toISOString().slice(0, 10);
+        console.log(`  ${when}  ${money(Number(e.usd) || 0).padStart(7)}  ${e.from || '?'} → ${e.to || '?'}`);
+        console.log(`            ${lang === 'ko' ? '룰' : 'rule'}: ${e.rule || '(unattributed)'}`);
+      }
+      console.log('');
+      console.log(lang === 'ko'
+        ? '금액은 "룰 승격 전 그 유형을 처리하던 모델"과 실제 실행 모델의 가격 차이입니다 (토큰 수는 고정 가정).'
+        : 'Each amount is the price gap between the model that handled this category before the rule and the model that actually ran it (token counts held constant).');
+      return;
+    }
+
     // 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') {

package/src/formatters/statusline.js

@@ -291,11 +291,25 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     const part = (usd, label) =>
       `${c(GRAY)}${label}${c(RESET)} ${c(GREEN)}${formatMoney(Number(usd) || 0)}${c(RESET)}`;
     const head = isIcon ? '🔀 Routing saved' : 'Routing saved';
+    // Model changes behind the total, family-level and version-free: `opus →
+    // haiku 2× $0.6`. Versions bump constantly and add nothing here — the
+    // shape of the trade is the point.
+    //
+    // Every pair is listed, not a top-N: the amounts are shown next to a
+    // total, so a truncated list reads as "this is what the total is made of"
+    // and quietly misstates it. Families collapse the list on their own —
+    // there are only so many tier-to-tier moves — so it stays short without
+    // being cut.
+    const pairs = Array.isArray(totals.pairs) ? totals.pairs : [];
+    const pairText = pairs
+      .map((p) => `${c(GRAY)}${p.from}→${p.to}${c(RESET)} ${c(GRAY)}${p.runs}×${c(RESET)} ${c(GREEN)}${formatMoney(p.usd)}${c(RESET)}`)
+      .join(` ${c(GRAY)}·${c(RESET)} `);
     totalsLine =
       `${c(GREEN)}${c(BOLD)}${head}${c(RESET)} ` +
       `${part(totals.week, 'weekly')} ${c(GRAY)}·${c(RESET)} ` +
       `${part(totals.month, 'monthly')} ${c(GRAY)}·${c(RESET)} ` +
-      `${part(totals.total, 'total')}`;
+      `${part(totals.total, 'total')}` +
+      (pairText ? `  ${c(GRAY)}|${c(RESET)}  ${pairText}` : '');
   }
 
   // Period label honors hour-precision configs (`mode 6h` → "6h", `mode 1d` → "1d").

package/src/model-rules.js

@@ -344,8 +344,15 @@ export function refreshModelRules(episodeStats, delegatedStats = new Map(), { no
       // it. Sticky once set: as a rule takes effect, fewer episodes stay on the
       // expensive model, so a recomputed baseline would drift downward and
       // shrink the very savings the rule is producing.
-      if (!r.baselineModel && s.baselineModel) {
+      //
+      // `baselineSource` marks which definition produced it. Baselines written
+      // before the definition changed from "priciest model seen" to "model that
+      // handled the most episodes" are recomputed once — a single stray record
+      // of a pricier model could otherwise hold the baseline above what the
+      // category was really running on, inflating every saving priced against it.
+      if (s.baselineModel && (!r.baselineModel || r.baselineSource !== 'dominant')) {
         r.baselineModel = s.baselineModel;
+        r.baselineSource = 'dominant';
         changed = true;
       }
     }

package/src/route-scan.js

@@ -262,6 +262,24 @@ export function episodeRank(ep) {
  * net loss. (Replaces the old boolean "is it haiku?" test, which could not
  * tell a Sonnet session from a Fable one.)
  */
+/**
+ * The model a category was mostly handled by, from a { model → episodes } map.
+ * Ties break toward the pricier model: with no majority either way, the more
+ * expensive reading of "what this used to cost" is the one worth stating.
+ * Returns null for an empty map, which callers read as "no baseline yet".
+ */
+export function dominantModel(counts) {
+  let best = null;
+  let bestN = 0;
+  for (const [model, n] of Object.entries(counts || {})) {
+    if (n > bestN || (n === bestN && best && modelRank(model) > modelRank(best))) {
+      best = model;
+      bestN = n;
+    }
+  }
+  return best;
+}
+
 export function worthDelegating(tier, rank) {
   const target = TIER_TARGET_RANK[tier];
   return target !== undefined && rank > target;
@@ -379,24 +397,29 @@ export async function runRouteScan({ days = 14 } = {}) {
   const episodeStats = new Map(); // "category|project" (+ "category|*") → outcome stats
   let tieredEpisodes = 0;
   const bumpStats = (key, ep) => {
-    const s = episodeStats.get(key) || { count: 0, errCount: 0, epCount: 0, baselineModel: null, baselineRank: -1 };
+    const s = episodeStats.get(key) || { count: 0, errCount: 0, epCount: 0, baselineModel: null, modelCounts: {} };
     s.count += 1;
     s.epCount += 1;
     if (ep.errors > 0) s.errCount += 1;
     // Baseline model: what actually handled this category BEFORE any rule sent
     // it elsewhere. This is the only honest counterfactual for "routing saved
     // money" — the session's priciest model is not, since it may never have
-    // touched work of this shape. Episodes counted here are by definition ones
-    // an expensive model handled directly, so the priciest model seen on them
-    // is the before-picture the rule replaced.
+    // touched work of this shape.
+    //
+    // Counted, not maxed. A transcript routinely carries more than one model
+    // (the user switches mid-session, a compaction pass runs elsewhere), and
+    // taking the priciest of them would let a single Fable record set the
+    // baseline for a category that Opus handled thirty times — inflating every
+    // later saving. The model that handled the most episodes is the one the
+    // rule actually replaced; price breaks a tie.
     for (const m of ep.models) {
       // Only ids the pricing table really recognizes may become a baseline —
       // an unresolved gateway id or a house alias would be priced as Sonnet
       // and quietly rewrite every saving computed against it.
       if (!isRecognizedModelId(m)) continue;
-      const r = modelRank(m);
-      if (r > s.baselineRank) { s.baselineRank = r; s.baselineModel = m; }
+      s.modelCounts[m] = (s.modelCounts[m] || 0) + 1;
     }
+    s.baselineModel = dominantModel(s.modelCounts);
     episodeStats.set(key, s);
   };
 
@@ -522,34 +545,13 @@ export async function runRouteScan({ days = 14 } = {}) {
         // not against whatever the session's priciest model happened to be.
         const rule = ruleForRun(runTier, cat.id, projectDir);
         if (!rule) continue; // no rule routed this run — not our saving to claim
-        const baseline = baselineFor(rule, runTier, cat.id, projectDir);
-        if (!baseline) continue; // baseline unknown → no honest counterfactual
-        // Both sides of the comparison must be ids the pricing table really
-        // recognizes. A house alias from a company gateway prices as Sonnet by
-        // default, which would fabricate a saving against a cheap baseline or
-        // erase a real one — worse than showing nothing. Map such ids in
-        // profile-map.json's `modelAliases` to bring these runs back in.
-        if (!isRecognizedModelId(baseline) || !isRecognizedModelId(run.model)) continue;
-        const routed = runSaving(run, baseline);
-        if (routed > 0) {
-          ledgerEvents.push({
-            key: run.path,
-            ts: run.endedAt ?? run.startedAt ?? Date.now(),
-            usd: routed,
-            rule: rule.signature,
-            from: baseline,
-            to: run.model,
-          });
-        }
+        // Priced below, after this scan's baselines have been written back to
+        // the registry — see the note at the ledger write.
+        if (!isRecognizedModelId(run.model)) continue;
+        ledgerEvents.push({ run, rule, tier: runTier, catId: cat.id, projectDir });
       }
     }
   }
-  try {
-    const { recordDelegationEvents } = await import('./savings-ledger.js');
-    recordDelegationEvents(ledgerEvents);
-  } catch {
-    // ledger write failure only delays the statusline totals, never the scan
-  }
 
   // Keep prior dismissed/promoted signatures across rescans.
   const prev = readRouteScan();
@@ -656,6 +658,40 @@ export async function runRouteScan({ days = 14 } = {}) {
     refreshModelRules(episodeStats, delegatedStats, { now: cache.scannedAt });
   } catch { /* registry unwritable — scan result still valid */ }
 
+  // Ledger last, so savings are priced against the baselines this scan just
+  // wrote. Pricing before the refresh made a changed baseline take two scans
+  // to show up: the first wrote the new baseline but billed against the old
+  // one, and the totals only settled on the second.
+  try {
+    const { recordDelegationEvents } = await import('./savings-ledger.js');
+    const { loadModelRules } = await import('./model-rules.js');
+    const fresh = loadModelRules().rules;
+    const priced = [];
+    for (const e of ledgerEvents) {
+      const rule = fresh.find((r) => r.signature === e.rule.signature) || e.rule;
+      const baseline = baselineFor(rule, e.tier, e.catId, e.projectDir);
+      // Both sides of the comparison must be ids the pricing table really
+      // recognizes. A house alias from a company gateway prices as Sonnet by
+      // default, which would fabricate a saving against a cheap baseline or
+      // erase a real one — worse than showing nothing. Map such ids in
+      // profile-map.json's `modelAliases` to bring these runs back in.
+      if (!baseline || !isRecognizedModelId(baseline)) continue;
+      const usd = runSaving(e.run, baseline);
+      if (usd <= 0) continue;
+      priced.push({
+        key: e.run.path,
+        ts: e.run.endedAt ?? e.run.startedAt ?? Date.now(),
+        usd,
+        rule: rule.signature,
+        from: baseline,
+        to: e.run.model,
+      });
+    }
+    recordDelegationEvents(priced);
+  } catch {
+    // ledger write failure only delays the statusline totals, never the scan
+  }
+
   return cache;
 }
 

package/src/savings-ledger.js

@@ -88,11 +88,31 @@ export function recordDelegationEvents(events) {
 }
 
 /**
- * Rolling totals: last 7 days, last 30 days, and lifetime. `now` is injectable
- * for tests. Never throws — an unreadable ledger yields all-zero totals.
+ * Family name of a model id, with the version dropped: `claude-opus-5` and
+ * `claude-opus-4-5-20251101-v1:0` both read as `opus`.
+ *
+ * Versions move constantly, and on a statusline the digits are noise — what
+ * the reader wants is the shape of the trade ("opus work now runs on haiku").
+ * Falls back to the id itself so an unmapped name is visible rather than
+ * silently folded into another family.
+ */
+export function modelFamily(model) {
+  const m = String(model || '').toLowerCase();
+  for (const f of ['fable', 'mythos', 'opus', 'sonnet', 'haiku']) {
+    if (m.includes(f)) return f;
+  }
+  return String(model || '?');
+}
+
+/**
+ * Rolling totals: last 7 days, last 30 days, and lifetime, plus `pairs` — the
+ * lifetime rollup by family-level model change, priciest first. `now` is
+ * injectable for tests. Never throws — an unreadable ledger yields zeros.
  */
 export function delegationSavedTotals(now = Date.now()) {
-  const totals = { week: 0, month: 0, total: 0 };
+  const empty = () => ({ week: 0, month: 0, total: 0, pairs: [] });
+  const totals = empty();
+  const byPair = new Map();
   try {
     for (const e of Object.values(loadLedger().events)) {
       const usd = Number(e.usd) || 0;
@@ -102,9 +122,16 @@ export function delegationSavedTotals(now = Date.now()) {
         if (now - e.ts <= WEEK_MS) totals.week += usd;
         if (now - e.ts <= MONTH_MS) totals.month += usd;
       }
+      if (!e.from || !e.to) continue;
+      const key = `${modelFamily(e.from)}→${modelFamily(e.to)}`;
+      const p = byPair.get(key) || { from: modelFamily(e.from), to: modelFamily(e.to), runs: 0, usd: 0 };
+      p.runs += 1;
+      p.usd += usd;
+      byPair.set(key, p);
     }
   } catch {
-    return { week: 0, month: 0, total: 0 };
+    return empty();
   }
+  totals.pairs = [...byPair.values()].sort((a, b) => b.usd - a.usd);
   return totals;
 }