sprag-cli 3.68.0 → 3.69.0

package/README.ko.md

@@ -5,7 +5,7 @@
   <img alt="Sprag" src="https://raw.githubusercontent.com/rootstudioyaml/sprag/main/site/assets/logo/sprag-lockup-light.svg" width="220">
 </picture>
 
-**Claude Code와 Codex가 쓰는 토큰을 첫 세션부터 줄입니다**
+**Claude Code와 Codex에 붙이는 모델 위임 라우터. 조회·확인·테스트 실행은 더 싼 모델에 보내고, 아낀 금액은 상태줄에 보여 줍니다.**
 
 [![npm](https://img.shields.io/npm/v/sprag-cli.svg?label=sprag-cli)](https://www.npmjs.com/package/sprag-cli)
 [![downloads](https://img.shields.io/npm/dm/sprag-cli.svg)](https://www.npmjs.com/package/sprag-cli)
@@ -26,11 +26,11 @@
 
 ---
 
-**일하는 방식은 그대로 두고 토큰만 줄입니다.** 조회와 확인, 테스트 실행은 저렴한 모델에 넘기고, 문서는 가벼운 Markdown으로 바꿔 넣습니다(54만 토큰짜리 발표 자료가 2.3만 토큰이 됩니다). 세션마다 쓴 금액과 아낀 금액은 상태줄에 바로 나타납니다. `npm i -g sprag-cli` 하나로 설정이 끝나며, 프로젝트마다 따로 설정할 것은 없습니다.
+**Sprag는 일마다 그 일을 한 번도 틀린 적 없는 가장 싼 모델에게 보냅니다.** Claude Code와 Codex는 프롬프트마다 모델을 바꿀 수 없으므로, 통하는 방법 하나를 씁니다. 메인 세션의 규칙이 조회, 상태 확인, 빌드·테스트 실행, 일괄 수정을 더 싼 모델로 고정한 서브에이전트에 넘깁니다. 규칙은 사용자의 세션 기록에서 나오고 하나씩 승인을 받으며, 위임한 실행마다 가격 차액을 원장에 적습니다. `npm i -g sprag-cli` 하나로 설정이 끝나며, 프로젝트마다 따로 설정할 것은 없습니다.
 
-**에이전트는 그대로 일하고, 퇴행만 막습니다.** 이름은 스프래그 클러치에서 왔습니다. 앞으로 도는 힘은 그대로 통과시키고, 역회전하는 순간 잠기는 부품입니다.
+두 가지가 함께 따라옵니다. 문서는 가벼운 Markdown으로 바뀌어 컨텍스트에 들어가고(54만 토큰짜리 발표 자료가 2.3만 토큰이 됩니다), 상태줄은 세션마다 쓴 금액과 아낀 금액을 보여 주다가 캐시·컨텍스트·사용량 한도에 문제가 생기면 경고 칩을 맨 앞에 띄웁니다.
 
-Sprag는 Claude Code와 Codex가 남기는 세션 기록을 읽어 반복 실패와 위임 후보를 찾습니다. 사용자가 승인한 규칙은 다음 세션에도 적용하며, 위임 기록과 모델 단가를 확인할 수 있으면 예상 차액을 원장에 적습니다. 캐시와 사용량 한도 문제는 상태줄이나 패널에서 확인할 수 있습니다.
+이름은 스프래그 클러치에서 왔습니다. 앞으로 도는 힘은 통과시키고 역회전하는 순간 잠기는 부품입니다. 기록에서 반복되는 실패는 세션 시작 때 불러오는 규칙이 되어, 에이전트는 그대로 일하고 퇴행만 걸립니다.
 
 세션 분석은 로컬에서 실행하므로 추가 모델 호출이나 API 키가 필요하지 않습니다. Codex의 선택 기능인 예산·단가 조회는 기존 인증 정보로 사용자가 설정한 LiteLLM에 접속합니다. CLI는 Node.js 20 이상과 TOML 파서 하나를 사용합니다.
 

package/README.md

@@ -5,7 +5,7 @@
   <img alt="Sprag" src="https://raw.githubusercontent.com/rootstudioyaml/sprag/main/site/assets/logo/sprag-lockup-light.svg" width="220">
 </picture>
 
-**Cut the tokens Claude Code and Codex spend, from the first session.**
+**A model-delegation router for Claude Code and Codex: lookups, checks and test runs go to cheaper models, and the savings show up in your statusline.**
 
 [![npm](https://img.shields.io/npm/v/sprag-cli.svg?label=sprag-cli)](https://www.npmjs.com/package/sprag-cli)
 [![downloads](https://img.shields.io/npm/dm/sprag-cli.svg)](https://www.npmjs.com/package/sprag-cli)
@@ -26,20 +26,22 @@ Same 12 requests, two terminals: **$6.68 → $1.83 (−72.6%)** with Sprag.<br>
 
 ---
 
-**Sprag saves tokens without changing how you work.** Lookups, checks and test
-runs go to a cheaper model, documents reach the context as compact Markdown (a
-540k-token deck becomes 23k tokens), and the statusline shows what each session
-spent and saved while it runs. `npm i -g sprag-cli` sets it all up; nothing to
-configure per project.
+**Sprag routes each piece of work to the cheapest model that has never got it
+wrong.** Claude Code and Codex cannot switch models per prompt, so Sprag does it
+the one way that works: rules in the main session hand lookups, status checks,
+build and test runs and batch edits to sub-agents pinned to a cheaper model. The
+rules come from your own session logs, you approve each one, and every delegated
+run writes its price difference to a ledger. `npm i -g sprag-cli` sets it all
+up; nothing to configure per project.
 
-Sprag is named after the sprag clutch: forward motion passes, backspin locks.
-Your agent keeps working, it just stops regressing.
+Two more things ride along. Documents reach the context as compact Markdown (a
+540k-token deck becomes 23k tokens), and the statusline shows what each session
+spent and saved, with a warning chip in front when the cache, the context or a
+rate limit needs attention.
 
-It reads the sessions you already ran, and what it finds there holds for every
-session after. Repeated failures become rules loaded at session start. Work that
-a cheaper tier has never got wrong goes to a sub-agent on that tier, and every
-delegated run writes its own price difference to a ledger. Cache and rate-limit
-trouble reaches your statusline while you can still act on it.
+The name is the sprag clutch: forward motion passes, backspin locks. Repeated
+failures in your logs become rules loaded at session start, so the agent keeps
+working and only the regressions get caught.
 
 Session analysis runs locally on the logs Claude Code and Codex already write.
 No extra model calls or API key are needed for analysis. Optional Codex gateway

package/bin/cli.js

@@ -59,6 +59,7 @@ import { chipForIssues } from '../src/advice.js';
 import { debug } from '../src/debug.js';
 import { createArgs } from '../src/cli-args.js';
 import { readUpdateChip } from '../src/update-notice.js';
+import { readStarChip } from '../src/star-note.js';
 import { selectAgent } from '../src/agent.js';
 
 const selection = (() => {
@@ -940,6 +941,11 @@ async function main() {
     options: { days, windowHours, windowLabel, version: PKG_VERSION },
     // Cached-only; the background refresh it may trigger lands on a later render.
     update: format === 'statusline' ? readUpdateChip(PKG_VERSION) : null,
+    // The totals are already in hand above; passing them spares a second read of
+    // both ledgers on every render.
+    star: format === 'statusline'
+      ? readStarChip({ savedUsd: delegationSaved + (Number(doc2mdTotals?.total) || 0) })
+      : null,
     lastActivity,
     monthSpend: monthSpendInfo,
     modelShare,
@@ -998,8 +1004,29 @@ async function main() {
       singleLine: hasFlag('--single-line'),
     });
   } else {
+    // The first screen is the pitch: what share of recent work a cheaper model
+    // could take. The scan is local and writes only sprag's own cache file;
+    // --project skips it because the scan covers all projects, not one.
+    let routing = null;
+    if (!projectFilter && process.env.CTS_NO_ROUTE_SCAN !== '1') {
+      try {
+        const rs = await import('../src/route-scan.js');
+        let cache = rs.readRouteScan();
+        if (!cache) {
+          process.stderr.write('Scanning for delegation candidates (first run)...\n');
+          cache = await rs.runRouteScan({ days: 14 });
+        }
+        routing = {
+          days: cache.days,
+          total: cache.totalEpisodes,
+          easy: cache.easyEpisodes,
+          scannedAt: cache.scannedAt,
+          candidates: rs.openCandidates(cache).slice(0, 3),
+        };
+      } catch (e) { debug('report:routing', e); }
+    }
     const { formatReport } = await import('../src/formatters/table.js');
-    output = formatReport(data, { color: tableColor() });
+    output = formatReport({ ...data, routing }, { color: tableColor() });
   }
 
   if (format === 'statusline') {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sprag-cli",
-  "version": "3.68.0",
-  "description": "Cut Claude Code and Codex token costs: cheaper-model routing, compact Markdown for documents, and a live statusline of spend and savings.",
+  "version": "3.69.0",
+  "description": "Model-delegation router for Claude Code and Codex: lookups, checks and test runs go to cheaper models, documents go in as compact Markdown, and a live statusline shows spend and savings.",
   "type": "module",
   "bin": {
     "sprag": "bin/cli.js",
@@ -49,6 +49,10 @@
     "claude-code-statusline",
     "statusline",
     "model-routing",
+    "model-router",
+    "model-delegation",
+    "llm-router",
+    "claude-code-router",
     "subagent",
     "prompt-caching",
     "haiku",

package/src/delegation-agents.js

@@ -22,10 +22,19 @@ const MARK_LINE = `# managed by sprag (${OWNER_MARK}); edits are overwritten`;
 
 // Models are aliases on purpose: behind a gateway they resolve through
 // ANTHROPIC_DEFAULT_*_MODEL, and a full model id would bypass that mapping.
+//
+// Effort is a separate axis from the tier and is set by how the work gets
+// verified, not by how hard it is. Where the check is command output or a file
+// comparison (lookups, test runs, mechanical conversion) extra thinking buys
+// nothing, so those agents run at low. The worker implements a design the
+// caller already fixed, against tests, so it takes the default for well-specified
+// work, medium. The main session's effort is never touched here, and
+// CLAUDE_CODE_EFFORT_LEVEL must stay unset: it overrides every agent's own value.
 export const DEFINITIONS = [
   {
     name: 'haiku-explore',
     model: 'haiku',
+    effort: 'low',
     tools: 'Read, Grep, Glob, Bash',
     role: 'Your role: read-only exploration, lookups, status checks, and questions about pasted logs or text.',
     description: 'Cheap read-only exploration, lookup, status checks and summaries for delegated tasks. It has no MCP tools.',
@@ -33,6 +42,7 @@ export const DEFINITIONS = [
   {
     name: 'haiku-runner',
     model: 'haiku',
+    effort: 'low',
     tools: 'Bash, Read, Grep, Glob',
     role: 'Your role: run the build, test, or git commands you are given and report the result.',
     description: 'Cheap runner for build, test and git commands in delegated tasks. It has no MCP tools.',
@@ -40,6 +50,7 @@ export const DEFINITIONS = [
   {
     name: 'haiku-translate',
     model: 'haiku',
+    effort: 'low',
     tools: 'Read, Grep, Glob, Edit, Write',
     role: 'Your role: batch translation and mechanical text conversion of the files or text you are given.',
     description: 'Cheap batch translation and structured text conversion for delegated tasks. It has no MCP tools.',
@@ -47,6 +58,7 @@ export const DEFINITIONS = [
   {
     name: 'sonnet-worker',
     model: 'sonnet',
+    effort: 'medium',
     tools: 'Read, Grep, Glob, Bash, Edit, Write, NotebookEdit',
     role: 'Your role: multi-step work and the implementation half of a design the caller already fixed.',
     description: 'Mid-tier worker for multi-step tasks and implementation handed over with a fixed design. It has no MCP tools.',
@@ -60,6 +72,7 @@ function render(def) {
     `description: ${def.description}`,
     `tools: ${def.tools}`,
     `model: ${def.model}`,
+    `effort: ${def.effort}`,
     MARK_LINE,
     '---',
     def.role,

package/src/first-run-note.js

@@ -34,6 +34,22 @@ function markShown(key, now) {
   writeFileSync(firstRunStatePath(), JSON.stringify(state) + '\n');
 }
 
+/** When `key` was marked shown (epoch ms), or null. For notes that stay
+ *  visible for a window after the first time instead of printing once. */
+export function noteShownAt(key) {
+  const at = Number(load()[key]);
+  return Number.isFinite(at) && at > 0 ? at : null;
+}
+
+/** Persist `key` as shown at `now`. Best-effort, like `shouldShowOnce`. */
+export function markNoteShown(key, now = Date.now()) {
+  try {
+    markShown(key, now);
+  } catch {
+    /* state dir unwritable — the note may show again, never a failure */
+  }
+}
+
 /** True only the first time this key is asked about. Best-effort — a
  *  read-only state dir just means the note repeats, never that we crash. */
 export function shouldShowOnce(key, { now = Date.now() } = {}) {

package/src/formatters/statusline.js

@@ -28,6 +28,7 @@ import { MIN_VOTES } from '../model-alias.js';
 import { bedrockDisplayFromId } from '../stdin-payload.js';
 import { modelFamily } from '../savings-ledger.js';
 import { shareLegend } from '../model-share.js';
+import { STAR_URL } from '../star-note.js';
 
 // The 8-color ANSI defaults (RED=31, GREEN=32, YELLOW=33…) read as garish
 // next to each other — terminal palettes set them with unbalanced perceptual
@@ -1032,6 +1033,13 @@ function buildDelegatedSeg(data, singleLine, c, isIcon, verbose, g, color) {
   };
 }
 
+/** The one-time star ask (see star-note.js); null unless the CLI passed a chip. */
+function buildStarSeg(star, c, isIcon) {
+  if (!star || typeof star !== 'object' || !Number.isFinite(star.usd)) return null;
+  const text = `${isIcon ? '⭐ ' : ''}${formatMoney(star.usd)} saved · star ${STAR_URL}`;
+  return `${c(YELLOW)}${text}${c(RESET)}`;
+}
+
 /**
  * Doc2md chip and headline line. As with routing, they are alternatives: money
  * earns the headline line, and the chip is for what a line would be all frame
@@ -1142,6 +1150,8 @@ export const DEFAULT_SEGMENT_ORDER = [
   // Lifetime, from the savings ledgers. Delegation stays ahead of the cache
   // figure: routing is what the tool is for, the cache number is a brag stat.
   'delegated', 'doc2md',
+  // One-time star ask; renders only while readStarChip returns an object.
+  'star',
   // Analysis window. These two are the only chips measured over it, so the label
   // sits with them and the three render as one group.
   'hit', 'saved', 'period',
@@ -1182,6 +1192,7 @@ function segmentsNamed(name, s, usageByKey) {
     // the session's own subagent runs.
     case 'delegated': return [...s.delegated, s.subagents];
     case 'doc2md':    return s.doc2md;
+    case 'star':      return [s.star];
     case 'hit':       return [s.hit];
     case 'ttl':       return [s.ttl];
     case 'month':     return [s.month];
@@ -1287,7 +1298,7 @@ function buildHeadlines(delegated, doc2md, want, eol) {
  * @param {boolean} [opts.verbose=false] - longer layout with labels
  * @param {boolean} [opts.timer=true] - show TTL countdown segment
  * @param {'text'|'icon'} [opts.mode='text'] - label style. 'icon' uses 🧠 ⏳ 💰 instead of word labels.
- * @param {string[]|null} [opts.segments] - segments to render, in the order given. Names: cap-warn, spike, version, harness (a full score with no warning draws only when named here), korean (draws only when named here), model, effort, hit, ttl, month, saved, delegated, doc2md, ctx, period, `subagents` (this session's subagent runs; also rides with `delegated`), `rules` (only when named here), `usage` (every rate-limit window), plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. cap-warn and spike keep the lead regardless of where they appear. Null/undefined = all, in the default order.
+ * @param {string[]|null} [opts.segments] - segments to render, in the order given. Names: cap-warn, spike, version, harness (a full score with no warning draws only when named here), korean (draws only when named here), model, effort, hit, ttl, month, saved, delegated, doc2md, star, ctx, period, `subagents` (this session's subagent runs; also rides with `delegated`), `rules` (only when named here), `usage` (every rate-limit window), plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. cap-warn and spike keep the lead regardless of where they appear. Null/undefined = all, in the default order.
  * @param {boolean} [opts.singleLine=false] - force the legacy one-line layout. By default, when the delegation ledger has lifetime savings, the routing totals lead on their own first line and everything else moves to line 2 (Claude Code renders multi-line statuslines; `--single-line` is the escape hatch for terminals that only show the first line).
  */
 export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null, singleLine = false } = {}) {
@@ -1344,6 +1355,7 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     delegated: delegated.chips,
     // The inline chip steps aside when a headline line owns the story.
     doc2md: doc2md.headline ? [] : [doc2md.chip],
+    star: buildStarSeg(data.star, c, isIcon),
     // This session's subagent runs by model family. It is a session figure, so
     // it sits with the routing chips rather than with the lifetime totals.
     subagents: buildSessionDelegationSeg(data.sessionDelegation, c, isIcon, verbose, g),

package/src/formatters/table.js

@@ -181,17 +181,48 @@ function renderCapWarnSection(caps) {
   return lines;
 }
 
-export function formatReport({ summary: sum, trend, ttl, anomalies, cost, options, spikeReport, contextWindow, caps }, { color } = {}) {
+// Opens the report with what the tool is for, before any warning. A first run
+// (`npx sprag-cli`) has nothing installed yet, so the pitch has to be on screen.
+function renderRoutingSection(routing) {
+  if (!routing || typeof routing !== 'object') return [];
+  const lines = [];
+  lines.push(b(`  🔀 Routing — last ${routing.days}d`));
+  lines.push(`  ${'─'.repeat(50)}`);
+  const total = Number(routing.total) || 0;
+  if (total === 0) {
+    lines.push(`  No Claude Code sessions in the last ${routing.days} days to scan.`);
+    lines.push('');
+    return lines;
+  }
+  const easy = Number(routing.easy) || 0;
+  const pct = Math.round(easy / total * 100);
+  lines.push(`  ${easy} of ${total} requests (${pct}%) were lookups, checks or test runs a cheaper model handles.`);
+  const cands = Array.isArray(routing.candidates) ? routing.candidates : [];
+  if (cands.length === 0) {
+    lines.push('  No recurring delegable work yet (a pattern needs 3 repeats). Approved rules apply from the next session.');
+  } else {
+    for (const c of cands) {
+      lines.push(`  R${c.id}  "${c.labelEn || c.label}" ×${c.count}  →  delegate to ${c.agent}`);
+    }
+    lines.push(`  Approve one:  ${b(`${CLI_NAME} harness promote R${cands[0].id} --global`)}      All candidates:  ${b(`${CLI_NAME} route-scan`)}`);
+  }
+  lines.push('');
+  return lines;
+}
+
+export function formatReport({ summary: sum, trend, ttl, anomalies, cost, options, spikeReport, contextWindow, caps, routing }, { color } = {}) {
   colorOk = color ?? !process.env.NO_COLOR;
   const lines = [];
 
   // Header
   lines.push('');
-  lines.push(`  Claude Token Saver — Last ${options.days} day${options.days === 1 ? '' : 's'}`);
+  lines.push(`  Sprag — Last ${options.days} day${options.days === 1 ? '' : 's'}`);
   lines.push(`  (${CLI_NAME} v${options.version || ''})`.trimEnd());
   lines.push(`  ${'═'.repeat(50)}`);
   lines.push('');
 
+  lines.push(...renderRoutingSection(routing));
+
   // Cap warning leads — it's the most time-sensitive signal we can show.
   if (caps) {
     lines.push(...renderCapWarnSection(caps));

package/src/model-rules.js

@@ -272,13 +272,23 @@ export function renderModelRatchet(rules, lang = userLanguage(), { root } = {})
     '  알려 주는 작업은 하위 티어가 안전하다. 검증 게이트가 품질 하한이 된다.',
     '  틀려도 조용한 작업(진단, 근본 원인 판정, 보안, 설계)은 티어를 내리지',
     '  않는다. 싼 모델은 결정을 옮겨 적을 뿐, 결정을 내리지 못한다.',
+    '- **effort**: 모델 티어와 다른 축이다. 설치된 서브에이전트는 검증 형태에 따라',
+    '  effort가 고정되어 있다. 명령 출력이나 파일 대조로 검증되는 위임(조회·명령',
+    '  실행·정형 변환을 맡는 haiku 에이전트)은 low, 확정된 설계를 테스트에 맞춰',
+    '  구현하는 위임(sonnet 워커)은 medium이다. 메인 세션의 effort는 바꾸지 않고,',
+    '  CLAUDE_CODE_EFFORT_LEVEL은 서브에이전트의 effort를 덮어쓰므로 설정하지 않는다.',
     '- **위임 배치**: 서브에이전트 비용의 지배 항은 생성이 아니라 컨텍스트',
     '  적재다. 같은 파일들을 읽어야 하는 작업 여러 개는 에이전트 하나에 묶어',
     '  보내고, 읽는 영역이 다른 작업만 나눈다.',
     implementationDelegationRule('claude', lang),
     '- **에스컬레이션**: 같은 에러 2회 반복, 답이 복수 후보로 갈림, 서브에이전트가',
-    '  질문을 멈추고 헛도는 징후가 보이면 즉시 인계한다. 대응 순서는',
-    '  ① 재지시 후 재시도 → ② 한 티어 상향 → ③ 메인 모델이 직접 수습.',
+    '  질문을 멈추고 헛도는 징후가 보이면 즉시 인계한다. 어느 축을 올릴지는 실패',
+    '  종류로 정한다. 파일을 읽지 않았거나 테스트를 돌리지 않았거나 상한에 걸려',
+    '  멈춘 누락형 실패는 같은 모델에서 effort를 한 단계 올려 한 번만 재시도하고,',
+    '  컨텍스트를 다 보고도 틀린 오판형 실패는 모델을 한 티어 올린다. 순서는',
+    '  ① 재지시 후 재시도(누락형이면 effort 한 단계 위) → ② 한 티어 상향(오판형)',
+    '  → ③ 메인 모델이 직접 수습. effort를 올릴 때는 에이전트 파일을 고치지 않고',
+    '  Agent 도구 호출의 effort 인자에 한 단계 위 값(low → medium → high)을 넘긴다.',
     '',
     '## Rules',
     '',
@@ -323,14 +333,25 @@ export function renderModelRatchet(rules, lang = userLanguage(), { root } = {})
     '  the verification gate is the quality floor. Never drop the tier on work',
     '  that fails silently (diagnosis, root-cause calls, security posture,',
     '  design). Cheap models transcribe decisions; they do not make them.',
+    '- **Effort**: a separate axis from the tier. The installed subagents pin it',
+    '  by how their work is verified: low where the check is command output or a',
+    '  file comparison (the haiku agents for lookups, command runs and mechanical',
+    '  conversion), medium where a fixed design is implemented against tests (the',
+    '  sonnet worker). Leave the main session\'s effort alone, and never set',
+    '  CLAUDE_CODE_EFFORT_LEVEL: it overrides every subagent\'s own value.',
     '- **Batching**: a subagent\'s dominant cost is context ingestion, not',
     '  generation. Bundle tasks that read the same files into one agent; split',
     '  only when the areas they read differ.',
     implementationDelegationRule('claude', lang),
     '- **Escalation**: hand off immediately on the same error twice, an answer',
     '  splitting into multiple candidates, or a subagent spinning without asking',
-    '  questions. Order: ① re-instruct and retry → ② move up one tier → ③ the',
-    '  main model takes over directly.',
+    '  questions. Which axis moves depends on the failure: an omission (a file',
+    '  not read, tests not run, a cap hit mid-task) retries once on the same',
+    '  model one effort step up; a wrong answer with the full context in hand',
+    '  moves up one tier. Order: ① re-instruct and retry (effort +1 on an',
+    '  omission) → ② move up one tier (on a wrong answer) → ③ the main model',
+    '  takes over directly. To raise effort, pass the next level (low → medium →',
+    '  high) in the Agent call\'s effort argument instead of editing the agent file.',
     '',
     '## Rules',
     '',

package/src/star-note.js

@@ -0,0 +1,62 @@
+/**
+ * star-note — a one-time "star the repo" ask in the statusline.
+ *
+ * The package is downloaded thousands of times a month and starred a handful
+ * of times: all of the value lands in the statusline, so users never see the
+ * repository. This asks once, at the moment the value is visible — when the
+ * savings sprag itself produced (routing + doc2md) first reach $10.
+ *
+ * Once, because a chip that keeps asking is an advertisement. For 24 hours,
+ * which is long enough to be seen across a day of sessions and short enough
+ * not to linger. CTS_NO_NOTE=1 suppresses it, the same opt-out as every
+ * other one-time note.
+ */
+
+import { createRequire } from 'node:module';
+import { delegationSavedTotals } from './savings-ledger.js';
+import { noteShownAt, markNoteShown } from './first-run-note.js';
+import { userDataDir } from './paths.js';
+import { debug } from './debug.js';
+
+const require = createRequire(import.meta.url);
+
+export const STAR_THRESHOLD_USD = 10;
+export const STAR_WINDOW_MS = 24 * 60 * 60 * 1000;
+export const STAR_URL = 'github.com/rootstudioyaml/sprag';
+
+/** Lifetime dollars saved by routing and doc2md; an unreadable ledger counts as 0. */
+export function toolSavedUsd(now = Date.now(), dir = userDataDir()) {
+  let total = 0;
+  try {
+    total += Number(delegationSavedTotals(now, dir).total) || 0;
+  } catch (e) {
+    debug('star-note:routing', e);
+  }
+  try {
+    total += Number(require('./doc2md-ledger.cjs').doc2mdSavedTotals(dir).total) || 0;
+  } catch (e) {
+    debug('star-note:doc2md', e);
+  }
+  return total;
+}
+
+/** `{ usd, shownAt }` while the chip should show, else null. Never throws. */
+export function readStarChip({ now = Date.now(), dir = userDataDir(), savedUsd } = {}) {
+  try {
+    if (process.env.CTS_NO_NOTE === '1') return null;
+    const shownAt = noteShownAt('star');
+    if (shownAt === null) {
+      const usd = savedUsd ?? toolSavedUsd(now, dir);
+      if (!(usd >= STAR_THRESHOLD_USD)) return null;
+      markNoteShown('star', now);
+      return { usd, shownAt: now };
+    }
+    if (now - shownAt < STAR_WINDOW_MS) {
+      return { usd: savedUsd ?? toolSavedUsd(now, dir), shownAt };
+    }
+    return null;
+  } catch (e) {
+    debug('star-note', e);
+    return null;
+  }
+}

package/src/changelog.js

@@ -1,70 +0,0 @@
-/**
- * changelog — read one version's section out of CHANGELOG.md, and say whether a
- * notes draft is still waiting on a person.
- *
- * Separate from scripts/release-notes.mjs, which is a CLI: importing that file
- * runs its argument parsing and exits, so the extraction it depends on cannot be
- * tested through it. The boundary logic is the part worth pinning — a section
- * pulled one line short drops the release's last item, and one line long carries
- * the previous release's first, and the upgrade offer shows either without
- * complaint.
- *
- * The draft marker lives here for a reason. Two scripts gate on it — the one that
- * writes drafts and the one that deploys — and they used to carry the string
- * separately. Renaming it in one left the other looking for text that no longer
- * existed, and a gate that greps for an absent string does not fail: it passes,
- * and an unreviewed draft goes out as the release. One definition, imported.
- */
-
-/**
- * The body of one version's section, heading excluded.
- *
- * @param {string} changelog - CHANGELOG.md contents
- * @param {string} version - e.g. "3.45.0"
- * @returns {string|null} the section text, or null when that version has none
- */
-export function sectionFor(changelog, version) {
-  const lines = String(changelog).split(/\r?\n/);
-  // The version has to match to its end: without the boundary, "3.42.0" would
-  // also match the "### v3.42.7" heading and publish the wrong notes.
-  const head = new RegExp(`^### v${String(version).replace(/\./g, '\\.')}(\\s|$|\\()`);
-  const start = lines.findIndex((l) => head.test(l));
-  if (start < 0) return null;
-  const out = [];
-  for (let i = start + 1; i < lines.length; i += 1) {
-    // The next version heading ends this section, and so does a shallower one:
-    // "## All releases" is a container, not part of any release.
-    if (/^### v/.test(lines[i]) || /^## /.test(lines[i])) break;
-    out.push(lines[i]);
-  }
-  return out.join('\n').trim();
-}
-
-/**
- * The line `release-notes.mjs` writes at the top of a fresh draft, and the line
- * every gate refuses on. A draft still carrying it has not been through a person.
- */
-export const DRAFT_MARKER =
-  '<!-- REVIEW: edit this draft, add the English half, then delete this line -->';
-
-/** Heading that opens the Korean half of a bilingual release body. */
-export const KO_HEADING = '## 한국어';
-
-/**
- * The opening of the marker, which is what the gate actually matches. Spelled out
- * rather than sliced off `DRAFT_MARKER`, so that editing the marker's front does
- * not silently change what is being tested for.
- */
-const REVIEW_OPENING = '<!-- REVIEW:';
-
-/**
- * Whether a draft still needs review. Matches on the `<!-- REVIEW:` opening
- * rather than the whole line, so editing the wording of the instruction does not
- * quietly disarm the gate.
- *
- * @param {string} draft - the draft file's contents
- * @returns {boolean} true while the draft is unreviewed
- */
-export function needsReview(draft) {
-  return String(draft || '').includes(REVIEW_OPENING);
-}