ctxline-claude 1.6.1 → 1.7.0

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="docs/assets/apple-touch-icon.png" width="64" height="64" alt="">
+</p>
+
 <h1 align="center">Claude Code Statusline</h1>
 
 <p align="center">
@@ -5,21 +9,14 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/ctxline-claude">
-    <img src="https://img.shields.io/npm/v/ctxline-claude" alt="npm version">
-  </a>
-  <a href="https://www.npmjs.com/package/ctxline-claude">
-    <img src="https://img.shields.io/npm/dm/ctxline-claude" alt="npm downloads">
-  </a>
-  <a href="LICENSE">
-    <img src="https://img.shields.io/github/license/MithunWijayasiri/ctxline-claude" alt="license">
-  </a>
-  <a href="https://github.com/MithunWijayasiri/ctxline-claude/stargazers">
-    <img src="https://img.shields.io/github/stars/MithunWijayasiri/ctxline-claude" alt="stars">
-  </a>
-  <a href="https://ko-fi.com/mithunwijayasiri">
-    <img src="https://img.shields.io/badge/Ko--fi-support-ff5e5b?logo=ko-fi&logoColor=white" alt="Support on Ko-fi">
-  </a>
+  <a href="https://github.com/MithunWijayasiri/ctxline-claude/stargazers"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.shieldcn.dev/github/stars/MithunWijayasiri/ctxline-claude.svg?variant=secondary&amp;size=sm&amp;mode=dark"><img alt="GitHub Stars" src="https://www.shieldcn.dev/github/stars/MithunWijayasiri/ctxline-claude.svg?variant=secondary&amp;size=sm&amp;mode=light"></picture></a>
+  <a href="https://github.com/MithunWijayasiri/ctxline-claude/graphs/contributors"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.shieldcn.dev/github/contributors/MithunWijayasiri/ctxline-claude.svg?variant=secondary&amp;size=sm&amp;mode=dark"><img alt="Contributors" src="https://www.shieldcn.dev/github/contributors/MithunWijayasiri/ctxline-claude.svg?variant=secondary&amp;size=sm&amp;mode=light"></picture></a>
+  <a href="https://github.com/MithunWijayasiri/ctxline-claude/commits/main"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.shieldcn.dev/github/last-commit/MithunWijayasiri/ctxline-claude.svg?variant=secondary&amp;size=sm&amp;mode=dark"><img alt="Last commit" src="https://www.shieldcn.dev/github/last-commit/MithunWijayasiri/ctxline-claude.svg?variant=secondary&amp;size=sm&amp;mode=light"></picture></a>
+  <a href="https://ko-fi.com/mithunwijayasiri"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.shieldcn.dev/badge/Ko--fi-support-FF5E5B.svg?logo=kofi&amp;variant=secondary&amp;size=sm&amp;mode=dark"><img alt="Ko-fi" src="https://www.shieldcn.dev/badge/Ko--fi-support-FF5E5B.svg?logo=kofi&amp;variant=secondary&amp;size=sm&amp;mode=light"></picture></a>
+  <br>
+  <a href="https://www.npmjs.com/package/ctxline-claude"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.shieldcn.dev/npm/ctxline-claude.svg?variant=secondary&amp;size=xs&amp;mode=dark"><img alt="npm Version" src="https://www.shieldcn.dev/npm/ctxline-claude.svg?variant=secondary&amp;size=xs&amp;mode=light"></picture></a>
+  <a href="https://www.npmjs.com/package/ctxline-claude"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.shieldcn.dev/npm/dm/ctxline-claude.svg?variant=secondary&amp;size=xs&amp;mode=dark"><img alt="npm Monthly Downloads" src="https://www.shieldcn.dev/npm/dm/ctxline-claude.svg?variant=secondary&amp;size=xs&amp;mode=light"></picture></a>
+  <a href="https://www.npmjs.com/package/ctxline-claude"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.shieldcn.dev/npm/dt/ctxline-claude.svg?variant=secondary&amp;size=xs&amp;mode=dark"><img alt="npm Total Downloads" src="https://www.shieldcn.dev/npm/dt/ctxline-claude.svg?variant=secondary&amp;size=xs&amp;mode=light"></picture></a>
 </p>
 
 <p align="center">
@@ -140,6 +137,7 @@ Remove-Item "$env:USERPROFILE\.claude\cache\usage-cache.json" -ErrorAction Silen
 | **Model limit** | Weekly limit scoped to a single model, when your account has one — labelled by the model's initial (`F` = Fable) |
 | **Cost** | Running session cost in USD (e.g. `$0.42`) |
 | **Task** | The in-progress todo, when there is one |
+| **Update** | An extra row with the upgrade command when a newer release is on npm — checked once a week, in the background |
 
 > [!NOTE]
 > Usage bars change color automatically as you approach your limits.
@@ -154,7 +152,7 @@ Remove-Item "$env:USERPROFILE\.claude\cache\usage-cache.json" -ErrorAction Silen
 
 The statusline is zero-config by default. To **hide segments you don't want**, set the `CTXLINE_DISABLE` environment variable to a comma-separated list of any of:
 
-`branch` · `effort` · `cost` · `task` · `usage` (5-hour + weekly + model-scoped)
+`branch` · `effort` · `cost` · `task` · `update` · `usage` (5-hour + weekly + model-scoped)
 
 Directory, model, and context always show; unknown names are ignored. Example below hides cost and the current task.
 
@@ -221,6 +219,13 @@ No, it's imperceptible. Almost every render reads a small local cache (sub-milli
 
 </details>
 
+<details>
+<summary>What is the ⬆ segment, and what does it send?</summary>
+
+An extra row appears below the statusline — `⬆ 1.7.0 available · npx ctxline-claude@latest` — so the upgrade command is right there to copy. It shows only while you're behind, and the command works whichever way you installed. Once a week a short-lived background process asks the public npm registry for the package's latest version number and writes it to a local cache; the statusline itself only ever reads that cache, so no render waits on the network. The request carries no session data, credentials, or identifiers — it's a plain GET for a public package, though as with any HTTP request the registry does see your IP address. Hide it (and skip the request entirely) with `CTXLINE_DISABLE=update`.
+
+</details>
+
 <details>
 <summary>Does this use the same data as /usage?</summary>
 

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "ctxline-claude",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "A customizable statusline for Claude Code that tracks context usage and session limits",
   "bin": {
     "ctxline-claude": "bin/install.js"
   },
   "scripts": {
     "test": "node --test",
-    "preview": "node scripts/preview.js"
+    "preview": "node scripts/preview.js",
+    "preview:svg": "node scripts/preview-svg.js"
   },
   "engines": {
     "node": ">=18"

package/statusline.js

@@ -8,12 +8,18 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const https = require('https');
-const { execSync, execFileSync } = require('child_process');
+const { execSync, execFileSync, spawn } = require('child_process');
+
+// Installed version, compared against the npm registry's latest for the update nudge.
+// This file is copied standalone into ~/.claude/hooks/ with no package.json beside it,
+// so the version has to live here. Must match package.json "version" (see CLAUDE.md).
+const VERSION = '1.7.0';
 
 const IS_API_KEY = !!process.env.ANTHROPIC_API_KEY;
 
 // Optional segment opt-out: CTXLINE_DISABLE is a comma list of segments to hide.
-// Recognized: branch, effort, cost, task, usage (H+W+model-scoped). dir/model/context always render.
+// Recognized: branch, effort, cost, task, update, usage (H+W+model-scoped). dir/model/context
+// always render.
 // Unknown names are ignored. Disabling a segment also skips its work (git, todo read,
 // usage fetch).
 const DISABLED = new Set(
@@ -54,6 +60,17 @@ const GIT_FRESH_TTL_MS = 5000;          // 5s: reuse counts within a render burs
 const GIT_STALE_TTL_MS = 60000;         // 60s: fall back to last counts if git fails
 const GIT_TIMEOUT_MS = 500;             // hard cap on the rev-list subprocess (warm ~130ms)
 
+// Update check: compares VERSION against the npm registry's dist-tags.latest. The render
+// only ever reads this cache; the refresh runs in a detached child (see refreshUpdateCheck),
+// so no render ever waits on the registry.
+const UPDATE_CACHE_FILE = path.join(CACHE_DIR, 'update-cache.json');
+const UPDATE_TTL_MS = 7 * 24 * 60 * 60 * 1000;  // 7 days between successful checks
+const UPDATE_RETRY_MS = 60 * 60 * 1000;         // 1h backoff after a failed/killed check
+const UPDATE_TIMEOUT_MS = 2000;                 // socket idle AND whole-request deadline
+const REGISTRY_HOST = 'registry.npmjs.org';
+const PACKAGE_NAME = 'ctxline-claude';
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;       // releases only: a prerelease never nudges
+
 // Subagent mode reads only stdin (no usage API to race), so its stdin read gets a
 // short hard cap of its own instead of the main-mode overallTimeout.
 const SUBAGENT_TIMEOUT_MS = 500;
@@ -249,6 +266,11 @@ function getContextBar(remaining) {
   return renderContextBar(used);
 }
 
+// "model" or "model · effort" (colored). Shared by the main line and subagent rows.
+function renderModelEffort(model, effort) {
+  return effort ? `${model}${getEffortColor(effort)} · ${effort}${colors.reset}` : model;
+}
+
 // Render a compact usage segment from raw data: "<label><pct> ↺ <countdown>"
 // (e.g. "H81 ↺ 2h21m") — no bar. Called on every read (live or cached) so the reset
 // countdown is always recomputed from resetsAt rather than frozen at fetch time.
@@ -290,12 +312,15 @@ const LEGACY_MODEL_WEEKLY_KEYS = [
   { key: 'seven_day_sonnet', label: 'S' }
 ];
 
-// Build the usage segments from raw entries. fiveHour/weekly are { percentage, resetsAt }
-// or null/absent; models is an array of { label, percentage, resetsAt } (possibly empty).
-// Returns { current, weekly, models } — the first two rendered strings or null, models a
-// (possibly empty) array of rendered strings. Scoped bars use getScopedColor instead of the
-// H/W thresholds, so the full threshold palette stays exclusive to H/W.
-function buildUsageBars(fiveHour, weekly, models) {
+// Build the usage segments from a raw { fiveHour, weekly, models } object — the shared
+// shape both buildUsageFromStdin and parseUsagePayload return. fiveHour/weekly are
+// { percentage, resetsAt } or null/absent; models is an array of { label, percentage,
+// resetsAt } (possibly empty). Returns { current, weekly, models } — the first two
+// rendered strings or null, models a (possibly empty) array of rendered strings. Scoped
+// bars use getScopedColor instead of the H/W thresholds, so the full threshold palette
+// stays exclusive to H/W.
+function buildUsageBars(raw) {
+  const { fiveHour, weekly, models } = raw || {};
   return {
     current: fiveHour ? buildUsageBar('H', fiveHour.percentage, fiveHour.resetsAt) : null,
     weekly: weekly ? buildUsageBar('W', weekly.percentage, weekly.resetsAt) : null,
@@ -344,9 +369,10 @@ function parseScopedLimits(usage) {
 // Build usage bars from stdin `rate_limits` (Claude.ai Pro/Max, present only after the
 // first API response of a session). Same data as the OAuth usage API, so reading it here
 // skips the network/credentials/cache path entirely. `resets_at` is a Unix epoch in
-// SECONDS (not ISO) — ×1000 before Date. Returns raw { fiveHour, weekly } entries, or null
-// when rate_limits is absent or the required five_hour segment is unusable (caller falls
-// back). Model-scoped weekly limits are never present here — see LEGACY_MODEL_WEEKLY_KEYS.
+// SECONDS (not ISO) — ×1000 before Date. Returns raw { fiveHour, weekly, models } — same
+// shape as parseUsagePayload — or null when rate_limits is absent or the required
+// five_hour segment is unusable (caller falls back). models is always [] here: model-scoped
+// weekly limits are never present in stdin — see LEGACY_MODEL_WEEKLY_KEYS.
 function buildUsageFromStdin(data) {
   const rl = data?.rate_limits;
   if (!rl) return null;
@@ -369,7 +395,29 @@ function buildUsageFromStdin(data) {
 
   const fiveHour = toEntry(rl.five_hour);
   if (!fiveHour) return null;          // five_hour is the required bar
-  return { fiveHour, weekly: toEntry(rl.seven_day) };
+  return { fiveHour, weekly: toEntry(rl.seven_day), models: [] };
+}
+
+// Parse a raw /usage API response body into { fiveHour, weekly, models } — same shape as
+// buildUsageFromStdin — or null on unparseable JSON or a missing/non-finite five_hour
+// utilization (that bar is required). Normalizes utilization first so a missing/non-finite
+// value omits a bar instead of rendering "NaN%". Pure — no fs/network — so it's unit
+// testable directly, unlike getApiUsage which needs a live socket.
+function parseUsagePayload(body) {
+  try {
+    const usage = JSON.parse(body);
+    const fivePct = usage?.five_hour ? normalizePercentage(usage.five_hour.utilization) : null;
+    if (fivePct == null) return null;
+
+    const fiveHour = { percentage: fivePct, resetsAt: usage.five_hour.resets_at || null };
+    const weeklyPct = usage.seven_day ? normalizePercentage(usage.seven_day.utilization) : null;
+    const weekly = weeklyPct != null ? { percentage: weeklyPct, resetsAt: usage.seven_day.resets_at || null } : null;
+    const models = parseScopedLimits(usage);
+
+    return { fiveHour, weekly, models };
+  } catch (e) {
+    return null;
+  }
 }
 
 // Validate a single usage entry ({ percentage, resetsAt }). Returns true only for a
@@ -410,6 +458,15 @@ function readCachedUsage() {
   }
 }
 
+// Serialize usage data into the on-disk cache shape ({ timestamp, data, lastAttempt }). Pure
+// -- no fs -- so setCachedUsage and the test/preview cache seeds all produce exactly the same
+// bytes the real writer would; a reader/writer format mismatch becomes structurally impossible
+// instead of merely untested. `timestamp` defaults to now; tests override it to seed a stale
+// cache. A successful write is itself an attempt, so `lastAttempt` starts equal to `timestamp`.
+function serializeUsageCache(data, timestamp = Date.now()) {
+  return JSON.stringify({ timestamp, data, lastAttempt: timestamp });
+}
+
 // Write usage data to cache (shared across all sessions)
 function setCachedUsage(data) {
   try {
@@ -417,17 +474,165 @@ function setCachedUsage(data) {
       fs.mkdirSync(CACHE_DIR, { recursive: true });
     }
 
-    const cache = {
-      timestamp: Date.now(),
-      data: data
-    };
+    fs.writeFileSync(USAGE_CACHE_FILE, serializeUsageCache(data), 'utf8');
+  } catch (e) {
+    // Silently fail
+  }
+}
 
-    fs.writeFileSync(USAGE_CACHE_FILE, JSON.stringify(cache), 'utf8');
+// Age in ms since the last API attempt (success or failure), or null if none recorded yet.
+// Read directly from the raw file rather than via readCachedUsage so the cooldown still
+// applies when no valid data has ever been cached (every attempt so far has failed).
+function getLastAttemptAge() {
+  try {
+    if (!fs.existsSync(USAGE_CACHE_FILE)) return null;
+    const cache = JSON.parse(fs.readFileSync(USAGE_CACHE_FILE, 'utf8'));
+    if (!cache || !Number.isFinite(cache.lastAttempt) || cache.lastAttempt <= 0) return null;
+    return Date.now() - cache.lastAttempt;
+  } catch (e) {
+    return null;
+  }
+}
+
+// Record that an API attempt is starting, preserving any existing cached data/timestamp so a
+// failed refresh doesn't erase the last successful one. Written before the request so a hang
+// or a process exit mid-request still counts as an attempt for cooldown purposes.
+function recordUsageAttempt() {
+  try {
+    if (!fs.existsSync(CACHE_DIR)) {
+      fs.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+    let existing = null;
+    try {
+      existing = JSON.parse(fs.readFileSync(USAGE_CACHE_FILE, 'utf8'));
+    } catch (e) {}
+    const merged = existing && typeof existing === 'object' ? { ...existing } : {};
+    merged.lastAttempt = Date.now();
+    fs.writeFileSync(USAGE_CACHE_FILE, JSON.stringify(merged), 'utf8');
   } catch (e) {
     // Silently fail
   }
 }
 
+// Compare two strict "x.y.z" versions -> -1 | 0 | 1, or null when either side isn't that
+// shape (prerelease tags, missing parts, non-numeric). The nudge is a nicety, so an
+// unparseable version means no segment rather than a guess.
+function compareVersions(a, b) {
+  const parse = (v) => SEMVER_RE.test(String(v ?? '')) ? String(v).split('.').map(Number) : null;
+  const x = parse(a);
+  const y = parse(b);
+  if (!x || !y) return null;
+  for (let i = 0; i < 3; i++) {
+    if (x[i] !== y[i]) return x[i] > y[i] ? 1 : -1;
+  }
+  return 0;
+}
+
+// Pure: an npm registry version-manifest body -> its "x.y.z" version string, or null on
+// unparseable JSON, a missing version, or a non-release version (404 bodies land here too).
+function parseRegistryVersion(body) {
+  try {
+    const v = JSON.parse(body)?.version;
+    return SEMVER_RE.test(String(v ?? '')) ? String(v) : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function readUpdateCache() {
+  try {
+    const c = JSON.parse(fs.readFileSync(UPDATE_CACHE_FILE, 'utf8'));
+    return c && typeof c === 'object' ? c : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function writeUpdateCache(obj) {
+  try {
+    if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, { recursive: true });
+    fs.writeFileSync(UPDATE_CACHE_FILE, JSON.stringify(obj), 'utf8');
+  } catch (e) {}
+}
+
+// The cached latest version when it's newer than VERSION, else ''. Cache-only by design:
+// collectFacts calls this on the render path, and the render must never touch the network.
+function getLatestUpdate() {
+  const cached = readUpdateCache();
+  if (!cached) return '';
+  return compareVersions(cached.latest, VERSION) === 1 ? String(cached.latest) : '';
+}
+
+// Fire the weekly check in a detached child, so the render neither waits on the registry
+// nor races its own exit against the response. lastAttempt is stamped before the spawn, so
+// an offline machine, a failed spawn, or a child that dies backs off UPDATE_RETRY_MS
+// instead of respawning on every render.
+function refreshUpdateCheck() {
+  try {
+    const cached = readUpdateCache();
+    const now = Date.now();
+    if (cached) {
+      if (Number.isFinite(cached.checkedAt) && now - cached.checkedAt < UPDATE_TTL_MS) return;
+      if (Number.isFinite(cached.lastAttempt) && now - cached.lastAttempt < UPDATE_RETRY_MS) return;
+    }
+    writeUpdateCache({ ...(cached || {}), lastAttempt: now });
+    // windowsHide: a detached console app would otherwise flash its own console window on
+    // Windows. detached + unref so the child outlives this render's exit(0).
+    spawn(process.execPath, [__filename, 'update-check'], {
+      detached: true, stdio: 'ignore', windowsHide: true
+    }).unref();
+  } catch (e) {}
+}
+
+// The 'update-check' entry point: the detached child. Fetches the registry's latest
+// version, stamps the cache, exits. Writes nothing to stdout — it is not a statusline
+// mode, and its stdio is discarded by the parent anyway. A failed fetch leaves checkedAt
+// untouched, so the UPDATE_RETRY_MS backoff (not the weekly TTL) governs the next try.
+function runUpdateCheck() {
+  let settled = false;
+  let deadline;
+
+  const done = (latest) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(deadline);
+    if (latest) writeUpdateCache({ ...(readUpdateCache() || {}), latest, checkedAt: Date.now() });
+    process.exit(0);
+  };
+
+  try {
+    const req = https.request({
+      hostname: REGISTRY_HOST,
+      path: `/${PACKAGE_NAME}/latest`,
+      method: 'GET',
+      headers: { 'Accept': 'application/json' },
+      timeout: UPDATE_TIMEOUT_MS
+    }, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => done(parseRegistryVersion(body)));
+    });
+
+    req.on('error', () => done(null));
+    req.on('timeout', () => {
+      req.destroy();
+      done(null);
+    });
+
+    // The `timeout` option above is socket inactivity, not total duration -- a response
+    // that trickles bytes would keep this detached child alive indefinitely, and the
+    // parent's UPDATE_RETRY_MS only delays the next spawn, it can't reap this one.
+    deadline = setTimeout(() => {
+      req.destroy();
+      done(null);
+    }, UPDATE_TIMEOUT_MS);
+
+    req.end();
+  } catch (e) {
+    done(null);
+  }
+}
+
 function getCredentials() {
   // Try file first (legacy / Linux / Windows)
   const credsPath = path.join(os.homedir(), '.claude', '.credentials.json');
@@ -483,37 +688,10 @@ function getApiUsage(callback) {
 
       res.on('data', chunk => data += chunk);
       res.on('end', () => {
-        try {
-          const usage = JSON.parse(data);
-
-          // 5-hour session usage is required; weekly (seven_day) is rendered when present.
-          // Normalize utilization first so a missing/non-finite value omits the bar
-          // instead of rendering "NaN%" or an out-of-range percentage.
-          const fivePct = usage.five_hour ? normalizePercentage(usage.five_hour.utilization) : null;
-          if (fivePct != null) {
-            const fiveHour = {
-              percentage: fivePct,
-              resetsAt: usage.five_hour.resets_at || null
-            };
-            const weeklyPct = usage.seven_day ? normalizePercentage(usage.seven_day.utilization) : null;
-            const weekly = weeklyPct != null ? {
-              percentage: weeklyPct,
-              resetsAt: usage.seven_day.resets_at || null
-            } : null;
-
-            // Model-scoped weekly limits, rendered only when the account reports them.
-            const models = parseScopedLimits(usage);
-
-            // Cache the raw data (shared across sessions); callers render from it.
-            const resolved = { fiveHour, weekly, models };
-            setCachedUsage(resolved);
-            callback(resolved);
-          } else {
-            callback(null);
-          }
-        } catch (e) {
-          callback(null);
-        }
+        const resolved = parseUsagePayload(data);
+        // Cache the raw data (shared across sessions); callers render from it.
+        if (resolved) setCachedUsage(resolved);
+        callback(resolved);
       });
     });
 
@@ -538,7 +716,17 @@ function getRawUsage(callback) {
     return callback(cached.data);
   }
 
-  // Cache is stale or missing -> refresh from the API.
+  // A refresh (successful or not) was attempted within FRESH_TTL_MS -> still in cooldown,
+  // don't hit the API again. Serve stale cached data if it's still within STALE_TTL_MS, else
+  // nothing. Without this, a repeatedly failing/timing-out refresh would re-hit the API on
+  // every render instead of backing off (issue #41).
+  const attemptAge = getLastAttemptAge();
+  if (attemptAge != null && attemptAge < FRESH_TTL_MS) {
+    return callback(cached && cached.age < STALE_TTL_MS ? cached.data : null);
+  }
+
+  // Cache is stale or missing and no attempt is in cooldown -> refresh from the API.
+  recordUsageAttempt();
   getApiUsage((fresh) => {
     if (fresh) {
       callback(fresh);
@@ -551,20 +739,6 @@ function getRawUsage(callback) {
   });
 }
 
-// Get usage, cache-first, rendered.
-function getUsageWithCache(callback) {
-  getRawUsage((data) => {
-    callback(data ? buildUsageBars(data.fiveHour, data.weekly, data.models) : null);
-  });
-}
-
-// Model-scoped weekly limits only, cache-first. Used alongside the stdin H/W bars, which
-// can't carry them. Falls back to the stale cache and finally to [] so a failed or slow
-// call costs the scoped bars but never the bars stdin already gave us.
-function getScopedModels(callback) {
-  getRawUsage((data) => callback(data?.models || []));
-}
-
 // Session cost from stdin `cost.total_cost_usd` (USD float, computed client-side by
 // Claude Code as tokens × per-model API pricing). Pure stdin — no network/cache.
 // Returns "$0.00" rendered dim, or '' when absent/non-finite so the segment is omitted.
@@ -604,63 +778,93 @@ function visibleWidth(str) {
 }
 
 // Responsive layout: one line when it fits the terminal, else line1 (identity + context)
-// on top and line2 (usage/cost/task) below. Splits only when COLUMNS is known (Claude Code
-// v2.1.153+) and the single line overflows — unknown width or an empty line2 stays single,
-// so there is no regression on older clients or wide terminals.
-function layout(line1Parts, line2Parts) {
+// on top and line2 (usage/cost/task) below. Splits only when cols is known (Claude Code
+// v2.1.153+ sets COLUMNS, read by collectFacts) and the single line overflows — unknown
+// width or an empty line2 stays single, so there is no regression on older clients or wide
+// terminals.
+function layout(line1Parts, line2Parts, cols) {
   const single = [...line1Parts, ...line2Parts].join(SEGMENT_SEP);
   if (line2Parts.length === 0) return single;
-  const cols = parseInt(process.env.COLUMNS, 10);
   if (Number.isFinite(cols) && cols > 0 && visibleWidth(single) > cols - WIDTH_MARGIN) {
     return line1Parts.join(SEGMENT_SEP) + '\n' + line2Parts.join(SEGMENT_SEP);
   }
   return single;
 }
 
-// Main
-function outputStatus(data, usage) {
+// Gathers everything outputStatus needs that touches fs/child_process/env: git branch +
+// ahead/behind (.git/HEAD, `git rev-list`), the in-progress task (~/.claude/todos), and the
+// terminal width (COLUMNS). Kept separate from renderStatusLine so the render step is pure.
+// Wrapped in its own try/catch (unlike renderStatusLine, it's called outside outputStatus's
+// try/catch in emit()) — a malformed workspace.current_dir (e.g. non-string) can throw from
+// path.basename or resolveGitDir, and this must still degrade to a renderable fallback.
+function collectFacts(data) {
   try {
-    const model = shortenModel(data?.model?.display_name || 'Claude');
     const dir = data?.workspace?.current_dir || process.cwd();
     const dirname = path.basename(dir);
     const branch = DISABLED.has('branch') ? '' : getGitBranch(dir);
     const sync = branch ? formatAheadBehind(getGitAheadBehind(dir)) : '';
-    const effort = DISABLED.has('effort') ? '' : (data?.effort?.level || '');
     const sessionId = data?.session_id || '';
-    const remaining = data?.context_window?.remaining_percentage;
-
-    const contextBar = getContextBar(remaining);
-    const cost = DISABLED.has('cost') ? '' : getCostSegment(data);
     const task = DISABLED.has('task') ? '' : getCurrentTask(sessionId);
+    const update = DISABLED.has('update') ? '' : getLatestUpdate();
+    const cols = parseInt(process.env.COLUMNS, 10);
+    return { dirname, branch, sync, task, update, cols };
+  } catch (e) {
+    return { dirname: '~', branch: '', sync: '', task: '', update: '', cols: undefined };
+  }
+}
+
+// The update nudge gets its own row rather than a segment: Claude Code renders every
+// stdout line as a separate row, and the point of the nudge is the copy-pasteable command,
+// which is too wide to inline without forcing the main line to wrap on most terminals.
+// `npx <pkg>@latest` is the right command for script-installed users too — it recopies the
+// hook. Only the target version is shown — the running one is what you're looking at.
+function renderUpdateLine(latest) {
+  return `${colors.green}⬆ ${latest}${colors.reset} `
+    + `${colors.dim}available ·${colors.reset} `
+    + `${colors.bold}npx ${PACKAGE_NAME}@latest${colors.reset}`;
+}
 
-    // line1 = identity + context (always); line2 = usage/cost/task (wrap target).
-    const line1 = [];
-    line1.push(branch
-      ? `${dirname} ${colors.dim}⎇ ${branch}${colors.reset}${sync ? ' ' + sync : ''}`
-      : dirname);
-    line1.push(effort ? `${model}${getEffortColor(effort)} · ${effort}${colors.reset}` : model);
-    line1.push(contextBar);
-
-    const line2 = [];
-    if (usage?.current) line2.push(usage.current);
-    if (usage?.weekly) line2.push(usage.weekly);
-    if (usage?.models?.length) line2.push(...usage.models);
-    if (cost) line2.push(cost);
-    if (task) line2.push(`${colors.dim}${task}${colors.reset}`);
-
-    process.stdout.write(layout(line1, line2));
+// Pure: data + facts (see collectFacts) + resolved usage bars -> the rendered line(s).
+// No fs/child_process/network access, so it's callable directly in tests.
+function renderStatusLine(data, facts, usage) {
+  const model = shortenModel(data?.model?.display_name || 'Claude');
+  const effort = DISABLED.has('effort') ? '' : (data?.effort?.level || '');
+  const remaining = data?.context_window?.remaining_percentage;
+
+  const contextBar = getContextBar(remaining);
+  const cost = DISABLED.has('cost') ? '' : getCostSegment(data);
+
+  // line1 = identity + context (always); line2 = usage/cost/task (wrap target).
+  const line1 = [];
+  line1.push(facts.branch
+    ? `${facts.dirname} ${colors.dim}⎇ ${facts.branch}${colors.reset}${facts.sync ? ' ' + facts.sync : ''}`
+    : facts.dirname);
+  line1.push(renderModelEffort(model, effort));
+  line1.push(contextBar);
+
+  const line2 = [];
+  if (usage?.current) line2.push(usage.current);
+  if (usage?.weekly) line2.push(usage.weekly);
+  if (usage?.models?.length) line2.push(...usage.models);
+  if (cost) line2.push(cost);
+  if (facts.task) line2.push(`${colors.dim}${facts.task}${colors.reset}`);
+
+  const body = layout(line1, line2, facts.cols);
+  return facts.update ? body + '\n' + renderUpdateLine(facts.update) : body;
+}
+
+// Main
+function outputStatus(data, facts, usage) {
+  try {
+    process.stdout.write(renderStatusLine(data, facts, usage));
   } catch (e) {
     process.stdout.write('Status unavailable');
   }
 }
 
 function outputFallback(usage) {
-  const contextBar = getContextBar(undefined);
-  const parts = ['~', 'Claude', contextBar];
-  if (usage?.current) parts.push(usage.current);
-  if (usage?.weekly) parts.push(usage.weekly);
-  if (usage?.models?.length) parts.push(...usage.models);
-  process.stdout.write(parts.join(' \u2502 '));
+  const facts = { dirname: '~', branch: '', sync: '', task: '', update: '', cols: undefined };
+  process.stdout.write(renderStatusLine(null, facts, usage));
 }
 
 // Resolve usage bars for a (possibly null) parsed stdin payload.
@@ -675,14 +879,15 @@ function resolveUsage(data, callback) {
     // stdin covers H and W with no network. Model-scoped weekly limits only exist in the
     // API payload, so they come from the cache — refreshed on the same TTL as every other
     // usage read, which keeps at most one call per FRESH_TTL_MS regardless of render rate.
-    return getScopedModels((models) => {
-      callback(buildUsageBars(fromStdin.fiveHour, fromStdin.weekly, models));
+    // Falls back to the stale cache and finally to [] so a failed or slow call costs only
+    // the scoped bars, never the H/W bars stdin already gave us.
+    return getRawUsage((cached) => {
+      callback(buildUsageBars({ ...fromStdin, models: cached?.models || [] }));
     });
   }
-  getUsageWithCache(callback);
+  getRawUsage((raw) => callback(raw ? buildUsageBars(raw) : null));
 }
 
-// Process with timeout
 // Parse the accumulated stdin into a payload object, or null if empty/unparseable.
 function parseInput(input) {
   if (!input || input.length === 0) return null;
@@ -693,11 +898,35 @@ function parseInput(input) {
   }
 }
 
+// Accumulate stdin then call fn(input) exactly once, on whichever fires first:
+// timeout, 'end', or 'error' (an unhandled stdin error would otherwise throw,
+// breaking the never-throw contract). Shared by both entry points below, which
+// differ only in timeoutMs.
+function readStdinThen(timeoutMs, fn) {
+  let input = '';
+  let finished = false;
+
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timeout);
+    fn(input);
+  };
+
+  const timeout = setTimeout(finish, timeoutMs);
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => input += chunk);
+  process.stdin.on('end', finish);
+  process.stdin.on('error', finish);
+}
+
 // Resolve usage for `data` (preferring stdin rate_limits), then render and exit.
 function emit(data) {
+  if (!DISABLED.has('update')) refreshUpdateCheck();
   resolveUsage(data, (usage) => {
     if (data) {
-      outputStatus(data, usage);
+      outputStatus(data, collectFacts(data), usage);
     } else {
       outputFallback(usage);
     }
@@ -733,9 +962,7 @@ function renderSubagentTask(t) {
   // effort absent = subagent inherits the session effort; show model alone then.
   const effort = t.effort != null ? String(t.effort) : '';
   if (model) {
-    parts.push(effort
-      ? `${model}${getEffortColor(effort)} · ${effort}${colors.reset}`
-      : model);
+    parts.push(renderModelEffort(model, effort));
   } else if (effort) {
     parts.push(`${getEffortColor(effort)}${effort}${colors.reset}`);
   }
@@ -777,51 +1004,21 @@ function emitSubagent(data) {
 // directly (the /usage response shape is the easiest thing here to get wrong, and it
 // can't be reached through stdin). Running the script normally is unchanged.
 if (require.main === module) {
-  if (process.argv[2] === 'subagent') {
-    if (process.stdin.isTTY) {
-      emitSubagent(null);
-    } else {
-      let input = '';
-      let finished = false;
-
-      // Single guarded exit shared by all three triggers: timeout, stdin 'end', and
-      // stdin 'error' (which can fire before 'end' and would otherwise throw unhandled,
-      // breaking the never-throw contract). Whatever accumulated so far gets rendered.
-      const finish = () => {
-        if (finished) return;
-        finished = true;
-        clearTimeout(timeout);
-        emitSubagent(parseInput(input));
-      };
-
-      const timeout = setTimeout(finish, SUBAGENT_TIMEOUT_MS);
-
-      process.stdin.setEncoding('utf8');
-      process.stdin.on('data', chunk => input += chunk);
-      process.stdin.on('end', finish);
-      process.stdin.on('error', finish);
-    }
+  const mode = process.argv[2];
+  const isSubagent = mode === 'subagent';
+  const finish = isSubagent ? emitSubagent : emit;
+
+  if (mode === 'update-check') {
+    // Detached child spawned by refreshUpdateCheck: no stdin, no output, just the fetch.
+    runUpdateCheck();
   } else if (process.stdin.isTTY) {
-    emit(null);
+    finish(null);
   } else {
-    let input = '';
-    let timeoutReached = false;
-
-    const overallTimeout = IS_API_KEY ? 500 : (fs.existsSync(USAGE_CACHE_FILE) ? 1300 : 1600);
-
-    const timeout = setTimeout(() => {
-      timeoutReached = true;
-      emit(parseInput(input));
-    }, overallTimeout);
-
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', chunk => input += chunk);
-    process.stdin.on('end', () => {
-      if (timeoutReached) return;
-      clearTimeout(timeout);
-      emit(parseInput(input));
-    });
+    const timeoutMs = isSubagent
+      ? SUBAGENT_TIMEOUT_MS
+      : (IS_API_KEY ? 500 : (fs.existsSync(USAGE_CACHE_FILE) ? 1300 : 1600));
+    readStdinThen(timeoutMs, (input) => finish(parseInput(input)));
   }
 } else {
-  module.exports = { parseScopedLimits, normalizePercentage };
+  module.exports = { parseScopedLimits, parseUsagePayload, serializeUsageCache, normalizePercentage, readStdinThen, renderStatusLine, renderSubagentTask, compareVersions, parseRegistryVersion, VERSION };
 }