claude-token-saver 3.11.2 → 3.12.0

package/README.en.md

@@ -301,6 +301,11 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.12.0 (2026-08-22)
+- **Routing saved now leads the statusline with weekly / monthly / lifetime totals** — `🔀 Routing saved $1.3 wk · $2.0 mo · $9.8 all`. Each delegated subagent run's saving is recorded in a ledger (`delegation-ledger.json`) keyed by its transcript path, so overlapping re-scans upsert instead of double-counting; the statusline sums 7-day, 30-day, and lifetime windows on line 1 while the other chips move to line 2. An empty ledger keeps the legacy one-line layout, and `--single-line` forces it (some macOS Claude Code builds render only the first line). Totals start accruing from the release — no back-fill.
+- **`harness check` reports context weight** — the approximate per-request token cost of CLAUDE.md (warns over the ~4k guideline) and whether a `.claudeignore` exists. Advisory only; the 🅷 N/5 score is unaffected.
+- **Self-describing ARNs resolve without learning** — `foundation-model/anthropic.claude-…` and system cross-region profiles (`inference-profile/us.anthropic.claude-…`) embed the model id yet resolved to `unknown`, dropping delegation and cost aggregation entirely on gateway machines that hadn't accumulated learning samples. They now pass straight to the existing tier classifier; opaque application-profile ids keep the override/learning path.
+
 ### v3.11.0 (2026-08-21)
 - **Routing savings chip in the statusline** — `🔀 Routing saved $3.2`. Cumulative savings from model routing, placed right after the model name so it reads early in the line. The existing `💰 Cache saved` covers the prompt cache and is a different number. Zero or missing data hides the chip entirely, so nothing changes for direct-API users. The statusline only reads `model-rules.json` — it never triggers a scan (it re-renders every few seconds). Segment name: `delegated`.
 - **Role-learning mis-classification fixed** — subagent records sometimes land in the parent transcript without an `isSidechain` flag, and that circumstantial evidence could outvote stated evidence, confirming a haiku profile as the session model (measured: 16 against 1, agreement exactly at the 80% line). Stated evidence (`Task(model:)` parameters, agent-definition frontmatter) and inferred evidence are now tallied separately, and an inference is not adopted when stated evidence contradicts it. Undecided ids stay `unknown` and leave the aggregate.

package/README.md

@@ -257,6 +257,11 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.12.0 (2026-08-22)
+- **Routing saved가 주간·월간·누적으로 statusline 1줄째에 올라옵니다** — `🔀 Routing saved $1.3 wk · $2.0 mo · $9.8 all`. 위임 절감 이벤트를 서브에이전트 run 단위로 원장(`delegation-ledger.json`)에 기록하고(트랜스크립트 경로 키라 재스캔이 겹쳐도 중복 집계 없음), 7일·30일·전체 합산을 표시합니다. 나머지 칩은 2줄째로 내려갑니다. 원장이 비어 있으면 기존 1줄 그대로이고, 일부 환경(macOS 구버전 Claude Code)에서 첫 줄만 보이면 `--single-line`으로 기존 레이아웃을 유지할 수 있습니다. 집계는 원장 도입 시점부터 시작합니다(소급 없음).
+- **`harness check`가 컨텍스트 무게도 알려줍니다** — CLAUDE.md의 요청당 대략 토큰(~4k 가이드라인 초과 시 경고)과 `.claudeignore` 유무를 표시합니다. 자문 정보일 뿐 🅷 N/5 점수에는 반영하지 않습니다.
+- **모델명이 내장된 ARN은 학습 없이 즉시 해석** — `foundation-model/anthropic.claude-…`와 시스템 교차 리전 프로파일(`inference-profile/us.anthropic.claude-…`)은 자원 ID가 곧 모델명인데도 `unknown`으로 떨어져, 학습 표본이 쌓이기 전의 게이트웨이 환경에서 위임·비용 집계가 통째로 빠졌습니다. 이제 즉시 기존 티어 분류로 넘깁니다. 불투명한 application-profile ID는 종전대로 오버라이드/학습 경로입니다.
+
 ### v3.11.0 (2026-08-21)
 - **statusline에 위임 절감 칩 추가** — `🔀 Routing saved $3.2`. 모델 위임으로 아낀 누적 비용이며, 모델 이름 바로 뒤에 놓여 줄 앞쪽에서 읽힙니다. 기존 `💰 Cache saved`(프롬프트 캐시 절감)와는 다른 수치입니다. 값이 0이거나 데이터가 없으면 칩을 아예 그리지 않아 직접 API 사용자에게는 아무것도 늘지 않습니다. statusline은 `model-rules.json`을 읽기만 하며 스캔을 돌리지 않습니다(5초마다 호출되는 자리입니다). 세그먼트 이름은 `delegated`입니다.
 - **역할 학습의 오분류 수정** — 서브에이전트 레코드가 부모 트랜스크립트에 `isSidechain` 없이 섞여 들어오는 경우가 있어, 그 정황 증거가 명시 증거를 이겨 haiku 프로파일이 세션 모델로 확정되곤 했습니다(실측 16건 대 1건, 합의율 정확히 80%). 이제 **명시 증거(`Task(model:)` 파라미터·에이전트 정의 frontmatter)와 정황 증거(sidechain 플래그 부재)를 분리해 집계**하고, 명시 증거가 이를 반박하면 정황 추론을 채택하지 않습니다. 확정이 안 되면 `unknown`으로 남아 집계에서 빠집니다.

package/bin/cli.js

@@ -18,6 +18,7 @@
  *   npx claude-token-saver --statusline --no-color # strip ANSI colors
  *   npx claude-token-saver --statusline --icon     # use 🧠 ⏳ 💰 icons
  *   npx claude-token-saver --statusline --no-timer # hide the TTL countdown
+ *   npx claude-token-saver --statusline --single-line # legacy 1-line layout (no routing-totals headline)
  *   npx claude-token-saver --statusline --exclude-session <path>
  *                                               # exclude a JSONL path from lastActivity
  *                                               # (or set CACHE_MONITOR_EXCLUDE_SESSION env var)
@@ -231,6 +232,7 @@ async function main() {
       timer: showTimer,
       mode: isIcon ? 'icon' : 'text',
       segments,
+      singleLine: hasFlag('--single-line'),
     });
     // For `cycle` mode, prefix with the scenario label so the screen recorder
     // shows what the viewer is looking at (only when explicitly requested).
@@ -443,6 +445,15 @@ async function main() {
   } catch (e) {
     debug('model-rules:saved', e); // an unreadable registry just hides the chip
   }
+  // Rolling week/month/lifetime totals from the delegation ledger — the
+  // statusline's headline line. Falls back to null (chip hidden) on any error.
+  let delegationTotals = null;
+  try {
+    const { delegationSavedTotals } = await import('../src/savings-ledger.js');
+    delegationTotals = delegationSavedTotals();
+  } catch (e) {
+    debug('savings-ledger:totals', e);
+  }
 
   const data = {
     summary: sum,
@@ -459,6 +470,7 @@ async function main() {
     caps,
     model,
     delegationSaved,
+    delegationTotals,
   };
 
   let output;
@@ -505,6 +517,10 @@ async function main() {
       timer: showTimer,
       mode: isIcon ? 'icon' : 'text',
       segments,
+      // macOS builds of Claude Code have rendered only the first line of a
+      // multi-line statusline in some versions (anthropics/claude-code#35176)
+      // — --single-line restores the legacy one-line layout in that case.
+      singleLine: hasFlag('--single-line'),
     });
   } else {
     const { formatReport } = await import('../src/formatters/table.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.11.2",
+  "version": "3.12.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/harness.js

@@ -27,7 +27,7 @@ export async function run({ args, hasFlag }) {
       }
       return dflt;
     };
-    const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessPull, harnessListRules, harnessRmRule, harnessPrune, ratchetSizeStatus, RATCHET_TOKEN_BUDGET, findProjectRoot } =
+    const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessPull, harnessListRules, harnessRmRule, harnessPrune, ratchetSizeStatus, RATCHET_TOKEN_BUDGET, contextWeightStatus, CLAUDE_MD_TOKEN_BUDGET, findProjectRoot } =
       await import('../harness.js');
     const { HARNESS_SECTIONS } = await import('../harness-templates.js');
     const { loadConfig, saveConfig, userLanguage } = await import('../config.js');
@@ -77,6 +77,24 @@ export async function run({ args, hasFlag }) {
           console.log(`${line}`);
         }
       }
+      // Advisory context-weight facts (never counted in 🅷 N/5): CLAUDE.md is
+      // charged on every request, and without a .claudeignore Claude Code can
+      // pull build artifacts and vendored code into context during searches.
+      try {
+        const w = contextWeightStatus({ root });
+        if (w.claudeMd) {
+          const line = `CLAUDE.md size: ~${w.claudeMd.tokens} tok/request (${w.claudeMd.path})`;
+          if (w.claudeMd.overBudget) {
+            console.log(`\n⚠ ${line} — over the ~${CLAUDE_MD_TOKEN_BUDGET} token guideline.`);
+            console.log('  Keep rules and file pointers here; move documentation into files it points to.');
+          } else {
+            console.log(line);
+          }
+        }
+        console.log(`.claudeignore: ${w.hasClaudeIgnore ? 'present' : 'absent — consider adding one so searches skip build output, vendored code, and large data files'}`);
+      } catch (e) {
+        debug('harness:context-weight', e);
+      }
       return;
     }
 

package/src/formatters/statusline.js

@@ -212,8 +212,9 @@ export function formatNoSession({ caps = null, model = null, windowLabel = '' }
  * @param {boolean} [opts.timer=true] - show TTL countdown segment
  * @param {'text'|'icon'} [opts.mode='text'] - label style. 'icon' uses 🧠 ⏳ 💰 instead of word labels.
  * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, harness, model, hit, ttl, saved, delegated, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
+ * @param {boolean} [opts.singleLine=false] - force the legacy one-line layout. By default, when the delegation ledger has lifetime savings, the routing totals lead on their own first line and everything else moves to line 2 (Claude Code renders multi-line statuslines; `--single-line` is the escape hatch for terminals that only show the first line).
  */
-export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null } = {}) {
+export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null, singleLine = false } = {}) {
   const { summary, ttl, cost, options, lastActivity, contextWindow, ctxLive, spikeChip, caps, model } = data;
   const { hitRate } = summary;
 
@@ -273,6 +274,24 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     ? `${c(GREEN)}${delegateLabel}${c(RESET)} ${formatMoney(delegationSaved)}`
     : null;
 
+  // Routing-totals headline line (multi-line layout). Week/month/lifetime
+  // sums from the delegation ledger — the number the whole tool exists to
+  // grow, so it gets line 1 to itself while the diagnostics move to line 2.
+  //   icon:  "🔀 Routing saved $1.2 wk · $3.4 mo · $9.8 all"
+  //   text:  "Routing saved $1.2 wk · $3.4 mo · $9.8 all"
+  const totals = data.delegationTotals;
+  let totalsLine = null;
+  if (!singleLine && totals && Number(totals.total) > 0) {
+    const part = (usd, label) =>
+      `${formatMoney(Number(usd) || 0)} ${c(GRAY)}${label}${c(RESET)}`;
+    const head = isIcon ? '🔀 Routing saved' : 'Routing saved';
+    totalsLine =
+      `${c(GREEN)}${c(BOLD)}${head}${c(RESET)} ` +
+      `${part(totals.week, 'wk')} ${c(GRAY)}·${c(RESET)} ` +
+      `${part(totals.month, 'mo')} ${c(GRAY)}·${c(RESET)} ` +
+      `${part(totals.total, 'all')}`;
+  }
+
   // Period label honors hour-precision configs (`mode 6h` → "6h", `mode 1d` → "1d").
   // Fall back to legacy `${days}d` when callers haven't supplied a label.
   const periodLabel = options.windowLabel || `${options.days}d`;
@@ -493,7 +512,9 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // Delegation savings ride up front, next to the model that would otherwise
   // have done the work. "Cache saved" stays at the tail: it is a lifetime brag
   // stat, while this one is the point of the tool.
-  if (delegateSeg && want('delegated')) segs.push(delegateSeg);
+  // When the totals headline owns line 1, the inline session chip would
+  // repeat the same story on line 2 — drop it there.
+  if (delegateSeg && want('delegated') && !totalsLine) segs.push(delegateSeg);
   if (want('hit')) segs.push(hitSeg);
   if (want('ttl')) segs.push(ttlSeg);
   for (const { key, seg } of usageSegs) {
@@ -509,5 +530,10 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // (longer) statusline render don't bleed into ours. \x1b[K is the standard
   // "erase from cursor to EOL" CSI. Only emitted when color (i.e. ANSI) is
   // allowed — --no-color/NO_COLOR consumers expect escape-free output.
-  return segs.join(' · ') + (color ? '\x1b[K' : '');
+  const eol = color ? '\x1b[K' : '';
+  const rest = segs.join(' · ') + eol;
+  if (totalsLine && want('delegated')) {
+    return totalsLine + eol + '\n' + rest;
+  }
+  return rest;
 }

package/src/harness.js

@@ -431,6 +431,35 @@ export function ratchetSizeStatus({ root = findProjectRoot(), scope = 'project'
   return { path, count: rules.length, bytes, tokens, overBudget: tokens > RATCHET_TOKEN_BUDGET };
 }
 
+// CLAUDE.md itself is also charged on every request. The community guideline
+// is "rules and file pointers, not documentation" — the harness block plus a
+// modest project section fits well under this; docs pasted wholesale do not.
+export const CLAUDE_MD_TOKEN_BUDGET = 4000;
+
+/**
+ * Advisory size/ignore facts for `harness check`:
+ *  - approx token weight of the project (or global) CLAUDE.md
+ *  - whether the project has a .claudeignore (limits what Claude Code will
+ *    read into context during searches)
+ * Purely informational — never affects the 🅷 N/5 score.
+ */
+export function contextWeightStatus({ root = findProjectRoot() } = {}) {
+  const out = { claudeMd: null, hasClaudeIgnore: false };
+  try {
+    out.hasClaudeIgnore = existsSync(join(root, '.claudeignore'));
+  } catch { /* fs error → treat as absent */ }
+  for (const file of [join(root, 'CLAUDE.md'), join(homedir(), '.claude', 'CLAUDE.md')]) {
+    try {
+      if (!existsSync(file)) continue;
+      const bytes = statSync(file).size;
+      const tokens = Math.round(bytes / 4);
+      out.claudeMd = { path: file, bytes, tokens, overBudget: tokens > CLAUDE_MD_TOKEN_BUDGET };
+      break; // project file wins; global only as fallback
+    } catch { /* unreadable → skip */ }
+  }
+  return out;
+}
+
 /**
  * harness prune — move rules out of ratchet.md into ratchet-archive.md next to
  * it. Selection is by tag and/or age; nothing is deleted, so a pruned rule can

package/src/model-alias.js

@@ -44,8 +44,10 @@ export function profileMapPath() {
 }
 
 // `converse/` (LiteLLM) or a bare ARN, foundation- or application-scoped.
+// `foundation-model` ARNs carry the model id directly in the resource part
+// (`foundation-model/anthropic.claude-haiku-…`), so they are captured too.
 const ARN_RE =
-  /arn:aws:bedrock:[^:]*:[^:]*:(?:application-)?inference-profile\/([A-Za-z0-9._:-]+)/;
+  /arn:aws:bedrock:[^:]*:[^:]*:(?:foundation-model|(?:application-)?inference-profile)\/([A-Za-z0-9._:-]+)/;
 
 /** True when the id came from a Bedrock gateway rather than the Claude API. */
 export function isGatewayModelId(model) {
@@ -158,6 +160,16 @@ export function resolveModelAlias(rawModel, { env = process.env } = {}) {
   const pid = profileIdFrom(model);
   if (!pid) return UNKNOWN_MODEL;
 
+  // Self-describing resource ids need no learning: foundation-model ARNs and
+  // system cross-region inference profiles both embed the model id
+  // (`anthropic.claude-haiku-4-5-…` / `us.anthropic.claude-haiku-4-5-…`).
+  // detectPricingTier() already classifies those strings, region prefix
+  // included — only opaque application-profile ids (random hex) fall through
+  // to the override / learned paths. Without this, a fresh gateway machine
+  // reported every run as 'unknown' until enough sessions accumulated to
+  // learn a mapping that the string had spelled out all along.
+  if (/claude/i.test(pid)) return pid;
+
   const entry = map.learned?.[pid];
   if (entry?.role) {
     const alias = aliasForRole(entry.role, env);

package/src/route-scan.js

@@ -451,6 +451,10 @@ export async function runRouteScan({ days = 14 } = {}) {
     d.savedUsd += saved;
     delegatedStats.set(key, d);
   };
+  // Ledger events feed the statusline's weekly/monthly "Routing saved"
+  // totals. Keyed by run transcript path so overlapping re-scans upsert the
+  // same event instead of double-counting it.
+  const ledgerEvents = [];
   for (const [sessionPath, index] of runIndexBySession) {
     const used = new Set();
     for (const { ep, projectDir, sessionPath: epSession } of all) {
@@ -474,9 +478,22 @@ export async function runRouteScan({ days = 14 } = {}) {
         const saved = runSaving(run, mainModel);
         bumpDelegated(`${runTier}|${cat.id}|${projectDir}`, run, saved);
         bumpDelegated(`${runTier}|${cat.id}|*`, run, saved);
+        if (saved > 0) {
+          ledgerEvents.push({
+            key: run.path,
+            ts: run.endedAt ?? run.startedAt ?? Date.now(),
+            usd: saved,
+          });
+        }
       }
     }
   }
+  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();

package/src/savings-ledger.js

@@ -0,0 +1,86 @@
+/**
+ * savings-ledger — per-run delegation saving events with timestamps.
+ *
+ * model-rules.json stores `savedUsd` as a scan-window snapshot per rule, which
+ * is right for rule-health but cannot answer "how much did routing save this
+ * week / this month / ever". This ledger keeps one event per subagent run,
+ * keyed by the run's transcript path so re-scans over overlapping windows
+ * upsert instead of double-counting.
+ *
+ * File: <userDataDir>/delegation-ledger.json
+ *   { "events": { "<run path>": { "ts": <ms epoch>, "usd": <number> } } }
+ *
+ * Best-effort like every other state file here: an unreadable ledger reads as
+ * empty, and the statusline renders totals of 0 as "no chip".
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+
+const WEEK_MS = 7 * 24 * 3600 * 1000;
+const MONTH_MS = 30 * 24 * 3600 * 1000;
+
+export function ledgerPath() {
+  return join(userDataDir(), 'delegation-ledger.json');
+}
+
+export function loadLedger() {
+  try {
+    const data = JSON.parse(readFileSync(ledgerPath(), 'utf8'));
+    return data && typeof data.events === 'object' && data.events !== null
+      ? data
+      : { events: {} };
+  } catch {
+    return { events: {} };
+  }
+}
+
+/**
+ * Upsert saving events. `events` is an array of { key, ts, usd } where `key`
+ * is the run's transcript path (unique per subagent run). Zero-saving runs
+ * are skipped — they carry no information the totals care about.
+ */
+export function recordDelegationEvents(events) {
+  if (!Array.isArray(events) || events.length === 0) return;
+  const data = loadLedger();
+  let changed = false;
+  for (const e of events) {
+    if (!e || !e.key || !(Number(e.usd) > 0) || !Number.isFinite(e.ts)) continue;
+    const prev = data.events[e.key];
+    const usd = Math.round(Number(e.usd) * 10000) / 10000;
+    if (prev && prev.ts === e.ts && prev.usd === usd) continue;
+    data.events[e.key] = { ts: e.ts, usd };
+    changed = true;
+  }
+  if (!changed) return;
+  try {
+    const dir = userDataDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(ledgerPath(), JSON.stringify(data) + '\n');
+  } catch {
+    // statusline totals just stay stale until the next successful scan
+  }
+}
+
+/**
+ * Rolling totals: last 7 days, last 30 days, and lifetime. `now` is injectable
+ * for tests. Never throws — an unreadable ledger yields all-zero totals.
+ */
+export function delegationSavedTotals(now = Date.now()) {
+  const totals = { week: 0, month: 0, total: 0 };
+  try {
+    for (const e of Object.values(loadLedger().events)) {
+      const usd = Number(e.usd) || 0;
+      if (usd <= 0) continue;
+      totals.total += usd;
+      if (Number.isFinite(e.ts)) {
+        if (now - e.ts <= WEEK_MS) totals.week += usd;
+        if (now - e.ts <= MONTH_MS) totals.month += usd;
+      }
+    }
+  } catch {
+    return { week: 0, month: 0, total: 0 };
+  }
+  return totals;
+}