claude-token-saver 3.5.2 → 3.6.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "claude-token-saver",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {
     "claude-token-saver": "bin/cli.js"
   },
   "scripts": {
+    "test": "node --test test/",
     "postinstall": "node bin/cli.js install || true"
   },
   "files": [

package/src/cli-args.js

@@ -0,0 +1,51 @@
+/**
+ * argv accessors shared by every subcommand.
+ *
+ * `createArgs(argv)` binds them to one argument list, so a subcommand module
+ * takes them as a parameter instead of reaching for a module-level global —
+ * which also makes them directly testable.
+ */
+
+export function createArgs(argv) {
+  const args = argv;
+
+  function getArg(name) {
+    const idx = args.indexOf(name);
+    if (idx !== -1) return args[idx + 1];
+    const prefix = `${name}=`;
+    const eq = args.find((a) => a.startsWith(prefix));
+    if (eq) return eq.slice(prefix.length);
+    return undefined;
+  }
+
+  function hasFlag(name) {
+    return args.includes(name);
+  }
+
+  /**
+   * Read a numeric option, rejecting garbage instead of letting NaN flow into
+   * the report window. `--days abc` used to render as `NaNd` on the statusline
+   * and as a bare "no session data" in the table view — a typo that looked
+   * exactly like "you have no logs".
+   *
+   * @param {string} name flag name, e.g. '--days'
+   * @param {object} [opts]
+   * @param {number} [opts.dflt] value when the flag is absent
+   * @param {number} [opts.min] inclusive lower bound
+   * @param {number} [opts.max] inclusive upper bound
+   * @throws {Error} on a non-numeric or out-of-range value
+   */
+  function numArg(name, { dflt, min, max } = {}) {
+    const raw = getArg(name);
+    if (raw === undefined) return dflt;
+    const n = parseFloat(raw);
+    if (!Number.isFinite(n)) {
+      throw new Error(`${name} expects a number, got "${raw}"`);
+    }
+    if (min !== undefined && n < min) throw new Error(`${name} must be >= ${min}, got ${n}`);
+    if (max !== undefined && n > max) throw new Error(`${name} must be <= ${max}, got ${n}`);
+    return n;
+  }
+
+  return { args, getArg, hasFlag, numArg };
+}

package/src/commands/brief.js

@@ -0,0 +1,31 @@
+/**
+ * Subcommand: route-scan — detect recurring easy work on expensive models
+ * and propose model-delegation ratchet rules. Zero token cost, fully local.
+ *   claude-token-saver route-scan                 # scan (24h cache) + print candidates
+ *   claude-token-saver route-scan --refresh       # force rescan
+ *   claude-token-saver route-scan --days 30       # wider lookback
+ *   claude-token-saver route-scan --hook          # SessionStart hook mode (context injection)
+ *   claude-token-saver route-scan dismiss <N>     # mute candidate R<N>
+ * Promote a candidate to a ratchet rule (scope is always explicit):
+ *   claude-token-saver harness promote R<N> --project|--global
+ * brief --hook — UserPromptSubmit hook mode: per-session, change-triggered
+ * briefing of state the statusline can only chip (ctx tier crossings,
+ * mid-session route/rule-health changes). Silent when nothing changed.
+ */
+
+import { readStdinJson } from '../stdin-payload.js';
+import { debug } from '../debug.js';
+
+export async function run({ hasFlag }) {
+    if (!hasFlag('--hook')) {
+      console.error('Usage: claude-token-saver brief --hook   (UserPromptSubmit hook mode)');
+      process.exit(1);
+    }
+    const ctx = readStdinJson() || {};
+    try {
+      const { runBrief } = await import('../brief.js');
+      const out = await runBrief({ sessionId: ctx.session_id, transcriptPath: ctx.transcript_path });
+      if (out) console.log(out);
+    } catch (e) { debug('brief:hook', e); /* briefing is best-effort — never block a prompt */ }
+    return;
+}

package/src/commands/handoff.js

@@ -0,0 +1,33 @@
+/**
+ * Subcommand: handoff — write a HANDOFF-YYYY-MM-DD-HHMM.md template in cwd
+ * capturing git status + the latest cap snapshot, so a fresh Claude Code
+ * session can pick up where this one stopped. Pairs with the cap-warn chip:
+ * when statusline shows 🚨 5H 90%+, run this to back up state before the cap
+ * hits.
+ *   claude-token-saver handoff             # write to cwd
+ *   claude-token-saver handoff --cwd PATH  # custom directory
+ */
+
+import { readStdinJson, extractCaps } from '../stdin-payload.js';
+import { debug } from '../debug.js';
+
+export async function run({ getArg }) {
+    const { writeHandoff } = await import('../handoff.js');
+    const { recordHandoff } = await import('../history.js');
+    const cwd = getArg('--cwd') || process.cwd();
+    // Cap data only flows in via stdin (Claude Code statusline contract).
+    // Direct CLI invocations won't have it — that's fine, the template will
+    // note the gap.
+    const stdinJson = readStdinJson();
+    const caps = extractCaps(stdinJson);
+    const { path, git } = writeHandoff({ cwd, caps });
+    try { recordHandoff(path); } catch (e) { debug('handoff:record', e); }
+    console.log(`Handoff written: ${path}`);
+    if (git) {
+      console.log(`  git: ${git.branch}${git.head ? ` @ ${git.head}` : ''}${git.status ? ' (dirty)' : ' (clean)'}`);
+    }
+    console.log('');
+    console.log('Fill in the empty sections, then start a new Claude Code session with:');
+    console.log('  Read the most recent HANDOFF-*.md in this directory and continue the work.');
+    return;
+}

package/src/commands/harness.js

@@ -0,0 +1,383 @@
+/**
+ * Subcommand: harness — manage the project's CLAUDE.md harness rules.
+ *   claude-token-saver harness init       # write CLAUDE.md (5 sections) + ratchet.md
+ *   claude-token-saver harness uninit     # remove harness block from CLAUDE.md (backup kept)
+ *   claude-token-saver harness check      # show 🅷 N/5 + which sections are missing
+ *   claude-token-saver harness promote "<rule>"  # append a rule to ratchet.md
+ *   claude-token-saver harness pull [--global|--project]  # register the package's curated preset rules (default global)
+ *   claude-token-saver harness off | on   # toggle the statusline 🅷 segment
+ */
+
+import { debug } from '../debug.js';
+
+export async function run({ args, hasFlag }) {
+    const sub = args[1];
+    // Scope flags for init/uninit/check (same convention as promote/list/rm):
+    //   --global | --project | --scope=global|project | --scope global|project
+    const parseHarnessScope = (argv, dflt) => {
+      for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--global') return 'global';
+        if (a === '--project') return 'project';
+        if (a === '--scope' && (argv[i + 1] === 'global' || argv[i + 1] === 'project')) return argv[i + 1];
+        if (a.startsWith('--scope=')) {
+          const v = a.slice('--scope='.length);
+          if (v === 'global' || v === 'project') return v;
+        }
+      }
+      return dflt;
+    };
+    const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessPull, harnessListRules, harnessRmRule, findProjectRoot } =
+      await import('../harness.js');
+    const { HARNESS_SECTIONS } = await import('../harness-templates.js');
+    const { loadConfig, saveConfig, userLanguage } = await import('../config.js');
+    const lang = userLanguage();
+
+    if (!sub || sub === 'check') {
+      const scope = parseHarnessScope(args.slice(2), 'auto'); // auto = project, else global fallback
+      const root = findProjectRoot();
+      const s = harnessStatus(root, { scope });
+      // Only call out "covered by global" when we *fell back* to it (auto), not
+      // when the user explicitly asked for the global scope.
+      const via = (scope === 'auto' && s.source === 'global') ? ' (covered by global ~/.claude/CLAUDE.md)' : '';
+      console.log(`🅷 ${s.configured}/${s.total} — ${s.file}${via}`);
+      console.log(`CLAUDE.md: ${s.hasFile ? 'present' : 'missing'}` +
+        (s.hasFile ? `, harness block: ${s.hasBlock ? 'yes' : 'no'}` : '') + ` [${s.source}]`);
+      if (s.missing.length) {
+        console.log('Missing sections:');
+        for (const id of s.missing) {
+          const sec = HARNESS_SECTIONS.find((x) => x.id === id);
+          console.log(`  - ${id}: ${sec ? sec.heading.replace(/^#+\s*/, '') : ''}`);
+        }
+        console.log('\nRun: claude-token-saver harness init        (this project)');
+        console.log('  or: claude-token-saver harness init --global  (all projects, ~/.claude/CLAUDE.md)');
+      } else {
+        console.log('All 5 harness sections present. ✅');
+      }
+      return;
+    }
+
+    if (sub === 'init') {
+      const scope = parseHarnessScope(args.slice(2), 'project'); // default project (back-compat)
+      const force = hasFlag('--force');
+      const r = harnessInit({ force, scope });
+      console.log(`Scope: ${scope}${scope === 'global' ? '  (~/.claude/CLAUDE.md — applies to all projects)' : `  (${r.root})`}`);
+      for (const p of r.backedUp) console.log(`Backed up: ${p}`);
+      for (const p of r.wrote) console.log(`Wrote:     ${p}`);
+      for (const p of r.skipped) console.log(`Skipped:   ${p}`);
+      console.log('\n🅷 Harness initialized. Statusline will show 🅷 5/5 on next refresh.');
+      return;
+    }
+
+    if (sub === 'promote') {
+      // Parse scope flags before stripping. Accepts: --global, --project,
+      //   --scope=global|project, --scope global|project
+      const promoteArgs = args.slice(2);
+      let scope = null;
+      const scopeFlags = new Set();
+      for (let i = 0; i < promoteArgs.length; i++) {
+        const a = promoteArgs[i];
+        if (a === '--global') { scope = 'global'; scopeFlags.add(i); }
+        else if (a === '--project') { scope = 'project'; scopeFlags.add(i); }
+        else if (a === '--scope' && promoteArgs[i + 1]) {
+          const v = promoteArgs[i + 1];
+          if (v !== 'global' && v !== 'project') {
+            console.error(`Invalid --scope value: ${v} (expected "global" or "project")`);
+            process.exit(1);
+          }
+          scope = v; scopeFlags.add(i); scopeFlags.add(i + 1); i++;
+        } else if (a.startsWith('--scope=')) {
+          const v = a.slice('--scope='.length);
+          if (v !== 'global' && v !== 'project') {
+            console.error(`Invalid --scope value: ${v} (expected "global" or "project")`);
+            process.exit(1);
+          }
+          scope = v; scopeFlags.add(i);
+        }
+      }
+      const raw = promoteArgs.filter((_, i) => !scopeFlags.has(i)).join(' ').trim();
+      if (!raw) {
+        console.error('Usage: claude-token-saver harness promote [--global|--project] <N>  # from statusline 🅷⚠ ratchet? #N');
+        console.error('   or: claude-token-saver harness promote [--global|--project] "<rule text>"');
+        process.exit(1);
+      }
+      let rule = raw;
+      // Numeric arg → look up candidate #N from analyzer state and turn its
+      // detected error pattern into a starter ratchet rule. Saves the user
+      // from retyping the error; they can edit ratchet.md afterward.
+      if (/^\d+$/.test(raw)) {
+        const n = parseInt(raw, 10);
+        const analyzer = await import('../harness-analyzer.cjs');
+        const a = analyzer.default || analyzer;
+        const state = a.readState();
+        const list = (state && state.ratchetCandidates) || [];
+        const cand = list.find((c) => c.id === n);
+        if (!cand) {
+          console.error(`No ratchet candidate #${n} in state. Run \`harness analyze\` or wait for the hook to populate it.`);
+          if (list.length) {
+            console.error('Available candidates:');
+            for (const c of list) console.error(`  #${c.id} (×${c.count}): ${c.pattern}`);
+          }
+          process.exit(1);
+        }
+        rule = `반복 감지 ×${cand.count}: ${cand.pattern} — TODO: 원인·예방책 한 줄로`;
+      }
+      // R-prefixed arg → route-scan delegation candidate (statusline `route? R<N>`).
+      // The rule text is pre-generated by the scan; promoting also resolves the
+      // candidate so the chip stops and rescans don't resurface it.
+      let routeCandidateId = null;
+      let routeCandidate = null;
+      if (/^[Rr]\d+$/.test(raw)) {
+        const n = parseInt(raw.slice(1), 10);
+        const rs = await import('../route-scan.js');
+        const cand = (rs.openCandidates(rs.readRouteScan()) || []).find((c) => c.id === n);
+        if (!cand) {
+          console.error(`No open route candidate R${n}. Run: claude-token-saver route-scan`);
+          process.exit(1);
+        }
+        rule = lang === 'ko' ? cand.rule : (cand.ruleEn || cand.rule);
+        routeCandidateId = n;
+        routeCandidate = cand;
+        if (!scope) {
+          console.error(`Route candidate R${n} requires an explicit scope (suggested: --${cand.suggestedScope}).`);
+          console.error('Ask the user, then pass --project or --global.');
+          process.exit(1);
+        }
+      }
+      // Scope resolution: explicit flag wins. Otherwise prompt interactively
+      // when running on a TTY; in non-TTY (CI/scripts) require an explicit
+      // flag so the choice is never silently made for the caller.
+      if (!scope) {
+        if (process.stdin.isTTY && process.stdout.isTTY) {
+          const readline = await import('node:readline');
+          const { homedir: hd } = await import('node:os');
+          const { findProjectRoot: fpr } = await import('../harness.js');
+          const projPath = `${fpr()}/.claude/ratchet.md`;
+          const globPath = `${hd()}/.claude/ratchet.md`;
+          const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+          const ask = (q) => new Promise((res) => rl.question(q, res));
+          console.log('Where should this rule live?');
+          console.log(`  [1] project  (${projPath})`);
+          console.log(`  [2] global   (${globPath})`);
+          const ans = (await ask('Choose [1/2] (default 1): ')).trim();
+          rl.close();
+          scope = (ans === '2' || ans.toLowerCase() === 'global' || ans.toLowerCase() === 'g')
+            ? 'global' : 'project';
+        } else {
+          console.error('Scope required in non-interactive mode.');
+          console.error('Pass --project or --global (or --scope=project|global).');
+          process.exit(1);
+        }
+      }
+      // Route candidates become MODEL-FITTING rules: they live in a
+      // tool-managed block (separate from user-authored ratchet rules) and
+      // keep updating from subsequent logs — recurrence counts, error rates,
+      // rule-health — on every rescan.
+      if (routeCandidate) {
+        const rs = await import('../route-scan.js');
+        const mr = await import('../model-rules.js');
+        // A --project rule must land in THE project the pattern was detected
+        // in, not the cwd's. Old caches without projectPath: verify cwd match.
+        let targetRoot = null;
+        if (scope === 'project') {
+          if (routeCandidate.projectPath) {
+            targetRoot = findProjectRoot(routeCandidate.projectPath);
+          } else if (rs.mungeProjectPath(findProjectRoot()) === routeCandidate.project) {
+            targetRoot = findProjectRoot();
+          } else {
+            console.error(`Route candidate R${routeCandidateId} was detected in another project (${routeCandidate.project}),`);
+            console.error('but this cached scan predates project-path tracking.');
+            console.error('Re-scan to capture it, then promote again:');
+            console.error('  claude-token-saver route-scan --refresh');
+            process.exit(1);
+          }
+        }
+        const entry = mr.addModelRule({
+          signature: routeCandidate.signature,
+          tier: routeCandidate.tier || 'T2',
+          category: routeCandidate.category,
+          label: routeCandidate.label,
+          labelEn: routeCandidate.labelEn,
+          agent: routeCandidate.agent,
+          scope,
+          targetRoot,
+          project: routeCandidate.project,
+          rule: lang === 'ko' ? routeCandidate.rule : (routeCandidate.ruleEn || routeCandidate.rule),
+          example: routeCandidate.example,
+          count: routeCandidate.count,
+          promotedAt: new Date().toISOString().slice(0, 10),
+          lastSeen: new Date().toISOString().slice(0, 10),
+        });
+        const written = mr.syncAllFiles();
+        rs.resolveCandidate(routeCandidateId);
+        console.log(`Model-fitting rule registered [${scope}${targetRoot ? ` → ${targetRoot}` : ''}] (tier ${entry.tier}):`);
+        console.log(`  - ${entry.rule}`);
+        for (const p of written) console.log(`  ratchet-model.md updated: ${p}`);
+        console.log(lang === 'ko'
+          ? `(route candidate R${routeCandidateId} resolved — 다음 세션부터 자동 위임, 이후 스캔마다 로그 기반 갱신됩니다)`
+          : `(route candidate R${routeCandidateId} resolved — delegation applies from the next session, refreshed from logs on every rescan)`);
+        console.log(lang === 'ko'
+          ? '룰 목록/제거: claude-token-saver route-scan rules [rm <N>]'
+          : 'List / remove: claude-token-saver route-scan rules [rm <N>]');
+        // Event-triggered refresh: establish the new rule's stat baseline
+        // right away instead of waiting for the next data-gated rescan.
+        try {
+          const { spawn } = await import('node:child_process');
+          spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet'],
+            { detached: true, stdio: 'ignore' }).unref();
+        } catch (e) { debug('promote:spawn-refresh', e); /* baseline arrives on the next gated rescan */ }
+        return;
+      }
+      const r = harnessPromote(rule, { scope });
+      console.log(`Appended to ${r.path} [${r.scope}]:`);
+      console.log(`  - ${rule}`);
+      if (/^\d+$/.test(raw)) {
+        console.log(lang === 'ko'
+          ? '\n👉 ratchet.md를 열어 TODO 부분을 실제 룰로 다듬어주세요.'
+          : '\n👉 Open ratchet.md and turn the TODO into the actual rule.');
+      }
+      return;
+    }
+
+    if (sub === 'analyze') {
+      // Run the analyzer once against the most recent session JSONL under
+      // ~/.claude/projects/ and dump the resulting state. Useful for users
+      // who don't have the hook installed but want to see warnings.
+      const analyzer = await import('../harness-analyzer.cjs');
+      const { analyzeTranscript, writeState } = analyzer.default || analyzer;
+      const { readdirSync, statSync } = await import('node:fs');
+      const { join: pj } = await import('node:path');
+      const { homedir } = await import('node:os');
+      const dir = pj(homedir(), '.claude', 'projects');
+      let latest = null;
+      let latestMtime = 0;
+      try {
+        for (const subdir of readdirSync(dir)) {
+          const full = pj(dir, subdir);
+          if (!statSync(full).isDirectory()) continue;
+          for (const f of readdirSync(full)) {
+            if (!f.endsWith('.jsonl')) continue;
+            const fp = pj(full, f);
+            const m = statSync(fp).mtimeMs;
+            if (m > latestMtime) { latestMtime = m; latest = fp; }
+          }
+        }
+      } catch (e) { debug('harness:analyze-scan', e); }
+      if (!latest) {
+        console.error('No session transcripts found under ~/.claude/projects/');
+        process.exit(1);
+      }
+      const state = analyzeTranscript(latest, { cwd: process.cwd() });
+      if (state) writeState(state);
+      console.log(JSON.stringify(state, null, 2));
+      return;
+    }
+
+    if (sub === 'uninit' || sub === 'remove') {
+      const scope = parseHarnessScope(args.slice(2), 'project');
+      const purgeRatchet = args.includes('--purge-ratchet');
+      const r = harnessUninit({ purgeRatchet, scope });
+      console.log(`Scope: ${scope}${scope === 'global' ? '  (~/.claude/CLAUDE.md)' : `  (${r.root})`}`);
+      r.removed.forEach((f) => console.log(`  removed: ${f}`));
+      r.backedUp.forEach((f) => console.log(`  backup:  ${f}`));
+      r.skipped.forEach((f) => console.log(`  skip:    ${f}`));
+      if (r.removed.length === 0) console.log('Nothing to remove.');
+      return;
+    }
+
+    if (sub === 'pull') {
+      // Register the package's curated preset rules (presets/ratchet-rules.md)
+      // into the user's ratchet — global by default (they're tool/environment
+      // rules, and a project ratchet inherits global anyway). Strictly opt-in:
+      // install/init never auto-injects rules.
+      const scope = parseHarnessScope(args.slice(2), 'global');
+      const r = harnessPull({ scope });
+      console.log(`Curated preset rules → ${r.path} [${r.scope}]`);
+      if (r.added.length) {
+        console.log(`✅ ${r.added.length}/${r.presets} rule(s) registered:`);
+        for (const t of r.added) console.log(`  - ${t}`);
+      } else {
+        console.log(`No new rules — all ${r.presets} presets already registered.`);
+      }
+      if (r.skippedRules && r.added.length) console.log(`   (${r.skippedRules} already present — skipped)`);
+      console.log(lang === 'ko'
+        ? '\n필요 없는 룰은 언제든: claude-token-saver harness list / rm <N>'
+        : '\nDrop any rule you do not want: claude-token-saver harness list / rm <N>');
+      return;
+    }
+
+    if (sub === 'list' || sub === 'ls') {
+      const wantGlobal = hasFlag('--global');
+      const wantProject = hasFlag('--project') || !wantGlobal;
+      const print = (scope) => {
+        const { path, rules } = harnessListRules({ scope });
+        if (!rules.length) {
+          console.log(`No ratchet rules in ${path} [${scope}]`);
+          return;
+        }
+        console.log(`📋 Ratchet rules [${scope}] — ${path}\n`);
+        for (const r of rules) console.log(`  #${r.index}  ${r.text}`);
+        console.log('');
+      };
+      if (wantProject) print('project');
+      if (wantGlobal) print('global');
+      console.log('Remove with: claude-token-saver harness rm [--global|--project] <N>');
+      return;
+    }
+
+    if (sub === 'rm') {
+      const rmScope = hasFlag('--global') ? 'global' : 'project';
+      const rmArgs = args.slice(2).filter((a) => a !== '--global' && a !== '--project');
+      const raw = (rmArgs[0] || '').trim();
+      if (!/^\d+$/.test(raw)) {
+        console.error('Usage: claude-token-saver harness rm [--global|--project] <N>   # N from `harness list`');
+        process.exit(1);
+      }
+      const n = parseInt(raw, 10);
+      // ⚠️ Heads-up before deletion. Ratchet's value is one-way accumulation —
+      // dropping a rule is sometimes right, but more often the rule is just
+      // too narrow. Surface the alternative loudly here.
+      if (lang === 'ko') {
+        console.log('⚠️  주의: ratchet 룰 삭제는 신중하게.');
+        console.log('   같은 실수가 또 발생할 가능성이 큽니다. 보통은 "조건이 너무 좁아서"');
+        console.log('   문제가 되는 경우가 많아요. 지우기 전에 한 번 더 검토하세요:');
+        console.log('   - 룰이 너무 광범위해서 정상 케이스도 막나? → 조건을 좁혀서 다듬기');
+        console.log('   - 룰이 너무 좁아서 거의 발동 안 되나? → 그냥 두기 (비용 0)');
+        console.log('   - 정말 잘못된 룰이라 확신? → 그때만 삭제');
+      } else {
+        console.log('⚠️  Careful: removing a ratchet rule is rarely the fix.');
+        console.log('   The mistake it guards against tends to come back. Usually the');
+        console.log('   problem is that the rule is worded too narrowly. Check first:');
+        console.log('   - Too broad, blocking legitimate cases? → tighten the condition');
+        console.log('   - Too narrow, almost never fires? → leave it (it costs nothing)');
+        console.log('   - Genuinely wrong? → only then delete it');
+      }
+      console.log('');
+      const r = harnessRmRule(n, { scope: rmScope });
+      if (!r.ok) {
+        console.error(`❌ ${r.error}`);
+        if (r.rules) {
+          console.error('Available:');
+          for (const x of r.rules) console.error(`  #${x.index}  ${x.text}`);
+        }
+        process.exit(1);
+      }
+      console.log(`✅ Removed #${n}: ${r.removed.text}`);
+      console.log(`   Backup: ${r.backup}`);
+      console.log(`   복구: cp "${r.backup}" "${r.path}"`);
+      return;
+    }
+
+    if (sub === 'off' || sub === 'on') {
+      const cfg = loadConfig();
+      cfg.harness = cfg.harness || {};
+      cfg.harness.enabled = sub === 'on';
+      saveConfig(cfg);
+      console.log(`Statusline 🅷 segment: ${sub}`);
+      return;
+    }
+
+    console.error(`Unknown harness subcommand: ${sub}`);
+    console.error('Usage: claude-token-saver harness [check|init|uninit [--purge-ratchet]|promote "<rule>"|pull [--global|--project]|list|rm <N>|off|on]');
+    process.exit(1);
+}

package/src/commands/history.js

@@ -0,0 +1,46 @@
+/**
+ * Subcommand: history — print recent warning transitions captured by the
+ * statusline. One markdown file per day, persisted under the platform-
+ * specific user-data dir.
+ *   claude-token-saver history              # last 7 days
+ *   claude-token-saver history --days 30    # custom window
+ *   claude-token-saver history --list       # just list available dates
+ */
+
+
+export async function run({ hasFlag, numArg }) {
+    const { readRecent, listDates, historyDir, formatHistoryForLanguage } =
+      await import('../history.js');
+    const { userLanguage } = await import('../config.js');
+    const lang = userLanguage();
+    if (hasFlag('--list')) {
+      const dates = listDates();
+      if (dates.length === 0) {
+        console.log(lang === 'ko'
+          ? `히스토리가 아직 없습니다. 파일은 다음 위치에 생성됩니다: ${historyDir()}`
+          : `No history yet. Files will appear under: ${historyDir()}`);
+        return;
+      }
+      console.log(lang === 'ko' ? `히스토리 (${historyDir()}):` : `History (${historyDir()}):`);
+      for (const d of dates) console.log(`  ${d}`);
+      return;
+    }
+    const days = numArg('--days', { dflt: 7, min: 0 });
+    const recent = readRecent(days);
+    if (recent.length === 0) {
+      if (lang === 'ko') {
+        console.log(`최근 ${days}일 내 경고 히스토리가 없습니다.`);
+        console.log(`(파일이 생성될 위치: ${historyDir()})`);
+      } else {
+        console.log(`No warning history in the last ${days} day${days === 1 ? '' : 's'}.`);
+        console.log(`(Files would be written to: ${historyDir()})`);
+      }
+      return;
+    }
+    for (const { content } of recent) {
+      const filtered = formatHistoryForLanguage(content, lang);
+      console.log(filtered.replace(/\n+$/, ''));
+      console.log('');
+    }
+    return;
+}

package/src/commands/install.js

@@ -0,0 +1,70 @@
+/**
+ * Subcommand: install — write the Claude Code auto-trigger skill so the
+ * user can just mention chip wording and Claude responds. v2.6.0 dropped
+ * the redundant /token-monitor slash command in favor of the skill alone;
+ * a legacy command file is removed automatically. Cross-platform.
+ *   claude-token-saver install              # install/update the skill
+ *   claude-token-saver install --force      # overwrite existing skill file
+ */
+
+import { debug } from '../debug.js';
+
+export async function run({ hasFlag }) {
+    const { installAll } = await import('../installer.js');
+    const { userLanguage } = await import('../config.js');
+    const lang = userLanguage();
+    const force = hasFlag('--force');
+    const print = (kind, r) => {
+      const verb = r.action === 'exists' ? 'already exists' : r.action;
+      console.log(`  ${kind}: ${r.path} (${verb})`);
+    };
+    const r = installAll({ force });
+    print('skill', r.skill);
+    print('SessionStart hook (route-scan)', r.sessionStartHook);
+    print('UserPromptSubmit hook (brief)', r.briefHook);
+    {
+      const s = r.statusline;
+      const verb = s.action === 'exists' ? 'already configured (refreshInterval=5)'
+        : s.action === 'skipped' ? `skipped — ${s.reason}`
+        : s.reason ? `${s.action} — ${s.reason}`
+        : s.action;
+      console.log(`  statusline: ${s.path} (${verb})`);
+    }
+    if (r.legacy.action === 'removed') {
+      print('legacy /token-monitor', r.legacy);
+      console.log('  (consolidated into the skill — same workflow, triggered by intent)');
+    }
+    // First-time setup: analyze existing session logs right away so the
+    // very first session already sees delegation candidates — without this,
+    // the initial scan would only start from the first session's hook and
+    // its results would surface one session late. Runs inline (a few
+    // seconds on a typical 14-day history): a detached child can be reaped
+    // by sandboxed installers before it finishes, and postinstall carries
+    // `|| true` so a failure here never breaks the install.
+    {
+      const rs = await import('../route-scan.js');
+      if (!rs.readRouteScan()) {
+        try {
+          console.log('');
+          console.log(lang === 'ko'
+            ? '  route-scan: 기존 세션 로그의 사용 패턴을 분석하는 중...'
+            : '  route-scan: analyzing usage patterns in your existing session logs...');
+          const cache = await rs.runRouteScan({ days: 14 });
+          console.log(lang === 'ko'
+            ? `  route-scan: 에피소드 ${cache.totalEpisodes}건 분석 완료 — 위임 후보 ${cache.candidates.length}건.`
+            : `  route-scan: analyzed ${cache.totalEpisodes} episodes — ${cache.candidates.length} delegation candidate(s).`);
+          console.log(lang === 'ko'
+            ? '              (다음 Claude Code 세션에서 티어 위임 후보가 표시됩니다)'
+            : '              (candidates surface in your next Claude Code session)');
+        } catch (e) { debug('install:route-scan-seed', e); /* hook-triggered scan covers it on the first session instead */ }
+      }
+    }
+    console.log('');
+    console.log('Open Claude Code in any directory and just mention:');
+    console.log('  "cache hit rate" / "1M context" / "5H cap" — the skill auto-activates.');
+    if (!force) {
+      console.log('');
+      console.log('Tip: re-run with --force to overwrite the existing skill file.');
+    }
+    return;
+}