sprag-cli 3.42.8 → 3.44.0

package/bin/cli.js

@@ -209,7 +209,7 @@ async function main() {
   //   sprag route-scan --hook          # SessionStart hook mode (context injection)
   //   sprag route-scan dismiss <N>     # mute candidate R<N>
   // Promote a candidate to a ratchet rule (scope is always explicit):
-  //   sprag harness promote R<N> --project|--global
+  //   sprag harness promote R<N> --global|--project
   // 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.
@@ -292,10 +292,12 @@ async function main() {
   }
 
   // Subcommand: litellm-budget · LiteLLM 게이트웨이 키의 max_budget/spend 조회.
-  //   sprag litellm-budget            # 캐시된 예산 상태 출력
+  //   sprag litellm-budget            # 캐시된 예산을 게이지·금액으로 출력
+  //   sprag litellm-budget --json     # 캐시 원본 JSON 출력
   //   sprag litellm-budget --refresh  # 지금 프록시에 물어봄 (detached 자식이 사용)
   if (args[0] === 'litellm-budget') {
-    const { gatewayEnv, readBudgetState, refreshBudgetState } = await import('../src/litellm-budget.js');
+    const { gatewayBase, readBudgetState, refreshBudgetState, formatBudgetReport } =
+      await import('../src/litellm-budget.js');
     const quiet = hasFlag('--quiet');
     if (hasFlag('--refresh')) {
       try {
@@ -308,12 +310,22 @@ async function main() {
       }
       return;
     }
-    const gw = gatewayEnv();
-    if (!gw) {
-      console.log('게이트웨이가 감지되지 않았습니다 (ANTHROPIC_BASE_URL + 키 필요).');
+    // 읽기 경로는 캐시만 보므로 키를 요구하지 않습니다 (apiKeyHelper 환경 배려).
+    const base = gatewayBase();
+    if (!base) {
+      console.log('게이트웨이가 감지되지 않았습니다 (ANTHROPIC_BASE_URL 필요).');
       return;
     }
-    console.log(JSON.stringify(readBudgetState(), null, 2));
+    const state = readBudgetState();
+    if (hasFlag('--json')) {
+      console.log(JSON.stringify(state, null, 2));
+      return;
+    }
+    if (state.base !== base || state.maxBudget === undefined) {
+      console.log('예산 캐시가 비어 있습니다. `sprag litellm-budget --refresh` 로 먼저 조회하십시오.');
+      return;
+    }
+    for (const line of formatBudgetReport(state)) console.log(line);
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.42.8",
+  "version": "3.44.0",
   "description": "Sprag - a quality ratchet harness for AI coding agents: model-fitting delegation, ratchet rules, doc2md, Korean style gate. Same tool as claude-token-saver, under its new name.",
   "type": "module",
   "bin": {

package/presets/ratchet-rules.json

@@ -15,8 +15,8 @@
       "en": "When a web fetch/search is blocked by robots or user-agent checks ('unable to fetch' and similar) → retry with curl carrying a browser UA header (Mozilla/5.0 ... Chrome/...). Sites like reddit also answer on their .json endpoints with that UA"
     },
     {
-      "ko": "ratchet 룰 promote 호출 직전 사용자에게 scope(project/global)를 먼저 묻는다 — Bash 환경은 non-TTY라 CLI readline 프롬프트가 안 뜨므로, 호출자(LLM)가 대신 묻고 --project/--global 플래그를 명시해 실행",
-      "en": "Ask the user for the scope (project or global) before calling ratchet promote — the Bash environment is non-TTY, so the CLI's readline prompt never appears; the caller (the model) has to ask and pass --project/--global explicitly"
+      "ko": "ratchet 룰 promote 호출 직전 사용자에게 scope(global/project)를 먼저 묻는다 — Bash 환경은 non-TTY라 CLI readline 프롬프트가 안 뜨므로, 호출자(LLM)가 대신 묻고 --global/--project 플래그를 명시해 실행",
+      "en": "Ask the user for the scope (global or project) before calling ratchet promote — the Bash environment is non-TTY, so the CLI's readline prompt never appears; the caller (the model) has to ask and pass --global/--project explicitly"
     },
     {
       "ko": "자동화 도구가 grep·정규식으로 찾는 마커 텍스트(헤더·앵커·키워드 라인)는 리팩터링·압축·수정 금지 — 정확 매칭 검출은 한 글자만 바뀌어도 깨짐",

package/src/brief.js

@@ -226,7 +226,7 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
     }
     for (const [kind, x] of fresh) {
       items.push(kind === 'route'
-        ? `새 위임 후보가 감지되었습니다 — "${x.label}" 유형 ${x.count}회 반복(statusline의 route? R${x.id} 칩). 등록: sprag harness promote R${x.id} --project|--global (적용 범위는 사용자에게 확인) / 무시: route-scan dismiss ${x.id}`
+        ? `새 위임 후보가 감지되었습니다 — "${x.label}" 유형 ${x.count}회 반복(statusline의 route? R${x.id} 칩). 등록: sprag harness promote R${x.id} --global|--project (적용 범위는 사용자에게 확인) / 무시: route-scan dismiss ${x.id}`
         : `승인된 위임 룰의 최근 에러율이 기준(20%)을 넘었습니다 — "${x.label}" (${x.healthSource === 'delegated' ? `위임 실행 ${x.delegatedRuns}건 중 에러율 ${Math.round((x.delegatedErrRate || 0) * 100)}%` : `유사 에피소드 기준 에러율 ${Math.round((x.errRate || 0) * 100)}%`}, statusline의 rule-health 칩). 조건 좁히기/제거를 사용자와 상의하세요: sprag route-scan rules`);
     }
     s.briefed = [...briefed];

package/src/commands/brief.js

@@ -7,7 +7,7 @@
  *   sprag route-scan --hook          # SessionStart hook mode (context injection)
  *   sprag route-scan dismiss <N>     # mute candidate R<N>
  * Promote a candidate to a ratchet rule (scope is always explicit):
- *   sprag harness promote R<N> --project|--global
+ *   sprag harness promote R<N> --global|--project
  * 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.

package/src/commands/route-scan.js

@@ -356,11 +356,11 @@ export async function run({ args, hasFlag, numArg }) {
         }
         if (lang === 'ko') {
           lines.push('등록하면 다음 세션부터 자동 위임됩니다. 사용자에게 등록 여부를 물을 때 위 룰 원문을 그대로 보여주고, 적용 범위까지 확인한 뒤 실행하세요:');
-          lines.push('  sprag harness promote R<N> --project|--global   # 적용 범위는 반드시 사용자에게 확인');
+          lines.push('  sprag harness promote R<N> --global|--project   # 적용 범위는 반드시 사용자에게 확인');
           lines.push('  sprag 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('  sprag harness promote R<N> --project|--global   # ALWAYS confirm the scope with the user first');
+          lines.push('  sprag harness promote R<N> --global|--project   # ALWAYS confirm the scope with the user first');
           lines.push('  sprag route-scan dismiss <N>                    # if they do not want it');
         }
       }
@@ -446,7 +446,7 @@ export async function run({ args, hasFlag, numArg }) {
     }
     console.log('');
     console.log(lang === 'ko' ? '등록 / 무시:' : 'Promote / dismiss:');
-    console.log('  sprag harness promote R<N> --project|--global');
+    console.log('  sprag harness promote R<N> --global|--project');
     console.log('  sprag route-scan dismiss <N>');
     // 최초 1회만 — 매번 찍으면 도구가 광고판이 된다 (CTS_NO_NOTE=1 로 끔)
     (await import('../first-run-note.js')).printOnce('route-scan', lang);

package/src/commands/upgrade.js

@@ -25,7 +25,8 @@ function runCommand(cmd) {
 }
 
 export async function run({ hasFlag, version }) {
-  const { updateStatus, refreshUpdateState, upgradeCommand } = await import('../update-check.js');
+  const { updateStatus, refreshUpdateState, upgradeCommand, INSTALLED_UNDER_LEGACY_NAME } =
+    await import('../update-check.js');
   const { userLanguage } = await import('../config.js');
   const lang = userLanguage();
   const cmd = upgradeCommand();
@@ -40,6 +41,25 @@ export async function run({ hasFlag, version }) {
   // network round trip is fine here.
   await refreshUpdateState(version);
   const s = updateStatus(version);
+  // A legacy-name copy has somewhere to go even on the newest version: the
+  // package was renamed, and only the new name keeps receiving releases.
+  if (!s.available && INSTALLED_UNDER_LEGACY_NAME) {
+    console.log(lang === 'ko'
+      ? `패키지 이름이 claude-token-saver 에서 sprag-cli 로 바뀌었습니다. 버전은 최신(v${version})이지만, 앞으로의 릴리스를 계속 받으려면 새 이름으로 옮겨야 합니다.`
+      : `The package was renamed from claude-token-saver to sprag-cli. You are on the latest version (v${version}), but future releases only ship under the new name.`);
+    console.log(`$ ${cmd}`);
+    const migrateCode = await runCommand(cmd);
+    if (migrateCode !== 0) {
+      console.error(lang === 'ko'
+        ? `이전 명령이 종료 코드 ${migrateCode}로 실패했습니다. 위 출력을 확인하십시오.`
+        : `Migration command failed with exit code ${migrateCode}. Check the output above.`);
+      process.exit(migrateCode);
+    }
+    console.log(lang === 'ko'
+      ? '이전이 끝났습니다. 새 셸에서 sprag --version 으로 확인하십시오.'
+      : 'Migration done. Confirm with sprag --version in a fresh shell.');
+    return;
+  }
   if (!s.available) {
     console.log(lang === 'ko'
       ? `이미 최신 버전입니다 (v${version}). 설치할 것이 없습니다.`
@@ -48,8 +68,12 @@ export async function run({ hasFlag, version }) {
   }
 
   console.log(lang === 'ko'
-    ? `v${version} → ${s.latest} 로 업그레이드합니다.`
-    : `Upgrading v${version} → ${s.latest}.`);
+    ? (INSTALLED_UNDER_LEGACY_NAME
+      ? `v${version} → ${s.latest} 로 업그레이드하면서 새 패키지 이름(sprag-cli)으로 함께 옮깁니다.`
+      : `v${version} → ${s.latest} 로 업그레이드합니다.`)
+    : (INSTALLED_UNDER_LEGACY_NAME
+      ? `Upgrading v${version} → ${s.latest} and moving to the new package name (sprag-cli).`
+      : `Upgrading v${version} → ${s.latest}.`));
   console.log(`$ ${cmd}`);
   const code = await runCommand(cmd);
   if (code !== 0) {

package/src/formatters/statusline.js

@@ -50,7 +50,7 @@ const MAGENTA = fg(167, 139, 250, '\x1b[35m');
 const GRAY = fg(100, 116, 139, '\x1b[90m');
 const BOLD = '\x1b[1m';
 
-function formatMoney(usd) {
+export function formatMoney(usd) {
   // Boundaries sit at 999.5/999500 so a value that would round up into the
   // next band's width ($999.9 → "$1000") jumps to that band's unit instead —
   // otherwise "$1000" renders visually larger than "$1.0K".
@@ -81,7 +81,7 @@ function formatPct(v) {
  * for ~4% effective precision around the fill edge. Stable monospace width
  * across all terminal fonts that ship Block Elements (U+2580–U+259F).
  */
-function gaugeBar(pct) {
+export function gaugeBar(pct) {
   const cells = 6;
   const clamped = Math.max(0, Math.min(100, pct));
   const filled = (clamped / 100) * cells; // e.g. 4.32 cells filled
@@ -640,15 +640,19 @@ export function formatReport(data, { color = true, verbose = false, timer = true
       Number.isFinite(info.maxBudget) && info.maxBudget > 0
         ? ` ${formatMoney(Number(info.spend) || 0)}/${formatMoney(info.maxBudget)}`
         : '';
+    // LiteLLM 의 internal user 한도는 차단 판정에 쓰이는 값이 아니라서, 팀
+    // 멤버십 한도와 수백 배 어긋나는 배포가 있습니다. 그 한도로 그린 게이지는
+    // 출처를 밝혀 두어야 사용자가 정확한 값으로 오해하지 않습니다.
+    const src = info.source === 'user' ? ' (user)' : '';
     if (isIcon) {
-      const labelPart = labels.usageLabel ? `${labels.usageLabel} ` : '';
+      const labelPart = labels.usageLabel ? `${labels.usageLabel}${src} ` : '';
       const bar = gaugeBar(pct);
       return `${c(tone)}${labels.icon} ${labelPart}${bar} ${pct}%${money}${tail}${c(RESET)}`;
     }
     if (verbose) {
-      return `${c(tone)}${labels.short} cap ${pct}% used${money}${tail}${c(RESET)}`;
+      return `${c(tone)}${labels.short}${src} cap ${pct}% used${money}${tail}${c(RESET)}`;
     }
-    return `${c(tone)}${labels.short} cap ${pct}%${money}${tail}${c(RESET)}`;
+    return `${c(tone)}${labels.short}${src} cap ${pct}%${money}${tail}${c(RESET)}`;
   }
   // Color tone: green <70%, yellow 70-89%, red 90+% (a 90+% window only
   // renders here when a *different* window won the cap-warn chip slot).

package/src/harness-templates.js

@@ -60,9 +60,10 @@ ${HARNESS_SECTIONS[0].heading}
 - 같은 에러·오해·반복 작업이 한 번 더 발생하면 즉시 \`.claude/ratchet.md\`에
   "조건 → 행동" 한 줄로 룰 추가.
 - sprag가 후보를 감지하면 statusline에 \`🅷⚠ ratchet?\`로 알림.
-  \`sprag harness promote "<rule>" --project|--global\`로 승인.
-- **scope는 항상 사용자에게 먼저 물어볼 것** — 프로젝트 한정이면 \`--project\`,
-  도구·환경 일반 룰이면 \`--global\`(\`~/.claude/ratchet.md\`). Bash 환경은
+  \`sprag harness promote "<rule>" --global|--project\`로 승인.
+- **scope는 항상 사용자에게 먼저 물어볼 것.** 선택지는 글로벌을 먼저 제시한다.
+  도구·환경 일반 룰이면 \`--global\`(\`~/.claude/ratchet.md\`), 프로젝트 한정이면
+  \`--project\`. Bash 환경은
   non-TTY라 CLI의 readline 프롬프트가 안 뜨므로, 호출자(LLM)가 직접 묻고
   플래그를 명시해야 함. 묻지 않고 기본값으로 등록하지 말 것.
 - 승인된 룰은 이 블록 맨 아래 \`@\` import로 매 세션 로드된다 — 그 import 라인을
@@ -109,7 +110,7 @@ ${HARNESS_SECTIONS[4].heading}
 
 📌 운영:
 - \`sprag harness check\` — 현재 셋업 점수
-- \`sprag harness promote "<룰>" --project|--global\` — ratchet에 룰 추가 (scope는 사용자에게 먼저 물어볼 것)
+- \`sprag harness promote "<룰>" --global|--project\` — ratchet에 룰 추가 (scope는 사용자에게 먼저 물어볼 것)
 - \`sprag harness off\` — statusline 표시 끄기
 
 ---

package/src/litellm-budget.js

@@ -18,9 +18,12 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { spawn } from 'node:child_process';
+import { spawn, execSync } from 'node:child_process';
 import { join } from 'node:path';
+import { homedir } from 'node:os';
 import { userDataDir } from './paths.js';
+import { gaugeBar, formatMoney } from './formatters/statusline.js';
+import { formatResetClock } from './format-time.js';
 import { cliEntryPath } from './update-check.js';
 import { debug } from './debug.js';
 
@@ -28,22 +31,79 @@ import { debug } from './debug.js';
 // 통계선 렌더(수 초 간격)가 프록시를 두들기지 않습니다.
 const CHECK_INTERVAL_MS = 5 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 5000;
+const HELPER_TIMEOUT_MS = 10000;
 
 export function budgetStatePath() {
   return join(userDataDir(), 'litellm-budget.json');
 }
 
-/** 게이트웨이 환경 정보. 감지되지 않으면 null. */
-export function gatewayEnv(env = process.env) {
+/**
+ * 게이트웨이 주소만 판정합니다. 캐시만 읽는 경로는 키가 필요하지 않으므로,
+ * 키 확보와 주소 판정을 분리해 둡니다. apiKeyHelper 로만 인증하는 환경에는
+ * 환경변수에 토큰이 없어서, 키를 함께 요구하면 렌더 경로가 통째로 탈락합니다.
+ */
+export function gatewayBase(env = process.env) {
   const base = (env.ANTHROPIC_BASE_URL || '').trim().replace(/\/+$/, '');
   if (!base) return null;
   // 공식 엔드포인트를 그대로 가리키면 게이트웨이가 아닙니다.
   if (/^https?:\/\/api\.anthropic\.com/i.test(base)) return null;
-  const key = (env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || '').trim();
+  return base;
+}
+
+/** 게이트웨이 주소와 키를 함께 돌려줍니다. 둘 중 하나라도 없으면 null. */
+export function gatewayEnv(env = process.env) {
+  const base = gatewayBase(env);
+  if (!base) return null;
+  const key = resolveKey(env);
   if (!key) return null;
   return { base, key };
 }
 
+/**
+ * Claude Code 와 같은 방식으로 apiKeyHelper 를 실행해 토큰을 얻습니다.
+ * 환경변수에 토큰을 두지 않고 헬퍼 스크립트로 매번 발급받는 구성이 공식 인증
+ * 방식 가운데 하나이며, 그 구성에서는 statusline 자식 프로세스의 process.env
+ * 안에 토큰이 존재하지 않습니다.
+ *
+ * 헬퍼 실행은 비용이 있으므로 갱신 경로(5분에 한 번 뜨는 detached 자식)에서만
+ * 부릅니다. 수 초 간격으로 도는 렌더 경로에서 부르면 통계선이 그만큼 느려집니다.
+ */
+export function keyFromApiKeyHelper(cwd = process.cwd()) {
+  const candidates = [
+    join(cwd, '.claude', 'settings.local.json'),
+    join(cwd, '.claude', 'settings.json'),
+    join(homedir(), '.claude', 'settings.json'),
+  ];
+  for (const p of candidates) {
+    let helper;
+    try {
+      helper = JSON.parse(readFileSync(p, 'utf8'))?.apiKeyHelper;
+    } catch {
+      continue;
+    }
+    if (typeof helper !== 'string' || !helper.trim()) continue;
+    try {
+      const out = execSync(helper, {
+        encoding: 'utf8',
+        timeout: HELPER_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      // 진행 로그를 함께 출력하는 헬퍼가 있으므로 마지막 비어 있지 않은 줄을 취합니다.
+      const token = out.trim().split(/\r?\n/).filter(Boolean).pop();
+      if (token) return token.trim();
+    } catch (e) {
+      debug('litellm-budget:helper', e);
+    }
+  }
+  return null;
+}
+
+/** 환경변수 토큰을 먼저 보고, 없으면 apiKeyHelper 로 내려갑니다. */
+export function resolveKey(env = process.env) {
+  const direct = (env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || '').trim();
+  return direct || keyFromApiKeyHelper();
+}
+
 export function readBudgetState() {
   try {
     const s = JSON.parse(readFileSync(budgetStatePath(), 'utf8'));
@@ -67,11 +127,11 @@ function writeBudgetState(next) {
  *            spend:number, maxBudget:number}|null}
  */
 export function budgetWindow(env = process.env) {
-  const gw = gatewayEnv(env);
-  if (!gw) return null;
+  const base = gatewayBase(env);
+  if (!base) return null;
   const s = readBudgetState();
   // 다른 프록시의 캐시를 재사용하지 않도록 base 단위로 격리합니다.
-  if (s.base !== gw.base) return null;
+  if (s.base !== base) return null;
   const max = Number(s.maxBudget);
   const spend = Number(s.spend);
   if (!Number.isFinite(max) || max <= 0 || !Number.isFinite(spend)) return null;
@@ -84,19 +144,66 @@ export function budgetWindow(env = process.env) {
     resetsAt: resetMs ? Math.round(resetMs / 1000) : null,
     spend,
     maxBudget: max,
+    // 렌더러가 출처를 함께 보여 줄 수 있도록 싣습니다. internal user 한도는
+    // LiteLLM 이 차단 판정에 쓰는 값이 아니라서 그대로 보여 주면 오해를 부릅니다.
+    source: typeof s.source === 'string' ? s.source : null,
   };
 }
 
+/**
+ * `sprag litellm-budget` 이 출력하는 사람용 보고서입니다. 통계선의 cap 게이지와
+ * 같은 모양(비주얼 바 + 백분율 + 금액)을 쓰되, 통계선에서는 폭이 부족해 생략하는
+ * 잔여 금액과 예산 출처, 캐시 신선도를 함께 적습니다.
+ *
+ * @param {object} state - readBudgetState() 가 돌려준 캐시 상태
+ * @param {Date} [now]
+ * @returns {string[]} 출력할 줄들
+ */
+export function formatBudgetReport(state, now = new Date()) {
+  const max = Number(state?.maxBudget);
+  const spend = Number(state?.spend);
+  if (!Number.isFinite(max) || max <= 0) {
+    const spent = Number.isFinite(spend) ? formatMoney(spend) : '알 수 없음';
+    return [`예산 한도가 설정되지 않은 키입니다 (무제한). 누적 지출: ${spent}`];
+  }
+  const used = Number.isFinite(spend) ? Math.max(0, spend) : 0;
+  const left = Math.max(0, max - used);
+  const pct = Math.min(100, (used / max) * 100);
+  const lines = [
+    `🔑 budget ${gaugeBar(pct)} ${Math.round(pct)}% ${formatMoney(used)}/${formatMoney(max)}`,
+    `   사용 ${formatMoney(used)} · 잔여 ${formatMoney(left)} (${(100 - pct).toFixed(1)}%)`,
+  ];
+  const resetMs = Number(state?.budgetResetAt);
+  if (Number.isFinite(resetMs) && resetMs > 0) {
+    const clock = formatResetClock(Math.round(resetMs / 1000), now);
+    if (clock) lines.push(`   리셋 ${clock}`);
+  }
+  const labels = { team: '팀 멤버십 예산', key: '키 예산', user: '사용자 예산' };
+  if (state?.source) lines.push(`   출처 ${labels[state.source] || state.source}`);
+  if (state?.source === 'user') {
+    // LiteLLM 은 팀 멤버십 한도로 차단 여부를 판정하므로, 사용자 한도만 잡힌
+    // 상태에서는 실제 한도와 크게 어긋날 수 있습니다.
+    lines.push('   주의: 사용자 한도는 차단 판정 기준과 다를 수 있습니다.');
+  }
+  const checkedAt = Number(state?.checkedAt);
+  if (Number.isFinite(checkedAt) && checkedAt > 0) {
+    const ageMin = Math.max(0, Math.round((now.getTime() - checkedAt) / 60000));
+    lines.push(`   조회 ${ageMin}분 전`);
+  }
+  return lines;
+}
+
 /** 캐시가 오래됐으면 detached 자식으로 갱신을 예약합니다. 즉시 반환. */
 export function maybeSpawnBudgetCheck(env = process.env) {
-  const gw = gatewayEnv(env);
-  if (!gw) return false;
+  // 키 확보는 자식이 담당합니다. 렌더 경로에서 헬퍼를 돌리면 통계선이 느려집니다.
+  const base = gatewayBase(env);
+  if (!base) return false;
   const s = readBudgetState();
   const age = Date.now() - (Number(s.checkedAt) || 0);
-  if (s.base === gw.base && age < CHECK_INTERVAL_MS) return false;
+  if (s.base === base && age < CHECK_INTERVAL_MS) return false;
   // 오프라인/오류 시 렌더마다 자식을 다시 띄우지 않도록 시도 시각을 먼저 기록합니다.
   try {
-    writeBudgetState({ ...s, base: gw.base, checkedAt: Date.now() });
+    writeBudgetState({ ...s, base, checkedAt: Date.now() });
   } catch (e) {
     debug('litellm-budget:stamp', e);
     return false;
@@ -135,7 +242,10 @@ function parseResetMs(v) {
  *            budgetResetAt:number|null}|null}
  */
 export function pickBudgetSource(keyInfo, userInfo) {
-  const userId = keyInfo?.user_id ?? null;
+  // /key/info 가 404 인 게이트웨이(커스텀 인증)에서는 keyInfo 가 비므로,
+  // /user/info 가 함께 주는 내 user_id 를 폴백으로 씁니다. 이 폴백이 없으면
+  // 팀 전체 멤버십을 돌려주는 배포에서 남의 예산을 집을 수 있습니다.
+  const userId = keyInfo?.user_id ?? userInfo?.user_info?.user_id ?? null;
   const teamId = keyInfo?.team_id ?? null;
   // ① 팀 멤버십 예산: 키의 team_id 에 해당하는 팀에서 내 user_id 의 멤버십을 찾는다.
   const teams = Array.isArray(userInfo?.teams) ? userInfo.teams : [];
@@ -184,34 +294,48 @@ export function pickBudgetSource(keyInfo, userInfo) {
  * /key/info(키·소속 식별)와 /user/info(팀 멤버십 예산)를 함께 조회합니다.
  */
 export async function refreshBudgetState(env = process.env, fetchImpl = fetch) {
-  const gw = gatewayEnv(env);
-  if (!gw) return null;
+  const base = gatewayBase(env);
+  if (!base) return null;
+  const key = resolveKey(env);
+  if (!key) return null;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   const headers = {
     accept: 'application/json',
-    authorization: `Bearer ${gw.key}`,
+    authorization: `Bearer ${key}`,
   };
   try {
-    const keyRes = await fetchImpl(`${gw.base}/key/info`, { signal: controller.signal, headers });
-    if (!keyRes.ok) throw new Error(`LiteLLM responded ${keyRes.status}`);
-    const keyBody = await keyRes.json();
-    const keyInfo = keyBody && typeof keyBody.info === 'object' ? keyBody.info : null;
-    if (!keyInfo) throw new Error('key/info response carried no info object');
-    // /user/info 는 팀 멤버십 예산 전용이라 실패해도 키 예산 폴백으로 진행한다.
+    // /key/info 는 커스텀 인증(JWT)을 쓰는 배포에서 404 가 정상입니다. 발급된
+    // 토큰에 해당하는 행이 LiteLLM_VerificationToken 에 없기 때문입니다. 예산
+    // 자체는 /user/info 에 있으므로, 여기서 중단하면 안 됩니다.
+    let keyInfo = null;
+    try {
+      const keyRes = await fetchImpl(`${base}/key/info`, { signal: controller.signal, headers });
+      if (keyRes.ok) {
+        const keyBody = await keyRes.json();
+        if (keyBody && typeof keyBody.info === 'object') keyInfo = keyBody.info;
+      } else {
+        debug('litellm-budget:key-info', new Error(`LiteLLM responded ${keyRes.status}`));
+      }
+    } catch (e) {
+      debug('litellm-budget:key-info', e);
+    }
     let userInfo = null;
     try {
-      const userRes = await fetchImpl(`${gw.base}/user/info`, { signal: controller.signal, headers });
+      const userRes = await fetchImpl(`${base}/user/info`, { signal: controller.signal, headers });
       if (userRes.ok) userInfo = await userRes.json();
+      else debug('litellm-budget:user-info', new Error(`LiteLLM responded ${userRes.status}`));
     } catch (e) {
       debug('litellm-budget:user-info', e);
     }
+    // 둘 다 받지 못했을 때만 실패로 봅니다.
+    if (!keyInfo && !userInfo) throw new Error('neither key/info nor user/info returned data');
     const picked = pickBudgetSource(keyInfo, userInfo);
     const next = {
-      base: gw.base,
+      base,
       checkedAt: Date.now(),
       source: picked ? picked.source : null,
-      spend: picked ? picked.spend : (numOrNull(keyInfo.spend) ?? 0),
+      spend: picked ? picked.spend : (numOrNull(keyInfo?.spend) ?? 0),
       maxBudget: picked ? picked.maxBudget : null,
       budgetResetAt: picked ? picked.budgetResetAt : null,
     };

package/src/route-scan.js

@@ -14,7 +14,7 @@
  *
  * Pipeline position (per design discussion): this scan is NOT a real-time
  * router — it is a session-boundary calibrator that feeds the existing
- * ratchet promote flow (`harness promote R<N> --project|--global`).
+ * ratchet promote flow (`harness promote R<N> --global|--project`).
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';

package/src/seed-rules.js

@@ -243,7 +243,9 @@ export function seedOfferBlock({ lang = userLanguage(), root = findProjectRoot()
   const lines = [];
   if (lang === 'ko') {
     lines.push(`[claude-token-saver seed] 아직 등록되지 않은 추천 룰이 ${pending.length}건 있습니다 (패키지 동봉 프리셋).`);
+    lines.push('**이 세션의 첫 응답에서 다른 작업보다 먼저 1번 룰의 등록 여부를 물어보십시오.** 사용자가 먼저 꺼낸 용건이 있으면 그 답변을 마친 직후에 이어서 묻고, 용건이 끝나기를 기다리지 마십시오. 사용자가 이 안내 문구에 대해 질문할 때까지 미루면 안 됩니다.');
     lines.push('사용자에게 **한 건씩 순서대로** 보여 주고 등록할지 물어보십시오. 한 번에 전체 등록을 권하지 말고, 답을 받은 뒤 바로 아래 명령을 실행하십시오.');
+    lines.push('적용 범위를 물을 때는 선택지를 **글로벌(모든 프로젝트)을 먼저, 이 프로젝트만을 그다음**으로 제시하십시오.');
     if (models.length > 0) {
       lines.push(`  · 모델 피팅 룰 ${models.length}건 — 등록하면 해당 유형 작업이 더 싼 서브에이전트로 위임됩니다.`);
       for (const s of models) {
@@ -260,7 +262,9 @@ export function seedOfferBlock({ lang = userLanguage(), root = findProjectRoot()
     lines.push('  (사용자가 "전부 등록"이라고 답하면 `seed accept all --global` 을 쓸 수 있습니다)');
   } else {
     lines.push(`[claude-token-saver seed] ${pending.length} recommended rule(s) from the bundled presets are not registered yet.`);
+    lines.push('**Ask about rule 1 in your very first reply of this session, before anything else.** If the user opened with their own request, answer it and then ask right away; do not wait for their task to finish, and never wait until they ask about this notice.');
     lines.push('Walk the user through them **one at a time** and ask about each. Do not push the whole set at once; run the matching command as soon as they answer.');
+    lines.push('When you ask about the scope, offer **global (all projects) first, this project only second**.');
     if (models.length > 0) {
       lines.push(`  · ${models.length} model-fitting rule(s) — once registered, that kind of work goes to a cheaper subagent.`);
       for (const s of models) {

package/src/update-check.js

@@ -23,10 +23,15 @@ import { fileURLToPath } from 'node:url';
 import { userDataDir } from './paths.js';
 import { debug } from './debug.js';
 
-// Whichever name this copy was installed under (sprag-cli or the legacy
-// claude-token-saver) is the one whose registry entry must be consulted.
+// This copy may be installed under the canonical name or under the legacy one.
+// Releases go out under the canonical name, so that is the entry the registry
+// check consults either way — a legacy copy must keep hearing about new
+// versions even after the legacy name stops receiving publishes.
 import { createRequire } from 'node:module';
 const PKG_NAME = createRequire(import.meta.url)('../package.json').name;
+const CANONICAL_NAME = 'sprag-cli';
+const LEGACY_NAME = 'claude-token-saver';
+const IS_LEGACY = PKG_NAME === LEGACY_NAME;
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h — the registry is not a health endpoint
 const FETCH_TIMEOUT_MS = 5000;
 
@@ -148,7 +153,7 @@ export async function refreshUpdateState(currentVersion) {
   try {
     // The `latest` dist-tag endpoint returns a few hundred bytes, unlike the
     // full packument which is megabytes for a package with this many releases.
-    const res = await fetch(`https://registry.npmjs.org/${PKG_NAME}/latest`, {
+    const res = await fetch(`https://registry.npmjs.org/${CANONICAL_NAME}/latest`, {
       signal: controller.signal,
       headers: { accept: 'application/json' },
     });
@@ -194,6 +199,15 @@ export function dismissUpdate(version) {
  */
 export function upgradeCommand() {
   const here = dirname(fileURLToPath(import.meta.url));
+  // A legacy copy upgrades by moving to the canonical name. Installing the new
+  // name alone would leave two copies fighting over the same `sprag` binary,
+  // so the old one comes off first.
+  if (IS_LEGACY) {
+    if (here.includes('/pnpm/')) return `pnpm remove -g ${LEGACY_NAME} && pnpm add -g ${CANONICAL_NAME}@latest`;
+    if (here.includes('/.bun/')) return `bun remove -g ${LEGACY_NAME} && bun add -g ${CANONICAL_NAME}@latest`;
+    if (here.includes('/.yarn/')) return `yarn global remove ${LEGACY_NAME} && yarn global add ${CANONICAL_NAME}@latest`;
+    return `npm uninstall -g ${LEGACY_NAME} && npm install -g ${CANONICAL_NAME}@latest`;
+  }
   if (here.includes('/pnpm/')) return `pnpm add -g ${PKG_NAME}@latest`;
   if (here.includes('/.bun/')) return `bun add -g ${PKG_NAME}@latest`;
   if (here.includes('/.yarn/')) return `yarn global add ${PKG_NAME}@latest`;
@@ -202,3 +216,6 @@ export function upgradeCommand() {
 
 export const UPDATE_CHECK_INTERVAL_MS = CHECK_INTERVAL_MS;
 export const PACKAGE_NAME = PKG_NAME;
+export const CANONICAL_PACKAGE_NAME = CANONICAL_NAME;
+/** True when this copy was installed under the legacy package name. */
+export const INSTALLED_UNDER_LEGACY_NAME = IS_LEGACY;