claude-token-saver 3.30.1 → 3.31.0

package/README.en.md

@@ -2,6 +2,8 @@
 
 [![npm](https://img.shields.io/npm/v/claude-token-saver.svg)](https://www.npmjs.com/package/claude-token-saver)
 
+🌐 **[Project page](https://rootstudioyaml.github.io/claude-token-saver/)**
+
 # claude-token-saver
 
 **Shows what it saved, on two lines.** It moves the easy work your expensive model keeps repeating onto cheaper ones, and turns documents the model cannot read into Markdown. Both figures are ledger entries rather than estimates, and whichever saved more takes the top line. Zero dependencies, one-line install.
@@ -214,6 +216,7 @@ Bootstrap five engineering principles (Ratchet · Evidence · PEV · Structured
 claude-token-saver harness init                # this project
 claude-token-saver harness init --global       # ~/.claude/CLAUDE.md — every project
 claude-token-saver harness check               # current score (global fallback honored)
+claude-token-saver harness analyze             # run the transcript analysis manually (no hook needed); refreshes harness-state.json
 claude-token-saver harness promote <N> --project|--global   # warning #N → ratchet rule (scope required)
 claude-token-saver harness promote "<rule text>" --project|--global  # register your own hand-written rules the same way
 claude-token-saver harness pull                # register the package's curated ratchet rules into your global ratchet (opt-in, dedupes)

package/README.md

@@ -2,6 +2,8 @@
 
 [![npm](https://img.shields.io/npm/v/claude-token-saver.svg)](https://www.npmjs.com/package/claude-token-saver)
 
+🌐 **[프로젝트 소개 페이지](https://rootstudioyaml.github.io/claude-token-saver/)**
+
 # claude-token-saver
 
 **아낀 돈을 두 줄로 보여 줍니다.** 비싼 모델이 반복하던 쉬운 작업을 싼 모델로 내려보내고, 모델이 읽지 못하는 문서를 Markdown 으로 바꿉니다. 두 절감액 모두 추정이 아니라 원장 기록이고, 더 많이 아낀 쪽이 첫 줄을 차지합니다. 의존성 0, 설치 한 줄.
@@ -194,6 +196,7 @@ statusline은 대화 상자를 띄울 수 없고, 300밀리초마다 다시 그
 claude-token-saver harness init                # 이 프로젝트에 셋업
 claude-token-saver harness init --global       # ~/.claude/CLAUDE.md, 모든 프로젝트에 적용
 claude-token-saver harness check               # 현재 점수 (글로벌 fallback 인정)
+claude-token-saver harness analyze             # 훅 없이도 수동으로 전사 분석을 실행해 harness-state.json 갱신
 claude-token-saver harness promote <N> --project|--global   # 경고 #N → ratchet 룰 (스코프 필수)
 claude-token-saver harness promote "<룰 텍스트>" --project|--global  # 내가 직접 정의한 룰도 같은 명령으로 등록
 claude-token-saver harness pull                # 패키지 동봉 큐레이션 룰 → 내 글로벌 랫쳇에 등록 (opt-in, 중복 스킵)

package/bin/cli.js

@@ -89,7 +89,40 @@ const KNOWN_SUBCOMMANDS = new Set([
   'doc2md', 'harness', 'route-scan', 'compact-window', 'update-check', 'upgrade',
 ]);
 
+const USAGE = `claude-token-saver — Claude Code token usage, cache health, and model routing
+
+Usage:
+  claude-token-saver                    default report (last 30 days)
+  claude-token-saver --days 7           last 7 days
+  claude-token-saver --format json      JSON output
+  claude-token-saver --format csv       CSV output
+  claude-token-saver --project myproj   filter by project
+  claude-token-saver route-scan         detect recurring easy work → delegation candidates
+  claude-token-saver install            set up skill/hooks/statusline
+  claude-token-saver install --yes      take the defaults without asking
+  claude-token-saver uninstall          remove everything install added
+  claude-token-saver harness check      score the harness setup in CLAUDE.md
+  claude-token-saver harness analyze    run the harness transcript analysis manually
+  claude-token-saver last               most recent warning + how to handle it
+  claude-token-saver history            recent warning transitions
+  claude-token-saver handoff            write a session handoff file
+  claude-token-saver upgrade            install the latest release
+  claude-token-saver --install-hook     install cache-monitor PostToolUse hook
+  claude-token-saver --uninstall-hook   remove that hook
+  claude-token-saver --statusline       one-line output for Claude Code statusline
+      --verbose / --no-color / --icon / --no-timer / --single-line
+
+Run any subcommand with --help for its own options where available.
+`;
+
 async function main() {
+  // Help must never fall through to the default report — that runs a full
+  // 30-day scan, which is the opposite of what someone asking for help wants.
+  if (hasFlag('--help') || hasFlag('-h') || args[0] === 'help') {
+    process.stdout.write(USAGE);
+    return;
+  }
+
   // A hook invocation names a subcommand and expects either silence or that
   // subcommand's own protocol on stdout. If this build does not have the
   // subcommand — an older global install against a newer settings.json, which

package/package.json

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

@@ -227,7 +227,7 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
     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}" (statusline의 rule-health 칩). 조건 좁히기/제거를 사용자와 상의하세요: claude-token-saver route-scan rules`);
+        : `승인된 위임 룰의 최근 에러율이 기준(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 */ }

package/src/cost.js

@@ -125,7 +125,12 @@ const TIER_RANK = {
  * from the ranking instead of guessed at.
  */
 export function isUnknownModel(model) {
-  return !model || String(model).toLowerCase() === 'unknown';
+  if (!model) return true;
+  const m = String(model).toLowerCase();
+  // "<synthetic>" is Claude Code's placeholder for locally-generated error
+  // stubs — no real API call happened, so pricing it as Sonnet would be a
+  // silent guess (session-records.js skips it for the same reason).
+  return m === 'unknown' || m === '<synthetic>';
 }
 
 /**

package/src/formatters/statusline.js

@@ -51,7 +51,11 @@ const GRAY = fg(100, 116, 139, '\x1b[90m');
 const BOLD = '\x1b[1m';
 
 function formatMoney(usd) {
-  if (usd >= 1000) return `$${(usd / 1000).toFixed(1)}K`;
+  // Boundaries sit at 999.5/999500 so a value that would round up into the
+  // next band's width ($999.9 → "$1000") jumps to that band's unit instead —
+  // otherwise "$1000" renders visually larger than "$1.0K".
+  if (usd >= 999500) return `$${(usd / 1e6).toFixed(1)}M`;
+  if (usd >= 999.5) return `$${(usd / 1000).toFixed(1)}K`;
   if (usd >= 100) return `$${usd.toFixed(0)}`;
   if (usd >= 10) return `$${usd.toFixed(1)}`;
   return `$${usd.toFixed(2)}`;

package/src/harness-analyzer.cjs

@@ -39,15 +39,20 @@ const PEV_TOOLUSE_THRESHOLD = 5;
 // researching, which is exactly the behavior we don't want to punish.
 const MUTATING_TOOL_RE = /^(edit|write|multiedit|notebookedit|bash)$/i;
 
+// Mirrors src/paths.js userDataDir() exactly (same order as doc2md.cjs).
+// Duplicated because this file is CommonJS and paths.js is ESM; the
+// precedence must match or state lands where the rest of the tool won't look.
 function stateDir() {
-  if (process.platform === 'win32') {
-    return path.join(process.env.APPDATA || os.homedir(), 'claude-token-saver');
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(process.env.XDG_CONFIG_HOME, 'claude-token-saver');
+  }
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    return path.join(process.env.APPDATA, 'claude-token-saver');
   }
   if (process.platform === 'darwin') {
     return path.join(os.homedir(), 'Library', 'Application Support', 'claude-token-saver');
   }
-  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  return path.join(xdg, 'claude-token-saver');
+  return path.join(os.homedir(), '.config', 'claude-token-saver');
 }
 
 function readJsonl(file) {

package/src/hook-manager.js

@@ -1,21 +1,31 @@
 /**
- * Install/uninstall the SessionEnd hook in ~/.claude/settings.json
+ * Install/uninstall the cache-monitor PostToolUse hook in ~/.claude/settings.json
+ *
+ * Registered as a CLI subcommand (`claude-token-saver --hook-run`) like every
+ * other hook in this package — NOT as a copied file. The old copy-to-home
+ * approach pinned a stale hook.cjs in ~/.claude/ forever, never shipped
+ * harness-analyzer.cjs alongside it, and survived `uninstall` because its
+ * command line did not contain the CLI name. Registering the CLI itself
+ * removes the copy, the staleness, and the orphan in one move.
  */
 
-import { readFile, writeFile, copyFile } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { readFile, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { fileURLToPath } from 'node:url';
 
 const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
-const HOOK_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), 'hook.cjs');
-const HOOK_DEST = join(homedir(), '.claude', 'cache-monitor-hook.cjs');
+// Legacy copied-file location — removed on install/uninstall so machines that
+// installed an older version don't keep a dead hook script around.
+const LEGACY_HOOK_DEST = join(homedir(), '.claude', 'cache-monitor-hook.cjs');
 const HOOK_MARKER = 'cache-monitor-hook';
 
-export async function installHook({ threshold = 0.7 } = {}) {
-  // Copy hook script to ~/.claude/ for stable path
-  await copyFile(HOOK_SCRIPT, HOOK_DEST);
+function isCacheMonitorHook(nh) {
+  const cmd = nh?.command;
+  if (typeof cmd !== 'string') return false;
+  return cmd.includes(HOOK_MARKER) || cmd.includes('--hook-run');
+}
 
+export async function installHook({ threshold = 0.7 } = {}) {
   let settings;
   try {
     const raw = await readFile(SETTINGS_PATH, 'utf8');
@@ -27,24 +37,18 @@ export async function installHook({ threshold = 0.7 } = {}) {
   if (!settings.hooks) settings.hooks = {};
   if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
 
-  // Remove existing cache-monitor hook if present
+  // Remove existing cache-monitor hook if present — matches both the current
+  // subcommand form and the legacy copied-file form.
   settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
-    (h) => {
-      // Check nested hooks structure
-      const nested = h.hooks || [];
-      return !nested.some((nh) => nh.command?.includes(HOOK_MARKER));
-    },
+    (h) => !(h.hooks || []).some(isCacheMonitorHook),
   );
 
-  // Add new hook (correct 3-level nested structure)
-  // Normalize path separators for Windows compatibility in shell commands
-  const hookPath = HOOK_DEST.replace(/\\/g, '/');
   settings.hooks.PostToolUse.push({
     matcher: 'Bash|Edit|Write',
     hooks: [
       {
         type: 'command',
-        command: `node "${hookPath}" --threshold ${threshold}`,
+        command: `claude-token-saver --hook-run --threshold ${threshold}`,
         timeout: 10,
       },
     ],
@@ -52,7 +56,10 @@ export async function installHook({ threshold = 0.7 } = {}) {
 
   await writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf8');
 
-  console.log(`✓ Hook installed at ${HOOK_DEST}`);
+  // Clean up the legacy copy left by older versions.
+  await rm(LEGACY_HOOK_DEST, { force: true }).catch(() => {});
+
+  console.log('✓ Hook installed (PostToolUse → claude-token-saver --hook-run)');
   console.log(`  Settings updated: ${SETTINGS_PATH}`);
   console.log(`  Threshold: ${(threshold * 100).toFixed(0)}%`);
   console.log(`  Stats file: ~/.claude/cache-stats.jsonl`);
@@ -71,10 +78,7 @@ export async function uninstallHook() {
   if (settings.hooks?.PostToolUse) {
     const before = settings.hooks.PostToolUse.length;
     settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
-      (h) => {
-        const nested = h.hooks || [];
-        return !nested.some((nh) => nh.command?.includes(HOOK_MARKER));
-      },
+      (h) => !(h.hooks || []).some(isCacheMonitorHook),
     );
     const removed = before - settings.hooks.PostToolUse.length;
 
@@ -86,4 +90,7 @@ export async function uninstallHook() {
   } else {
     console.log('No cache-monitor hook found in settings.');
   }
+
+  // The legacy copied hook file is dead weight either way.
+  await rm(LEGACY_HOOK_DEST, { force: true }).catch(() => {});
 }

package/src/hook.cjs

@@ -12,6 +12,15 @@
 
 'use strict';
 
+// CJS twin of src/debug.js \u2014 hook failures must stay silent for the session
+// but be visible under CTS_DEBUG=1, otherwise a broken path is
+// indistinguishable from "nothing to do".
+var CTS_DEBUG = !!process.env.CTS_DEBUG;
+function dbg(scope, err) {
+  if (!CTS_DEBUG) return;
+  process.stderr.write('[cts:' + scope + '] ' + ((err && err.stack) || String(err)) + '\n');
+}
+
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
@@ -30,14 +39,15 @@ if (thIdx !== -1 && process.argv[thIdx + 1]) {
 let stdin = '';
 try {
   stdin = fs.readFileSync(0, 'utf8');
-} catch {
-  // no stdin
+} catch (e) {
+  dbg('hook:stdin', e);
 }
 
 let context;
 try {
   context = JSON.parse(stdin);
-} catch {
+} catch (e) {
+  dbg('hook:parse-stdin', e);
   process.exit(0);
 }
 
@@ -52,8 +62,8 @@ function resolveSessionFile() {
     try {
       fs.statSync(context.transcript_path);
       return context.transcript_path;
-    } catch {
-      // path provided but file not found, try fallback
+    } catch (e) {
+      dbg('hook:transcript-path', e);
     }
   }
 
@@ -69,8 +79,8 @@ function resolveSessionFile() {
         // not here
       }
     }
-  } catch {
-    // no projects dir
+  } catch (e) {
+    dbg('hook:projects-dir', e);
   }
 
   return null;
@@ -83,7 +93,8 @@ if (!sessionFile) process.exit(0);
 let content;
 try {
   content = fs.readFileSync(sessionFile, 'utf8');
-} catch {
+} catch (e) {
+  dbg('hook:read-session', e);
   process.exit(0);
 }
 
@@ -155,8 +166,8 @@ const record = {
 // Append to stats file
 try {
   fs.appendFileSync(STATS_FILE, JSON.stringify(record) + '\n', 'utf8');
-} catch {
-  // can't write, ignore
+} catch (e) {
+  dbg('hook:append-stats', e);
 }
 
 // Alert if hit rate below threshold
@@ -179,6 +190,7 @@ try {
     cwd: cwd,
   });
   if (state) harnessAnalyzer.writeState(state);
-} catch (_) {
+} catch (e) {
+  dbg('hook:harness-analyzer', e);
   // analyzer is purely advisory \u2014 never break the hook on failure
 }

package/src/installer.js

@@ -88,6 +88,11 @@ honor that for the rest of the turn without changing the saved setting.
    | \`⚠ Output heavy\`  | Output ratio dominates input — inspect long generations. |
    | \`⚠ Call surge\`    | Request count is well above baseline.                 |
 
+   Note: the \`🚨 5H/7D\` cap chips come from Claude Code's own
+   \`rate_limits\` payload, which gateway backends (Bedrock, Vertex,
+   LiteLLM) do not provide — on those setups the chips never appear, and
+   that is expected, not a failure of this tool.
+
 6. **Suggest the next action.** For \`🚨 5H/7D\` chips, recommend running
    \`claude-token-saver handoff\` to back up the current work to a
    \`HANDOFF-*.md\` file before the cap hits, then continue in a fresh
@@ -150,8 +155,8 @@ export function removeLegacyCommand() {
 }
 
 // Registers/repairs the Claude Code statusLine entry in ~/.claude/settings.json.
-// - No statusLine yet: insert ours with refreshInterval:1.
-// - statusLine already points at claude-token-saver: ensure refreshInterval:1
+// - No statusLine yet: insert ours with refreshInterval:STATUSLINE_REFRESH_INTERVAL.
+// - statusLine already points at claude-token-saver: ensure that refreshInterval
 //   (this is the bit that makes the TTL countdown tick every second while idle).
 // - statusLine points at a different command: leave it alone unless --force.
 export function installStatusline({ force = false } = {}) {
@@ -187,7 +192,7 @@ export function installStatusline({ force = false } = {}) {
     }
     cur.refreshInterval = STATUSLINE_REFRESH_INTERVAL;
     writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-    return { path: file, action: 'updated', reason: 'set refreshInterval=1' };
+    return { path: file, action: 'updated', reason: `set refreshInterval=${STATUSLINE_REFRESH_INTERVAL}` };
   }
 
   if (!force) {
@@ -512,7 +517,8 @@ export function uninstallAll({ purge = false } = {}) {
       if (!Array.isArray(list)) continue;
       const kept = list.filter((m) => !(
         Array.isArray(m?.hooks)
-        && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('claude-token-saver'))
+        && m.hooks.some((h) => typeof h?.command === 'string'
+          && (h.command.includes('claude-token-saver') || h.command.includes('cache-monitor-hook')))
       ));
       if (kept.length === list.length) continue;
       result.removed.push(`hooks.${event}`);
@@ -548,12 +554,51 @@ export function uninstallAll({ purge = false } = {}) {
   return { ...result, action: 'removed' };
 }
 
+// Older versions registered the cache-monitor hook as a file copied to
+// ~/.claude/cache-monitor-hook.cjs. That copy never included
+// harness-analyzer.cjs, went stale across upgrades, and escaped uninstall.
+// Rewrite any such entry to the CLI subcommand form and delete the copy.
+// Runs on every install (postinstall included) so upgrades self-heal.
+export function migrateLegacyCacheMonitorHook() {
+  const dir = claudeUserDir();
+  const file = join(dir, 'settings.json');
+  if (!existsSync(file)) return { path: file, action: 'none' };
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    return { path: file, action: 'skipped', reason: `unreadable JSON (${e.message})` };
+  }
+  const list = settings.hooks?.PostToolUse;
+  if (!Array.isArray(list)) return { path: file, action: 'none' };
+
+  let migrated = false;
+  for (const m of list) {
+    if (!Array.isArray(m?.hooks)) continue;
+    for (const h of m.hooks) {
+      if (typeof h?.command !== 'string' || !h.command.includes('cache-monitor-hook')) continue;
+      const th = h.command.match(/--threshold\s+([\d.]+)/);
+      h.command = `claude-token-saver --hook-run --threshold ${th ? th[1] : '0.7'}`;
+      migrated = true;
+    }
+  }
+  if (migrated) writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+
+  const legacyCopy = join(dir, 'cache-monitor-hook.cjs');
+  if (existsSync(legacyCopy)) {
+    rmSync(legacyCopy, { force: true });
+    migrated = true;
+  }
+  return { path: file, action: migrated ? 'migrated' : 'none' };
+}
+
 export function installAll({ force = false } = {}) {
   return {
     skill: installSkill({ force }),
     statusline: installStatusline({ force }),
     sessionStartHook: installSessionStartHook(),
     briefHook: installBriefHook(),
+    cacheMonitorMigration: migrateLegacyCacheMonitorHook(),
     legacy: removeLegacyCommand(),
   };
 }

package/src/model-rules.js

@@ -48,6 +48,23 @@ export const HEALTH_MIN_SAMPLE = 10;
 // that merely resemble the rule's shape.
 export const HEALTH_MIN_SAMPLE_DELEGATED = 5;
 
+/**
+ * Wilson 95% lower bound for an observed error proportion. A raw rate over a
+ * tiny sample flips healthy rules to review (2/8 = 25% has a 95% interval of
+ * [7%, 59%] — it does NOT establish the rate exceeds 20%). Only flag when the
+ * evidence actually clears the threshold.
+ */
+export function wilsonLowerBound(errs, n) {
+  if (!n) return 0;
+  const z = 1.96;
+  const p = errs / n;
+  const z2 = z * z;
+  const denom = 1 + z2 / n;
+  const center = p + z2 / (2 * n);
+  const margin = z * Math.sqrt((p * (1 - p) + z2 / (4 * n)) / n);
+  return Math.max(0, (center - margin) / denom);
+}
+
 // Fallback budget for rules promoted before budgets were recorded — matches
 // route-scan's pre-calibration defaults. Kept as local constants rather than
 // imported: route-scan imports this module, and a static back-import would
@@ -402,10 +419,12 @@ export function refreshModelRules(episodeStats, delegatedStats = new Map(), { no
     // catch a rule that is mis-firing on requests it should never have taken.
     if (r.delegatedRuns >= HEALTH_MIN_SAMPLE_DELEGATED) {
       r.healthSource = 'delegated';
-      r.status = r.delegatedErrRate > HEALTH_ERR_RATE ? 'review' : 'active';
+      r.status = wilsonLowerBound(d ? d.errRuns : 0, r.delegatedRuns) > HEALTH_ERR_RATE
+        ? 'review' : 'active';
     } else {
       r.healthSource = 'proxy';
-      r.status = s && r.errRate > HEALTH_ERR_RATE && s.epCount >= HEALTH_MIN_SAMPLE
+      r.status = s && s.epCount >= HEALTH_MIN_SAMPLE
+        && wilsonLowerBound(s.errCount || Math.round((r.errRate || 0) * s.epCount), s.epCount) > HEALTH_ERR_RATE
         ? 'review' : 'active';
     }
     changed = true;

package/src/parser.js

@@ -72,6 +72,10 @@ export async function parseSessionFile(filePath) {
 
     requests.set(reqId, {
       requestId: reqId,
+      // Per-request timestamp so callers can filter by time window — the
+      // mtime-based file filter alone lets a long-lived session drag
+      // months-old requests into a narrow --days window.
+      ts: ts ? Date.parse(ts) : null,
       model: resolveModelAlias(msg.model),
       inputTokens: usage.input_tokens || 0,
       cacheCreationTokens: usage.cache_creation_input_tokens || 0,
@@ -84,6 +88,22 @@ export async function parseSessionFile(filePath) {
 
   const reqs = [...requests.values()];
   let maxContextPerRequest = 0;
+  // Representative model: the one that handled the most requests, skipping
+  // "<synthetic>" (Claude Code's local error-stub placeholder — no real API
+  // call). Taking reqs[0] blindly let an error stub at session start
+  // misclassify the whole session (route-scan.js already counts for the same
+  // reason). Falls back to '<synthetic>' only when nothing else exists.
+  const modelCounts = new Map();
+  for (const r of reqs) {
+    if (r.model === '<synthetic>') continue;
+    modelCounts.set(r.model, (modelCounts.get(r.model) || 0) + 1);
+  }
+  let model = 'unknown';
+  let best = 0;
+  for (const [m, n] of modelCounts) {
+    if (n > best) { best = n; model = m; }
+  }
+  if (best === 0 && reqs.length > 0) model = reqs[0].model || 'unknown';
   const totals = reqs.reduce(
     (acc, r) => {
       acc.input += r.inputTokens;
@@ -108,7 +128,7 @@ export async function parseSessionFile(filePath) {
     requests: reqs,
     totals,
     maxContextPerRequest,
-    model: reqs[0]?.model || 'unknown',
+    model,
     gatewayObserved,
   };
 }
@@ -209,6 +229,52 @@ export async function discoverSessionFiles(options = {}) {
  * @param {object} [options] forwarded to discoverSessionFiles
  * @param {boolean} [options.noCache=false] bypass the cache entirely
  */
+function spansCutoff(session, cutoffMs) {
+  return !!(session.startTime && session.startTime.getTime() < cutoffMs);
+}
+
+/**
+ * Re-aggregate a fully parsed session keeping only requests at or after the
+ * cutoff. Requests without a timestamp are kept — dropping data on a missing
+ * field would be worse than slight over-counting.
+ */
+function trimToCutoff(session, cutoffMs) {
+  const reqs = (session.requests || []).filter((r) => r.ts == null || r.ts >= cutoffMs);
+  let maxContextPerRequest = 0;
+  let firstTs = null;
+  let lastTs = null;
+  const totals = reqs.reduce(
+    (acc, r) => {
+      acc.input += r.inputTokens;
+      acc.cacheCreation += r.cacheCreationTokens;
+      acc.cacheRead += r.cacheReadTokens;
+      acc.ephemeral5m += r.ephemeral5mTokens;
+      acc.ephemeral1h += r.ephemeral1hTokens;
+      acc.output += r.outputTokens;
+      const ctx = r.inputTokens + r.cacheCreationTokens + r.cacheReadTokens;
+      if (ctx > maxContextPerRequest) maxContextPerRequest = ctx;
+      if (r.ts != null) {
+        if (firstTs === null || r.ts < firstTs) firstTs = r.ts;
+        if (lastTs === null || r.ts > lastTs) lastTs = r.ts;
+      }
+      return acc;
+    },
+    { input: 0, cacheCreation: 0, cacheRead: 0, ephemeral5m: 0, ephemeral1h: 0, output: 0 },
+  );
+  return {
+    sessionId: session.sessionId,
+    filePath: session.filePath,
+    projectDir: session.projectDir,
+    startTime: firstTs !== null ? new Date(firstTs) : session.startTime,
+    endTime: lastTs !== null ? new Date(lastTs) : session.endTime,
+    requestCount: reqs.length,
+    totals,
+    maxContextPerRequest,
+    model: session.model,
+    gatewayObserved: session.gatewayObserved,
+  };
+}
+
 export async function parseAllSessions(options = {}) {
   const files = await discoverSessionFiles(options);
   const concurrency = 10;
@@ -216,23 +282,39 @@ export async function parseAllSessions(options = {}) {
   const useCache = !options.noCache;
   const cache = useCache ? loadCache() : { entries: {} };
   let misses = 0;
+  // The file-level mtime filter (discoverSessionFiles) is only a cheap
+  // pre-selection: a session started months ago but touched today passes it,
+  // and its old requests would pollute every aggregate in the window. Any
+  // session whose startTime precedes the cutoff is re-aggregated from its
+  // per-request timestamps. The trimmed summary is NOT cached — the cache
+  // stores the window-independent full parse.
+  const days = options.days ?? 30;
+  const cutoffMs = Date.now() - days * 24 * 60 * 60 * 1000;
 
   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 {
+          if (useCache) {
+            const hit = getCached(cache, f);
+            if (hit) {
+              if (!spansCutoff(hit, cutoffMs)) return hit;
+              // Boundary session from cache: the cached summary has no
+              // per-request data, so re-read the file to trim it.
+              const full = await parseSessionFile(f.path);
+              full.projectDir = f.projectDir;
+              return trimToCutoff(full, cutoffMs);
+            }
+          }
           const session = await parseSessionFile(f.path);
           session.projectDir = f.projectDir;
-          const { requests, ...summary } = session;
           if (useCache) {
             putCached(cache, f, session);
             misses++;
           }
+          if (spansCutoff(session, cutoffMs)) return trimToCutoff(session, cutoffMs);
+          const { requests, ...summary } = session;
           return summary;
         } catch {
           return null;

package/src/session-cache.js

@@ -29,7 +29,9 @@ const CACHE_PATH = join(userDataDir(), 'session-cache.json');
 // 2: sessions carry `gatewayObserved`. Entries written by version 1 lack it,
 // and a missing flag reads as "not a gateway" — the wrong default for exactly
 // the users the flag exists for.
-const CACHE_VERSION = 2;
+// 3: version 2's serialize() never actually wrote `gatewayObserved`, so every
+// v2 entry lacks the flag it was bumped for. Bumped again to discard them.
+const CACHE_VERSION = 3;
 // Entries for transcripts this old are pruned on write. Keeps the file
 // bounded without an existence check per entry (which would cost the syscalls
 // the cache exists to avoid).
@@ -58,6 +60,7 @@ function serialize(session) {
     totals: session.totals,
     maxContextPerRequest: session.maxContextPerRequest,
     model: session.model,
+    gatewayObserved: !!session.gatewayObserved,
   };
 }
 
@@ -72,6 +75,7 @@ function deserialize(stored, filePath, projectDir) {
     totals: stored.totals,
     maxContextPerRequest: stored.maxContextPerRequest || 0,
     model: stored.model || 'unknown',
+    gatewayObserved: !!stored.gatewayObserved,
   };
 }
 

package/src/session-records.js

@@ -53,7 +53,18 @@ const REJECTION_RE = /doesn't want to proceed|tool use was rejected|doesn't want
 // yet" was 7/65 real errors in one project, edit-races + Task-lifecycle several
 // more). Kept NARROW on purpose: ambiguous shell failures ("Exit code N", "File
 // does not exist" on a Read) stay counted — those are genuine difficulty signal.
-const SELF_CORRECTED_RE = /File has not been read yet|has been modified since read|String to replace not found|is not running \(status:|<tool_use_error>Blocked:/i;
+// Tool-argument schema violations (InputValidationError, "does not match the
+// required schema/pattern") are the model mis-building a call, corrected on
+// the next attempt — same self-correction family, not task difficulty.
+// Measured 2026-09-09: they were the single largest numerator item (10/125).
+const SELF_CORRECTED_RE = /File has not been read yet|has been modified since read|String to replace not found|is not running \(status:|<tool_use_error>Blocked:|InputValidationError|does not match the required/i;
+
+// Failures with no diagnosable content — a bare exit code or "no output" —
+// carry no evidence about WHY they failed, so they cannot support a
+// rule-health verdict either way. Excluded from the numerator (16% of it was
+// this plus schema errors, against a 20% review threshold). Anchored: an
+// "Exit code 1" followed by a traceback still counts.
+const NO_SIGNAL_RE = /^\s*(Command failed with no output|Exit code \d+)\s*$/;
 
 // Environment constraints — a sandbox without `curl`/`wc`, a corporate proxy
 // timing a fetch out — are not task difficulty either. The agent routinely
@@ -72,7 +83,8 @@ function toolResultText(content) {
 function isRealToolError(block) {
   if (!block || block.type !== 'tool_result' || !block.is_error) return false;
   const txt = toolResultText(block.content);
-  return !REJECTION_RE.test(txt) && !SELF_CORRECTED_RE.test(txt) && !ENVIRONMENT_RE.test(txt);
+  return !REJECTION_RE.test(txt) && !SELF_CORRECTED_RE.test(txt)
+    && !ENVIRONMENT_RE.test(txt) && !NO_SIGNAL_RE.test(txt);
 }
 
 export async function collectSessionRecords(filePath, { includeContent = true } = {}) {

package/src/stdin-payload.js

@@ -35,13 +35,29 @@ export function readStdinJson() {
   }
 }
 
+/**
+ * A percentage from the payload, or null when the field is absent, empty, or
+ * non-numeric. `Number(null|''|[])` is 0, so a plain Number() call renders
+ * missing data as "0% used" — the most dangerously wrong reading possible for
+ * a cap gauge. Out-of-range values are clamped to 0..100 at this entry point
+ * so every renderer (and caps-cache.js, which persists the value) agrees.
+ */
+function normalizePct(raw) {
+  if (typeof raw !== 'number') {
+    if (typeof raw !== 'string' || raw.trim() === '') return null;
+    raw = Number(raw);
+  }
+  if (!Number.isFinite(raw)) return null;
+  return Math.max(0, Math.min(100, raw));
+}
+
 export function extractCaps(stdinJson) {
   if (!stdinJson || !stdinJson.rate_limits || typeof stdinJson.rate_limits !== 'object') return null;
   const windows = [];
   for (const [key, value] of Object.entries(stdinJson.rate_limits)) {
     if (!value || typeof value !== 'object') continue;
-    const usedPct = Number(value.used_percentage);
-    if (!Number.isFinite(usedPct)) continue;
+    const usedPct = normalizePct(value.used_percentage);
+    if (usedPct === null) continue;
     const resetsAt = Number(value.resets_at);
     windows.push({
       key,
@@ -82,9 +98,9 @@ export function bedrockDisplayFromId(id) {
 export function extractContextUsage(stdinJson) {
   const cw = stdinJson && stdinJson.context_window;
   if (!cw || typeof cw !== 'object') return null;
-  const usedPct = Number(cw.used_percentage);
+  const usedPct = normalizePct(cw.used_percentage);
   const size = Number(cw.context_window_size);
-  if (!Number.isFinite(usedPct)) return null;
+  if (usedPct === null) return null;
   return {
     usedPct,
     size: Number.isFinite(size) && size > 0 ? size : null,