claude-token-saver 2.17.0 → 3.0.0

package/src/advice.js

@@ -39,25 +39,33 @@ function toggleShortcut() {
  */
 export const ISSUE_MESSAGES = {
   LARGE_INPUT_PER_REQUEST: {
-    title: 'Per-request input tokens are unusually large (1M context suspected)',
-    titleKo: '요청당 입력 토큰이 비정상적으로 큼 (1M 컨텍스트 의심)',
+    title: 'Per-request input tokens are unusually large (context past 200k)',
+    titleKo: '요청당 입력 토큰이 비정상적으로 큼 (컨텍스트 200k 초과)',
+    // Since Opus 4.7 there is NO long-context price premium — 1M is standard
+    // rate and the default window on current models. The cost driver is the
+    // token volume itself: a 500k-token context re-reads ~500k tokens every
+    // turn (cache-read billed) and burns the subscription 5H/7D windows
+    // several times faster. That's what this warning is about.
     explain:
-      'Since Opus 4.7, 1M context is priced at the standard rate, and Max plans auto-promote ' +
-      'sessions to 1M. Once context goes past 200k, long-context pricing kicks in and cache reuse drops.',
+      'Current models default to a 1M window with no long-context premium — but the token ' +
+      'volume itself is the cost: every turn re-reads the whole context (billed as cache reads) ' +
+      'and drains the 5H/7D rate-limit windows several times faster. Cache reuse also drops.',
     explainKo:
-      'Opus 4.7부터 1M 컨텍스트가 표준 요금이 되었고, Max 플랜은 세션을 자동으로 1M으로 승격합니다. ' +
-      '200k를 넘는 순간 장기 컨텍스트 요금이 적용되며 캐시 재사용률도 떨어집니다.',
+      '현재 모델은 1M 윈도가 기본이고 장기 컨텍스트 프리미엄도 없습니다 — 하지만 토큰량 자체가 비용입니다. ' +
+      '매 턴 컨텍스트 전체를 다시 읽고(캐시 읽기 과금) 5H/7D 한도도 몇 배 빠르게 소모됩니다. ' +
+      '캐시 재사용률도 떨어집니다.',
     actions: () => [
       {
-        label: 'Disable 1M context (env var)',
-        labelKo: '1M 컨텍스트 끄기 (환경변수)',
-        commands: disable1mEnvSnippet(),
-      },
-      {
-        label: 'In-session toggle',
-        labelKo: '세션 내 즉시 토글',
-        commands: [`Press ${toggleShortcut()} to toggle on/off instantly`],
-        commandsKo: [`${toggleShortcut()} 누르면 즉시 on/off 토글`],
+        label: 'Compact or clear when context grows (first lever)',
+        labelKo: '컨텍스트가 커지면 /compact 또는 /clear (1순위)',
+        commands: [
+          '/compact  — summarize the session history in place',
+          '/clear    — drop history entirely at a clean task boundary',
+        ],
+        commandsKo: [
+          '/compact — 세션 히스토리를 그 자리에서 요약',
+          '/clear   — 작업 분기점에서 히스토리를 통째로 비우기',
+        ],
       },
       {
         label: 'Cap extended-thinking budget (⚠ check /effort first)',
@@ -90,16 +98,14 @@ export const ISSUE_MESSAGES = {
         ],
       },
       {
-        label: 'Compact or clear when context grows',
-        labelKo: '컨텍스트가 커지면 /compact 또는 /clear',
-        commands: [
-          '/compact  — summarize the session history in place',
-          '/clear    — drop history entirely at a clean task boundary',
-        ],
-        commandsKo: [
-          '/compact — 세션 히스토리를 그 자리에서 요약',
-          '/clear   — 작업 분기점에서 히스토리를 통째로 비우기',
-        ],
+        label: 'Cap the window at 200k if you never need more (optional)',
+        labelKo: '더 큰 윈도가 필요 없으면 200k로 제한 (선택)',
+        commands: disable1mEnvSnippet().concat([
+          `Or press ${toggleShortcut()} to toggle in-session`,
+        ]),
+        commandsKo: disable1mEnvSnippet().concat([
+          `또는 ${toggleShortcut()}로 세션 내 즉시 토글`,
+        ]),
       },
       {
         label: '⚠ Known bug #31640',
@@ -337,11 +343,13 @@ export const ISSUE_MESSAGES = {
     title: 'Context window is approaching the limit',
     titleKo: '컨텍스트 창이 한계에 근접',
     explain:
-      'As context grows toward 200k (or 1M), each turn becomes more expensive and cache ' +
-      'reuse efficiency drops. Past 200k, long-context pricing applies.',
+      'As context grows, each turn becomes more expensive (the whole context is re-read every ' +
+      'turn) and cache reuse efficiency drops. There is no price premium past 200k on current ' +
+      'models — the token volume itself is the cost, and it drains the 5H/7D caps faster.',
     explainKo:
-      '컨텍스트가 200k(또는 1M)에 가까워질수록 매 턴 비용이 높아지고 캐시 재사용 효율이 떨어집니다. ' +
-      '200k를 넘으면 장기 컨텍스트 요금이 적용됩니다.',
+      '컨텍스트가 커질수록 매 턴 비용이 높아지고(전체 컨텍스트를 매 턴 다시 읽음) 캐시 재사용 효율이 ' +
+      '떨어집니다. 현재 모델은 200k 초과 프리미엄이 없습니다 — 토큰량 자체가 비용이며 5H/7D 한도도 ' +
+      '더 빠르게 소모됩니다.',
     actions: () => [
       {
         label: '/compact at the next natural break',
@@ -435,8 +443,8 @@ export const ISSUE_MESSAGES = {
  */
 export const ISSUE_TIPS = {
   LARGE_INPUT_PER_REQUEST: {
-    en: 'Check `/effort` — `xhigh` is the #1 cap killer; switch to `/effort medium` (or `low`); disable 1M context; `/compact` when context grows',
-    ko: '`/effort` 확인 — `xhigh`가 캡 소진 1순위 원인, `medium`(또는 `low`)으로 복귀; 1M 컨텍스트 끄기; 컨텍스트 커지면 `/compact`',
+    en: '`/compact` or `/clear` — big contexts re-bill every turn and burn the 5H/7D caps; check `/effort` (`xhigh` is the #1 cap killer)',
+    ko: '`/compact` 또는 `/clear` — 큰 컨텍스트는 매 턴 재과금되고 5H/7D 한도를 태움; `/effort` 확인 (`xhigh`가 캡 소진 1순위)',
   },
   LOW_HIT_RATE: {
     en: 'Continue with `claude --continue`; keep CLAUDE.md trim — every line ships every turn',
@@ -463,8 +471,8 @@ export const ISSUE_TIPS = {
     ko: '지금 바로 아무 프롬프트나 보내 TTL 타이머 리셋; 또는 자리 비우기 전 `/compact` (Pro = 5분, Max = 1시간)',
   },
   CONTEXT_NEAR_LIMIT: {
-    en: '`/compact` before hitting the limit; `/clear` + re-attach only needed files; disable 1M: `export CLAUDE_MODEL_CONTEXT=200000`',
-    ko: '한계 도달 전 `/compact`; `/clear` 후 필요한 파일만 재첨부; 1M 끄기: `export CLAUDE_MODEL_CONTEXT=200000`',
+    en: '`/compact` before hitting the limit; `/clear` + re-attach only needed files',
+    ko: '한계 도달 전 `/compact`; `/clear` 후 필요한 파일만 재첨부',
   },
 };
 
@@ -474,6 +482,9 @@ export const ISSUE_TIPS = {
  * need a fallback so history.js can still surface the right tip.
  */
 export const CHIP_TO_CODES = {
+  '⚠ Ctx 200k+': ['LARGE_INPUT_PER_REQUEST'],
+  // Legacy chip name (pre-v2.18) — kept so `last`/`history` can still resolve
+  // codes from history files written by older versions.
   '⚠ 1M ON': ['LARGE_INPUT_PER_REQUEST'],
   '⚠ Cache miss': ['LOW_HIT_RATE'],
   '⚠ Input spike': ['LARGE_INPUT_PER_REQUEST'],
@@ -502,7 +513,11 @@ export const CAP_TIPS = {
  * shown to a global audience.
  */
 export function chipForIssues(issues, contextWindow) {
-  if (contextWindow?.size === '1M') return '⚠ 1M ON';
+  // Fires on *actual usage* (a real request carried >210k input tokens), not
+  // on the model merely supporting 1M — current models are all 1M by default
+  // with no price premium, so "1M ON" stopped being a meaningful alarm. The
+  // meaningful signal is "your context genuinely exceeded 200k".
+  if (contextWindow?.size === '1M') return '⚠ Ctx 200k+';
   const codes = issues.map((i) => i.code);
   if (codes.includes('LARGE_INPUT_PER_REQUEST')) return '⚠ Input spike';
   if (codes.includes('BUCKET_5M_DOMINANT')) return '⚠ 5m TTL';

package/src/demo.js

@@ -26,6 +26,7 @@ const SCENARIOS = [
       savings: 2123,
       elapsedSec: 30,
       contextSize: '200k',
+      ctxUsedPct: 34,
       spikeChip: null,
       caps: HEALTHY_CAPS,
     },
@@ -98,14 +99,15 @@ const SCENARIOS = [
   },
   {
     name: 'ctx-1m',
-    label: '⚠ 1M context auto-on',
+    label: '⚠ Context past 200k',
     data: {
       hitRate: 0.78,
       pct1h: 0.92,
       savings: 1340,
       elapsedSec: 30,
       contextSize: '1M',
-      spikeChip: '⚠ 1M ON',
+      ctxUsedPct: 28, // 28% of 1M ≈ 280k actually in context
+      spikeChip: '⚠ Ctx 200k+',
       caps: HEALTHY_CAPS,
     },
   },
@@ -271,7 +273,7 @@ export function buildTableDemoData(options = {}) {
     spikeReport: { spikes, baseline: { p95: 940_000 } },
     contextWindow: { size: '1M', maxContext: 280_000 },
     lastActivity: Date.now() - 60 * 1000,
-    spikeChip: '⚠ 1M ON',
+    spikeChip: '⚠ Ctx 200k+',
   };
 }
 
@@ -301,7 +303,7 @@ export function buildScenarioData(scenarioName, options) {
     if (!scenario) return null;
   }
 
-  const { hitRate, pct1h, pct5m, savings, elapsedSec, contextSize, spikeChip, caps } = scenario.data;
+  const { hitRate, pct1h, pct5m, savings, elapsedSec, contextSize, ctxUsedPct, spikeChip, caps } = scenario.data;
   return {
     summary: { hitRate },
     ttl: { pct1h, pct5m: pct5m ?? (1 - pct1h) },
@@ -314,6 +316,11 @@ export function buildScenarioData(scenarioName, options) {
     },
     lastActivity: Date.now() - elapsedSec * 1000,
     contextWindow: { size: contextSize },
+    // Live fill level (`📦 68%`) — scenarios that set ctxUsedPct exercise the
+    // stdin-driven segment; the rest fall back to the size-based chip.
+    ctxLive: ctxUsedPct != null
+      ? { usedPct: ctxUsedPct, size: contextSize === '1M' ? 1_000_000 : 200_000 }
+      : undefined,
     spikeChip,
     caps: buildCapsShape(caps),
     model: DEFAULT_MODEL,

package/src/formatters/statusline.js

@@ -214,7 +214,7 @@ export function formatNoSession({ caps = null, model = null, windowLabel = '' }
  * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, harness, model, hit, ttl, saved, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
  */
 export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null } = {}) {
-  const { summary, ttl, cost, options, lastActivity, contextWindow, spikeChip, caps, model } = data;
+  const { summary, ttl, cost, options, lastActivity, contextWindow, ctxLive, spikeChip, caps, model } = data;
   const { hitRate } = summary;
 
   // Hit rate → color signal
@@ -321,15 +321,36 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     }
   }
 
-  // Context window chip (e.g. "📦 1M" or "📦 200k"). 1M gets a warning color
-  // because it's the expensive default on Max plans after Opus 4.7.
+  // Context chip. Two data sources, best first:
+  //
+  //  1. Live fill level from Claude Code's stdin (`context_window.used_percentage`)
+  //     — the current session's actual usage, refreshed every render. Rendered
+  //     as `📦 68%` and colored by fill (green <70, yellow 70–89, red 90+),
+  //     matching the cap-segment tone scale.
+  //  2. Fallback (table view / older Claude Code): transcript-inferred window
+  //     size. Note the semantics: `size === '1M'` means a real request already
+  //     carried >210k input tokens — actual heavy usage, not just the model
+  //     supporting 1M. Current models are all 1M by default with no price
+  //     premium, so this renders yellow ("your context is genuinely big"),
+  //     not red ("expensive mode on") like it used to.
   let ctxSeg = null;
-  if (contextWindow && contextWindow.size && contextWindow.size !== 'unknown') {
+  if (ctxLive && Number.isFinite(ctxLive.usedPct)) {
+    const pct = Math.max(0, Math.round(ctxLive.usedPct));
+    const tone = pct >= 90 ? RED : pct >= 70 ? YELLOW : GREEN;
+    const sizeLabel = ctxLive.size
+      ? (ctxLive.size >= 900_000 ? '1M' : `${Math.round(ctxLive.size / 1000)}k`)
+      : null;
+    const longLabel = sizeLabel ? `${pct}% of ${sizeLabel}` : `${pct}%`;
+    if (isIcon && verbose) {
+      ctxSeg = `${c(tone)}📦 Ctx ${longLabel}${c(RESET)}`;
+    } else if (isIcon) {
+      ctxSeg = `${c(tone)}📦 ${pct}%${c(RESET)}`;
+    } else {
+      ctxSeg = `${c(tone)}Ctx ${longLabel}${c(RESET)}`;
+    }
+  } else if (contextWindow && contextWindow.size && contextWindow.size !== 'unknown') {
     const label = contextWindow.size === '1M' ? '1M' : '200k';
-    const ctxColor = contextWindow.size === '1M' ? RED : GREEN;
-    // `Ctx` (not the full word `Context`) across every mode — the icon already
-    // tells the eye what the chip is, and the short form fits the same cadence
-    // as `Hit`/`Saved` peers when we eventually shorten those too.
+    const ctxColor = contextWindow.size === '1M' ? YELLOW : GREEN;
     if (isIcon && verbose) {
       ctxSeg = `${c(ctxColor)}📦 Ctx ${label}${c(RESET)}`;
     } else if (isIcon) {

package/src/formatters/table.js

@@ -86,7 +86,7 @@ function renderSpikeSection(spikes, contextWindow) {
   lines.push(r(`  ${'─'.repeat(50)}`));
   if (contextWindow && contextWindow.size === '1M') {
     lines.push(
-      r(`  Context mode: 1M  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`),
+      r(`  Context usage exceeded 200k  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`),
     );
     lines.push('');
   }
@@ -197,7 +197,7 @@ export function formatReport({ summary: sum, trend, ttl, anomalies, cost, option
   if (contextWindow && contextWindow.size !== 'unknown') {
     const note =
       contextWindow.size === '1M'
-        ? '⚠ 1M context active (Opus 4.7+ Max default). Disable with CLAUDE_CODE_DISABLE_1M_CONTEXT=1'
+        ? '⚠ Context exceeded 200k in recent requests — big contexts re-bill every turn and drain the 5H/7D caps. Use /compact or /clear.'
         : '✓ 200k context (standard)';
     lines.push(`  Context window: ${contextWindow.size}  ${note}`);
     lines.push(`  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`);

package/src/frugon-export.js

@@ -0,0 +1,211 @@
+/**
+ * frugon export — convert Claude Code session transcripts into the
+ * OpenAI-compatible JSONL log format frugon analyzes.
+ * (frugon: local LLM cost analyzer — github.com/Rodiun/frugon)
+ *
+ * One output line per API call:
+ *   {
+ *     "model": "claude-opus-4-8",
+ *     "timestamp": "2026-07-12T02:11:05.123Z",
+ *     "usage": { "prompt_tokens": 1234, "completion_tokens": 56 },
+ *     "request": { "messages": [ ...stubs..., { "role": "user", "content": "<last user prompt>" } ] },
+ *     "response": { "choices": [ { "message": { "role": "assistant", "content": "<reply>" } } ] }
+ *   }
+ *
+ * Design notes (kept in sync with frugon 0.2.x internals):
+ *  - frugon prefers the usage block for token counts, so message content is
+ *    never re-tokenized — stubs with empty content are safe.
+ *  - frugon's easy/hard difficulty score reads prompt_tokens, completion_tokens
+ *    and conversation depth (len(messages) - 1, saturating at 6 turns). We emit
+ *    up to MAX_STUB_MESSAGES role-alternating stubs so depth survives the
+ *    export without duplicating the whole conversation into every record.
+ *  - frugon has no notion of prompt caching: every prompt token is priced at
+ *    the base input rate. Claude Code sessions are cache-read heavy (~90%+),
+ *    so raw totals would overstate spend ~10x. By default we fold Anthropic's
+ *    cache multipliers (5m write 1.25x, 1h write 2x, read 0.1x) into an
+ *    "effective" prompt_tokens so frugon's dollar figures match reality.
+ *    Pass cacheWeighted: false for raw physical token counts.
+ */
+
+import { createReadStream, createWriteStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { discoverSessionFiles } from './parser.js';
+
+// Depth cap: frugon's turn signal saturates at 6 turns (len(messages)-1 >= 6),
+// so 7 messages carry the maximum-depth signal at minimum size.
+const MAX_STUB_MESSAGES = 7;
+
+// Anthropic cache multipliers relative to the base input rate — uniform
+// across model tiers (see src/cost.js PRICING).
+const CACHE_WEIGHTS = { write5m: 1.25, write1h: 2, read: 0.1 };
+
+/** Strip context-window suffixes like "[1m]" so frugon's pricing table matches. */
+export function normalizeModelId(model) {
+  return String(model || 'unknown').replace(/\[[^\]]*\]$/, '');
+}
+
+/**
+ * Effective prompt tokens: what the call *costs* expressed in base-rate
+ * input tokens, so frugon (which prices all prompt tokens at the input rate)
+ * reproduces the real cache-discounted spend.
+ */
+export function effectivePromptTokens(r) {
+  const tracked = (r.ephemeral5mTokens || 0) + (r.ephemeral1hTokens || 0);
+  const untracked = Math.max(0, (r.cacheCreationTokens || 0) - tracked);
+  return Math.round(
+    (r.inputTokens || 0) +
+    ((r.ephemeral5mTokens || 0) + untracked) * CACHE_WEIGHTS.write5m +
+    (r.ephemeral1hTokens || 0) * CACHE_WEIGHTS.write1h +
+    (r.cacheReadTokens || 0) * CACHE_WEIGHTS.read,
+  );
+}
+
+/** Raw physical prompt tokens (input + cache writes + cache reads). */
+export function rawPromptTokens(r) {
+  return (r.inputTokens || 0) + (r.cacheCreationTokens || 0) + (r.cacheReadTokens || 0);
+}
+
+/** Extract plain text from a Claude transcript message content field. */
+function contentText(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+    .map((b) => b.text)
+    .join('\n');
+}
+
+/**
+ * Parse one session transcript into frugon records.
+ * Deduplicates by requestId (last-write-wins, matching parser.js) while
+ * tracking the conversation depth and last user prompt at each call.
+ */
+export async function collectSessionRecords(filePath, { cacheWeighted = true, includeContent = true } = {}) {
+  const records = new Map();
+  let depth = 0;
+  let lastUserText = '';
+  let lastCwd = '';
+
+  const rl = createInterface({
+    input: createReadStream(filePath, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const msg = entry.message;
+    if (typeof entry.cwd === 'string' && entry.cwd) lastCwd = entry.cwd;
+    if (entry.type === 'user' && msg) {
+      depth += 1;
+      const text = contentText(msg.content);
+      if (text) lastUserText = text;
+      continue;
+    }
+    if (entry.type !== 'assistant' || !msg) continue;
+    depth += 1;
+
+    if (!msg.usage || !msg.id) continue;
+    // "<synthetic>" is Claude Code's placeholder for locally-generated
+    // entries (e.g. error stubs) — no real API call, nothing to price.
+    if (msg.model === '<synthetic>') continue;
+    const usage = msg.usage;
+    const reqId = entry.requestId || msg.id;
+    const r = {
+      inputTokens: usage.input_tokens || 0,
+      cacheCreationTokens: usage.cache_creation_input_tokens || 0,
+      cacheReadTokens: usage.cache_read_input_tokens || 0,
+      ephemeral5mTokens: usage.cache_creation?.ephemeral_5m_input_tokens || 0,
+      ephemeral1hTokens: usage.cache_creation?.ephemeral_1h_input_tokens || 0,
+      outputTokens: usage.output_tokens || 0,
+    };
+
+    records.set(reqId, {
+      model: normalizeModelId(msg.model),
+      timestamp: entry.timestamp || null,
+      prompt_tokens: cacheWeighted ? effectivePromptTokens(r) : rawPromptTokens(r),
+      completion_tokens: r.outputTokens,
+      depth,
+      userText: includeContent ? lastUserText : '',
+      assistantText: includeContent ? contentText(msg.content) : '',
+      cwd: lastCwd,
+    });
+  }
+
+  return [...records.values()];
+}
+
+/** Build the frugon JSONL object for one collected record. */
+export function toFrugonRecord(rec) {
+  const msgCount = Math.max(1, Math.min(rec.depth, MAX_STUB_MESSAGES));
+  const messages = [];
+  for (let i = 0; i < msgCount - 1; i++) {
+    messages.push({ role: i % 2 === 0 ? 'user' : 'assistant', content: '' });
+  }
+  messages.push({ role: 'user', content: rec.userText || '' });
+
+  const out = {
+    model: rec.model,
+    request: { messages },
+    response: {
+      choices: [{ message: { role: 'assistant', content: rec.assistantText || '' } }],
+    },
+    usage: {
+      prompt_tokens: rec.prompt_tokens,
+      completion_tokens: rec.completion_tokens,
+    },
+  };
+  if (rec.timestamp) out.timestamp = rec.timestamp;
+  return out;
+}
+
+/**
+ * Export Claude Code transcripts to a frugon-compatible JSONL file.
+ *
+ * @param {object} options
+ *   days           lookback window (default 30)
+ *   projectFilter  substring match on the project dir name
+ *   outPath        output JSONL path
+ *   cacheWeighted  fold cache pricing into prompt_tokens (default true)
+ *   includeContent include user prompt / assistant reply text (default true)
+ * @returns {Promise<{records:number, sessions:number, models:Object, outPath:string}>}
+ */
+export async function exportFrugonLogs({
+  days = 30,
+  projectFilter,
+  outPath,
+  cacheWeighted = true,
+  includeContent = true,
+} = {}) {
+  const files = await discoverSessionFiles({ days, projectFilter });
+  const models = {};
+  let recordCount = 0;
+  let sessionCount = 0;
+
+  const stream = createWriteStream(outPath, { encoding: 'utf8' });
+  for (const f of files) {
+    let recs;
+    try {
+      recs = await collectSessionRecords(f.path, { cacheWeighted, includeContent });
+    } catch {
+      continue;
+    }
+    if (recs.length === 0) continue;
+    sessionCount += 1;
+    for (const rec of recs) {
+      stream.write(JSON.stringify(toFrugonRecord(rec)) + '\n');
+      models[rec.model] = (models[rec.model] || 0) + 1;
+      recordCount += 1;
+    }
+  }
+  await new Promise((resolve, reject) => {
+    stream.end((err) => (err ? reject(err) : resolve()));
+  });
+
+  return { records: recordCount, sessions: sessionCount, models, outPath };
+}

package/src/harness.js

@@ -19,6 +19,7 @@ import {
   harnessRatchetMdInitial,
   appendRatchetRule,
 } from './harness-templates.js';
+import { routeWarningForStatusline } from './route-scan.js';
 
 const require = createRequire(import.meta.url);
 function readHarnessState() {
@@ -276,6 +277,82 @@ export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'pr
   return { path: rmPath, root, scope };
 }
 
+/**
+ * harness pull — copy the user's GLOBAL ratchet rules (~/.claude/ratchet.md)
+ * into the current project's .claude/ratchet.md, on demand. Opt-in by design:
+ * install/init never auto-injects rules; this is the explicit "땡겨오기" verb.
+ *
+ * Rules are deduped by text (ignoring the leading YYYY-MM-DD stamp) so
+ * repeated pulls are idempotent. With `includeBlock`, the global CLAUDE.md
+ * harness block (including any user customizations) is also copied into the
+ * project CLAUDE.md — replacing the project's block if one exists.
+ *
+ * Returns { root, added, skippedRules, wrote, skipped }.
+ */
+export function harnessPull({ root = findProjectRoot(), includeBlock = false } = {}) {
+  const result = { root, added: [], skippedRules: 0, wrote: [], skipped: [] };
+  const stripDate = (t) => t.replace(/^\d{4}-\d{2}-\d{2}:\s*/, '').trim();
+
+  // 1) Ratchet rules: global → project, dedup by rule text.
+  const globalRules = harnessListRules({ scope: 'global' }).rules;
+  const projPath = ratchetMdPath(root);
+  let content = existsSync(projPath)
+    ? readFileSync(projPath, 'utf8')
+    : harnessRatchetMdInitial();
+  const have = new Set(
+    harnessListRules({ root, scope: 'project' }).rules.map((r) => stripDate(r.text)),
+  );
+  for (const g of globalRules) {
+    const key = stripDate(g.text);
+    if (have.has(key)) {
+      result.skippedRules += 1;
+      continue;
+    }
+    content = appendRatchetRule(content, key);
+    have.add(key);
+    result.added.push(key);
+  }
+  if (result.added.length) {
+    mkdirSync(dirname(projPath), { recursive: true });
+    writeFileSync(projPath, content);
+    result.wrote.push(projPath);
+  }
+
+  // 2) Harness block (opt-in): copy the global block as-is so user edits to
+  //    the global sections travel with it.
+  if (includeBlock) {
+    const gPath = globalClaudeMdPath();
+    const blockRe = new RegExp(
+      `${escapeRe(HARNESS_BLOCK_BEGIN)}[\\s\\S]*?${escapeRe(HARNESS_BLOCK_END)}\\n?`,
+      'm',
+    );
+    const gContent = existsSync(gPath) ? readFileSync(gPath, 'utf8') : '';
+    const m = gContent.match(blockRe);
+    if (!m) {
+      result.skipped.push(`${gPath} (no global harness block to pull)`);
+    } else {
+      const block = m[0];
+      const pPath = claudeMdPath(root);
+      if (existsSync(pPath)) {
+        const pc = readFileSync(pPath, 'utf8');
+        if (pc.includes(HARNESS_BLOCK_BEGIN)) {
+          writeFileSync(pPath, pc.replace(blockRe, block));
+          result.wrote.push(`${pPath} (harness block replaced with global copy)`);
+        } else {
+          const sep = pc.endsWith('\n') ? '\n' : '\n\n';
+          writeFileSync(pPath, pc + sep + block);
+          result.wrote.push(`${pPath} (harness block appended from global)`);
+        }
+      } else {
+        writeFileSync(pPath, block);
+        result.wrote.push(pPath);
+      }
+    }
+  }
+
+  return result;
+}
+
 /**
  * harness list — return numbered ratchet rules from .claude/ratchet.md.
  * Numbering is 1-based and matches `harness rm <N>`.
@@ -362,6 +439,14 @@ export function harnessStatusForStatusline(cfg, { root } = {}) {
       else if (state.pevSkip) warning = 'PEV-skip';
     }
   }
+  // Lowest precedence: route-scan delegation candidate (`route? R<N>`).
+  // Session-quality warnings above always win — routing is an optimization
+  // nudge, not a correctness signal. Cheap: one small cached-JSON read.
+  if (!warning) {
+    try {
+      warning = routeWarningForStatusline(projectRoot);
+    } catch { /* scan cache unreadable — stay silent */ }
+  }
   return { ...status, warning };
 }
 

package/src/history.js

@@ -69,7 +69,8 @@ function saveState(state) {
 function chipKo(chip) {
   if (!chip) return chip;
   const map = {
-    '⚠ 1M ON': '⚠ 1M 컨텍스트 활성',
+    '⚠ Ctx 200k+': '⚠ 컨텍스트 200k 초과',
+    '⚠ 1M ON': '⚠ 1M 컨텍스트 활성', // legacy (pre-v2.18)
     '⚠ Cache miss': '⚠ 캐시 미스',
     '⚠ Rebuild churn': '⚠ 캐시 재빌드 빈발',
     '⚠ Input spike': '⚠ 입력 급증',
@@ -92,6 +93,9 @@ function chipKo(chip) {
  */
 function detailKo(detail) {
   if (!detail) return detail;
+  const m0 = detail.match(/^Single-request context exceeded 200k \(max (\d+)k tokens\)$/);
+  if (m0) return `단일 요청 컨텍스트 200k 초과 (최대 ${m0[1]}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 ([^:]+): (.+)$/);

package/src/installer.js

@@ -202,10 +202,47 @@ export function installStatusline({ force = false } = {}) {
   return { path: file, action: 'updated', reason: 'replaced previous statusLine' };
 }
 
+// Registers the SessionStart hook that surfaces route-scan delegation
+// candidates as session context (startup + /clear). Idempotent: skips when a
+// claude-token-saver route-scan hook is already present; never touches other
+// hooks the user configured.
+const ROUTE_SCAN_HOOK_COMMAND = 'claude-token-saver route-scan --hook';
+
+export function installSessionStartHook() {
+  const dir = claudeUserDir();
+  const file = join(dir, 'settings.json');
+  mkdirSync(dir, { recursive: true });
+
+  let settings = {};
+  if (existsSync(file)) {
+    try {
+      settings = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (e) {
+      return { path: file, action: 'skipped', reason: `unreadable JSON (${e.message})` };
+    }
+  }
+
+  settings.hooks = settings.hooks || {};
+  const list = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : [];
+  const already = list.some((m) =>
+    Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('route-scan --hook')),
+  );
+  if (already) return { path: file, action: 'exists' };
+
+  list.push({
+    matcher: 'startup|clear',
+    hooks: [{ type: 'command', command: ROUTE_SCAN_HOOK_COMMAND, timeout: 10 }],
+  });
+  settings.hooks.SessionStart = list;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { path: file, action: 'created' };
+}
+
 export function installAll({ force = false } = {}) {
   return {
     skill: installSkill({ force }),
     statusline: installStatusline({ force }),
+    sessionStartHook: installSessionStartHook(),
     legacy: removeLegacyCommand(),
   };
 }