sprag-cli 3.40.0

package/src/commands/last.js

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

package/src/commands/mode.js

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

package/src/commands/route-scan.js

@@ -0,0 +1,454 @@
+/**
+
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+import { readStdinJson } from '../stdin-payload.js';
+import { debug } from '../debug.js';
+
+/**
+ * Whether the user turned doc2md on.
+ *
+ * Read from settings.json rather than from a config flag because the hook
+ * registration *is* the switch: a note telling the model how to convert
+ * documents is noise in a session where nothing will convert them.
+ */
+function doc2mdHookRegistered() {
+  try {
+    const { homedir } = require('node:os');
+    const settings = JSON.parse(readFileSync(join(homedir(), '.claude', 'settings.json'), 'utf8'));
+    return Object.values(settings?.hooks || {}).some((matchers) =>
+      (matchers || []).some((m) =>
+        (m.hooks || []).some((h) => typeof h.command === 'string' && h.command.includes('doc2md --hook')),
+      ),
+    );
+  } catch (e) {
+    debug('route-scan:doc2md-registered', e);
+    return false;
+  }
+}
+
+/** This package's own version — the baseline the upgrade offer compares against. */
+function readPackageVersion() {
+  try {
+    const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    return JSON.parse(readFileSync(pkg, 'utf8')).version || null;
+  } catch (e) {
+    debug('route-scan:pkg-version', e);
+    return null;
+  }
+}
+
+export async function run({ args, hasFlag, numArg }) {
+    const rs = await import('../route-scan.js');
+    const { userLanguage } = await import('../config.js');
+    const lang = userLanguage();
+
+    // route-scan 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)}`;
+      // Lifetime leads (it is what the breakdown below adds up to); the
+      // rolling windows follow as context rather than as competing headlines.
+      console.log(lang === 'ko'
+        ? `🔀 라우팅 절감 누적 ${money(t.total)}  (최근 7일 ${money(t.week)} · 30일 ${money(t.month)})`
+        : `🔀 Routing saved, lifetime ${money(t.total)}  (last 7d ${money(t.week)} · 30d ${money(t.month)})`);
+
+      // 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') {
+      const mr = await import('../model-rules.js');
+      if (args[2] === 'rm') {
+        const n = parseInt(args[3], 10);
+        const removed = Number.isFinite(n) ? mr.removeModelRule(n) : null;
+        if (!removed) {
+          console.error('Usage: claude-token-saver route-scan rules rm <N>   # N from `route-scan rules`');
+          process.exit(1);
+        }
+        // A target whose last rule was removed gets its (tool-owned) file deleted.
+        mr.syncAllFiles({ previousPaths: [mr.modelRatchetPathFor(removed.scope, removed.targetRoot)] });
+        console.log(`Removed model-fitting rule #${n}: ${removed.rule}`);
+        return;
+      }
+      const { rules } = mr.loadModelRules();
+      if (rules.length === 0) {
+        console.log(lang === 'ko' ? '등록된 모델 피팅 룰 없음.' : 'No model-fitting rules registered.');
+        return;
+      }
+      console.log(lang === 'ko' ? '📐 모델 피팅 룰 (로그 기반 자동 갱신):' : '📐 Model-fitting rules (auto-refreshed from logs):');
+      // A T1 rule delegates to sonnet, so in a session whose own model is
+      // already sonnet it can never save anything. That is correct behaviour,
+      // but listed as "measured delegations — (none yet)" it reads as a
+      // promise of savings that will never arrive.
+      const { aliasForRole } = await import('../model-alias.js');
+      const { modelRank } = await import('../cost.js');
+      const sessionModel = aliasForRole('main');
+      const sessionRank = sessionModel ? modelRank(sessionModel) : null;
+      rules.forEach((r, i) => {
+        const health = r.status === 'review'
+          ? (lang === 'ko' ? '  ⚠ 에러율 초과 — 재검토 필요' : '  ⚠ error rate over threshold — needs review')
+          : '';
+        // A seeded rule has no recurrence of its own until a scan measures one,
+        // so "반복 0회 / seen ×0" would misreport a curated preset as work that
+        // never happens.
+        const evidence = r.origin === 'preset' && !r.count
+          ? (lang === 'ko' ? '동봉 프리셋 (로그 누적 전)' : 'bundled preset (no local history yet)')
+          : (lang === 'ko'
+            ? `반복 ${r.count || 0}회 · 에러율 ${Math.round((r.errRate || 0) * 100)}%`
+            : `seen ×${r.count || 0} · err ${Math.round((r.errRate || 0) * 100)}%`);
+        const stat = lang === 'ko'
+          ? `${r.tier} (${rs.tierLabel(r.tier)}) · ${rs.scopeLabel(r.scope)} · ${evidence}`
+          : `${r.tier} (${rs.tierLabel(r.tier, 'en')}) · ${rs.scopeLabel(r.scope, 'en')} · ${evidence}`;
+        console.log(`  #${i + 1} ${stat}${health}`);
+        // Measured outcome of the rule actually firing, plus what it saved.
+        // A rule with no measured delegations shows "—", never "$0.00": the
+        // two mean opposite things (no data vs. data showing no value).
+        const measured = r.delegatedRuns
+          ? (lang === 'ko'
+            ? `실제 위임 ${r.delegatedRuns}건 · 에러율 ${Math.round((r.delegatedErrRate || 0) * 100)}% · 절감 ~$${(r.savedUsd || 0).toFixed(2)}`
+            : `measured ×${r.delegatedRuns} · err ${Math.round((r.delegatedErrRate || 0) * 100)}% · saved ~$${(r.savedUsd || 0).toFixed(2)}`)
+          : (sessionRank !== null && !rs.worthDelegating(r.tier, sessionRank)
+            ? (lang === 'ko'
+              ? `이 규칙은 현재 기본 모델(${sessionModel}) 기준으로는 적용되지 않습니다. 세션 모델이 이미 위임 목표와 같은 급이어서 절감이 발생하지 않습니다.`
+              : `not in effect for the current default model (${sessionModel}) — the session already runs at the delegation target's tier`)
+            : (lang === 'ko'
+              ? '실제 위임 기록이 아직 없습니다.'
+              : 'measured delegations — (none yet)'));
+        console.log(`      ${measured}`);
+        // Same composer the md file uses, so what is listed here is exactly
+        // what the model reads.
+        console.log(`      ${mr.composeRuleText(r.rule, r, lang)}`);
+      });
+      // Runs on a model id we cannot price never reach the aggregate, so a
+      // rule whose tier runs entirely on such an id reads as "never fired".
+      // Say so here rather than leaving the zero unexplained.
+      const scan = rs.readRouteScan();
+      if (scan?.unresolvedRuns > 0) {
+        const ids = (scan.unresolvedModels || []).join(', ');
+        console.log(lang === 'ko'
+          ? `\n⚠ 해석되지 않은 모델 ID 때문에 위임 ${scan.unresolvedRuns}건이 집계에서 제외됐습니다${ids ? ` (${ids})` : ''}.`
+            + '\n  profile-map.json 의 modelAliases 에 해당 ID 를 매핑한 뒤 route-scan --refresh 를 실행하십시오.'
+          : `\n⚠ ${scan.unresolvedRuns} delegated run(s) were excluded — unpriceable model id${ids ? ` (${ids})` : ''}.`
+            + '\n  Map it under modelAliases in profile-map.json, then run route-scan --refresh.');
+      }
+      console.log(lang === 'ko'
+        ? '\n제거: claude-token-saver route-scan rules rm <N>'
+        : '\nRemove with: claude-token-saver route-scan rules rm <N>');
+      return;
+    }
+
+    if (args[1] === 'dismiss') {
+      const n = parseInt(args[2], 10);
+      if (!Number.isFinite(n)) {
+        console.error('Usage: claude-token-saver route-scan dismiss <N>   # N from `route? R<N>`');
+        process.exit(1);
+      }
+      const cand = rs.resolveCandidate(n);
+      if (!cand) {
+        console.error(`No route candidate R${n}. Run: claude-token-saver route-scan`);
+        process.exit(1);
+      }
+      console.log(lang === 'ko'
+        ? `R${n} 무시 처리: ${cand.label} (${cand.project}) — 재스캔에도 다시 뜨지 않습니다.`
+        : `Dismissed R${n}: ${cand.label} (${cand.project}) — won't resurface on rescans.`);
+      return;
+    }
+
+    // --hook: SessionStart hook mode. Never scans inline (session start must
+    // stay fast) — reads the cache, kicks a detached refresh when stale, and
+    // prints delegation-candidate context for the new session.
+    if (hasFlag('--hook')) {
+      const hookCtx = readStdinJson() || {};
+      let cache = rs.readRouteScan();
+      if (await rs.shouldRescan(cache)) {
+        try {
+          const { spawn } = await import('node:child_process');
+          spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet'],
+            { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+        } catch (e) { debug('route-scan:spawn-refresh', e); /* stale cache is still usable below */ }
+      }
+      const open = rs.openCandidates(cache);
+      // Rule text shown to the model must be composed the same way the md file
+      // composes it, budget clause included — otherwise the briefing promises
+      // one rule and the file carries another.
+      const mrHook = await import('../model-rules.js');
+      const composed = (base, c) => mrHook.composeRuleText(base, c, lang);
+      // Re-render ratchet-model.md from THIS version's template. Rule text is
+      // composed in code, so an upgrade that rewords it leaves every existing
+      // file stale, and the rewrite used to ride along with refreshModelRules
+      // — which only runs on a rescan. A session that starts on a warm cache
+      // would keep reading the old wording indefinitely. The call writes only
+      // when the rendering differs, so the common case is a read and a string
+      // compare.
+      try { mrHook.syncAllFiles(); } catch (e) { debug('route-scan:sync-ratchet', e); }
+      // Registered rules whose delegated-category error rate crossed the
+      // health threshold since promotion — the user approved these, so a
+      // status change must be briefed, not just written into the md file.
+      let reviewRules = [];
+      try {
+        const mr = mrHook;
+        reviewRules = mr.loadModelRules().rules
+          .map((r, i) => ({ ...r, n: i + 1 }))
+          .filter((r) => r.status === 'review');
+      } catch (e) { debug('route-scan:load-rules', e); /* candidate briefing still goes out */ }
+      // Korean writing guidance, when the user enabled it. Printed before the
+      // route-scan briefing and independently of it: the style has to reach a
+      // session even when there is no candidate to report, which is the usual
+      // case. Injecting here rather than through a separate hook keeps it on
+      // one SessionStart round-trip and one cached prefix.
+      let koreanBlock = null;
+      try {
+        const { koreanStyleInjection } = await import('../korean-style.js');
+        koreanBlock = koreanStyleInjection();
+      } catch (e) { debug('route-scan:korean-style', e); /* style is optional */ }
+
+      // English cohesion guidance, when enabled. Same round-trip; skipped
+      // internally when the Korean guidance already carries the same rules.
+      let cohesionBlock = null;
+      try {
+        const { cohesionInjection } = await import('../cohesion.js');
+        cohesionBlock = await cohesionInjection();
+      } catch (e) { debug('route-scan:cohesion', e); /* the guidance is optional */ }
+
+      // doc2md's standing note, only when the user turned the feature on.
+      // Rides the same SessionStart round-trip as the style block for the same
+      // reason: one injection, one cached prefix. It carries the two things the
+      // model cannot work out for itself — that a binary-file refusal has a
+      // one-command answer, and that an attached document costs far more than
+      // the path to it.
+      let doc2mdBlock = null;
+      try {
+        if (doc2mdHookRegistered()) doc2mdBlock = require('../doc2md.cjs').sessionNote(lang);
+      } catch (e) { debug('route-scan:doc2md-note', e); /* the note is optional */ }
+
+      // Starter rules that the user has not answered yet (bundled presets, both
+      // model-fitting and ratchet). A fresh install has an empty model ratchet
+      // and an empty ratchet.md, so without this the tool delegates nothing
+      // until the user's own history is long enough to propose a candidate.
+      // The asking happens here because a CLI prompt cannot reach a user whose
+      // only interface is the chat: the model gets the list and asks one rule
+      // at a time. Silent — and free — once everything has an answer.
+      let seedBlock = null;
+      try {
+        const { seedOfferBlock } = await import('../seed-rules.js');
+        seedBlock = seedOfferBlock({ lang });
+      } catch (e) { debug('route-scan:seed-offer', e); /* the offer is optional */ }
+
+      // Upgrade offer. A statusline cannot open a dialog, so session start is
+      // where the *asking* happens: the model gets one line telling it a newer
+      // version exists and to ask before installing anything. Cached read only
+      // — the refresh runs detached off the statusline path, never here.
+      let updateBlock = null;
+      try {
+        const { updateStatus, maybeSpawnUpdateCheck } = await import('../update-check.js');
+        const pkgVersion = readPackageVersion();
+        // Session start is the one moment where a stale cache matters most, so
+        // kick the detached refresh here too. It lands in time for the
+        // statusline and for the next session, not for this line.
+        if (pkgVersion) maybeSpawnUpdateCheck(pkgVersion);
+        const u = pkgVersion ? updateStatus(pkgVersion) : null;
+        // `dismissed` is the whole point of asking once: a user who said no to
+        // this version must not be asked again every `/clear`.
+        if (u && u.available && !u.dismissed) {
+          updateBlock = lang === 'ko'
+            ? [
+                `[claude-token-saver update] 새 버전이 나와 있습니다: v${u.current} → ${u.latest}.`,
+                '사용자에게 지금 업그레이드할지 물어보고, 승낙하면 아래 명령을 실행하십시오. 묻지 않고 설치하지는 마십시오.',
+                '  claude-token-saver upgrade            # 업그레이드 실행',
+                '  claude-token-saver update-check --dismiss   # 사용자가 원치 않으면 (다음 버전이 나올 때까지 다시 묻지 않습니다)',
+              ].join('\n')
+            : [
+                `[claude-token-saver update] A newer version is available: v${u.current} → ${u.latest}.`,
+                'Ask the user whether to upgrade now, and run the command below only if they agree. Do not install without asking.',
+                '  claude-token-saver upgrade                  # perform the upgrade',
+                '  claude-token-saver update-check --dismiss   # if they decline (stays quiet until a newer release)',
+              ].join('\n');
+        }
+      } catch (e) { debug('route-scan:update-check', e); /* the offer is optional */ }
+
+      if (open.length === 0 && reviewRules.length === 0) {
+        if (updateBlock) console.log(updateBlock);
+        if (seedBlock) console.log(seedBlock);
+        if (doc2mdBlock) console.log(doc2mdBlock);
+        if (koreanBlock) console.log(koreanBlock);
+        if (cohesionBlock) console.log(cohesionBlock);
+        return; // nothing else to inject
+      }
+      if (updateBlock) console.log(updateBlock);
+      if (seedBlock) console.log(seedBlock);
+      if (doc2mdBlock) console.log(doc2mdBlock);
+      // This text is injected straight into the model's context, so it must
+      // follow the user's configured language — a Korean-only briefing in an
+      // English session steers the whole first response into Korean.
+      const lines = [];
+      if (open.length > 0) {
+        if (lang === 'ko') {
+          lines.push(`[claude-token-saver route-scan] 최근 ${cache.days}일 세션에서 비싼 모델(opus/fable)이 반복 처리해 온, 더 싼 모델로 넘겨도 되는 작업이 감지되었습니다.`);
+          lines.push('(R<N>은 후보 번호, T2/T1은 난이도 등급입니다 — 사용자에게 전달할 때는 코드가 아니라 아래 풀어쓴 설명으로 브리핑하세요)');
+        } else {
+          lines.push(`[claude-token-saver route-scan] Over the last ${cache.days} days, expensive models (opus/fable) repeatedly handled work that a cheaper model could take.`);
+          lines.push('(R<N> is the candidate id, T2/T1 the difficulty tier — brief the user with the spelled-out wording below, not the codes.)');
+        }
+        for (const c of open) {
+          const tier = c.tier || 'T2';
+          const label = lang === 'ko' ? c.label : (c.labelEn || c.label);
+          const rule = composed(lang === 'ko' ? c.rule : (c.ruleEn || c.rule), c);
+          if (lang === 'ko') {
+            lines.push(`  후보 R${c.id} — "${label}" 유형, ${c.count}회 반복 (프로젝트: ${c.project})`);
+            lines.push(`      판정: ${tier} (${rs.tierLabel(tier)}) → ${c.agent} 서브에이전트 위임 권장 · 적용 범위 제안: ${rs.scopeLabel(c.suggestedScope)}`);
+            lines.push(`      예시 요청: "${c.example}"`);
+            lines.push(`      등록 시 ratchet-model.md에 기록될 룰: "${rule}"`);
+          } else {
+            lines.push(`  Candidate R${c.id} — "${label}", seen ×${c.count} (project: ${c.project})`);
+            lines.push(`      verdict: ${tier} (${rs.tierLabel(tier, 'en')}) → delegate to the ${c.agent} subagent · suggested scope: ${rs.scopeLabel(c.suggestedScope, 'en')}`);
+            lines.push(`      example request: "${c.example}"`);
+            lines.push(`      rule that would be written to ratchet-model.md: "${rule}"`);
+          }
+        }
+        if (lang === 'ko') {
+          lines.push('등록하면 다음 세션부터 자동 위임됩니다. 사용자에게 등록 여부를 물을 때 위 룰 원문을 그대로 보여주고, 적용 범위까지 확인한 뒤 실행하세요:');
+          lines.push('  claude-token-saver harness promote R<N> --project|--global   # 적용 범위는 반드시 사용자에게 확인');
+          lines.push('  claude-token-saver route-scan dismiss <N>                    # 사용자가 원치 않으면');
+        } else {
+          lines.push('Once registered, delegation happens automatically from the next session. Show the user the rule text verbatim, confirm the scope with them, then run:');
+          lines.push('  claude-token-saver harness promote R<N> --project|--global   # ALWAYS confirm the scope with the user first');
+          lines.push('  claude-token-saver route-scan dismiss <N>                    # if they do not want it');
+        }
+      }
+      if (reviewRules.length > 0) {
+        lines.push(lang === 'ko'
+          ? '[claude-token-saver rule-health] 사용자가 승인한 위임 룰 중, 위임 대상 유형의 최근 에러율이 기준(20%)을 넘어 재검토가 필요한 룰이 있습니다 — 사용자에게 브리핑하고 조건 좁히기/제거를 상의하세요:'
+          : '[claude-token-saver rule-health] Some user-approved delegation rules now exceed the 20% error-rate threshold for their delegated category — brief the user and discuss narrowing or removing them:');
+        for (const r of reviewRules) {
+          // Say WHICH signal tripped: a measured delegation failure rate is a
+          // much stronger claim than the shape-based proxy, and the user's
+          // decision (narrow vs. remove) depends on knowing which it is.
+          const measured = r.healthSource === 'delegated';
+          const rate = Math.round(((measured ? r.delegatedErrRate : r.errRate) || 0) * 100);
+          const evidence = lang === 'ko'
+            ? (measured ? `실제 위임 ${r.delegatedRuns}건 실측 에러율 ${rate}%` : `유형 에러율 ${rate}% (형태 기반 추정)`)
+            : (measured ? `${rate}% measured across ${r.delegatedRuns} real delegations` : `${rate}% for the category (shape-based proxy)`);
+          lines.push(lang === 'ko'
+            ? `  룰 #${r.n} (${r.tier} ${rs.tierLabel(r.tier)} · ${rs.scopeLabel(r.scope)}) — ${evidence}`
+            : `  rule #${r.n} (${r.tier} ${rs.tierLabel(r.tier, 'en')} · ${rs.scopeLabel(r.scope, 'en')}) — ${evidence}`);
+          lines.push(`      "${r.rule}"`);
+        }
+        lines.push(lang === 'ko'
+          ? '  제거: claude-token-saver route-scan rules rm <N>'
+          : '  remove with: claude-token-saver route-scan rules rm <N>');
+      }
+      lines.push(lang === 'ko'
+        ? '위 내용은 사용자의 첫 메시지 주제와 무관하더라도(단순 인사여도) 첫 응답 말미에 `※ [claude-token-saver]` 라벨을 달아 요약 브리핑하세요 — 사용자가 물어볼 때까지 기다리지 말 것.'
+        : 'Summarize the above at the end of your first response under a `※ [claude-token-saver]` label, even if the user\'s first message is unrelated (a bare greeting counts) — do not wait to be asked.');
+      // Style first, briefing second: the briefing is Korean prose too, so the
+      // guidance has to be in context before the model reads it.
+      if (koreanBlock) console.log(koreanBlock + '\n');
+      if (cohesionBlock) console.log(cohesionBlock + '\n');
+      console.log(lines.join('\n'));
+      // Record what was actually briefed so the UserPromptSubmit brief hook
+      // suppresses exactly these — a candidate landing after this read (e.g.
+      // the detached rescan above finishing) still gets briefed next prompt.
+      try {
+        const { seedSessionBriefed } = await import('../brief.js');
+        seedSessionBriefed(hookCtx.session_id, [
+          ...open.map((c) => `route|${c.signature}`),
+          ...reviewRules.map((r) => `health|${r.signature}|${r.scope}`),
+        ]);
+      } catch (e) { debug('route-scan:seed-briefed', e); /* worst case is one duplicate brief */ }
+      return;
+    }
+
+    const days = numArg('--days', { dflt: 14, min: 0 });
+    let cache = rs.readRouteScan();
+    if (hasFlag('--refresh') || (cache && cache.days !== days) || await rs.shouldRescan(cache, { days })) {
+      cache = await rs.runRouteScan({ days });
+    }
+    if (hasFlag('--quiet')) return;
+    if (hasFlag('--json')) {
+      console.log(JSON.stringify(cache, null, 2));
+      return;
+    }
+    const easyPct = cache.totalEpisodes ? Math.round(cache.easyEpisodes / cache.totalEpisodes * 100) : 0;
+    console.log(lang === 'ko'
+      ? `route-scan — 최근 ${cache.days}일: 에피소드 ${cache.totalEpisodes}건 중 easy ${cache.easyEpisodes}건 (${easyPct}%)  [스캔: ${cache.scannedAt}]`
+      : `route-scan — last ${cache.days}d: ${cache.easyEpisodes}/${cache.totalEpisodes} episodes easy (${easyPct}%)  [scanned: ${cache.scannedAt}]`);
+    const open = rs.openCandidates(cache);
+    if (open.length === 0) {
+      console.log(lang === 'ko'
+        ? '위임 후보 없음 (반복 3회 미만이거나 이미 처리됨).'
+        : 'No delegation candidates (below recurrence threshold or already resolved).');
+      (await import('../first-run-note.js')).printOnce('route-scan', lang);
+      return;
+    }
+    console.log(lang === 'ko' ? '\n위임 후보 (R<N>=후보 번호, T2/T1=난이도 등급):' : '\nDelegation candidates (R<N> = candidate id, T2/T1 = difficulty tier):');
+    for (const c of open) {
+      const tier = c.tier || 'T2';
+      if (lang === 'ko') {
+        console.log(`  R${c.id}  "${c.label}" ×${c.count}회 [${c.project}]`);
+        console.log(`       판정: ${tier} (${rs.tierLabel(tier)}) → ${c.agent} 위임 권장 · 적용 범위 제안: ${rs.scopeLabel(c.suggestedScope)}`);
+      } else {
+        console.log(`  R${c.id}  "${c.labelEn || c.label}" ×${c.count} [${c.project}]`);
+        console.log(`       verdict: ${tier} (${rs.tierLabel(tier, 'en')}) → delegate to ${c.agent} · suggested scope: ${rs.scopeLabel(c.suggestedScope, 'en')}`);
+      }
+      console.log(`       ${lang === 'ko' ? '예시' : 'example'}: "${c.example}"`);
+      const mrList = await import('../model-rules.js');
+      const base = lang === 'ko' ? c.rule : (c.ruleEn || c.rule);
+      console.log(`       ${lang === 'ko' ? '룰' : 'rule'}: ${mrList.composeRuleText(base, c, lang)}`);
+    }
+    console.log('');
+    console.log(lang === 'ko' ? '등록 / 무시:' : 'Promote / dismiss:');
+    console.log('  claude-token-saver harness promote R<N> --project|--global');
+    console.log('  claude-token-saver route-scan dismiss <N>');
+    // 최초 1회만 — 매번 찍으면 도구가 광고판이 된다 (CTS_NO_NOTE=1 로 끔)
+    (await import('../first-run-note.js')).printOnce('route-scan', lang);
+    return;
+}