claude-token-saver 3.24.0 → 3.25.0

package/README.en.md

@@ -130,6 +130,8 @@ With an empty ledger (no measured delegation yet) row 1 is not drawn and the lay
 | `✦ current` / `📅 weekly` | 5-hour / 7-day rate-limit window usage + reset time |
 | `📦` | Context usage (e.g. `Ctx 68% of 1M`) — colored by fill. Current models default to 1M with no premium, but token volume itself drives per-turn cost and 5H/7D burn |
 | `💰` | Cumulative savings from prompt caching — a **different** number from row 1's `🔀` (model routing) |
+| `v3.24.0` | The version you are running. Gray, at the tail, when it is the latest one |
+| `⬆ v3.24.0 → 3.25.0` | A newer release exists. Actionable, so it moves to the front of the line ([Update notifications](#-update-notifications)) |
 
 When something is wrong, a **warning chip leads the line**:
 
@@ -161,6 +163,9 @@ Run these in your shell (inside Claude Code, the `/claude-token-saver` Skill is
 | `claude-token-saver korean on\|off\|status` | Inject Korean writing guidance at session start and install the write-time check (below) |
 | `claude-token-saver korean lint block\|warn\|off` | How the write-time check handles findings |
 | `claude-token-saver korean lint scope all\|prose` | Check every text file, or documents only |
+| `claude-token-saver --version` | Print the installed version |
+| `claude-token-saver update-check` | Is a newer version out? (`--refresh` to ask now, `--dismiss` to mute this version's offer) |
+| `claude-token-saver upgrade` | Install the latest release with the package manager that installed this copy (`--print` shows the command only) |
 | `claude-token-saver install` | Manually register Skill + statusline |
 
 Switch output language with `mode ko` / `mode en` (English default; statusline chips stay symbolic).
@@ -184,6 +189,16 @@ Switch output language with `mode ko` / `mode en` (English default; statusline c
 | `--install-hook` / `--uninstall-hook` | Manage the PostToolUse hook | – |
 </details>
 
+## ⬆ Update notifications
+
+A statusline cannot open a dialog, and it re-renders every ~300ms, so it can never touch the network while drawing. The notification is therefore split in two:
+
+- **The statusline tells you.** Up to date: a quiet gray `v3.24.0` at the tail. Newer release out: `⬆ v3.24.0 → 3.25.0` in yellow, moved to the front. Never red — nothing is broken.
+- **Session start asks you.** On a new session or `/clear`, the SessionStart hook injects one line telling the model a newer version exists and to ask before installing anything. Only after you agree does it run `claude-token-saver upgrade`.
+- **Declining sticks.** `claude-token-saver update-check --dismiss` mutes the offer for that version; the next release asks again. The statusline chip stays — you declined the question, not the fact.
+
+The registry lookup runs at most once every 24h in a detached background process and only ever writes a cache file (`update-check.json`) — the same shape npm's `update-notifier` uses. A failed check still stamps its timestamp, so an offline machine backs off instead of retrying on every render. Turn checks off entirely with `CTS_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER`.
+
 ## 🅷 Harness mode
 
 Bootstrap five engineering principles (Ratchet · Evidence · PEV · Structured Task · Default Safe Path) into `CLAUDE.md` with one command; the statusline scores it as `🅷 5/5`. When the same error keeps recurring, a `🅷⚠ ratchet?` nudge appears so you can promote it to a rule.
@@ -439,6 +454,11 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.25.0 (2026-09-04)
+- **The statusline now shows which version is running** — until now the version lived only in the table report's footer, so "which version am I on" meant running a full report. A `--version` flag was added alongside it.
+- **A new release asks at session start** — a statusline cannot open a dialog, so telling and asking are split. The statusline only reports (`⬆ v3.24.0 → 3.25.0`); the SessionStart hook injects a line telling the model to ask the user whether to upgrade. On yes it runs `claude-token-saver upgrade`, which uses the package manager that installed this copy; on no, `update-check --dismiss` mutes that version until a newer one ships.
+- **The check never blocks a render** — the registry lookup runs at most once every 24h in a detached background process, and the render path only reads the cache file. A failed check still stamps its timestamp, so an offline machine backs off instead of retrying every render. Disable with `CTS_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER`.
+
 ### v3.21.0 (2026-08-22)
 - **The install shows what it is about to enable, then asks** — the harness 5 principles and the Korean writing guidance used to be switched on by the installer, leaving the user with the result rather than the choice. The install now prints the five principle headings, and for the Korean guidance what it changes plus its per-session cost and source, before asking. Locale detection is demoted from an answer to the question's default, so an English-locale machine used for Korean work can enable it on the spot.
 - **Unattended installs behave exactly as before** — npm `postinstall`, CI, piped stdin and `CTS_NO_INPUT=1` skip the question and apply the old defaults, because a blocked prompt hangs an install. `--yes` and `--no-input` force that path explicitly. A non-interactive install on a non-Korean machine now leaves the setting undecided instead of recording an answer nobody gave, so a later run at a terminal still asks.

package/README.md

@@ -129,6 +129,8 @@ npm i -g claude-token-saver
 | `✦ current` / `📅 weekly` | 5시간 / 7일 rate-limit 윈도 사용률 + 리셋 시각 |
 | `📦` | 컨텍스트 사용률입니다(예: `Ctx 68% of 1M`). 사용률에 따라 녹색·노란색·빨간색으로 표시합니다. 최신 모델은 1M 컨텍스트가 기본이고 별도 요금이 붙지 않지만, 토큰량 자체가 턴당 비용과 5시간·7일 한도를 빠르게 소모시킵니다 |
 | `💰` | 프롬프트 캐시가 절약해 준 누적 금액입니다. 첫째 줄의 `🔀`(모델 라우팅 절감액)와는 **서로 다른 수치입니다** |
+| `v3.24.0` | 지금 실행 중인 claude-token-saver의 버전입니다. 최신이면 회색으로 줄 끝에 조용히 놓입니다 |
+| `⬆ v3.24.0 → 3.25.0` | 새 버전이 배포되어 있다는 표시입니다. 조치가 필요한 칩이므로 줄 앞쪽으로 올라옵니다 ([업데이트 안내](#-업데이트-안내)) |
 
 문제가 감지되면 **경고 칩을 줄 맨 앞에** 붙입니다.
 
@@ -160,10 +162,23 @@ Claude Code 안에서 `/claude-token-saver` Skill을 실행하거나, 칩에 적
 | `claude-token-saver korean on\|off\|status` | 한국어 문체 지침을 세션 시작 시 주입하고, 쓰기 시점 검사를 함께 설치합니다 (아래 참고) |
 | `claude-token-saver korean lint block\|warn\|off` | 쓰기 시점 검사가 위반을 어떻게 처리할지 정합니다 |
 | `claude-token-saver korean lint scope all\|prose` | 검사 범위를 모든 텍스트 파일과 문서 전용 사이에서 고릅니다 |
+| `claude-token-saver --version` | 설치된 버전을 출력합니다 |
+| `claude-token-saver update-check` | 새 버전이 있는지 확인합니다 (`--refresh`로 즉시 조회, `--dismiss`로 그 버전 안내 끄기) |
+| `claude-token-saver upgrade` | 설치 경로에 맞는 명령으로 최신 버전을 설치합니다 (`--print`로 실행 없이 명령만 확인) |
 | `claude-token-saver install` | Skill·statusline 수동 등록 |
 
 출력 언어는 `mode ko`와 `mode en`으로 전환합니다. 기본값은 영어이며, statusline의 칩은 언제나 기호로 표시합니다. 전체 옵션은 [영문 README](./README.en.md#options)를 참고하십시오.
 
+## ⬆ 업데이트 안내
+
+statusline은 대화 상자를 띄울 수 없고, 300밀리초마다 다시 그려지기 때문에 그리는 시점에 네트워크를 쓸 수도 없습니다. 그래서 안내를 두 지점으로 나누었습니다.
+
+- **statusline은 알리기만 합니다.** 최신 버전이면 줄 끝에 `v3.24.0`을 회색으로 조용히 표시하고, 새 버전이 있으면 `⬆ v3.24.0 → 3.25.0`을 줄 앞쪽에 노란색으로 올립니다. 빨간색은 쓰지 않습니다. 무엇도 고장 난 상태가 아니기 때문입니다.
+- **묻는 일은 세션 시작에서 합니다.** 새 세션이나 `/clear` 시점에 SessionStart 훅이 "새 버전이 있으니 사용자에게 업그레이드할지 물어보라"는 한 줄을 모델에게 주입합니다. 모델은 사용자에게 확인한 뒤에만 `claude-token-saver upgrade`를 실행합니다. 묻지 않고 설치하지 않습니다.
+- **거절은 기억합니다.** 사용자가 원치 않으면 `claude-token-saver update-check --dismiss`로 그 버전을 묻지 않도록 설정합니다. 더 새로운 버전이 배포되면 다시 묻습니다. statusline 칩은 그대로 남습니다. 거절한 것은 질문이지, 새 버전이 있다는 사실이 아니기 때문입니다.
+
+버전 조회는 24시간에 한 번, 분리된 백그라운드 프로세스가 수행하고 결과만 파일에 남깁니다(`update-check.json`). 이 방식은 npm의 `update-notifier`가 쓰는 것과 같습니다. 네트워크가 끊겨 있어도 실패 시각을 기록해 두므로 매 렌더마다 재시도하지 않습니다. 확인 자체를 끄려면 환경 변수 `CTS_NO_UPDATE_CHECK=1` 또는 `NO_UPDATE_NOTIFIER`를 설정하십시오.
+
 ## 🅷 Harness 모드
 
 다섯 원칙(Ratchet · Evidence · PEV · Structured Task · Default Safe Path)을 한 줄 명령으로 `CLAUDE.md`에 셋업하고 statusline이 `🅷 5/5`로 점수화합니다. 같은 에러가 반복되면 `🅷⚠ ratchet?` 알림이 떠서 룰로 승격할 수 있습니다.
@@ -405,6 +420,11 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.25.0 (2026-09-04)
+- **statusline에 실행 중인 버전을 표시합니다.** 지금까지는 표 형식 리포트의 각주에만 버전이 있었기 때문에, 어떤 버전이 도는지 확인하려면 전체 리포트를 실행해야 했습니다. `--version` 플래그도 함께 추가했습니다.
+- **새 버전이 나오면 세션 시작에 물어봅니다.** statusline은 대화 상자를 띄울 수 없으므로, 알림과 질문을 나누었습니다. statusline은 `⬆ v3.24.0 → 3.25.0`으로 알리기만 하고, 실제 질문은 SessionStart 훅이 모델에게 "사용자에게 업그레이드 여부를 확인하라"고 주입해서 이루어집니다. 승낙하면 `claude-token-saver upgrade`가 설치 경로에 맞는 명령을 실행하고, 거절하면 `update-check --dismiss`가 그 버전을 더 묻지 않도록 기록합니다.
+- **버전 확인이 렌더를 붙잡지 않습니다.** 조회는 24시간에 한 번 분리된 백그라운드 프로세스가 수행하고, 렌더 경로는 캐시 파일만 읽습니다. 확인에 실패해도 시각을 기록하므로 오프라인에서 매 렌더마다 재시도하지 않습니다. `CTS_NO_UPDATE_CHECK=1` 또는 `NO_UPDATE_NOTIFIER`로 끌 수 있습니다.
+
 ### v3.21.0 (2026-08-22)
 - **설치가 무엇을 켜는지 보여 준 뒤 물어봅니다** — 지금까지는 🅷 Harness 5원칙과 한국어 문체 지침을 설치가 스스로 켰고, 사용자는 결과만 볼 수 있었습니다. 이제 harness는 다섯 원칙의 제목을, 한국어 지침은 바꾸는 내용과 세션당 비용과 출처를 먼저 출력한 다음 켤지 묻습니다. 로캘 감지는 답이 아니라 질문의 기본값으로 내려왔으므로, 영어 로캘에서 한국어로 작업하는 경우에도 그 자리에서 켤 수 있습니다.
 - **사람이 붙어 있지 않은 설치는 예전대로 동작합니다** — npm의 `postinstall`, CI, 파이프 입력, `CTS_NO_INPUT=1`에서는 질문을 건너뛰고 기존 기본값을 그대로 적용합니다. 프롬프트가 멈춰 서면 설치가 걸리기 때문입니다. `--yes`와 `--no-input`으로 직접 강제할 수도 있습니다. 비대화형이면서 로캘이 한국어가 아닌 경우에는 설정을 저장하지 않고 미결정으로 남겨 두므로, 나중에 터미널에서 설치하면 그때 물어봅니다.

package/bin/cli.js

@@ -52,6 +52,7 @@ import { estimateCost } from '../src/cost.js';
 import { chipForIssues } from '../src/advice.js';
 import { debug } from '../src/debug.js';
 import { createArgs } from '../src/cli-args.js';
+import { updateStatus, maybeSpawnUpdateCheck } from '../src/update-check.js';
 
 const args = process.argv.slice(2);
 
@@ -66,6 +67,22 @@ const PKG_VERSION = (() => {
 
 const { getArg, hasFlag, numArg } = createArgs(args);
 
+/**
+ * Version/update state for the statusline chip. Reads a cache file and, when
+ * that cache has aged past the check interval, kicks a detached child to
+ * refresh it for a later render. Never awaits the network, never throws into
+ * the render: a registry outage must not cost the statusline its other chips.
+ */
+function readUpdateChip() {
+  try {
+    maybeSpawnUpdateCheck(PKG_VERSION);
+    return updateStatus(PKG_VERSION);
+  } catch (e) {
+    debug('update-check:chip', e);
+    return null;
+  }
+}
+
 async function main() {
   // Subcommand: last — print the most recent warning + how to handle it.
   // Designed for the auto-trigger skill so the user immediately sees
@@ -166,6 +183,37 @@ async function main() {
     return (await import('../src/commands/compact-window.js')).run({ args, hasFlag });
   }
 
+  // `--version` / `-v` — the flag every CLI is expected to answer. Until now
+  // the version was only visible in the table view's footer, which meant
+  // "which version am I on" required running a full report.
+  if (hasFlag('--version') || hasFlag('-v')) {
+    console.log(PKG_VERSION);
+    return;
+  }
+
+  // Subcommand: update-check — the registry lookup behind the ⬆ statusline
+  // chip and the session-start upgrade offer.
+  //   claude-token-saver update-check              # print cached status
+  //   claude-token-saver update-check --refresh    # hit the registry now (detached child uses this)
+  //   claude-token-saver update-check --dismiss    # stop offering THIS version at session start
+  if (args[0] === 'update-check') {
+    return (await import('../src/commands/update-check.js')).run({
+      hasFlag,
+      version: PKG_VERSION,
+    });
+  }
+
+  // Subcommand: upgrade — run the install command that matches how this copy
+  // got here, then confirm the new version.
+  //   claude-token-saver upgrade          # install the latest release
+  //   claude-token-saver upgrade --print  # just show the command, run nothing
+  if (args[0] === 'upgrade') {
+    return (await import('../src/commands/upgrade.js')).run({
+      hasFlag,
+      version: PKG_VERSION,
+    });
+  }
+
   // Hook management
   if (hasFlag('--install-hook')) {
     const { installHook } = await import('../src/hook-manager.js');
@@ -319,7 +367,7 @@ async function main() {
         } catch (e) { debug('caps-cache:persist', e); }
       }
       console.log(formatNoSession(
-        { caps, model, windowLabel },
+        { caps, model, windowLabel, version: PKG_VERSION, update: readUpdateChip() },
         { color: colorOk, mode: isIcon ? 'icon' : 'text' },
       ));
       return;
@@ -471,6 +519,8 @@ async function main() {
     anomalies,
     cost,
     options: { days, windowHours, windowLabel, version: PKG_VERSION },
+    // Cached-only; the background refresh it may trigger lands on a later render.
+    update: format === 'statusline' ? readUpdateChip() : null,
     lastActivity,
     spikeReport,
     contextWindow,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.24.0",
+  "version": "3.25.0",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/src/commands/route-scan.js

@@ -2,9 +2,23 @@
 
  */
 
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { readStdinJson } from '../stdin-payload.js';
 import { debug } from '../debug.js';
 
+/** This package's own version — the baseline the upgrade offer compares against. */
+function readPackageVersion() {
+  try {
+    const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    return JSON.parse(readFileSync(pkg, 'utf8')).version || null;
+  } catch (e) {
+    debug('route-scan:pkg-version', e);
+    return null;
+  }
+}
+
 export async function run({ args, hasFlag, numArg }) {
     const rs = await import('../route-scan.js');
     const { userLanguage } = await import('../config.js');
@@ -190,10 +204,44 @@ export async function run({ args, hasFlag, numArg }) {
         koreanBlock = koreanStyleInjection();
       } catch (e) { debug('route-scan:korean-style', e); /* style is optional */ }
 
+      // Upgrade offer. A statusline cannot open a dialog, so session start is
+      // where the *asking* happens: the model gets one line telling it a newer
+      // version exists and to ask before installing anything. Cached read only
+      // — the refresh runs detached off the statusline path, never here.
+      let updateBlock = null;
+      try {
+        const { updateStatus, maybeSpawnUpdateCheck } = await import('../update-check.js');
+        const pkgVersion = readPackageVersion();
+        // Session start is the one moment where a stale cache matters most, so
+        // kick the detached refresh here too. It lands in time for the
+        // statusline and for the next session, not for this line.
+        if (pkgVersion) maybeSpawnUpdateCheck(pkgVersion);
+        const u = pkgVersion ? updateStatus(pkgVersion) : null;
+        // `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) {
+          updateBlock = lang === 'ko'
+            ? [
+                `[claude-token-saver update] 새 버전이 나와 있습니다: v${u.current} → ${u.latest}.`,
+                '사용자에게 지금 업그레이드할지 물어보고, 승낙하면 아래 명령을 실행하십시오. 묻지 않고 설치하지는 마십시오.',
+                '  claude-token-saver upgrade            # 업그레이드 실행',
+                '  claude-token-saver update-check --dismiss   # 사용자가 원치 않으면 (다음 버전이 나올 때까지 다시 묻지 않습니다)',
+              ].join('\n')
+            : [
+                `[claude-token-saver 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.',
+                '  claude-token-saver upgrade                  # perform the upgrade',
+                '  claude-token-saver update-check --dismiss   # if they decline (stays quiet until a newer release)',
+              ].join('\n');
+        }
+      } catch (e) { debug('route-scan:update-check', e); /* the offer is optional */ }
+
       if (open.length === 0 && reviewRules.length === 0) {
+        if (updateBlock) console.log(updateBlock);
         if (koreanBlock) console.log(koreanBlock);
         return; // nothing else to inject
       }
+      if (updateBlock) console.log(updateBlock);
       // This text is injected straight into the model's context, so it must
       // follow the user's configured language — a Korean-only briefing in an
       // English session steers the whole first response into Korean.

package/src/commands/update-check.js

@@ -0,0 +1,77 @@
+/**
+ * Subcommand: update-check — everything around "is a newer version out".
+ *
+ *   claude-token-saver update-check              # print the cached answer
+ *   claude-token-saver update-check --refresh    # ask the registry now
+ *   claude-token-saver update-check --refresh --quiet
+ *                                                # what the detached background child runs
+ *   claude-token-saver update-check --dismiss    # stop offering this version at session start
+ *
+ * The statusline never calls the --refresh path directly; it spawns this
+ * command detached so the render itself stays offline and instant.
+ */
+
+export async function run({ hasFlag, version }) {
+  const {
+    updateStatus,
+    refreshUpdateState,
+    dismissUpdate,
+    upgradeCommand,
+    updateCheckDisabled,
+    updateStatePath,
+  } = await import('../update-check.js');
+  const { userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+  const quiet = hasFlag('--quiet');
+
+  if (hasFlag('--refresh')) {
+    const res = await refreshUpdateState(version);
+    if (quiet) return;
+    if (!res.ok) {
+      console.error(lang === 'ko'
+        ? `최신 버전을 확인하지 못했습니다: ${res.error}`
+        : `Could not reach the registry: ${res.error}`);
+      process.exit(1);
+    }
+  }
+
+  if (hasFlag('--dismiss')) {
+    const s = updateStatus(version);
+    if (s.latest) dismissUpdate(s.latest);
+    console.log(lang === 'ko'
+      ? `${s.latest || '최신'} 버전 안내를 끕니다. 그 다음 버전이 나오면 다시 안내합니다.`
+      : `Muted the ${s.latest || 'latest'} notice. The next release after it will ask again.`);
+    return;
+  }
+
+  if (updateCheckDisabled()) {
+    console.log(lang === 'ko'
+      ? `현재 버전 v${version} — 업데이트 확인이 환경 변수로 꺼져 있습니다 (CTS_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER).`
+      : `v${version} — update checks are disabled by env var (CTS_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER).`);
+    return;
+  }
+
+  const s = updateStatus(version);
+  if (s.available) {
+    console.log(lang === 'ko'
+      ? `새 버전이 있습니다: v${version} → ${s.latest}`
+      : `Update available: v${version} → ${s.latest}`);
+    console.log(lang === 'ko'
+      ? `업그레이드: ${upgradeCommand()}   (또는 claude-token-saver upgrade)`
+      : `Upgrade with: ${upgradeCommand()}   (or: claude-token-saver upgrade)`);
+    if (s.dismissed) {
+      console.log(lang === 'ko'
+        ? '이 버전은 사용자가 한 번 넘긴 상태라, 세션 시작 시에는 다시 묻지 않습니다.'
+        : 'This version was dismissed, so the session-start offer stays quiet for it.');
+    }
+    return;
+  }
+  console.log(lang === 'ko'
+    ? `최신 버전을 쓰고 있습니다 (v${version}).`
+    : `Up to date (v${version}).`);
+  if (!s.latest) {
+    console.log(lang === 'ko'
+      ? `아직 확인된 기록이 없습니다. 지금 확인하려면: claude-token-saver update-check --refresh (기록 파일: ${updateStatePath()})`
+      : `No check has completed yet. Run: claude-token-saver update-check --refresh (state: ${updateStatePath()})`);
+  }
+}

package/src/commands/upgrade.js

@@ -0,0 +1,68 @@
+/**
+ * Subcommand: upgrade — install the latest release with the package manager
+ * that put this copy on disk.
+ *
+ *   claude-token-saver upgrade          # refresh the check, then install
+ *   claude-token-saver upgrade --print  # show the command, run nothing
+ *
+ * This is the command the model runs after the user says yes to the
+ * session-start offer, so it prints the exact command it is about to execute
+ * before executing it: an install that writes outside the project should never
+ * be a black box.
+ */
+
+import { spawn } from 'node:child_process';
+
+function runCommand(cmd) {
+  return new Promise((resolve) => {
+    // Shell form: the upgrade command is a fixed string we composed ourselves
+    // (no user input reaches it), and `npm install -g` needs the user's PATH
+    // resolution to find the same npm that installed us.
+    const child = spawn(cmd, { shell: true, stdio: 'inherit' });
+    child.on('close', (code) => resolve(code === null ? 1 : code));
+    child.on('error', () => resolve(1));
+  });
+}
+
+export async function run({ hasFlag, version }) {
+  const { updateStatus, refreshUpdateState, upgradeCommand } = await import('../update-check.js');
+  const { userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+  const cmd = upgradeCommand();
+
+  if (hasFlag('--print')) {
+    console.log(cmd);
+    return;
+  }
+
+  // Refresh first so the "already latest" answer is trustworthy rather than up
+  // to 24h stale — an upgrade is a deliberate, interactive action, so one
+  // network round trip is fine here.
+  await refreshUpdateState(version);
+  const s = updateStatus(version);
+  if (!s.available) {
+    console.log(lang === 'ko'
+      ? `이미 최신 버전입니다 (v${version}). 설치할 것이 없습니다.`
+      : `Already on the latest version (v${version}). Nothing to install.`);
+    return;
+  }
+
+  console.log(lang === 'ko'
+    ? `v${version} → ${s.latest} 로 업그레이드합니다.`
+    : `Upgrading v${version} → ${s.latest}.`);
+  console.log(`$ ${cmd}`);
+  const code = await runCommand(cmd);
+  if (code !== 0) {
+    console.error(lang === 'ko'
+      ? `업그레이드 명령이 종료 코드 ${code}로 실패했습니다. 위 출력을 확인하고, 권한 문제라면 sudo 없이 설치되는 전역 경로인지 점검하십시오.`
+      : `Upgrade command failed with exit code ${code}. Check the output above; if it is a permissions error, verify your global install prefix.`);
+    process.exit(code);
+  }
+  // The freshly installed copy is a different file on disk, so this process
+  // still reports the old version. Refresh the cache against the new latest so
+  // the statusline chip clears on the next render instead of lingering.
+  await refreshUpdateState(s.latest);
+  console.log(lang === 'ko'
+    ? `설치가 끝났습니다. 새 셸에서 claude-token-saver --version 으로 ${s.latest} 인지 확인하십시오.`
+    : `Done. In a fresh shell, run claude-token-saver --version to confirm ${s.latest}.`);
+}

package/src/formatters/statusline.js

@@ -157,6 +157,33 @@ function buildKoreanSeg(c, isIcon, verbose) {
   }
 }
 
+/**
+ * Version segment builder — "which copy of this tool am I looking at", plus
+ * the upgrade nudge when a newer one has been published.
+ *
+ * Two states, deliberately different in weight:
+ *   - up to date  → `v3.24.0` in gray. Identity context, not news.
+ *   - update available → `⬆ v3.24.0 → 3.25.0` in yellow. Same tone as the
+ *     other "you should do something eventually" chips, never red: nothing is
+ *     broken, and a permanently-red statusline trains the eye to ignore red.
+ *
+ * A statusline cannot open a dialog, so the *asking* happens at session start
+ * (see route-scan --hook, which briefs the model to offer the upgrade). This
+ * chip is the persistent reminder between those offers, which is why it keeps
+ * rendering after the user declines — declining hides the session-start
+ * question, not the fact that a new version exists.
+ */
+function buildVersionSeg(version, update, c, isIcon, verbose) {
+  if (!version) return null;
+  if (update && update.available && update.latest) {
+    const body = verbose
+      ? `Update v${version} → ${update.latest}`
+      : `v${version} → ${update.latest}`;
+    return `${c(YELLOW)}${isIcon ? '⬆ ' : ''}${body}${c(RESET)}`;
+  }
+  return `${c(GRAY)}v${version}${c(RESET)}`;
+}
+
 /**
  * Harness 🅷 segment builder — shared by the full report and the no-session
  * fallback line. Best-effort: never throws into the statusline (corrupted
@@ -209,18 +236,21 @@ function buildCapWarnSeg(capWarn, c, isIcon) {
  * just because the user has been idle past the window — so cap-warn,
  * harness, and model chips still render around the "no session data" note.
  */
-export function formatNoSession({ caps = null, model = null, windowLabel = '' } = {}, { color = true, mode = 'icon' } = {}) {
+export function formatNoSession({ caps = null, model = null, windowLabel = '', version = '', update = null } = {}, { color = true, mode = 'icon' } = {}) {
   const c = (v) => (color ? v : '');
   const isIcon = mode === 'icon';
   const segs = [];
   const capSeg = buildCapWarnSeg(pickCapWarn(caps), c, isIcon);
   if (capSeg) segs.push(capSeg);
+  const versionSeg = buildVersionSeg(version, update, c, isIcon, false);
+  if (versionSeg && update && update.available) segs.push(versionSeg);
   const harnessSeg = buildHarnessSeg(c, isIcon);
   if (harnessSeg) segs.push(harnessSeg);
   if (typeof model === 'string' && model.length > 0) {
     segs.push(isIcon ? `${c(MAGENTA)}🤖 ${model}${c(RESET)}` : `${c(MAGENTA)}${model}${c(RESET)}`);
   }
   segs.push(`${c(GRAY)}🧠 no session data${windowLabel ? ` · ${windowLabel}` : ''}${c(RESET)}`);
+  if (versionSeg && !(update && update.available)) segs.push(versionSeg);
   return segs.join(' · ') + (color ? '\x1b[K' : '');
 }
 
@@ -231,7 +261,7 @@ export function formatNoSession({ caps = null, model = null, windowLabel = '' }
  * @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] - whitelist of segments to render. Names: cap-warn, spike, harness, korean, model, hit, ttl, saved, delegated, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
+ * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, version, harness, korean, model, hit, ttl, saved, delegated, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
  * @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 } = {}) {
@@ -446,6 +476,11 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // a missing section at a glance and know to run `harness init`.
   const harnessSeg = buildHarnessSeg(c, isIcon);
 
+  // Version / upgrade chip. Read from a cache written by a detached background
+  // check — this render path never touches the network.
+  const versionSeg = buildVersionSeg(options.version, data.update, c, isIcon, verbose);
+  const updateAvailable = !!(data.update && data.update.available);
+
   // Korean-style chip — rendered only when the session-start injection is on.
   const koreanSeg = buildKoreanSeg(c, isIcon, verbose);
 
@@ -550,6 +585,10 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   const segs = [];
   if (capWarnSeg && want('cap-warn')) segs.push(capWarnSeg);
   if (spikeSeg && want('spike')) segs.push(spikeSeg);
+  // An available upgrade rides up front with the other "act on this" chips.
+  // When there is nothing to upgrade to, the same segment is pure identity and
+  // sits at the tail instead (pushed after `saved`, below).
+  if (versionSeg && updateAvailable && want('version')) segs.push(versionSeg);
   if (harnessSeg && want('harness')) segs.push(harnessSeg);
   if (koreanSeg && want('korean')) segs.push(koreanSeg);
   if (modelSeg && want('model')) segs.push(modelSeg);
@@ -569,6 +608,7 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // it sits near the tail. The period label closes the line as a quiet
   // timeframe footer.
   if (want('saved')) segs.push(saveSeg);
+  if (versionSeg && !updateAvailable && want('version')) segs.push(versionSeg);
   if (want('period')) segs.push(periodSeg);
   // Trailing erase-to-end-of-line so any leftover characters from a previous
   // (longer) statusline render don't bleed into ours. \x1b[K is the standard

package/src/update-check.js

@@ -0,0 +1,198 @@
+/**
+ * update-check — "is there a newer claude-token-saver?", answered without ever
+ * blocking a render.
+ *
+ * The statusline command runs every ~300ms, so a network call on that path is
+ * out of the question. We use the same shape sindresorhus/update-notifier
+ * settled on: the foreground only ever READS a cached answer, and when that
+ * answer is older than the check interval it spawns a detached, unref'd child
+ * that refreshes the cache for the *next* render. Nothing awaits the network.
+ *
+ * State lives next to the other user-data files:
+ *   { checkedAt: <ms>, latest: "3.25.0", current: "3.24.0",
+ *     dismissedVersion: "3.25.0"|undefined }
+ *
+ * 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).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { userDataDir } from './paths.js';
+import { debug } from './debug.js';
+
+const PKG_NAME = 'claude-token-saver';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h — the registry is not a health endpoint
+const FETCH_TIMEOUT_MS = 5000;
+
+export function updateStatePath() {
+  return join(userDataDir(), 'update-check.json');
+}
+
+export function updateCheckDisabled() {
+  return process.env.CTS_NO_UPDATE_CHECK === '1' || !!process.env.NO_UPDATE_NOTIFIER;
+}
+
+export function readUpdateState() {
+  try {
+    const s = JSON.parse(readFileSync(updateStatePath(), 'utf8'));
+    return s && typeof s === 'object' ? s : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeUpdateState(next) {
+  const dir = userDataDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(updateStatePath(), JSON.stringify(next, null, 2) + '\n');
+}
+
+/**
+ * Compare two semver-ish strings. Returns true when `a` is strictly newer than
+ * `b`. Pre-release tags (`3.25.0-beta.1`) are treated as older than the plain
+ * release, which is what we want: we never nudge anyone onto a pre-release.
+ */
+export function isNewer(a, b) {
+  const parse = (v) => {
+    const m = String(v || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+    if (!m) return null;
+    return { nums: [+m[1], +m[2], +m[3]], pre: m[4] || null };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return false;
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] > pb.nums[i];
+  }
+  if (pa.pre && !pb.pre) return false; // 3.25.0-beta < 3.25.0
+  if (!pa.pre && pb.pre) return true;
+  return false;
+}
+
+/**
+ * The read-only accessor every render path uses.
+ *
+ * @returns {{current: string, latest: string|null, available: boolean, dismissed: boolean, stale: boolean}}
+ */
+export function updateStatus(currentVersion) {
+  if (updateCheckDisabled()) {
+    return { current: currentVersion, latest: null, available: false, dismissed: false, stale: false };
+  }
+  const s = readUpdateState();
+  const latest = typeof s.latest === 'string' ? s.latest : null;
+  const available = !!latest && isNewer(latest, currentVersion);
+  const age = Date.now() - (Number(s.checkedAt) || 0);
+  return {
+    current: currentVersion,
+    latest,
+    available,
+    // A version the user already declined stays out of the statusline and out
+    // of the session briefing until a newer one ships — otherwise "no thanks"
+    // means "ask me again in five minutes", forever.
+    dismissed: available && s.dismissedVersion === latest,
+    stale: age >= CHECK_INTERVAL_MS,
+  };
+}
+
+/**
+ * Fire the background refresh when the cached answer has aged out. Returns
+ * immediately in every case; the child is detached and unref'd so it cannot
+ * hold the statusline process open.
+ */
+export function maybeSpawnUpdateCheck(currentVersion) {
+  if (updateCheckDisabled()) return false;
+  const { stale } = updateStatus(currentVersion);
+  if (!stale) return false;
+  // Stamp the attempt before spawning. Without this, an offline machine
+  // re-spawns a doomed child on every single statusline render — several per
+  // second — because the cache never gets a fresh timestamp.
+  try {
+    writeUpdateState({ ...readUpdateState(), checkedAt: Date.now(), current: currentVersion });
+  } catch (e) {
+    debug('update-check:stamp', e);
+    return false;
+  }
+  try {
+    spawn(process.execPath, [cliEntryPath(), 'update-check', '--refresh', '--quiet'], {
+      detached: true,
+      stdio: 'ignore',
+    }).unref();
+    return true;
+  } catch (e) {
+    debug('update-check:spawn', e);
+    return false;
+  }
+}
+
+/** Path to this package's CLI entry point (bin/cli.js). */
+export function cliEntryPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'cli.js');
+}
+
+/**
+ * Actually hit the registry and persist the answer. Only the detached child
+ * and the explicit `update-check --refresh` command call this.
+ */
+export async function refreshUpdateState(currentVersion) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  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`, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) throw new Error(`registry responded ${res.status}`);
+    const body = await res.json();
+    const latest = typeof body.version === 'string' ? body.version : null;
+    if (!latest) throw new Error('registry response carried no version');
+    const prev = readUpdateState();
+    const next = { ...prev, checkedAt: Date.now(), latest, current: currentVersion };
+    // A newly published version clears an older dismissal: the user declined
+    // 3.25.0, not "all future upgrades".
+    if (prev.dismissedVersion && isNewer(latest, prev.dismissedVersion)) {
+      delete next.dismissedVersion;
+    }
+    writeUpdateState(next);
+    return { ok: true, latest };
+  } catch (e) {
+    debug('update-check:refresh', e);
+    // Keep the timestamp fresh even on failure so an offline machine backs off
+    // for the full interval instead of retrying on every render.
+    try {
+      writeUpdateState({ ...readUpdateState(), checkedAt: Date.now(), current: currentVersion });
+    } catch (e2) {
+      debug('update-check:refresh-stamp', e2);
+    }
+    return { ok: false, error: String(e && e.message ? e.message : e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Record that the user said "not now" for this exact version. */
+export function dismissUpdate(version) {
+  const s = readUpdateState();
+  writeUpdateState({ ...s, dismissedVersion: version });
+}
+
+/**
+ * How this copy was installed, and therefore what command upgrades it.
+ * Best-effort: the install root is the only reliable signal we have, and when
+ * it tells us nothing we fall back to the npm global install, which is how the
+ * overwhelming majority of copies got here.
+ */
+export function upgradeCommand() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  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`;
+  return `npm install -g ${PKG_NAME}@latest`;
+}
+
+export const UPDATE_CHECK_INTERVAL_MS = CHECK_INTERVAL_MS;
+export const PACKAGE_NAME = PKG_NAME;