sprag-cli 3.45.0 → 3.46.0

package/README.ko.md

@@ -66,7 +66,7 @@ gemini-2.5-pro        57.9%             $734  ▰▰▰▰▰▰▰▰▰▰▰
 
 ```
 🔀 라우팅 절감 $2.09  |  fable→sonnet 1회 $0.72 · opus→haiku 1회 $0.57
-🚨 5H █████▓ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 5 · 🧠 Cache hit 98.8% · ⏳ Cache expires 59:46 · 📅 weekly ██▒░░░ 38% · 💵 Sep $42 · 📦 Ctx 47% of 1M
+🚨 5H ▰▰▰▰▰▰▰▰▰▰▰▱ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 5 · 🧠 Cache hit 98.8% · ⏳ Cache expires 59:46 · 📅 weekly ▰▰▰▰▰▱▱▱▱▱▱▱ 38% · 💵 Sep $42 · 📦 Ctx 47% of 1M
 ```
 
 문제가 생기면 경고 칩이 줄 맨 앞으로 옵니다. `🚨 5H/7D NN%`, `⚠ Ctx 500k+`, `⚠ Cache miss`, `⚠ Input spike`, `⚠ Output heavy`, `⚠ Call surge`, `⚠ Rebuild churn`, `⚠ 5m TTL` 여덟 가지이며, 칩 문구를 그대로 말하면 Skill이 원인 코드와 조치 순서를 꺼내 줍니다. 세그먼트별 의미와 색 기준은 [statusline 문서](https://github.com/rootstudioyaml/sprag/blob/main/docs/STATUSLINE.md)에 정리했습니다.

package/README.md

@@ -72,7 +72,7 @@ gemini-2.5-pro        57.9%             $734  ▰▰▰▰▰▰▰▰▰▰▰
 
 ```
 🔀 라우팅 절감 $2.09  |  fable→sonnet 1회 $0.72 · opus→haiku 1회 $0.57
-🚨 5H █████▓ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 5 · 🧠 Cache hit 98.8% · ⏳ Cache expires 59:46 · 📅 weekly ██▒░░░ 38% · 💵 Sep $42 · 📦 Ctx 47% of 1M
+🚨 5H ▰▰▰▰▰▰▰▰▰▰▰▱ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 5 · 🧠 Cache hit 98.8% · ⏳ Cache expires 59:46 · 📅 weekly ▰▰▰▰▰▱▱▱▱▱▱▱ 38% · 💵 Sep $42 · 📦 Ctx 47% of 1M
 ```
 
 문제가 생기면 경고 칩이 줄 맨 앞으로 옵니다. `🚨 5H/7D NN%`, `⚠ Ctx 500k+`, `⚠ Cache miss`, `⚠ Input spike`, `⚠ Output heavy`, `⚠ Call surge`, `⚠ Rebuild churn`, `⚠ 5m TTL` 여덟 가지이며, 칩 문구를 그대로 말하면 Skill이 원인 코드와 조치 순서를 꺼내 줍니다. 세그먼트별 의미와 색 기준은 [statusline 문서](https://github.com/rootstudioyaml/sprag/blob/main/docs/STATUSLINE.md)에 정리했습니다.
@@ -211,7 +211,7 @@ The measured −18.6% comes from the harness and ratchet; routing and conversion
 
 ```
 🔀 Routing saved $2.09  |  fable→sonnet 1× $0.72 · opus→haiku 1× $0.57
-🚨 5H █████▓ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 5 · 🧠 Cache hit 98.8% · ⏳ Cache expires 59:46 · 📅 weekly ██▒░░░ 38% · 💵 Sep $42 · 📦 Ctx 47% of 1M
+🚨 5H ▰▰▰▰▰▰▰▰▰▰▰▱ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 5 · 🧠 Cache hit 98.8% · ⏳ Cache expires 59:46 · 📅 weekly ▰▰▰▰▰▱▱▱▱▱▱▱ 38% · 💵 Sep $42 · 📦 Ctx 47% of 1M
 ```
 
 When something is wrong the warning chip leads the line: `🚨 5H/7D NN%`, `⚠ Ctx 500k+`, `⚠ Cache miss`, `⚠ Input spike`, `⚠ Output heavy`, `⚠ Call surge`, `⚠ Rebuild churn`, `⚠ 5m TTL`. Say the chip wording inside Claude and the Skill surfaces the root-cause code and the fix. Segment-by-segment meanings live in [the statusline reference](./docs/STATUSLINE.md).

package/bin/cli.js

@@ -325,7 +325,12 @@ async function main() {
       console.log('예산 캐시가 비어 있습니다. `sprag litellm-budget --refresh` 로 먼저 조회하십시오.');
       return;
     }
-    for (const line of formatBudgetReport(state)) console.log(line);
+    // Same resolver the statusline uses: this report draws a gauge too, and a
+    // glyph the terminal's font lacks garbles here exactly as it does there.
+    const { resolveLabelMode } = await import('../src/statusline-mode.js');
+    const { statuslineDefaults } = await import('../src/config.js');
+    const { mode: labelMode } = resolveLabelMode({ hasFlag, cfg: statuslineDefaults() });
+    for (const line of formatBudgetReport(state, new Date(), labelMode)) console.log(line);
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.45.0",
+  "version": "3.46.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": {
@@ -13,6 +13,7 @@
     "postinstall": "node bin/cli.js install || true",
     "publish:legacy": "node scripts/publish-legacy.mjs",
     "sync:ko": "node scripts/sync-readme-ko.mjs",
+    "release:notes": "node scripts/release-notes.mjs",
     "prepublishOnly": "node scripts/sync-readme-ko.mjs"
   },
   "files": [

package/src/changelog.js

@@ -0,0 +1,34 @@
+/**
+ * changelog — read one version's section out of CHANGELOG.md.
+ *
+ * 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 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();
+}

package/src/commands/install.js

@@ -71,6 +71,7 @@ export async function run({ hasFlag }) {
     const r = installAll({ force });
     print('skill', r.skill);
     print('SessionStart hook (route-scan)', r.sessionStartHook);
+    print('PostToolUse hook (delegation rescan)', r.delegationHook);
     print('UserPromptSubmit hook (brief)', r.briefHook);
     {
       let s = r.statusline;

package/src/commands/route-scan.js

@@ -174,11 +174,27 @@ export async function run({ args, hasFlag, numArg }) {
       const scan = rs.readRouteScan();
       if (scan?.unresolvedRuns > 0) {
         const ids = (scan.unresolvedModels || []).join(', ');
+        // Unlike the statusline chip, this listing reports even a single one: the
+        // user ran this command to find out why a rule reads as never fired, and
+        // there is room here to answer properly. But a gateway's opaque profile
+        // ARN is normally resolved by learning from observed runs, which needs
+        // MIN_VOTES of them — so below that, the honest advice is to wait rather
+        // than to go edit a config file.
+        const { MIN_VOTES } = await import('../model-alias.js');
+        const learning = scan.unresolvedRuns < MIN_VOTES;
+        const remedyKo = learning
+          ? `\n  위임이 ${MIN_VOTES}건 이상 쌓이면 자동으로 해석될 수 있습니다. 그때까지 기다렸다가 다시 확인하고,`
+            + '\n  게이트웨이가 모델 이름을 아예 알려 주지 않는 환경이라면 profile-map.json 의 modelAliases 에'
+            + '\n  해당 ID 를 매핑한 뒤 route-scan --refresh 를 실행하십시오.'
+          : '\n  profile-map.json 의 modelAliases 에 해당 ID 를 매핑한 뒤 route-scan --refresh 를 실행하십시오.';
+        const remedyEn = learning
+          ? `\n  These may resolve on their own once ${MIN_VOTES} or more delegated runs accumulate — check again then.`
+            + '\n  If the gateway never reports a model name at all, map the id under modelAliases in'
+            + '\n  profile-map.json and run route-scan --refresh.'
+          : '\n  Map it under modelAliases in profile-map.json, then run route-scan --refresh.';
         console.log(lang === 'ko'
-          ? `\n⚠ 해석되지 않은 모델 ID 때문에 위임 ${scan.unresolvedRuns}건이 집계에서 제외됐습니다${ids ? ` (${ids})` : ''}.`
-            + '\n  profile-map.json 의 modelAliases 에 해당 ID 를 매핑한 뒤 route-scan --refresh 를 실행하십시오.'
-          : `\n⚠ ${scan.unresolvedRuns} delegated run(s) were excluded — unpriceable model id${ids ? ` (${ids})` : ''}.`
-            + '\n  Map it under modelAliases in profile-map.json, then run route-scan --refresh.');
+          ? `\n⚠ 해석되지 않은 모델 ID 때문에 위임 ${scan.unresolvedRuns}건이 집계에서 제외됐습니다${ids ? ` (${ids})` : ''}.` + remedyKo
+          : `\n⚠ ${scan.unresolvedRuns} delegated run(s) were excluded — unpriceable model id${ids ? ` (${ids})` : ''}.` + remedyEn);
       }
       console.log(lang === 'ko'
         ? '\n제거: sprag route-scan rules rm <N>'
@@ -203,6 +219,33 @@ export async function run({ args, hasFlag, numArg }) {
       return;
     }
 
+    // --hook-delegated: PostToolUse hook for Task/Agent. A delegation just
+    // finished, which is the one event guaranteed to change what a scan
+    // produces — its savings and its error rate both move. Kicks a detached
+    // refresh so the statusline shows the new figure on its next render
+    // instead of waiting out the hourly gate, and prints nothing: a tool
+    // result is not a place for our commentary.
+    if (hasFlag('--hook-delegated')) {
+      const payload = readStdinJson() || {};
+      // Claude Code matches the hook by tool name already, but the payload is
+      // the only thing that proves it: a mis-registered matcher would otherwise
+      // have us rescanning after every Read.
+      const tool = payload.tool_name;
+      if (tool !== 'Task' && tool !== 'Agent') return;
+      try {
+        const cache = rs.readRouteScan();
+        if (!(await rs.shouldRescan(cache, { afterDelegation: true }))) return;
+        const { spawn } = await import('node:child_process');
+        spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet'],
+          { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+      } catch (e) {
+        // A missed refresh only means the figure lags, which is what happened
+        // before this hook existed. Never fail the tool call over it.
+        debug('route-scan:delegated-refresh', e);
+      }
+      return;
+    }
+
     // --hook: SessionStart hook mode. Never scans inline (session start must
     // stay fast) — reads the cache, kicks a detached refresh when stale, and
     // prints delegation-candidate context for the new session.
@@ -299,16 +342,32 @@ export async function run({ args, hasFlag, numArg }) {
         // `dismissed` is the whole point of asking once: a user who said no to
         // this version must not be asked again every `/clear`.
         if (u && u.available && !u.dismissed) {
+          // What the release adds, when we managed to read it. "A newer version
+          // exists" is not a reason to upgrade; the reason is in this list, and
+          // without it the user is being asked to decide on no information.
+          const notes = Array.isArray(u.highlights) ? u.highlights : [];
+          const koNotes = notes.length
+            ? ['  이 버전에서 새로 생긴 것:', ...notes.map((n) => `    · ${n}`)]
+            : [];
+          const enNotes = notes.length
+            ? ['  What this release adds:', ...notes.map((n) => `    · ${n}`)]
+            : [];
           updateBlock = lang === 'ko'
             ? [
                 `[sprag update] 새 버전이 나와 있습니다: v${u.current} → ${u.latest}.`,
-                '사용자에게 지금 업그레이드할지 물어보고, 승낙하면 아래 명령을 실행하십시오. 묻지 않고 설치하지는 마십시오.',
-                '  sprag upgrade            # 업그레이드 실행',
+                ...koNotes,
+                notes.length
+                  ? '  위 내용을 사용자에게 보여 주고 업그레이드할지 물어보십시오. 승낙하면 아래 명령을 실행하고, 묻지 않고 설치하지는 마십시오.'
+                  : '  사용자에게 지금 업그레이드할지 물어보고, 승낙하면 아래 명령을 실행하십시오. 묻지 않고 설치하지는 마십시오.',
+                '  sprag upgrade                  # 업그레이드 실행',
                 '  sprag update-check --dismiss   # 사용자가 원치 않으면 (다음 버전이 나올 때까지 다시 묻지 않습니다)',
               ].join('\n')
             : [
                 `[sprag update] A newer version is available: v${u.current} → ${u.latest}.`,
-                'Ask the user whether to upgrade now, and run the command below only if they agree. Do not install without asking.',
+                ...enNotes,
+                notes.length
+                  ? '  Show that list to the user and ask whether to upgrade. Run the command below only if they agree; do not install without asking.'
+                  : 'Ask the user whether to upgrade now, and run the command below only if they agree. Do not install without asking.',
                 '  sprag upgrade                  # perform the upgrade',
                 '  sprag update-check --dismiss   # if they decline (stays quiet until a newer release)',
               ].join('\n');

package/src/formatters/statusline.js

@@ -23,6 +23,7 @@ import { labelForKey } from '../window-labels.js';
 import { harnessStatusForStatusline } from '../harness.js';
 import { loadConfig } from '../config.js';
 import { koreanStyleEnabled } from '../korean-style.js';
+import { MIN_VOTES } from '../model-alias.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
@@ -67,88 +68,86 @@ function formatPct(v) {
 }
 
 /**
- * Render a 6-cell density-gradient gauge for `pct` (0..100). All cells share
- * the same Unicode "Block Elements" density family — `█` (100%) → `▓` (75%)
- * → `▒` (50%) → `░` (25%) — so the fill→empty boundary reads as one smooth
- * gradient instead of an awkward step.
+ * Render the gauge for `pct` (0..100) as a row of separate ticks.
  *
- * Earlier we used partial-fill glyphs (`▏▎▍▌▋▊▉`) for sub-cell precision, but
- * those have transparent halves that clash visually with the `░` track next
- * to them (the eye sees "solid edge | gap | dotted track" — three zones).
- * Density chars are the same shape, just darker/lighter, so the boundary
- * cell reads as a single smooth fade.
+ * The bar used to be six cells of one continuous block, with the boundary cell
+ * subdivided into eighths for sub-cell precision. That precision had no reader:
+ * every chip that draws a gauge prints the exact percentage immediately after it
+ * (`▰▰▰▱▱▱ 26%`), so the bar's job is the glance, not the number. What the solid
+ * run cost instead was legibility — adjacent full cells fuse into one shape, and
+ * a shape has no quantity you can read off it. Separate ticks do: twelve of them
+ * are countable at a glance and land on a familiar 1/12 grid.
  *
- * Each cell is ~17% wide; the boundary cell uses 3 intermediate density steps
- * for ~4% effective precision around the fill edge. Stable monospace width
- * across all terminal fonts that ship Block Elements (U+2580–U+259F).
+ * Two ends get special treatment, because they are the two readings that change
+ * a decision. A full row means the limit is reached, so nothing below 100% may
+ * draw one; conversely anything above zero draws at least one tick, so "barely
+ * started" never looks like "untouched". Rounding alone gets both wrong: it fills
+ * the last cell from 96% and leaves the first empty until 5%.
+ *
+ * Glyphs come from the mode's set (src/glyphs.js) rather than being fixed here.
+ * ▰▱ is the shape we want, but JetBrains Mono ships neither character, and a
+ * missing glyph is drawn by a fallback font whose advance width does not match
+ * the cell grid — which is the whole reason narrow mode exists. So narrow draws
+ * the same segmented bar with ■□, which that font does have.
+ *
+ * @param {number} pct
+ * @param {string} [mode] label mode; selects the tick glyphs
+ * @returns {{ filled: string, empty: string }} the two halves, so a caller can
+ *   color them separately
  */
-export function gaugeParts(pct) {
-  const cells = 6;
+export function gaugeParts(pct, mode = 'icon') {
+  const CELLS = 12;
+  const g = glyphsFor(mode);
   const clamped = Math.max(0, Math.min(100, pct));
-  const filled = (clamped / 100) * cells; // e.g. 4.32 cells filled
-  const fullCells = Math.floor(filled);
-  const remainder = filled - fullCells; // 0..1 — fill fraction of the boundary cell
-  // Boundary cell in eighths. The earlier version had three steps (░ ▒ ▓), which
-  // meant 25% and 31% drew the same bar; eighths keep the resolution the width
-  // of the bar can carry, so the gauge moves as the number does. Every character
-  // here is present in JetBrains Mono, which is why the gauge was the one part
-  // of the line that never garbled under IntelliJ (see src/glyphs.js).
-  const EIGHTHS = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉'];
-  // Empty cells use ▒ rather than ░. In JetBrains Mono the eighth blocks all sit
-  // at yMin -300 / xMin 0, while ░ sits at yMin -240 / xMin 60 — about 4% of the
-  // cell height and 10% of its width inset — so a bar mixing them looks visibly
-  // misaligned, the empty half riding high and shifted inward. ▒ shares the box
-  // with the filled glyphs and still reads clearly lighter than █.
-  const step = Math.round(remainder * 8);
-  // A boundary cell rounded up to 8/8 is a full cell, not a ninth glyph.
-  const extra = step === 8 ? 1 : 0;
-  const totalFull = Math.min(cells, fullCells + extra);
-  const partial = totalFull < cells && extra === 0 ? EIGHTHS[step] : '';
-  const usedCells = totalFull + (partial ? 1 : 0);
-  const empty = '▒'.repeat(Math.max(0, cells - usedCells));
-  return { filled: '█'.repeat(totalFull) + partial, empty };
+  let ticks = Math.round((clamped / 100) * CELLS);
+  // A full row is reserved for an actual 100%: at the cap the gauge alone has to
+  // say so, and 96% rounding up to twelve would spend that signal on a window
+  // that still has room.
+  if (ticks >= CELLS && clamped < 100) ticks = CELLS - 1;
+  // And any nonzero usage earns a tick, so an empty row means untouched.
+  if (ticks === 0 && clamped > 0) ticks = 1;
+  return {
+    filled: g.gaugeFull.repeat(ticks),
+    empty: g.gaugeEmpty.repeat(CELLS - ticks),
+  };
 }
 
 /**
  * The bar as one string, for callers that render it in a single color.
  * @param {number} pct
+ * @param {string} [mode] label mode; selects the tick glyphs
  * @returns {string}
  */
-export function gaugeBar(pct) {
-  const { filled, empty } = gaugeParts(pct);
+export function gaugeBar(pct, mode = 'icon') {
+  const { filled, empty } = gaugeParts(pct, mode);
   return filled + empty;
 }
 
 /**
- * The bar with the unused cells dimmed.
+ * The bar with the unused ticks dimmed.
  *
- * ▒ shares its glyph box with the filled blocks, which is why it replaced ░, but
- * it is also denser than ░ was — in one color the used and unused halves stop
- * reading as different. Graying the remainder restores the contrast that the
- * shading alone used to carry. The segment tone is reinstated at the end so the
- * text after the bar keeps the color it started in.
+ * The hollow tick already distinguishes the two halves by shape, so color is not
+ * carrying that distinction the way it had to when both halves were the same
+ * solid block. It still helps: graying the remainder keeps the filled run as the
+ * only thing at full brightness, which is what the eye should land on. The
+ * segment tone is reinstated at the end so the text after the bar keeps the color
+ * it started in.
  *
  * @param {number} pct
  * @param {(code: string) => string} c - color emitter (returns '' when color is off)
  * @param {string} tone - the segment's own color code
  * @param {boolean} color - whether ANSI is allowed. Passed explicitly rather
  *   than inferred from `c` emitting nothing: that inference reads the emitter's
- *   current implementation, and a caller that wraps or replaces `c` would flip
- *   the track glyph as a side effect nobody asked for.
+ *   current implementation, and a caller that wraps or replaces `c` would change
+ *   behaviour here as a side effect nobody asked for.
+ * @param {string} [mode] label mode; selects the tick glyphs
  * @returns {string}
  */
-function gaugeColored(pct, c, tone, color) {
-  const { filled, empty } = gaugeParts(pct);
+function gaugeColored(pct, c, tone, color, mode = 'icon') {
+  const { filled, empty } = gaugeParts(pct, mode);
   if (!empty) return filled;
-  // With color available, the unused cells are the same solid block as the used
-  // ones, just gray. Shading characters (░ ▒) carry a dither pattern that reads
-  // as noise beside a solid fill — the two halves look like different materials
-  // rather than two states of one bar. One glyph in two colors reads as a track
-  // filling up, and it sidesteps the glyph-box mismatch between the shades and
-  // the blocks entirely. Without color there is nothing but texture to tell them
-  // apart, so the shading stays.
-  const track = color ? '█'.repeat(empty.length) : empty;
-  return `${filled}${c(RESET)}${c(GRAY)}${track}${c(RESET)}${c(tone)}`;
+  if (!color) return filled + empty;
+  return `${filled}${c(RESET)}${c(GRAY)}${empty}${c(RESET)}${c(tone)}`;
 }
 
 /**
@@ -266,11 +265,9 @@ function buildHarnessSeg(c, isIcon, g) {
  * the wall-clock reset time rides along in the same `🔄 HH:MM` shape as the
  * always-on usage segments.
  */
-function buildCapWarnSeg(capWarn, c, isIcon, g, color) {
-  // `color` is only for the gauge. At 90%+ the bar has no unused cells left, so
-  // gaugeColored returns early and never reads it today — it is threaded through
-  // anyway, because a change to the cap-warn threshold or the bar width would
-  // otherwise start drawing the wrong track with nothing to catch it.
+function buildCapWarnSeg(capWarn, c, isIcon, g, color, mode) {
+  // `color` and `mode` are both for the gauge: the first decides whether the
+  // unused ticks are dimmed, the second which pair of tick glyphs to draw.
   if (!capWarn) return null;
   const pct = Math.round(capWarn.usedPct);
   const clock = formatResetClock(capWarn.resetsAt);
@@ -281,7 +278,7 @@ function buildCapWarnSeg(capWarn, c, isIcon, g, color) {
     // Gauge keeps shape parity with the always-on usage segment — the
     // cap-warn is just the same gauge "filled to alarm". Visual continuity
     // helps the eye understand "this is the 5H bar I was watching, just red now."
-    const bar = gaugeColored(pct, c, RED, color);
+    const bar = gaugeColored(pct, c, RED, color, mode);
     return `${c(BOLD)}${c(RED)}${g.capWarn} ${capWarn.label} ${bar} ${pct}%${clockTail}${c(RESET)}`;
   }
   return `${c(BOLD)}${c(RED)}${capWarn.label} cap ${pct}%${clockTail}${c(RESET)}`;
@@ -301,7 +298,7 @@ export function formatNoSession({ caps = null, model = null, windowLabel = '', v
   const isIcon = mode === 'icon' || mode === 'narrow';
   const g = glyphsFor(mode);
   const segs = [];
-  const capSeg = buildCapWarnSeg(pickCapWarn(caps), c, isIcon, g, color);
+  const capSeg = buildCapWarnSeg(pickCapWarn(caps), c, isIcon, g, color, mode);
   if (capSeg) segs.push(capSeg);
   const versionSeg = buildVersionSeg(version, update, c, isIcon, false, g);
   if (versionSeg && update && update.available) segs.push(versionSeg);
@@ -443,10 +440,18 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // identical, so users in the second case had no reason to suspect anything
   // was wrong. The count gets a chip; the explanation stays in `route-scan
   // rules`, where there is room for it.
+  //
+  // But only once there are enough of them to mean anything. A gateway reports
+  // an opaque profile ARN, and the fix for that is learned from observed runs —
+  // which needs MIN_VOTES of them before it can conclude anything. Below that
+  // threshold an unresolved run is not a problem, it is the first day of a
+  // working mechanism, and warning about it makes a fresh install look broken.
+  // Tied to MIN_VOTES rather than a literal so the two cannot drift: the chip
+  // appears exactly when learning has had its chance and still came up short.
   const unresolvedRuns = Number(data.unresolvedRuns) || 0;
   const delegateSeg = delegationSaved > 0
     ? `${c(GREEN)}${delegateLabel}${c(RESET)} ${formatMoney(delegationSaved)}`
-    : (unresolvedRuns > 0
+    : (unresolvedRuns >= MIN_VOTES
       ? `${c(YELLOW)}${g.routing} ${unresolvedRuns} unresolved${c(RESET)}`
       : null);
 
@@ -750,7 +755,7 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     const src = info.source === 'user' ? ' (user)' : '';
     if (isIcon) {
       const labelPart = labels.usageLabel ? `${labels.usageLabel}${src} ` : '';
-      const bar = gaugeColored(pct, c, tone, color);
+      const bar = gaugeColored(pct, c, tone, color, mode);
       const winGlyph = mode === 'narrow' ? (labels.narrowIcon || labels.icon) : labels.icon;
       return `${c(tone)}${winGlyph} ${labelPart}${bar} ${pct}%${money}${tail}${c(RESET)}`;
     }
@@ -787,7 +792,7 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     }
   }
 
-  const capWarnSeg = buildCapWarnSeg(capWarn, c, isIcon, g, color);
+  const capWarnSeg = buildCapWarnSeg(capWarn, c, isIcon, g, color, mode);
 
   // Warning chip leads — a glance at the statusline catches "something's wrong"
   // before parsing any numbers. Healthy states have no chip and look unchanged.

package/src/glyphs.js

@@ -19,6 +19,13 @@
  * Per-window glyphs (the 5h star, the weekly grid, the budget box) live in
  * src/window-labels.js instead, next to the labels they belong to.
  *
+ * The gauge cells live here too, for the same reason the chip glyphs do. The
+ * shapes differ by mode rather than only the vocabulary: ▰▱ read as a row of
+ * separate ticks, which is what a gauge is, but JetBrains Mono ships neither
+ * (verified via its cmap: U+25B0 and U+25B1 are absent, U+25A0 and U+25A1 are
+ * present). So the narrow set draws the same segmented shape with ■□ instead of
+ * falling back to a font whose advance width would garble the line.
+ *
  * Width still matters as a second filter — a fullwidth glyph would occupy two
  * cells — so every narrow glyph is also East Asian Width N/Na. The test suite
  * enforces both properties.
@@ -40,6 +47,12 @@ const ICON = {
   ctx: '📦',
   saved: '💰',
   reset: '🔄',
+  // Gauge cells. Separate ticks rather than one continuous block: the bar is a
+  // count of how much of a budget is gone, and ticks are countable where a solid
+  // run is not. Precision is not this bar's job — an exact percentage is printed
+  // immediately after it in every chip that draws one.
+  gaugeFull: '▰',
+  gaugeEmpty: '▱',
 };
 
 /**
@@ -62,6 +75,10 @@ const NARROW = {
   ctx: '◧',       // a box filling up
   saved: '✓',
   reset: '↩',     // the window turning over
+  // Same segmented shape as the icon set, in the two glyphs this font has.
+  // ▰▱ (U+25B0/25B1) are absent from JetBrains Mono; ■□ (U+25A0/25A1) are there.
+  gaugeFull: '■',
+  gaugeEmpty: '□',
 };
 
 const SETS = { icon: ICON, narrow: NARROW };

package/src/installer.js

@@ -244,8 +244,11 @@ export function installSessionStartHook() {
     return { path: file, action: 'skipped', reason: 'hooks.SessionStart is not an array — fix settings.json manually' };
   }
   const list = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : [];
+  // Match the flag exactly. `route-scan --hook-delegated` contains
+  // `route-scan --hook` as a prefix, so a substring test would see that hook and
+  // conclude this one is already installed.
   const already = list.some((m) =>
-    Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('route-scan --hook')),
+    Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && /route-scan --hook(?![\w-])/.test(h.command)),
   );
   if (already) return { path: file, action: 'exists' };
 
@@ -263,6 +266,51 @@ export function installSessionStartHook() {
 // conversation — the model cannot see statusline chips, so without this a
 // change that happens mid-session goes unexplained until the user asks.
 // Silent (no output, zero context cost) when nothing changed. Idempotent.
+/**
+ * PostToolUse hook for Task/Agent. The statusline's `Routing saved` figure comes
+ * from a cached scan, and the gate in front of that scan holds a fresh
+ * delegation back an hour at best. That gate is there to skip scans that would
+ * produce identical output; a delegation is precisely the event that changes it,
+ * so this hook rescans on the spot. Detached, so the tool call does not wait.
+ */
+const ROUTE_SCAN_DELEGATED_HOOK_COMMAND = 'claude-token-saver route-scan --hook-delegated';
+
+export function installDelegationHook() {
+  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 || {};
+  if (settings.hooks.PostToolUse !== undefined && !Array.isArray(settings.hooks.PostToolUse)) {
+    return { path: file, action: 'skipped', reason: 'hooks.PostToolUse is not an array — fix settings.json manually' };
+  }
+  const list = Array.isArray(settings.hooks.PostToolUse) ? settings.hooks.PostToolUse : [];
+  // Same exact-flag match as the SessionStart hook above, for the same reason:
+  // a substring test is what confused `--hook` with `--hook-delegated`, and a
+  // future `--hook-delegated-batch` would confuse this one in turn.
+  const already = list.some((m) =>
+    Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && /route-scan --hook-delegated(?![\w-])/.test(h.command)),
+  );
+  if (already) return { path: file, action: 'exists' };
+
+  list.push({
+    matcher: 'Task|Agent',
+    hooks: [{ type: 'command', command: ROUTE_SCAN_DELEGATED_HOOK_COMMAND, timeout: 10 }],
+  });
+  settings.hooks.PostToolUse = list;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { path: file, action: 'created' };
+}
+
 const BRIEF_HOOK_COMMAND = 'claude-token-saver brief --hook';
 
 export function installBriefHook() {
@@ -623,6 +671,7 @@ export function installAll({ force = false } = {}) {
     skill: installSkill({ force }),
     statusline: installStatusline({ force }),
     sessionStartHook: installSessionStartHook(),
+    delegationHook: installDelegationHook(),
     briefHook: installBriefHook(),
     cacheMonitorMigration: migrateLegacyCacheMonitorHook(),
     legacy: removeLegacyCommand(),

package/src/litellm-budget.js

@@ -23,6 +23,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { userDataDir } from './paths.js';
 import { gaugeBar, formatMoney } from './formatters/statusline.js';
+import { labelForKey } from './window-labels.js';
 import { formatResetClock } from './format-time.js';
 import { cliEntryPath } from './update-check.js';
 import { debug } from './debug.js';
@@ -155,11 +156,16 @@ export function budgetWindow(env = process.env) {
  * 같은 모양(비주얼 바 + 백분율 + 금액)을 쓰되, 통계선에서는 폭이 부족해 생략하는
  * 잔여 금액과 예산 출처, 캐시 신선도를 함께 적습니다.
  *
+ * `mode` 는 통계선과 같은 판정 결과를 받습니다. 이 보고서도 결국 터미널에
+ * 출력되므로, IntelliJ 에서 실행하면 폰트에 없는 글리프가 대체 폰트로 그려져
+ * 통계선과 똑같이 어긋납니다. 게이지 눈금과 예산 아이콘을 함께 모드에 맞춥니다.
+ *
  * @param {object} state - readBudgetState() 가 돌려준 캐시 상태
  * @param {Date} [now]
+ * @param {string} [mode] - 라벨 모드 ('icon' | 'narrow' | 'text')
  * @returns {string[]} 출력할 줄들
  */
-export function formatBudgetReport(state, now = new Date()) {
+export function formatBudgetReport(state, now = new Date(), mode = 'icon') {
   const max = Number(state?.maxBudget);
   const spend = Number(state?.spend);
   if (!Number.isFinite(max) || max <= 0) {
@@ -169,8 +175,16 @@ export function formatBudgetReport(state, now = new Date()) {
   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 win = labelForKey('litellm_budget');
+  // 통계선의 text 모드는 게이지를 아예 그리지 않지만 이 보고서는 그립니다. text 는
+  // 이모지를 피하려고 고른 모드이므로, 그 선택을 존중해 눈금도 폰트 커버리지가
+  // 확인된 narrow 쪽 글리프를 씁니다. 라벨은 아이콘 없이 이름만 적습니다.
+  const bare = mode === 'text';
+  const tickMode = mode === 'icon' ? 'icon' : 'narrow';
+  const icon = bare ? '' : (mode === 'narrow' ? (win.narrowIcon || win.icon) : win.icon);
+  const head = bare ? 'budget' : `${icon} budget`;
   const lines = [
-    `💳 budget ${gaugeBar(pct)} ${Math.round(pct)}% ${formatMoney(used)}/${formatMoney(max)}`,
+    `${head} ${gaugeBar(pct, tickMode)} ${Math.round(pct)}% ${formatMoney(used)}/${formatMoney(max)}`,
     `   사용 ${formatMoney(used)} · 잔여 ${formatMoney(left)} (${(100 - pct).toFixed(1)}%)`,
   ];
   const resetMs = Number(state?.budgetResetAt);

package/src/route-inject.js

@@ -36,9 +36,12 @@ const MIN_LEN = 8;
  * @param {object} [opts]
  * @param {Array} [opts.rules] registered rules (defaults to the stored registry)
  * @param {string} [opts.lang] 'ko' | 'en'
+ * @param {string} [opts.root] project root used to look for a subagent's .md.
+ *   The hint names the agent when that file exists and only its model tier when
+ *   it does not, so a caller that needs a predictable phrase pins this.
  * @returns {string|null} the line to inject, or null to stay quiet
  */
-export function routeHint(text, { rules, lang = userLanguage() } = {}) {
+export function routeHint(text, { rules, lang = userLanguage(), root } = {}) {
   const t = String(text || '').trim();
   if (t.length < MIN_LEN) return null;
   // Judgement and irreversible work stay on the top tier. This check comes
@@ -57,7 +60,12 @@ export function routeHint(text, { rules, lang = userLanguage() } = {}) {
   const t1 = matched.find((r) => r.tier === 'T1');
   const ko = lang === 'ko';
   const label = ko ? (cat.label || cat.id) : (cat.labelEn || cat.label || cat.id);
-  const phrase = ko ? agentPhrase : agentPhraseEn;
+  // `root` is threaded through to agentPhrase, which names the subagent only
+  // when its .md actually exists on this machine. A caller that pins it can
+  // therefore get a deterministic phrase; a test that does not pin it reads
+  // whatever the developer happens to have installed.
+  const raw = ko ? agentPhrase : agentPhraseEn;
+  const phrase = (name) => raw(name, root === undefined ? undefined : { root });
 
   let target;
   if (t2 && t1) {

package/src/route-scan.js

@@ -67,6 +67,18 @@ export const RESCAN_MIN_INTERVAL_MS = 60 * 60 * 1000;      // never more than ho
 export const RESCAN_BIG_DELTA_BYTES = 5 * 1024 * 1024;     // this much new data → rescan now
 export const RESCAN_MAX_AGE_MS = 24 * 60 * 60 * 1000;      // any new data + a day old → rescan
 
+// One event is exempt from all three: a delegation that just finished. The
+// clauses above exist to skip scans that would produce identical output, and a
+// delegation is the one thing guaranteed to change it — savings and the rule's
+// own error rate both move. Its transcript is nowhere near 5MB, so the gate
+// would otherwise hold the figure back an hour at best and a day at worst,
+// which is exactly the window in which the user is asking whether delegating
+// paid off. Measured on this machine: a scan is ~0.5s over 14 days / 67MB, and
+// delegations run ~1.6×/day, so the exemption costs well under a second a day.
+// A short floor still applies, so a fan-out of parallel agents finishing
+// together triggers one scan rather than one per agent.
+export const RESCAN_AFTER_DELEGATION_MS = 30 * 1000;
+
 // Categories → recommended subagent. Classification is behavior-first with
 // weighted keyword scoring as fallback — see categorize().
 const PASTE_MIN_LEN = 400;
@@ -740,12 +752,23 @@ export function readRouteScan() {
 /**
  * Data-driven rescan gate (see constants above). Cheap: one stat() per
  * transcript file (~32 files on measured data) — a few milliseconds.
+ *
+ * @param {object|null} cache - readRouteScan() result
+ * @param {object} [opts]
+ * @param {number} [opts.days] - analysis window
+ * @param {boolean} [opts.afterDelegation] - a delegation just finished, so this
+ *   scan is known to produce different numbers. Skips the byte and age clauses
+ *   and applies only the anti-thrash floor.
+ * @returns {Promise<boolean>}
  */
-export async function shouldRescan(cache, { days = 14 } = {}) {
+export async function shouldRescan(cache, { days = 14, afterDelegation = false } = {}) {
   if (!cache?.scannedAt) return true;
   const ts = Date.parse(cache.scannedAt);
   if (!Number.isFinite(ts)) return true;
   const age = Date.now() - ts;
+  // A delegation just finished, so the numbers this scan produces are known to
+  // differ. Only the anti-thrash floor applies — see RESCAN_AFTER_DELEGATION_MS.
+  if (afterDelegation) return age >= RESCAN_AFTER_DELEGATION_MS;
   if (age < RESCAN_MIN_INTERVAL_MS) return false;
 
   let total = 0;

package/src/seed-rules.js

@@ -243,42 +243,54 @@ 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('적용 범위를 물을 때는 선택지를 **글로벌(모든 프로젝트)을 먼저, 이 프로젝트만을 그다음**으로 제시하십시오.');
+    lines.push('**이 세션의 첫 응답에서 다른 작업보다 먼저 물어보십시오.** 사용자가 먼저 꺼낸 용건이 있으면 그 답변을 마친 직후에 이어서 묻고, 용건이 끝나기를 기다리지 마십시오. 사용자가 이 안내 문구에 대해 질문할 때까지 미루면 안 됩니다.');
+    lines.push(`첫 질문에서 다음 네 선택지를 **이 순서대로** 제시하십시오. ${pending.length}건을 한 건씩 답하는 것은 대부분의 사용자에게 과한 부담이므로, 일괄 등록이 맨 앞에 옵니다.`);
+    lines.push('  1. 전부 글로벌로 등록 — `seed accept all --global`');
+    lines.push('  2. 전부 이 프로젝트만 등록 — `seed accept all --project`');
+    lines.push('  3. 한 건씩 보면서 결정 — 아래 목록을 순서대로 하나씩 묻고, 답을 받는 즉시 해당 명령을 실행합니다');
+    lines.push('  4. 전부 등록하지 않음 — `seed skip all` (다시 묻지 않습니다)');
+    lines.push('3번을 고른 경우에만 한 건씩 진행하고, 그때도 적용 범위는 **글로벌(모든 프로젝트)을 먼저, 이 프로젝트만을 그다음**으로 제시하십시오.');
     if (models.length > 0) {
       lines.push(`  · 모델 피팅 룰 ${models.length}건 — 등록하면 해당 유형 작업이 더 싼 서브에이전트로 위임됩니다.`);
       for (const s of models) {
         lines.push(`    [${s.id}] ${s.tier} · "${s.label}" → ${s.agent}`);
-        lines.push(`        "${s.ruleText}"`);
+        // No wrapping quotes: the composed rule text already opens with the
+        // quoted work-type name, so adding a pair produced `""명령 실행 …`.
+        lines.push(`        ${s.ruleText}`);
       }
     }
     if (fixes.length > 0) {
       lines.push(`  · 래칫 룰 ${fixes.length}건 — 같은 실수를 반복하지 않도록 세션마다 읽히는 규칙입니다.`);
       for (const s of fixes) lines.push(`    [${s.id}] ${s.ruleText}`);
     }
-    lines.push('  등록: claude-token-saver seed accept <id> --global|--project   # 적용 범위는 반드시 사용자에게 확인');
-    lines.push('  거절: claude-token-saver seed skip <id>                        # 다시 묻지 않습니다');
-    lines.push('  (사용자가 "전부 등록"이라고 답하면 `seed accept all --global` 을 쓸 수 있습니다)');
+    lines.push('  일괄: claude-token-saver seed accept all --global|--project   # 적용 범위는 반드시 사용자에게 확인');
+    lines.push('  개별: claude-token-saver seed accept <id> --global|--project');
+    lines.push('  거절: claude-token-saver seed skip <id>|all                    # 다시 묻지 않습니다');
   } 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**.');
+    lines.push('**Ask 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(`Offer these four choices, **in this order**. Answering ${pending.length} rules one by one is more than most users want to do, so registering them all comes first.`);
+    lines.push('  1. Register all, globally — `seed accept all --global`');
+    lines.push('  2. Register all, this project only — `seed accept all --project`');
+    lines.push('  3. Decide one at a time — walk the list below in order, running each command as soon as they answer');
+    lines.push('  4. Register none — `seed skip all` (never offered again)');
+    lines.push('Only go rule-by-rule if they pick 3, and even then 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) {
         lines.push(`    [${s.id}] ${s.tier} · "${s.label}" → ${s.agent}`);
-        lines.push(`        "${s.ruleText}"`);
+        // No wrapping quotes: the composed rule text already opens with the
+        // quoted work-type name, so adding a pair produced `""명령 실행 …`.
+        lines.push(`        ${s.ruleText}`);
       }
     }
     if (fixes.length > 0) {
       lines.push(`  · ${fixes.length} ratchet rule(s) — read at the start of every session so the same mistake is not repeated.`);
       for (const s of fixes) lines.push(`    [${s.id}] ${s.ruleText}`);
     }
-    lines.push('  register: claude-token-saver seed accept <id> --global|--project   # ALWAYS confirm the scope with the user');
-    lines.push('  decline:  claude-token-saver seed skip <id>                        # never offered again');
-    lines.push('  (if the user says "register them all", `seed accept all --global` does that)');
+    lines.push('  all:      claude-token-saver seed accept all --global|--project   # ALWAYS confirm the scope with the user');
+    lines.push('  one:      claude-token-saver seed accept <id> --global|--project');
+    lines.push('  decline:  claude-token-saver seed skip <id>|all                    # never offered again');
   }
   return lines.join('\n');
 }

package/src/update-check.js

@@ -10,7 +10,16 @@
  *
  * State lives next to the other user-data files:
  *   { checkedAt: <ms>, latest: "3.25.0", current: "3.24.0",
- *     dismissedVersion: "3.25.0"|undefined }
+ *     dismissedVersion: "3.25.0"|undefined,
+ *     highlights: ["…", "…"]|undefined, highlightsFor: "3.25.0"|undefined }
+ *
+ * `highlights` is what the new version actually adds, read from the GitHub
+ * release for that tag. A bare "v3.24 → v3.25 is available" gives the user
+ * nothing to weigh: the answer to "should I upgrade" is in what changed, and
+ * asking them to go find that themselves is how an upgrade notice becomes
+ * something to dismiss. The release body is fetched on the same detached,
+ * once-a-day pass as the version check, and its absence never blocks the
+ * notice — a version number alone is still worth saying.
  *
  * Opt out with CTS_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER (the de-facto
  * standard env var — anyone who set it for other CLIs meant us too).
@@ -102,6 +111,9 @@ export function updateStatus(currentVersion) {
     // means "ask me again in five minutes", forever.
     dismissed: available && s.dismissedVersion === latest,
     stale: age >= CHECK_INTERVAL_MS,
+    // Only when they describe THIS version. A cache written for an earlier
+    // release would otherwise sell the wrong upgrade.
+    highlights: Array.isArray(s.highlights) && s.highlightsFor === latest ? s.highlights : [],
   };
 }
 
@@ -143,6 +155,116 @@ export function cliEntryPath() {
   return join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'cli.js');
 }
 
+// Release notes come from the repository's own releases, because the registry
+// does not carry them: `/latest` answers with package metadata and no changelog
+// of any kind. Unauthenticated reads are allowed at 60/hour, and this runs once
+// a day behind the same interval as the version check, so the budget is ample.
+const RELEASES_API = 'https://api.github.com/repos/rootstudioyaml/sprag/releases/tags';
+const MAX_HIGHLIGHTS = 3;
+const MAX_HIGHLIGHT_LEN = 110;
+
+/**
+ * The headline items of a release body, as short single lines.
+ *
+ * Release notes are written for people reading a web page: headings, prose
+ * paragraphs, links, and bold runs. A session-start notice has one line per
+ * item and no room for any of that, so this keeps only what reads as an item
+ * of a list and strips it to plain text. Anything that survives is a sentence
+ * the user can judge an upgrade by; anything that does not is left behind
+ * rather than truncated into nonsense.
+ *
+ * @param {string} body - the release body as published
+ * @returns {string[]} at most MAX_HIGHLIGHTS lines, or [] when nothing fits
+ */
+export function releaseHighlights(body) {
+  const text = String(body || '');
+  if (!text.trim()) return [];
+  const out = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    // Bullets only. A heading names a section, and a prose paragraph in a
+    // release body is usually the rationale rather than the change itself.
+    const m = /^[-*+]\s+(.*)$/.exec(line);
+    if (!m) continue;
+    // Markup goes first, so the sentence split below sees the text a reader
+    // would: `**Bash writes are checked.**` is one sentence, not a bold run.
+    // One exception has to be caught before that: a stop followed straight by a
+    // code span (`…checked.\`install\` migrates…`) is a sentence boundary, and
+    // stripping the backtick first leaves a lowercase letter the split ignores.
+    // A space there is what the author meant, and it costs nothing if not.
+    let item = m[1]
+      .replace(/([.。])(`)/g, '$1 $2')
+      .replace(/`([^`]*)`/g, '$1')            // code spans read fine as plain text
+      .replace(/\*\*([^*]*)\*\*/g, '$1')      // bold
+      .replace(/\*([^*]*)\*/g, '$1')          // italics
+      .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links keep their label
+      .replace(/\s+/g, ' ')
+      .trim();
+    if (!item) continue;
+    // Release notes lead with the change and follow with the reasoning, often
+    // for several sentences. The first sentence is the change, so that is what
+    // a one-line notice keeps — cutting at a character count instead lands
+    // mid-clause and reads as a broken string rather than a short one.
+    //
+    // The break does not require a space after the stop: "…checked.The matcher…"
+    // is a typo a release body can carry, and requiring one there merged the two
+    // sentences into a single over-long line. A capital letter or a Hangul
+    // syllable directly after the stop is enough to say a new sentence started;
+    // a digit is not, so "0.5s" and "v3.45.0" stay intact.
+    //
+    // Abbreviations are excluded by name. "Fixed e.g. the matcher" would
+    // otherwise end after two words, which is worse than a long line: it reads
+    // as a complete thought and is not one. This list covers what actually turns
+    // up in release prose rather than trying to be exhaustive.
+    // `etc.` is deliberately absent: it ends a sentence as often as it continues
+    // one, so either choice is wrong half the time and the wrong one here merges
+    // two sentences rather than truncating one. Merging is the milder failure,
+    // and the length cap below bounds it.
+    const ABBREV = /\b(?:e\.g|i\.e|vs|cf|Dr|Mr|Ms|St|approx|no)\.$/i;
+    const parts = item.split(/(?<=[.。])(?:\s+|(?=[A-Z가-힣]))/);
+    let first = parts[0];
+    for (let k = 1; k < parts.length && ABBREV.test(first); k += 1) {
+      // The stop belonged to an abbreviation, so the sentence continues.
+      first = `${first} ${parts[k]}`;
+    }
+    item = first || item;
+    // Some first sentences are themselves a paragraph. Those get cut, but at a
+    // word boundary and with the ellipsis that says so.
+    if (item.length > MAX_HIGHLIGHT_LEN) {
+      const cut = item.slice(0, MAX_HIGHLIGHT_LEN);
+      const space = cut.lastIndexOf(' ');
+      item = (space > 40 ? cut.slice(0, space) : cut).replace(/[,;:—\-]$/, '').trim() + '…';
+    }
+    out.push(item);
+    if (out.length >= MAX_HIGHLIGHTS) break;
+  }
+  return out;
+}
+
+/**
+ * Fetch the highlights for one version. Returns [] on any failure: the notice
+ * is worth showing with a bare version number, so a missing release, a rate
+ * limit, or an offline machine must not cost the user the notice itself.
+ */
+export async function fetchHighlights(version, { timeoutMs = FETCH_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${RELEASES_API}/v${version}`, {
+      signal: controller.signal,
+      headers: { accept: 'application/vnd.github+json' },
+    });
+    if (!res.ok) throw new Error(`releases responded ${res.status}`);
+    const body = await res.json();
+    return releaseHighlights(body && body.body);
+  } catch (e) {
+    debug('update-check:highlights', e);
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
  * Actually hit the registry and persist the answer. Only the detached child
  * and the explicit `update-check --refresh` command call this.
@@ -168,6 +290,21 @@ export async function refreshUpdateState(currentVersion) {
     if (prev.dismissedVersion && isNewer(latest, prev.dismissedVersion)) {
       delete next.dismissedVersion;
     }
+    // What the new version adds, so the notice can answer "why would I".
+    // Only worth a second request when there is actually an upgrade to describe,
+    // and only when we do not already hold the notes for that exact version.
+    if (isNewer(latest, currentVersion) && prev.highlightsFor !== latest) {
+      const highlights = await fetchHighlights(latest);
+      if (highlights.length) {
+        next.highlights = highlights;
+        next.highlightsFor = latest;
+      } else {
+        // Drop notes belonging to an older version rather than showing them
+        // against this one.
+        delete next.highlights;
+        delete next.highlightsFor;
+      }
+    }
     writeUpdateState(next);
     return { ok: true, latest };
   } catch (e) {