cc-cream 0.1.18 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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

package/README.md

@@ -173,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",
@@ -285,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.18",
+  "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.
+//
+// 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 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
+// 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,46 +151,26 @@ function destinationPath() {
   return path.join(os.homedir(), '.claude', 'cc-cream', 'cc-cream.js');
 }
 
-// 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;
-  }
-}
-
-// 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) {
@@ -276,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;
@@ -290,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}`);
@@ -313,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);

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;
+  }
+}