cc-cream 0.1.17 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to cc-cream are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] — 2026-05-30
+
+### Added
+- **`cc-cream-setup --check-config`** lints `~/.claude/cc-cream.json` and reports unknown keys and out-of-domain values — the fields the renderer silently falls back to defaults for. Exits non-zero when there's something to fix, so a typo'd key ("`ambre`", "`colour`") is no longer a silent no-op.
+- **`CC_CREAM_DEBUG=1` opt-in diagnostics.** When the bar is unexpectedly empty or short, set it to log — to `~/.claude/cc-cream-debug.log` (override with `CC_CREAM_DEBUG_LOG`) — which on-by-default segments rendered and which were dropped, plus the resolved TTL window and stdin size. Claude Code discards status-line stderr, so the channel is a file; **stdout stays untouched** (zero tokens). Off by default: no file, no overhead.
+
+### Changed
+- **The plugin status line no longer resolves its version with a shell glob.** The wired command was `ls … | grep -E … | sort -V | tail -1` over the plugin cache, run on every render — it depended on GNU `sort -V` (not guaranteed in the status-line subprocess, notably on macOS) and reverse-engineered Claude Code's undocumented cache layout. `${CLAUDE_PLUGIN_ROOT}` doesn't expand in the status-line command context, so the command can't discover the current version itself. Instead the command now bakes the current version's **absolute** `cc-cream.js` path, and the `SessionStart` hook — which *does* receive `${CLAUDE_PLUGIN_ROOT}` — re-pins it after a `/plugin update`. Both install modes now share one command shape (`[ -f "<entrypoint>" ] || exit 0; exec "<node>" "<entrypoint>"`); the `[ -f … ]` guard preserves the silent exit-0 when the plugin cache is deleted out from under a stale line.
+
+### Internal
+- **Settings.json read/parse/atomic-write logic is shared** between the installer and the `SessionStart` hook via a new `src/settings.js`, instead of a copy in each.
+- **Segment rendering is now pure.** The TTL anchor (including its `transcript_path` `statSync`) is resolved once in the I/O layer (`cc-cream.js`) and injected into `render()`, so `src/segments.js` no longer performs any filesystem access.
+- **Config normalization is now a single schema table** (`src/config.js`) instead of an ad-hoc per-field conditional ladder. The same table powers `--check-config`, so validation rules live in one place.
+
+## [0.1.18] — 2026-05-29
+
+### Security
+- **Status-line text is now stripped of terminal control characters before output.** Three stdin-derived fields — `model.display_name`, `session_name`, and `effort.level` — were written to the terminal verbatim on every render. Because `session_name` can be derived from conversation content (which may include untrusted material), an embedded ANSI/OSC escape sequence would have been interpreted by the terminal (window-title/clipboard rewrites via OSC, or cursor/erase sequences that spoof or hide output). `paint()` now passes every segment through a `sanitize()` pass that drops C0/C1 control bytes (incl. ESC, BEL, DEL) while preserving the tool's own color codes, which are added afterward. The bar is purely visual, so the strip is lossless.
+- **A crafted `session_id` can no longer corrupt the session-state map.** `session_id` is used as an object key; values of `__proto__`/`constructor`/`prototype` are now rejected in `getSessionState`/`patchSessionState`, and reads use `Object.hasOwn`.
+
+### Fixed
+- **Writes to `settings.json` (and the state file) are now atomic.** `install.js`, the `SessionStart` auto-setup hook, and `state.js` wrote via a direct `writeFileSync` over the live file; an interruption (crash, `ENOSPC`) mid-write could truncate `settings.json` and erase the user's permissions/hooks/plugins/MCP config — the very loss `readSettings` works to avoid. They now write a sibling temp file and `rename` it over the target (atomic within a filesystem; the temp shares the target's directory so the rename never crosses devices).
+- **The plugin auto-update command now quotes the node binary path** (`exec "${nodePath}"`), so a node path containing spaces no longer breaks the status line.
+
+### Changed
+- **The session-state map is capped at 50 entries**, evicting the least-recently-touched sessions. It previously gained one key per `session_id` and was never pruned, growing without bound.
+
 ## [0.1.17] — 2026-05-29
 
 ### Fixed
@@ -142,6 +169,7 @@ line and prints a colored ≤3-row bar — zero tokens, the model never sees it.
 - Supports **macOS and Linux**; Windows is a planned fast-follow.
 - Requires Claude Code **2.1.132+** (`effort` / `thinking` need 2.1.145+).
 
+[0.1.18]: https://github.com/bart-turczynski/cc-cream/compare/v0.1.17...v0.1.18
 [0.1.17]: https://github.com/bart-turczynski/cc-cream/compare/v0.1.16...v0.1.17
 [0.1.16]: https://github.com/bart-turczynski/cc-cream/compare/v0.1.15...v0.1.16
 [0.1.15]: https://github.com/bart-turczynski/cc-cream/compare/v0.1.14...v0.1.15

package/README.md

@@ -1,5 +1,11 @@
 # cc-cream
 
+[![CI](https://img.shields.io/github/actions/workflow/status/bart-turczynski/cc-cream/ci.yml?branch=main&label=CI)](https://github.com/bart-turczynski/cc-cream/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/cc-cream)](https://www.npmjs.com/package/cc-cream)
+[![Socket Badge](https://socket.dev/api/badge/npm/package/cc-cream)](https://socket.dev/npm/package/cc-cream)
+[![install size](https://img.shields.io/bundlephobia/minzip/cc-cream)](https://bundlephobia.com/package/cc-cream)
+[![License: MIT](https://img.shields.io/npm/l/cc-cream)](https://github.com/bart-turczynski/cc-cream/blob/main/LICENSE)
+
 **C.R.E.A.M. — Cache Rules Everything Around Me.**
 
 A lightweight status-line tool for [Claude Code](https://claude.com/claude-code)
@@ -116,6 +122,13 @@ The installer:
 After install, Claude Code must be **trusted** for the directory (if prompted),
 and you may need to **restart** it for the bar to appear.
 
+> **Pick one install method.** If you wire cc-cream via npm/manual (Options 2–3)
+> and *then* install the plugin, the plugin won't take over the existing wiring —
+> it points at your home copy, so `/plugin update` won't auto-update the bar. To
+> switch to the auto-updating plugin, run `/cc-cream:setup` (or `cc-cream-setup
+> --uninstall` first). Nothing breaks either way; it just stays on whichever
+> method wired it.
+
 ### Uninstall
 
 Plugin users — two steps, **in this order** (Claude Code can't clean
@@ -160,6 +173,13 @@ or ask Claude to. It is strict JSON with no comments. **Every field falls back t
 its built-in default if missing or malformed** — a typo degrades one value rather
 than breaking the bar; a whole-file parse error falls back to all defaults.
 
+Because unknown or out-of-range fields are silently ignored, run the doctor after
+editing by hand to catch typos:
+
+```bash
+cc-cream-setup --check-config   # reports unknown keys / out-of-domain values; exits non-zero if any
+```
+
 ```json
 {
   "numbers": "compact",
@@ -272,6 +292,21 @@ Default: `amber: 75`, `red: 90` (absolute `used_percentage`).
   Anthropic's faster-drain window. Defaults `5`–`11`. Weekday-only (Mon–Fri) and
   the `America/Los_Angeles` timezone are hardcoded policy facts, not config.
 
+## Troubleshooting
+
+cc-cream is built to degrade silently — if a stdin field is missing or malformed
+it just hides that segment rather than crashing. When the bar is unexpectedly
+empty or shorter than you expect, turn on diagnostics:
+
+```bash
+export CC_CREAM_DEBUG=1   # then trigger a render in Claude Code
+```
+
+Each render appends a line to `~/.claude/cc-cream-debug.log` (override the path
+with `CC_CREAM_DEBUG_LOG`) listing which segments rendered, which were dropped,
+the resolved TTL window, and the stdin size. It never writes to the status line
+itself, so it costs zero tokens. Unset the variable to turn it off.
+
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for how to run the tests. The runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-cream",
-  "version": "0.1.17",
+  "version": "0.2.0",
   "description": "Claude Code cache/context/cost status-line tool",
   "directories": {
     "doc": "docs"

package/src/cc-cream.js

@@ -3,11 +3,12 @@
 // Reads the session JSON Claude Code pipes on stdin and prints a colored
 // <=3-row bar. Hard rule: degrade, never crash.
 
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { loadConfig, readConfigFile } from './config.js';
-import { render } from './render.js';
+import { buildSegments, render } from './render.js';
 import {
   getSessionState,
   nextSessionPatch,
@@ -15,7 +16,7 @@ import {
   readState,
   writeState,
 } from './state.js';
-import { isEntrypoint } from './utils.js';
+import { isEntrypoint, isNum } from './utils.js';
 
 export { DEFAULTS } from './defaults.js';
 export { loadConfig } from './config.js';
@@ -51,8 +52,63 @@ function nowFromEnv(env) {
   return rawNow && Number.isFinite(Number(rawNow)) ? Number(rawNow) : Date.now();
 }
 
+// Resolve when the cache TTL window last reset, in epoch ms (or null to hide the
+// ttl segment). This is the ONLY filesystem read on the render path — kept here
+// in the I/O layer so render.js and the segments stay pure. Priority: token
+// growth this turn (reset is now) → the last recorded API timestamp → the
+// transcript file's mtime as a last resort.
+function resolveTtlAnchor(data, prevSessionState, now) {
+  const curTokens = data?.context_window?.total_input_tokens;
+  const prevTokens = prevSessionState?.total_input_tokens;
+  if (isNum(curTokens) && isNum(prevTokens) && curTokens > prevTokens) return now;
+  if (isNum(prevSessionState?.last_api_ts)) return prevSessionState.last_api_ts;
+  const tp = data?.transcript_path;
+  if (typeof tp !== 'string' || tp === '') return null;
+  try {
+    return fs.statSync(tp).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+// CC_CREAM_DEBUG is opt-in diagnostics. Claude Code SILENTLY DISCARDS statusLine
+// stderr (it's only surfaced under `claude --debug`, first invocation), so the
+// channel is a log FILE — never stdout, which would cost tokens / corrupt the
+// bar. CC_CREAM_DEBUG_LOG overrides the path (used by tests).
+const debugEnabled = (env) => {
+  const v = env.CC_CREAM_DEBUG;
+  return typeof v === 'string' && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+};
+
+function writeDebug(env, lines) {
+  const file = env.CC_CREAM_DEBUG_LOG || path.join(os.homedir(), '.claude', 'cc-cream-debug.log');
+  try {
+    fs.appendFileSync(file, `${lines.join('\n')}\n`);
+  } catch {
+    // diagnostics must never affect the render — swallow any write failure
+  }
+}
+
+// Record why the bar looks the way it does: which on-by-config segments rendered
+// and which were dropped (the usual reason a bar is shorter/emptier than
+// expected — a missing or malformed stdin field). Recomputes the segment map
+// through buildSegments() so it can never diverge from what render() drew.
+function logDebug(env, { data, cfg, now, prevSessionState, sessionId, rawLen, ttlAnchorMs, out }) {
+  const { ttlMin, segs } = buildSegments(data, cfg, env, now, prevSessionState, ttlAnchorMs);
+  const onIds = Object.keys(cfg.segments).filter((id) => cfg.segments[id].on);
+  const visible = onIds.filter((id) => segs[id]);
+  const hidden = onIds.filter((id) => !segs[id]);
+  writeDebug(env, [
+    `[${new Date(now).toISOString()}] session=${sessionId ?? 'none'} stdinBytes=${rawLen} ttlMin=${ttlMin} ttlAnchor=${ttlAnchorMs ?? 'none'}`,
+    `  output=${out ? JSON.stringify(out) : '<empty>'}`,
+    `  visible=[${visible.join(',')}]`,
+    `  hidden(on-but-absent)=[${hidden.join(',')}]`,
+  ]);
+}
+
 async function main() {
-  const data = parseSession(await readStdin());
+  const raw = await readStdin();
+  const data = parseSession(raw);
   const cfg = loadConfig(readConfigFile());
   const now = nowFromEnv(process.env);
 
@@ -61,9 +117,14 @@ async function main() {
   const state = sessionId ? readState(stateFile) : {};
   const prevSessionState = getSessionState(state, sessionId);
 
-  const out = render(data, cfg, process.env, now, prevSessionState);
+  const ttlAnchorMs = resolveTtlAnchor(data, prevSessionState, now);
+  const out = render(data, cfg, process.env, now, prevSessionState, ttlAnchorMs);
   if (out) process.stdout.write(`${out}\n`);
 
+  if (debugEnabled(process.env)) {
+    logDebug(process.env, { data, cfg, now, prevSessionState, sessionId, rawLen: raw.length, ttlAnchorMs, out });
+  }
+
   if (sessionId) {
     const patch = nextSessionPatch(data, prevSessionState, cfg, now);
     writeState(stateFile, patchSessionState(state, sessionId, patch));

package/src/config.js

@@ -4,6 +4,10 @@ import path from 'node:path';
 import { DEFAULTS } from './defaults.js';
 import { clone, isNum, numOr } from './utils.js';
 
+// Each normalizer is `(value, fallback) => value | fallback`: it returns the
+// value when it's in-domain, else the fallback. The same table drives BOTH the
+// forgiving merge (fallback = the default) and the --check-config doctor
+// (fallback = a sentinel, so a returned sentinel means "rejected").
 const boolOr = (v, d) => (typeof v === 'boolean' ? v : d);
 const rowOr = (v, d) => (v === 1 || v === 2 || v === 3 ? v : d);
 const posOr = (v, d) => (isNum(v) && v > 0 ? v : d); // a ceiling of 0/neg would divide-by-zero
@@ -11,6 +15,7 @@ const basisOr = (v, d) => (v === 'window' || v === 'ceiling' ? v : d);
 const ctxDisplayOr = (v, d) => (v === 'basis' || v === 'window' ? v : d);
 const hourOr = (v, d) => (isNum(v) && v >= 0 && v <= 23 ? v : d);
 const percentageOr = (v, d) => (v === 'consumed' || v === 'remaining' ? v : d);
+const numbersOr = (v, d) => (v === 'compact' || v === 'exact' ? v : d);
 
 function ttlOr(v, d) {
   if (v === 'auto') return 'auto';
@@ -19,11 +24,37 @@ function ttlOr(v, d) {
   return d;
 }
 
+// Top-level config keys and their normalizers (besides `segments`, handled below).
+const TOP_LEVEL = {
+  numbers: numbersOr,
+  ttl: ttlOr,
+  percentage: percentageOr,
+};
+
+// Per-segment field normalizers. The set of fields VALID for a given segment is
+// that segment's own keys in DEFAULTS (so `ctx` accepts `ceiling`, `peak`
+// accepts `start`/`end`, etc.); this table just says how each is normalized.
+const SEGMENT_FIELDS = {
+  on: boolOr,
+  row: rowOr,
+  order: numOr,
+  amber: numOr,
+  orange: numOr,
+  red: numOr,
+  drop: posOr,
+  drop_recover: posOr,
+  basis: basisOr,
+  ceiling: posOr,
+  display: ctxDisplayOr,
+  start: hourOr,
+  end: hourOr,
+};
+
 function mergeConfig(parsed) {
   const cfg = clone(DEFAULTS);
-  cfg.numbers = parsed.numbers === 'compact' || parsed.numbers === 'exact' ? parsed.numbers : DEFAULTS.numbers;
-  cfg.ttl = ttlOr(parsed.ttl, DEFAULTS.ttl);
-  cfg.percentage = percentageOr(parsed.percentage, DEFAULTS.percentage);
+  for (const [key, norm] of Object.entries(TOP_LEVEL)) {
+    cfg[key] = norm(parsed[key], DEFAULTS[key]);
+  }
 
   const segs = parsed.segments;
   if (segs && typeof segs === 'object' && !Array.isArray(segs)) {
@@ -32,19 +63,10 @@ function mergeConfig(parsed) {
       const s = segs[id];
       const out = clone(def);
       if (s && typeof s === 'object' && !Array.isArray(s)) {
-        out.on = boolOr(s.on, def.on);
-        out.row = rowOr(s.row, def.row);
-        out.order = numOr(s.order, def.order);
-        if ('amber' in def) out.amber = numOr(s.amber, def.amber);
-        if ('orange' in def) out.orange = numOr(s.orange, def.orange);
-        if ('red' in def) out.red = numOr(s.red, def.red);
-        if ('drop' in def) out.drop = posOr(s.drop, def.drop);
-        if ('drop_recover' in def) out.drop_recover = posOr(s.drop_recover, def.drop_recover);
-        if ('basis' in def) out.basis = basisOr(s.basis, def.basis);
-        if ('ceiling' in def) out.ceiling = posOr(s.ceiling, def.ceiling);
-        if ('display' in def) out.display = ctxDisplayOr(s.display, def.display);
-        if ('start' in def) out.start = hourOr(s.start, def.start);
-        if ('end' in def) out.end = hourOr(s.end, def.end);
+        for (const field of Object.keys(def)) {
+          const norm = SEGMENT_FIELDS[field];
+          if (norm) out[field] = norm(s[field], def[field]);
+        }
       }
       cfg.segments[id] = out;
     }
@@ -65,6 +87,59 @@ export function loadConfig(raw) {
   return mergeConfig(parsed);
 }
 
+// Diagnose a parsed config object: report unknown keys and out-of-domain values
+// using the same schema table the merge uses. Returns a list of human-readable
+// problems (empty = clean). The runtime silently ignores these (per-field
+// fallback); the doctor surfaces them so a typo'd key isn't a silent no-op.
+export function checkConfig(parsed) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return ['cc-cream.json must be a JSON object.'];
+  }
+  const problems = [];
+  const INVALID = Symbol('invalid');
+
+  for (const key of Object.keys(parsed)) {
+    if (key === 'segments') continue;
+    const norm = TOP_LEVEL[key];
+    if (!norm) {
+      problems.push(`unknown top-level key: "${key}"`);
+    } else if (norm(parsed[key], INVALID) === INVALID) {
+      problems.push(`out-of-domain value for "${key}": ${JSON.stringify(parsed[key])}`);
+    }
+  }
+
+  const segs = parsed.segments;
+  if (segs !== undefined) {
+    if (!segs || typeof segs !== 'object' || Array.isArray(segs)) {
+      problems.push('"segments" must be an object.');
+    } else {
+      for (const id of Object.keys(segs)) {
+        if (!(id in DEFAULTS.segments)) {
+          problems.push(`unknown segment: "${id}"`);
+          continue;
+        }
+        const s = segs[id];
+        if (!s || typeof s !== 'object' || Array.isArray(s)) {
+          problems.push(`segment "${id}" must be an object.`);
+          continue;
+        }
+        const def = DEFAULTS.segments[id];
+        for (const field of Object.keys(s)) {
+          if (!(field in def)) {
+            problems.push(`unknown field on "${id}": "${field}"`);
+            continue;
+          }
+          const norm = SEGMENT_FIELDS[field];
+          if (norm && norm(s[field], INVALID) === INVALID) {
+            problems.push(`out-of-domain value for "${id}.${field}": ${JSON.stringify(s[field])}`);
+          }
+        }
+      }
+    }
+  }
+  return problems;
+}
+
 export function readConfigFile() {
   try {
     return fs.readFileSync(path.join(os.homedir(), '.claude', 'cc-cream.json'), 'utf8');

package/src/install.js

@@ -14,34 +14,42 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { checkConfig } from './config.js';
+import { isSafeToWrite, readSettings as readSettingsFile, writeFileAtomic } from './settings.js';
 import { isEntrypoint } from './utils.js';
 
+export { writeFileAtomic } from './settings.js';
+
 const TRUST_NOTE =
   'Claude Code must be trusted and possibly restarted for the status line to appear.';
 
-// The cache-glob auto-update command (docs/RELEASE_PLAN.md "Auto-update mechanism").
+// The statusLine command: a missing-file guard, then exec node on an ABSOLUTE
+// entrypoint. Both install modes use this one shape — only the entrypoint path
+// differs (plugin cache vs the copied home runtime).
+//
 // `nodePath` is the ABSOLUTE node binary, resolved once at setup time — the
 // statusLine subprocess may not inherit the user's PATH, so a bare `node` is
-// unsafe. The `-d .../*/` glob yields directory paths with a trailing slash, so
-// `src/cc-cream.js` concatenates directly. The `grep` keeps ONLY semver-named
-// dirs (e.g. `0.1.10/`) before `sort -V | tail -1` picks the highest — without
-// it, a non-numeric cache dir (a git-sha install like `c83650b6360f/`) sorts
-// last and pins the bar to whatever version that happens to be, defeating
-// auto-update. With it, `/plugin update` is applied live with no re-run of setup.
+// unsafe. `entrypoint` is the absolute path to cc-cream.js.
 //
-// The resolved dir is captured in `$d` and GUARDED with `[ -z "$d" ] && exit 0`:
-// when the glob matches nothing — the state left behind if a user runs
-// `/plugin uninstall cc-cream` WITHOUT first running `/cc-cream:uninstall`, so a
-// stale statusLine outlives the deleted cache — the command degrades to a silent
-// exit 0 instead of running a bare relative `src/cc-cream.js` that crashes with
+// Why no version resolution here: `${CLAUDE_PLUGIN_ROOT}` does NOT expand in the
+// statusLine command context (only in hook/MCP/command contexts — verified), so
+// the command can't discover the current plugin version at render time. Instead
+// the SessionStart hook — which DOES get `${CLAUDE_PLUGIN_ROOT}` — bakes the
+// current version's absolute path here and re-pins it after `/plugin update`.
+//
+// The `[ -f "<entrypoint>" ] || exit 0` guard degrades to a silent exit 0 when
+// the entrypoint is gone — the state left behind if a user runs `/plugin
+// uninstall cc-cream` WITHOUT first running `/cc-cream:uninstall`, so a stale
+// statusLine outlives the deleted cache. Without it, node would crash with
 // MODULE_NOT_FOUND on every render. "Degrade, never crash" (CLAUDE.md). `exec`
 // replaces the shell so stdin/stdout pass straight through to the renderer.
-export function autoUpdateCommand(nodePath) {
-  return `d="$(ls -1d "\${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/cc-cream/*/ 2>/dev/null | grep -E '/[0-9]+(\\.[0-9]+)+/$' | sort -V | tail -1)"; [ -z "$d" ] && exit 0; exec ${nodePath} "\${d}src/cc-cream.js"`;
+export function statusLineCommand(nodePath, entrypoint) {
+  return `[ -f "${entrypoint}" ] || exit 0; exec "${nodePath}" "${entrypoint}"`;
 }
 
 // `desired` is considered already installed if it matches the planned command
-// verbatim (so switching strategy or node path re-plans), at refreshInterval 60.
+// verbatim (so a changed version path or node path re-plans), at refreshInterval 60.
 function isInstalled(existing, command) {
   return (
     !!existing &&
@@ -90,21 +98,19 @@ export function planUninstall(settings) {
 }
 
 // Decide what to do. Returns { settings, changed, messages, needsConsent }.
-// `consent` is the user's yes/no when an existing statusLine must be replaced.
+// `consent` is the user's yes/no when a FOREIGN statusLine must be replaced.
 //
-// Two command strategies:
-//   - manual (default): `node <entrypoint>` pointing at the copied-to-home runtime.
-//   - plugin: the cache-glob auto-update command, using the absolute `nodePath`.
-//     Pass `{ plugin: true, nodePath }` to select it; the plugin cache IS the
-//     install, so no files are copied to home in that mode.
-export function plan(settings, { entrypoint, consent, plugin = false, nodePath } = {}) {
+// Both install modes produce the same command shape (statusLineCommand); only
+// the entrypoint differs:
+//   - manual (default): the copied-to-home runtime (~/.claude/cc-cream/cc-cream.js).
+//   - plugin: the versioned plugin-cache entrypoint (install.js's sibling).
+// Pass `{ entrypoint, nodePath }` for either.
+export function plan(settings, { entrypoint, consent, nodePath } = {}) {
   const s = settings && typeof settings === 'object' ? settings : {};
   const existing = s.statusLine;
   const messages = [];
 
-  const command = plugin
-    ? autoUpdateCommand(nodePath)
-    : `node ${entrypoint}`;
+  const command = statusLineCommand(nodePath, entrypoint);
   const desired = { type: 'command', command, refreshInterval: 60 };
   // Preserve any user padding — it shrinks the 80-col budget (PRD §7).
   if (existing && typeof existing === 'object' && existing.padding !== undefined) {
@@ -116,9 +122,11 @@ export function plan(settings, { entrypoint, consent, plugin = false, nodePath }
     return { settings: s, changed: false, messages, needsConsent: false };
   }
 
-  // An existing (different) statusLine must be confirmed before replacing.
-  const hasExisting = existing && typeof existing === 'object';
-  if (hasExisting) {
+  // A FOREIGN statusLine must be confirmed before replacing. Replacing our OWN
+  // out-of-date line (e.g. re-pinning to a new version after /plugin update)
+  // needs no consent — it's ours to maintain.
+  const hasForeign = existing && typeof existing === 'object' && !isCcCreamStatusLine(existing);
+  if (hasForeign) {
     messages.push('An existing statusLine is configured.');
     messages.push('Replace it with cc-cream?');
     if (consent !== true) {
@@ -129,7 +137,7 @@ export function plan(settings, { entrypoint, consent, plugin = false, nodePath }
 
   messages.push('Setting the cc-cream statusLine.');
   messages.push(TRUST_NOTE);
-  return { settings: { ...s, statusLine: desired }, changed: true, messages, needsConsent: hasExisting };
+  return { settings: { ...s, statusLine: desired }, changed: true, messages, needsConsent: hasForeign };
 }
 
 // ---------------------------------------------------------------------------
@@ -143,30 +151,26 @@ function destinationPath() {
   return path.join(os.homedir(), '.claude', 'cc-cream', 'cc-cream.js');
 }
 
-// Read settings.json safely. A MISSING or empty file -> {} (fresh start, nothing
-// to lose). A file that exists with content but fails to parse, or parses to a
-// non-object, is REFUSED: we exit rather than overwrite and erase the user's
-// other settings (permissions, hooks, plugins...). This guards the one path
-// where a blind write would be destructive.
+// Read settings.json safely for the CLI. A MISSING or empty file -> {} (fresh
+// start, nothing to lose); a valid object is returned as-is. Any other state
+// (corrupt JSON, a non-object, or an unreadable file) is REFUSED: we exit rather
+// than overwrite and erase the user's other settings (permissions, hooks,
+// plugins...). This guards the one path where a blind write would be destructive.
 function readSettings(file) {
-  if (!fs.existsSync(file)) return {};
-  const raw = fs.readFileSync(file, 'utf8');
-  if (raw.trim() === '') return {};
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
+  const { state, value } = readSettingsFile(file);
+  if (isSafeToWrite(state)) return value;
+  if (state === 'corrupt') {
     console.error(`Error: ${file} is not valid JSON.`);
     console.error('Refusing to write it — that would erase your other settings.');
     console.error('Fix the JSON (or move the file aside) and re-run.');
-    process.exit(1);
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+  } else if (state === 'nonobject') {
     console.error(`Error: ${file} does not contain a JSON object.`);
     console.error('Refusing to overwrite it. Move it aside and re-run if intended.');
-    process.exit(1);
+  } else {
+    console.error(`Error: cannot read ${file}.`);
+    console.error('Refusing to overwrite it. Fix permissions (or move it aside) and re-run.');
   }
-  return parsed;
+  process.exit(1);
 }
 
 function runtimeFiles(sourceFile) {
@@ -221,7 +225,7 @@ async function uninstall({ purge }) {
   const result = planUninstall(settings);
   for (const m of result.messages) console.log(m);
   if (result.changed) {
-    fs.writeFileSync(file, `${JSON.stringify(result.settings, null, 2)}\n`);
+    writeFileAtomic(file, `${JSON.stringify(result.settings, null, 2)}\n`);
     console.log(`\nUpdated ${file}.`);
   }
 
@@ -260,8 +264,43 @@ async function uninstall({ purge }) {
   console.log('\nRestart Claude Code to drop the bar.');
 }
 
+// `cc-cream-setup --check-config`: lint ~/.claude/cc-cream.json against the
+// config schema, reporting unknown keys and out-of-domain values (which the
+// renderer silently ignores). Exits non-zero when problems are found.
+function checkConfigCli() {
+  const file = path.join(os.homedir(), '.claude', 'cc-cream.json');
+  if (!fs.existsSync(file)) {
+    console.log(`No config at ${file} — cc-cream uses its defaults. Nothing to check.`);
+    return;
+  }
+  const raw = fs.readFileSync(file, 'utf8');
+  if (raw.trim() === '') {
+    console.log(`${file} is empty — cc-cream uses its defaults. Nothing to check.`);
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    console.error(`Error: ${file} is not valid JSON — the whole file is ignored.`);
+    process.exit(1);
+  }
+  const problems = checkConfig(parsed);
+  if (problems.length === 0) {
+    console.log(`${file}: OK — config looks good.`);
+    return;
+  }
+  console.error(`${file}: ${problems.length} problem(s) — each falls back to the default:`);
+  for (const p of problems) console.error(`  - ${p}`);
+  process.exit(1);
+}
+
 async function main() {
   const args = process.argv.slice(2);
+  if (args.includes('--check-config')) {
+    checkConfigCli();
+    return;
+  }
   if (args.includes('--uninstall')) {
     await uninstall({ purge: args.includes('--purge') });
     return;
@@ -274,18 +313,21 @@ async function main() {
   const file = settingsPath();
   const settings = readSettings(file);
 
-  // planOpts holds whatever the chosen strategy needs to build its command.
+  // planOpts holds the entrypoint + node path the command bakes in.
   let planOpts;
   if (plugin) {
-    // Plugin mode: the plugin cache IS the install — do NOT copy to home. The
-    // command self-resolves the latest cached version on every render.
-    planOpts = { plugin: true, nodePath: resolveNodePath() };
+    // Plugin mode: the plugin cache IS the install — do NOT copy to home. Point
+    // the statusLine at this install.js's sibling cc-cream.js, i.e. the current
+    // version's absolute path in the plugin cache. The SessionStart hook re-pins
+    // it after a /plugin update (the command can't self-resolve the version).
+    const entrypoint = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'cc-cream.js');
+    planOpts = { entrypoint, nodePath: resolveNodePath() };
   } else {
     // Manual / GitHub mode: copy the runtime into ~/.claude/cc-cream and point
-    // the statusLine at that copied entrypoint.
+    // the statusLine at that copied (stable) entrypoint.
     const sourceFile = positional[0]
       ? path.resolve(positional[0])
-      : path.resolve(path.dirname(new URL(import.meta.url).pathname), 'cc-cream.js');
+      : path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'cc-cream.js');
 
     if (!fs.existsSync(sourceFile)) {
       console.error(`Error: cc-cream.js not found at ${sourceFile}`);
@@ -297,7 +339,7 @@ async function main() {
     if (copyRuntimeFiles(sourceFile, destDir)) {
       console.log(`Copied cc-cream runtime files to ${destDir}`);
     }
-    planOpts = { entrypoint: dest };
+    planOpts = { entrypoint: dest, nodePath: resolveNodePath() };
   }
 
   let result = plan(settings, planOpts);
@@ -323,7 +365,7 @@ async function main() {
   for (const m of result.messages) console.log(m);
   if (result.changed) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, `${JSON.stringify(result.settings, null, 2)}\n`);
+    writeFileAtomic(file, `${JSON.stringify(result.settings, null, 2)}\n`);
     console.log(`\nWrote ${file}.`);
   }
 }

package/src/render.js

@@ -3,12 +3,21 @@ import { renderSegments } from './segments.js';
 import { resolveTtl } from './ttl.js';
 import { paint } from './utils.js';
 
-// Assemble enabled+visible segments into up to three rows.
-export function render(data, cfg, env, now, prevSessionState = null) {
+// Build the raw segment map (id → {text,color}|null) plus the resolved ttlMin.
+// Shared by render() and the CC_CREAM_DEBUG diagnostics so the segment logic runs
+// through exactly one path. `ttlAnchorMs` is injected by the I/O layer.
+export function buildSegments(data, cfg, env, now, prevSessionState = null, ttlAnchorMs = null) {
   const ttlMin = resolveTtl({ rateLimits: data?.rate_limits, config: cfg, env });
   // CC_CREAM_TZ is an internal test/diagnostic seam, not a documented config key.
   const tz = env?.CC_CREAM_TZ || 'America/Los_Angeles';
-  const segs = renderSegments(data, cfg, ttlMin, now, prevSessionState, tz);
+  return { ttlMin, segs: renderSegments(data, cfg, ttlMin, now, prevSessionState, tz, ttlAnchorMs) };
+}
+
+// Assemble enabled+visible segments into up to three rows. `ttlAnchorMs` (the
+// resolved cache-window reset time) is computed by the I/O layer and injected so
+// render and the segments stay free of filesystem access.
+export function render(data, cfg, env, now, prevSessionState = null, ttlAnchorMs = null) {
+  const { segs } = buildSegments(data, cfg, env, now, prevSessionState, ttlAnchorMs);
 
   const visible = (id, row) => cfg.segments[id]?.on && segs[id] && cfg.segments[id].row === row;
   const byOrder = (a, b) => cfg.segments[a].order - cfg.segments[b].order;

package/src/segments.js

@@ -1,4 +1,3 @@
-import fs from 'node:fs';
 import { band, countdown, flipPct, fmtNum, isNum, isPeak, numOr, pad2 } from './utils.js';
 import { hasWindow } from './ttl.js';
 
@@ -56,25 +55,12 @@ function segCache(data, cfg, prevCachePct, recovering) {
   return { text: `cache:${pct}%`, color };
 }
 
-function segTtl(data, cfg, ttlMin, now, prevSessionState) {
-  const prevTokens = prevSessionState?.total_input_tokens;
-  const curTokens = data?.context_window?.total_input_tokens;
-  const tokensGrew = isNum(curTokens) && isNum(prevTokens) && curTokens > prevTokens;
-
-  let anchorMs;
-  if (tokensGrew) {
-    anchorMs = now;
-  } else if (isNum(prevSessionState?.last_api_ts)) {
-    anchorMs = prevSessionState.last_api_ts;
-  } else {
-    const tp = data?.transcript_path;
-    if (typeof tp !== 'string' || tp === '') return null;
-    try {
-      anchorMs = fs.statSync(tp).mtimeMs;
-    } catch {
-      return null;
-    }
-  }
+// Pure: the TTL anchor (when the cache window last reset) is resolved upstream in
+// the I/O layer — see resolveTtlAnchor() in cc-cream.js — and injected as
+// `anchorMs`, so this segment does no filesystem access. A null anchor (no token
+// growth, no last_api_ts, no readable transcript) hides the segment.
+function segTtl(cfg, ttlMin, now, anchorMs) {
+  if (!isNum(anchorMs)) return null;
   const elapsedMin = Math.floor(Math.max(0, now - anchorMs) / 60000);
   const remainingMin = Math.max(0, ttlMin - elapsedMin);
   const text = `ttl:${pad2(Math.floor(remainingMin / 60))}:${pad2(remainingMin % 60)}`;
@@ -158,7 +144,7 @@ function segBurn(fiveHour, prev, now) {
   return { text: h >= 1 ? `~${h}h${pad2(m)}m` : `~${minEta}m`, color: null };
 }
 
-export function renderSegments(data, cfg, ttlMin, now, prevSessionState = null, tz = 'America/Los_Angeles') {
+export function renderSegments(data, cfg, ttlMin, now, prevSessionState = null, tz = 'America/Los_Angeles', ttlAnchorMs = null) {
   return {
     model: segModel(data),
     ctx: segCtx(data, cfg),
@@ -168,7 +154,7 @@ export function renderSegments(data, cfg, ttlMin, now, prevSessionState = null,
       prevSessionState && isNum(prevSessionState.cache_pct) ? prevSessionState.cache_pct : undefined,
       prevSessionState?.recovering === true,
     ),
-    ttl: segTtl(data, cfg, ttlMin, now, prevSessionState),
+    ttl: segTtl(cfg, ttlMin, now, ttlAnchorMs),
     cost: segCost(data),
     '5h': segRate(data?.rate_limits?.five_hour, '5h', cfg, '5h', now),
     '7d': segRate(data?.rate_limits?.seven_day, '7d', cfg, '7d', now),

package/src/settings.js

@@ -0,0 +1,64 @@
+// Shared settings.json I/O for the installer (src/install.js) and the
+// SessionStart hook (hooks/auto-setup.js). Both must read settings.json without
+// ever destroying it, and write it atomically. Previously each carried its own
+// copy of this safety-critical parsing; they live here once so they can't drift.
+//
+// `readSettings` does NOT decide policy — it classifies the file and lets each
+// caller choose what to do (the installer refuses + exits on a corrupt file; the
+// hook stays silent and leaves it alone). That split is the whole reason this is
+// a classifier returning `{ state, value }` rather than a function that throws.
+
+import fs from 'node:fs';
+import process from 'node:process';
+
+// Read and classify settings.json. Returns `{ state, value }`:
+//   missing   — file absent              → value {}
+//   empty     — present but whitespace    → value {}
+//   object    — valid JSON object         → value <parsed>
+//   nonobject — valid JSON, not an object → value null
+//   corrupt   — invalid JSON              → value null
+//   unreadable— read failed (perms, …)    → value null
+// The destructive-write guard lives in the caller: a non-{missing,empty,object}
+// state means "we cannot safely overwrite this — it holds the user's other
+// config (permissions, hooks, plugins, MCP)".
+export function readSettings(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    return err.code === 'ENOENT' ? { state: 'missing', value: {} } : { state: 'unreadable', value: null };
+  }
+  if (raw.trim() === '') return { state: 'empty', value: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { state: 'corrupt', value: null };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { state: 'nonobject', value: null };
+  }
+  return { state: 'object', value: parsed };
+}
+
+// True when `state` is safe to start from and overwrite (the file holds nothing
+// to lose, or a well-formed object we can extend).
+export function isSafeToWrite(state) {
+  return state === 'missing' || state === 'empty' || state === 'object';
+}
+
+// Write `contents` to `file` atomically: write a sibling temp file, then rename
+// over the target (rename is atomic within a filesystem). settings.json holds
+// the user's permissions/hooks/plugins/MCP config — a direct writeFileSync that
+// is interrupted (crash, ENOSPC) could truncate it and erase all of that. The
+// temp file shares the target's directory so the rename never crosses devices.
+export function writeFileAtomic(file, contents) {
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, contents);
+  try {
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+    throw err;
+  }
+}

package/src/state.js

@@ -1,6 +1,17 @@
 import fs from 'node:fs';
+import process from 'node:process';
 import { isNum, numOr } from './utils.js';
 
+// Cap on retained per-session entries. The state file gains one key per
+// session_id and is never otherwise pruned, so without a cap it grows without
+// bound. We keep the most-recently-touched sessions (by `ts`) and drop the rest.
+const MAX_SESSIONS = 50;
+
+// session_id is used as an object key. A value of __proto__/constructor/prototype
+// would mutate the object's prototype instead of storing data; reject those so a
+// crafted or poisoned id can't corrupt the session map.
+const isUnsafeKey = (k) => k === '__proto__' || k === 'constructor' || k === 'prototype';
+
 export function readState(stateFilePath) {
   try {
     const raw = fs.readFileSync(stateFilePath, 'utf8');
@@ -13,25 +24,45 @@ export function readState(stateFilePath) {
 }
 
 export function writeState(stateFilePath, state) {
+  // Atomic write: a direct writeFileSync interrupted mid-write (crash, ENOSPC)
+  // would truncate the state file. Write a sibling temp file, then rename over
+  // the target (atomic within a filesystem; the temp shares the target's dir so
+  // the rename never crosses devices). State is regenerable, so any failure
+  // degrades silently — a stateless render is fine.
+  const tmp = `${stateFilePath}.tmp-${process.pid}`;
   try {
-    fs.writeFileSync(stateFilePath, JSON.stringify(state));
+    fs.writeFileSync(tmp, JSON.stringify(state));
+    fs.renameSync(tmp, stateFilePath);
   } catch {
-    // degrade silently — stateless render is fine
+    try { fs.rmSync(tmp, { force: true }); } catch {}
   }
 }
 
 export function getSessionState(state, sessionId) {
-  if (!sessionId || typeof sessionId !== 'string') return null;
+  if (!sessionId || typeof sessionId !== 'string' || isUnsafeKey(sessionId)) return null;
   const sessions = state?.sessions;
   if (!sessions || typeof sessions !== 'object') return null;
-  return sessions[sessionId] ?? null;
+  return Object.hasOwn(sessions, sessionId) ? sessions[sessionId] : null;
+}
+
+// Keep at most MAX_SESSIONS entries, evicting the lowest `ts` (oldest touched)
+// first. Sessions without a numeric ts sort oldest.
+function prune(sessions) {
+  const keys = Object.keys(sessions);
+  if (keys.length <= MAX_SESSIONS) return sessions;
+  const keep = keys
+    .sort((a, b) => numOr(sessions[b]?.ts, 0) - numOr(sessions[a]?.ts, 0))
+    .slice(0, MAX_SESSIONS);
+  const out = {};
+  for (const k of keep) out[k] = sessions[k];
+  return out;
 }
 
 export function patchSessionState(state, sessionId, patch) {
-  if (!sessionId || typeof sessionId !== 'string') return state;
+  if (!sessionId || typeof sessionId !== 'string' || isUnsafeKey(sessionId)) return state;
   const sessions = { ...(state?.sessions ?? {}) };
   sessions[sessionId] = { ...(sessions[sessionId] ?? {}), ...patch };
-  return { ...state, sessions };
+  return { ...state, sessions: prune(sessions) };
 }
 
 export function nextSessionPatch(data, prevSessionState, cfg, now) {

package/src/utils.js

@@ -32,8 +32,19 @@ export function fmtNum(n, mode) {
   return String(n);
 }
 
+// Strip C0/C1 control characters (incl. ESC, BEL, DEL) from any text bound for
+// the terminal. stdin fields like session_name, model.display_name, and
+// effort.level are echoed into the status line verbatim; without this, escape
+// sequences smuggled into them would be interpreted by the terminal (title/OSC
+// rewrites, clipboard writes, cursor moves that spoof or hide output). The bar
+// is purely visual, so dropping control bytes is lossless. The tool's own ANSI
+// color codes are added AFTER sanitizing, so they survive.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control bytes is the intent
+const sanitize = (text) => String(text).replace(/[\x00-\x1f\x7f-\x9f]/g, '');
+
 export function paint(text, color) {
-  return color && ANSI[color] ? `${ANSI[color]}${text}\x1b[0m` : text;
+  const clean = sanitize(text);
+  return color && ANSI[color] ? `${ANSI[color]}${clean}\x1b[0m` : clean;
 }
 
 // 3-arg form: band(value, amber, red) — used by ttl / rate limits.