sprag-cli 3.40.0

package/src/history.js

@@ -0,0 +1,383 @@
+/**
+ * Warning history — appends an entry whenever the active chip transitions
+ * (none → warning, warning A → warning B, warning → none). One markdown file
+ * per calendar day so users can pinpoint "when did this start" easily.
+ *
+ * Each event is written bilingually: the canonical English line first, the
+ * Korean translation as an indented "└" continuation right below. The chip
+ * text itself stays as-is (its symbol+English is part of the UX surface), but
+ * the diagnostic detail and resolved-status verbs are translated.
+ *
+ * Storage path is platform-aware (see paths.userDataDir):
+ *   Windows: %APPDATA%\claude-token-saver\history\YYYY-MM-DD.md
+ *   macOS:   ~/Library/Application Support/claude-token-saver/history/YYYY-MM-DD.md
+ *   Linux:   ~/.config/claude-token-saver/history/YYYY-MM-DD.md
+ *
+ * State (last-seen chip, prevents duplicate appends every 1s refresh):
+ *   <userDataDir>/last-chip.json
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+import { formatResetIn, formatResetClock } from './format-time.js';
+import { labelForKey } from './window-labels.js';
+import { ISSUE_TIPS, CHIP_TO_CODES, CAP_TIPS } from './advice.js';
+
+const BASE_DIR = userDataDir();
+const HISTORY_DIR = join(BASE_DIR, 'history');
+const STATE_PATH = join(BASE_DIR, 'last-chip.json');
+
+export function historyDir() {
+  return HISTORY_DIR;
+}
+
+function ensureDir(p) {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+}
+
+function pad(n) {
+  return String(n).padStart(2, '0');
+}
+
+function ymd(d = new Date()) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+function hms(d = new Date()) {
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+function loadState() {
+  try {
+    return JSON.parse(readFileSync(STATE_PATH, 'utf8'));
+  } catch {
+    return { chip: null, ts: null };
+  }
+}
+
+function saveState(state) {
+  ensureDir(BASE_DIR);
+  writeFileSync(STATE_PATH, JSON.stringify(state) + '\n');
+}
+
+/**
+ * Map a chip's English label to its Korean equivalent.
+ * Returns the input unchanged if no mapping is registered (forward-compat
+ * with chips added in advice.js after this map was last updated).
+ */
+function chipKo(chip) {
+  if (!chip) return chip;
+  const map = {
+    '⚠ Ctx 500k+': '⚠ 컨텍스트 500k 초과',
+    '⚠ Ctx 200k+': '⚠ 컨텍스트 200k 초과', // legacy (pre-v3.32)
+    '⚠ 1M ON': '⚠ 1M 컨텍스트 활성', // legacy (pre-v2.18)
+    '⚠ Cache miss': '⚠ 캐시 미스',
+    '⚠ Rebuild churn': '⚠ 캐시 재빌드 빈발',
+    '⚠ Input spike': '⚠ 입력 급증',
+    '⚠ Output heavy': '⚠ 출력 과다',
+    '⚠ Call surge': '⚠ 호출 급증',
+    '⚠ 5m TTL': '⚠ 5분 TTL',
+    '⏳ Cache expires': '⏳ 캐시 만료 임박',
+    '💰 Cache saved': '💰 캐시 절약',
+    '🧠 Cache hit': '🧠 캐시 적중',
+  };
+  return map[chip] || chip;
+}
+
+/**
+ * Translate the diagnostic detail string to Korean. The detail is constructed
+ * in cli.js and follows two stable shapes:
+ *   "Context auto-promoted to 1M (max single-request {N}k tokens)"
+ *   "session {ID}: CODE_A, CODE_B"
+ * Anything else falls through unchanged.
+ */
+function detailKo(detail) {
+  if (!detail) return detail;
+  // The threshold moved from 200k to 500k in v3.32, so both spellings have to
+  // resolve: history files written by older versions still carry the old one.
+  const m0 = detail.match(/^Single-request context exceeded (200|500)k \(max (\d+)k tokens\)$/);
+  if (m0) return `단일 요청 컨텍스트 ${m0[1]}k 초과 (최대 ${m0[2]}k 토큰)`;
+  // legacy detail shape (pre-v2.18)
+  const m1 = detail.match(/^Context auto-promoted to 1M \(max single-request (\d+)k tokens\)$/);
+  if (m1) return `1M 컨텍스트 자동 활성 (단일 요청 최대 ${m1[1]}k 토큰)`;
+  const m2 = detail.match(/^session ([^:]+): (.+)$/);
+  if (m2) {
+    const codeKo = {
+      LOW_HIT_RATE: '캐시 적중률 낮음',
+      FREQUENT_CACHE_REBUILD: '캐시 재빌드 빈발',
+      OUTPUT_HEAVY: '출력 과다',
+      INPUT_SPIKE: '입력 급증',
+      CALL_SURGE: '호출 급증',
+      TTL_5M: '5분 TTL',
+    };
+    const codes = m2[2]
+      .split(',')
+      .map((c) => c.trim())
+      .map((c) => codeKo[c] || c)
+      .join(', ');
+    return `세션 ${m2[1]}: ${codes}`;
+  }
+  return detail;
+}
+
+/**
+ * Resolve the diagnostic codes that apply to a transition. We try, in order:
+ *   1. `detail` of shape "session ID: CODE_A, CODE_B" (chip transitions with
+ *      explicit per-session codes — the richest source).
+ *   2. `chip` text mapped via CHIP_TO_CODES (covers 1M ON and chips that fire
+ *      without a per-session detail).
+ * Returns an array of unique codes, possibly empty.
+ */
+function codesForEvent(chip, detail) {
+  const out = [];
+  if (detail) {
+    const m = detail.match(/^session [^:]+:\s*(.+)$/);
+    if (m) {
+      for (const c of m[1].split(',').map((s) => s.trim()).filter(Boolean)) {
+        if (!out.includes(c)) out.push(c);
+      }
+    }
+  }
+  if (chip && CHIP_TO_CODES[chip]) {
+    for (const c of CHIP_TO_CODES[chip]) if (!out.includes(c)) out.push(c);
+  }
+  return out;
+}
+
+/**
+ * Build the "💡 ..." tip block for a given chip+detail pair. Returns
+ * { en: string, ko: string } where each may be empty if no tips apply
+ * (resolution events, unknown chips, etc.).
+ */
+function tipsForEvent(chip, detail) {
+  const codes = codesForEvent(chip, detail);
+  const enLines = [];
+  const koLines = [];
+  for (const code of codes) {
+    const tip = ISSUE_TIPS[code];
+    if (!tip) continue;
+    enLines.push(`  💡 ${tip.en}`);
+    // KR tip carries the `└` marker so language-filtered renderers can
+    // pair it with its EN counterpart (mirrors the event-line continuation).
+    koLines.push(`  └ 💡 ${tip.ko}`);
+  }
+  return { en: enLines.join('\n'), ko: koLines.join('\n') };
+}
+
+function appendDayLine(en, ko, date = new Date(), tips = null) {
+  ensureDir(HISTORY_DIR);
+  const path = join(HISTORY_DIR, `${ymd(date)}.md`);
+  // Bilingual event line. Tip lines (when present) follow on their own lines so
+  // the file reads as: event-en / └ event-ko / 💡 tip-en / 💡 tip-ko.
+  let block = ko && ko !== en ? `${en}\n  └ ${ko}\n` : `${en}\n`;
+  if (tips && tips.en) block += `${tips.en}\n`;
+  if (tips && tips.ko) block += `${tips.ko}\n`;
+  if (!existsSync(path)) {
+    const header = `# Token Monitor / 토큰 모니터 — ${ymd(date)}\n\n## Events / 이벤트\n`;
+    writeFileSync(path, header + block);
+  } else {
+    const existing = readFileSync(path, 'utf8');
+    const sep = existing.endsWith('\n') ? '' : '\n';
+    writeFileSync(path, existing + sep + block);
+  }
+}
+
+/**
+ * Record a chip transition. Called from the statusline render path.
+ * Returns `true` if a transition was logged, `false` if duplicate (same chip
+ * as last call).
+ */
+export function recordChip(chip, contextHints = {}) {
+  const state = loadState();
+  const now = new Date();
+  const current = chip || null;
+  const last = state.chip || null;
+
+  if (current === last) return false;
+
+  const detail = contextHints.detail || null;
+  const detailEn = detail ? `  — ${detail}` : '';
+  const detailKr = detail ? `  — ${detailKo(detail)}` : '';
+
+  let en, ko;
+  // Tips only on warning entry/transition (not resolution) — based on the
+  // *new* chip so users see how to handle what's currently active.
+  let tips = null;
+  if (current && !last) {
+    en = `- ${hms(now)} ${current}${detailEn}`;
+    ko = `${chipKo(current)}${detailKr}`;
+    tips = tipsForEvent(current, detail);
+  } else if (current && last) {
+    en = `- ${hms(now)} ${last} → ${current}${detailEn}`;
+    ko = `${chipKo(last)} → ${chipKo(current)}${detailKr}`;
+    tips = tipsForEvent(current, detail);
+  } else {
+    // current === null, last was something — warning resolved
+    en = `- ${hms(now)} ✓ resolved (was ${last})`;
+    ko = `✓ 해소됨 (이전: ${chipKo(last)})`;
+  }
+  appendDayLine(en, ko, now, tips);
+  saveState({ chip: current, ts: now.toISOString() });
+  return true;
+}
+
+/**
+ * Read history files for the most recent N days (oldest first).
+ * Returns array of { date, content } — empty content for days with no file.
+ */
+export function readRecent(days = 7) {
+  ensureDir(HISTORY_DIR);
+  const out = [];
+  for (let i = days - 1; i >= 0; i--) {
+    const d = new Date();
+    d.setDate(d.getDate() - i);
+    const date = ymd(d);
+    const path = join(HISTORY_DIR, `${date}.md`);
+    if (existsSync(path)) {
+      out.push({ date, content: readFileSync(path, 'utf8') });
+    }
+  }
+  return out;
+}
+
+/**
+ * Record entering or exiting the cap-warn (>=90%) zone for a rate-limit
+ * window. Each window (keyed by its stdin name — e.g. `five_hour`, `seven_day`)
+ * has its own dedup slot, so the daily file gets two transitions max per
+ * window per warning episode.
+ *
+ * @param {{ key: string, usedPct: number, resetsAt: number|null } | null} window
+ * @returns {boolean} true when a line was appended
+ */
+export function recordCapTransition(window) {
+  if (!window || typeof window.key !== 'string') return false;
+  const state = loadState();
+  const slotKey = `cap_${window.key}`;
+  const wasWarn = !!state[slotKey];
+  const isWarn = Number.isFinite(window.usedPct) && window.usedPct >= 90;
+  if (wasWarn === isWarn) return false;
+
+  const now = new Date();
+  const labels = labelForKey(window.key);
+  const labelEn = labels.short;
+  // Korean labels map only the well-known windows; everything else falls back
+  // to the English short label (still readable for the bilingual line).
+  const KO_OVERRIDES = {
+    five_hour: '5시간 윈도',
+    seven_day: '7일 윈도',
+    seven_day_sonnet: '7일 윈도 (Sonnet)',
+    seven_day_opus: '7일 윈도 (Opus)',
+  };
+  const labelKo = KO_OVERRIDES[window.key] || labels.short;
+  let en;
+  let ko;
+  if (isWarn) {
+    const pct = Math.round(window.usedPct);
+    const reset = formatResetIn(window.resetsAt, now);
+    const clock = formatResetClock(window.resetsAt, now);
+    const tail = reset && clock
+      ? ` (resets in ${reset}, at ${clock})`
+      : reset
+        ? ` (resets in ${reset})`
+        : clock
+          ? ` (resets at ${clock})`
+          : '';
+    const tailKo = reset && clock
+      ? ` (${clock}에 리셋, 남은 ${reset})`
+      : reset
+        ? ` (리셋까지 ${reset})`
+        : clock
+          ? ` (${clock}에 리셋)`
+          : '';
+    en = `- ${hms(now)} 🚨 ${labelEn} ${pct}% cap warning${tail}`;
+    ko = `🚨 ${labelKo} ${pct}% 캡 경고${tailKo}`;
+  } else {
+    en = `- ${hms(now)} ✓ ${labelEn} cap warning resolved`;
+    ko = `✓ ${labelKo} 캡 경고 해소`;
+  }
+  // Cap-warn entry → handoff tip; resolution → no tip (just the ✓ line).
+  const capTips = isWarn ? { en: `  💡 ${CAP_TIPS.en}`, ko: `  └ 💡 ${CAP_TIPS.ko}` } : null;
+  appendDayLine(en, ko, now, capTips);
+  state[slotKey] = isWarn;
+  saveState(state);
+  return true;
+}
+
+/**
+ * Record a handoff write — invoked by the `handoff` subcommand so
+ * `claude-token-saver history` shows when work was backed up to a HANDOFF file.
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function recordHandoff(filePath) {
+  const now = new Date();
+  const en = `- ${hms(now)} 📝 handoff written: ${filePath}`;
+  const ko = `📝 핸드오프 백업 작성: ${filePath}`;
+  appendDayLine(en, ko, now);
+  return true;
+}
+
+/**
+ * Filter a daily-history file's content down to a single language.
+ *
+ * History files are written bilingual (EN line + `  └ KO` continuation +
+ * `  💡 EN tip` + `  └ 💡 KO tip`). This helper renders just the chosen side
+ * for display, while the on-disk file stays bilingual for archival.
+ *
+ *   en: drop every `  └ ...` line (KR continuations + KR tips).
+ *   ko: replace each EN line with the immediately following `  └ KO` line
+ *       (preserving the leading `- HH:MM:SS` from the EN line so timestamps
+ *       still appear); drop unpaired EN-only events.
+ *
+ * Lines that don't match the bilingual pattern (headers, blank lines,
+ * legacy entries from older versions without the `└ 💡` marker) pass through
+ * unchanged.
+ */
+export function formatHistoryForLanguage(content, lang) {
+  if (lang !== 'ko') {
+    // English: simply strip the `└` continuations.
+    return content
+      .split('\n')
+      .filter((line) => !/^\s*└\s/.test(line))
+      .join('\n');
+  }
+  // Korean: pair each line with its `└` continuation when present.
+  const lines = content.split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const next = lines[i + 1] || '';
+    const cont = next.match(/^(\s*)└\s+(.*)$/);
+    // Event line: `- HH:MM:SS <english>` → keep the timestamp prefix, swap text.
+    const evt = line.match(/^(- \d{2}:\d{2}:\d{2}\s+)(.*)$/);
+    if (evt && cont) {
+      out.push(`${evt[1]}${cont[2]}`);
+      i++;
+      continue;
+    }
+    // Tip line: `  💡 <english>` paired with `  └ 💡 <korean>`.
+    const tip = line.match(/^(\s*)💡\s+(.*)$/);
+    if (tip && cont && /^💡\s/.test(cont[2])) {
+      out.push(`${tip[1]}${cont[2]}`);
+      i++;
+      continue;
+    }
+    // Header / blank / unpaired line — pass through.
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
+/**
+ * List all available history file dates (sorted newest first).
+ */
+export function listDates() {
+  ensureDir(HISTORY_DIR);
+  return readdirSync(HISTORY_DIR)
+    .filter((f) => /^\d{4}-\d{2}-\d{2}\.md$/.test(f))
+    .map((f) => f.replace(/\.md$/, ''))
+    .sort()
+    .reverse();
+}

package/src/hook-manager.js

@@ -0,0 +1,96 @@
+/**
+ * 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, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
+// 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';
+
+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');
+    settings = JSON.parse(raw);
+  } catch {
+    settings = {};
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+
+  // 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) => !(h.hooks || []).some(isCacheMonitorHook),
+  );
+
+  settings.hooks.PostToolUse.push({
+    matcher: 'Bash|Edit|Write',
+    hooks: [
+      {
+        type: 'command',
+        command: `claude-token-saver --hook-run --threshold ${threshold}`,
+        timeout: 10,
+      },
+    ],
+  });
+
+  await writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+
+  // 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`);
+}
+
+export async function uninstallHook() {
+  let settings;
+  try {
+    const raw = await readFile(SETTINGS_PATH, 'utf8');
+    settings = JSON.parse(raw);
+  } catch {
+    console.log('No settings.json found, nothing to uninstall.');
+    return;
+  }
+
+  if (settings.hooks?.PostToolUse) {
+    const before = settings.hooks.PostToolUse.length;
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
+      (h) => !(h.hooks || []).some(isCacheMonitorHook),
+    );
+    const removed = before - settings.hooks.PostToolUse.length;
+
+    if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+    await writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    console.log(`✓ Removed ${removed} hook(s) from settings.json`);
+  } 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

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PostToolUse hook — standalone, zero dependencies, CommonJS.
+ * Appends per-session cache stats to ~/.claude/cache-stats.jsonl.
+ * Warns if hit rate drops below threshold.
+ *
+ * Written in CommonJS so it works standalone in ~/.claude/ without package.json.
+ *
+ * Receives hook context on stdin:
+ *   { session_id, transcript_path, cwd, tool_name, tool_input, tool_response }
+ */
+
+'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');
+
+const STATS_FILE = path.join(os.homedir(), '.claude', 'cache-stats.jsonl');
+const PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
+
+// Parse threshold from args
+let threshold = 0.7;
+const thIdx = process.argv.indexOf('--threshold');
+if (thIdx !== -1 && process.argv[thIdx + 1]) {
+  threshold = parseFloat(process.argv[thIdx + 1]);
+}
+
+// Read stdin (hook context)
+let stdin = '';
+try {
+  stdin = fs.readFileSync(0, 'utf8');
+} catch (e) {
+  dbg('hook:stdin', e);
+}
+
+let context;
+try {
+  context = JSON.parse(stdin);
+} catch (e) {
+  dbg('hook:parse-stdin', e);
+  process.exit(0);
+}
+
+const sessionId = context.session_id;
+const cwd = context.cwd || '';
+if (!sessionId) process.exit(0);
+
+// Resolve session file: prefer transcript_path, fallback to directory scan
+function resolveSessionFile() {
+  // Method 1: transcript_path (Claude Code v2.1.85+)
+  if (context.transcript_path) {
+    try {
+      fs.statSync(context.transcript_path);
+      return context.transcript_path;
+    } catch (e) {
+      dbg('hook:transcript-path', e);
+    }
+  }
+
+  // Method 2: scan projects directory (older versions)
+  try {
+    const dirs = fs.readdirSync(PROJECTS_DIR);
+    for (const d of dirs) {
+      const fp = path.join(PROJECTS_DIR, d, `${sessionId}.jsonl`);
+      try {
+        fs.statSync(fp);
+        return fp;
+      } catch {
+        // not here
+      }
+    }
+  } catch (e) {
+    dbg('hook:projects-dir', e);
+  }
+
+  return null;
+}
+
+const sessionFile = resolveSessionFile();
+if (!sessionFile) process.exit(0);
+
+// Parse session file
+let content;
+try {
+  content = fs.readFileSync(sessionFile, 'utf8');
+} catch (e) {
+  dbg('hook:read-session', e);
+  process.exit(0);
+}
+
+const lines = content.trim().split('\n');
+const requests = new Map();
+
+for (const line of lines) {
+  let entry;
+  try {
+    entry = JSON.parse(line);
+  } catch {
+    continue;
+  }
+
+  const msg = entry.message;
+  if (!msg || !msg.usage || !msg.id) continue;
+
+  const u = msg.usage;
+  const cc = u.cache_creation || {};
+  const reqId = entry.requestId || msg.id;
+
+  requests.set(reqId, {
+    input: u.input_tokens || 0,
+    cacheCreation: u.cache_creation_input_tokens || 0,
+    cacheRead: u.cache_read_input_tokens || 0,
+    ephemeral5m: cc.ephemeral_5m_input_tokens || 0,
+    ephemeral1h: cc.ephemeral_1h_input_tokens || 0,
+    output: u.output_tokens || 0,
+    model: msg.model || 'unknown',
+  });
+}
+
+if (requests.size === 0) process.exit(0);
+
+const reqs = Array.from(requests.values());
+const totals = reqs.reduce(
+  function (a, r) {
+    a.input += r.input;
+    a.cacheCreation += r.cacheCreation;
+    a.cacheRead += r.cacheRead;
+    a.ephemeral5m += r.ephemeral5m;
+    a.ephemeral1h += r.ephemeral1h;
+    a.output += r.output;
+    return a;
+  },
+  { input: 0, cacheCreation: 0, cacheRead: 0, ephemeral5m: 0, ephemeral1h: 0, output: 0 },
+);
+
+const totalInput = totals.cacheRead + totals.cacheCreation + totals.input;
+const hitRate = totalInput > 0 ? totals.cacheRead / totalInput : 0;
+
+const record = {
+  timestamp: new Date().toISOString(),
+  sessionId: sessionId,
+  cwd: cwd,
+  apiCalls: requests.size,
+  hitRate: Math.round(hitRate * 10000) / 10000,
+  tokens: {
+    input: totals.input,
+    cacheCreation: totals.cacheCreation,
+    cacheRead: totals.cacheRead,
+    ephemeral5m: totals.ephemeral5m,
+    ephemeral1h: totals.ephemeral1h,
+    output: totals.output,
+  },
+  model: reqs[0] ? reqs[0].model : 'unknown',
+};
+
+// Append to stats file
+try {
+  fs.appendFileSync(STATS_FILE, JSON.stringify(record) + '\n', 'utf8');
+} catch (e) {
+  dbg('hook:append-stats', e);
+}
+
+// Alert if hit rate below threshold
+if (hitRate < threshold && requests.size >= 5) {
+  var pct = (hitRate * 100).toFixed(1);
+  var ccTotal = totals.ephemeral5m + totals.ephemeral1h;
+  var pct5m = ccTotal > 0 ? ((totals.ephemeral5m / ccTotal) * 100).toFixed(0) : '0';
+  process.stdout.write(
+    '\u26a0 Cache hit rate: ' + pct + '% (threshold: ' + (threshold * 100).toFixed(0) + '%) | 5m TTL: ' + pct5m + '% | ' + requests.size + ' API calls\n',
+  );
+}
+
+// Harness analysis \u2014 best-effort, never throws into the hook stream. The
+// statusline picks up the resulting state file (`harness-state.json`) on
+// the next render, so warnings appear within ~1s of the triggering turn.
+try {
+  var harnessAnalyzer = require('./harness-analyzer.cjs');
+  var state = harnessAnalyzer.analyzeTranscript(sessionFile, {
+    sessionId: sessionId,
+    cwd: cwd,
+  });
+  if (state) harnessAnalyzer.writeState(state);
+} catch (e) {
+  dbg('hook:harness-analyzer', e);
+  // analyzer is purely advisory \u2014 never break the hook on failure
+}