cc-cream 0.1.18 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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).
 
+## [Unreleased]
+
+## [0.3.0] — 2026-05-30
+
+### Added
+- **`cc-cream-setup --status` — a read-only footprint report.** Because no Claude Code host removal path drops our `statusLine` or garbage-collects the version cache, users couldn't easily tell whether cc-cream had fully gone away. `--status` reports the whole footprint in one shot: the `statusLine` wiring (flagging a stale/ghost line whose entrypoint is missing), every cached plugin version, the marketplace clone + both registrations, the auto-wire marker, session state, config, and the manual runtime copy — with a "clean slate" verdict when nothing remains and removal guidance when something does (CREAM-zgdcbmfj).
+
+### Fixed
+- **The status bar no longer zombies after the plugin is uninstalled.** No Claude Code host removal path deletes our `statusLine` *or* the version cache: `/plugin uninstall` is partial (it deregisters the plugin but leaves the cache tree and our `statusLine`), so the entrypoint still exists and the `[ -f … ] || exit 0` guard can never fire — the bar kept rendering every session, with no in-product way out (`/cc-cream:uninstall` deregisters with the plugin). The renderer now defends itself: when it detects it's running **from the plugin cache** while cc-cream is **absent from `~/.claude/plugins/installed_plugins.json`**, it exits 0 silently. The check costs one tiny read and runs *only* on the plugin-cache path — manual/npm installs skip it entirely. A corrupt/unreadable registry is treated as "still installed" so a transient glitch can't suppress a live bar (CREAM-uchemxln).
+- **Non-interactive `--force` no longer prints a contradictory "Declined … then replaced" receipt.** The installer's consent path printed the detection-only first plan pass — including a speculative "Declined — your existing statusLine is unchanged." — and then replaced the line anyway. It now resolves consent first and prints a single coherent result (CREAM-hpjebzes).
+
+### Changed
+- **Setup/uninstall copy now matches how the bar actually appears.** The status line shows on the **next message** of a new session — no restart needed; a restart only matters for an already-open session. The installer note, the `SessionStart` hook message, and the uninstall receipt were reworded accordingly (dropping the misleading "Restart Claude Code" framing) (CREAM-wvtiftfw).
+- **`/cc-cream:uninstall` is now self-sufficient.** It auto-cleans the regenerable scratch (the copied runtime and `cc-cream-state.json`) with no prompt — the old interactive artifact prompt was dead code, since both the `!` bang runner and the slash commands run without a TTY. `--purge` additionally removes the user-authored `~/.claude/cc-cream.json`, and `commands/uninstall.md` now forwards `$ARGUMENTS` so `/cc-cream:uninstall --purge` actually reaches the script. The closing receipt enumerates the final state and the leftovers the host *doesn't* clean — the version cache (`rm -rf ~/.claude/plugins/cache/cc-cream`), `/plugin marketplace remove`, the slash commands that linger until restart, and the npm-free cache-path escape hatch (CREAM-lznfgrap, CREAM-wvtiftfw).
+
+### Internal
+- **One-command releases (`npm run release <patch|minor|major>`).** A new `scripts/release.mjs` bumps every version location in lockstep — `package.json`, `package-lock.json`, and `.claude-plugin/plugin.json` — and rolls the CHANGELOG's `[Unreleased]` section into a dated `## [x.y.z]` heading, gates on the test suite, then commits + tags (and pushes + creates the GitHub Release with `--publish`). It removes the hand-syncing every prior release required, where `npm version` touched only the first two and the version-match gate punished the drift. A new CI gate (`features/25`) now also asserts `plugin.json`'s version matches `package.json`, so that manifest can no longer go stale.
+
+## [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

@@ -136,36 +136,56 @@ Plugin users — two steps, **in this order** (Claude Code can't clean
 from the cache):
 ```
 /cc-cream:uninstall          # 1. removes the statusLine wiring (run this FIRST)
-/plugin uninstall cc-cream   # 2. drops the plugin from the cache
+/plugin uninstall cc-cream   # 2. drops the plugin
 ```
-
-> **Order matters.** `/cc-cream:uninstall` lives inside the plugin, so once you
-> run `/plugin uninstall` it's gone. The status line itself degrades to nothing
-> if the cache is missing (it won't error), but the now-inert `statusLine` block
-> lingers in `settings.json`. To clear it after the plugin is already gone, run
-> the npm bin (no global install needed):
+`/cc-cream:uninstall` also auto-cleans cc-cream's regenerable scratch (the copied
+runtime and session-state file); add `--purge` (`/cc-cream:uninstall --purge`) to
+also delete your `~/.claude/cc-cream.json` config. The bar disappears on your next
+message — restart an already-open session to drop it immediately.
+
+> **Order matters — but you're covered if you get it wrong.** `/cc-cream:uninstall`
+> lives inside the plugin, so once you run `/plugin uninstall` it's gone. Neither
+> host command clears the `statusLine` block *or* the version cache. The renderer
+> notices when it's running from a cache the host no longer lists as installed and
+> **self-suppresses**, so the bar stops on the next session even though the inert
+> `statusLine` line still lingers in `settings.json`.
+>
+> To clear that leftover line once the plugin is gone, the **guaranteed** route is
+> the copy of the uninstaller still in the cache — npm-free and always present:
+> ```bash
+> node ~/.claude/plugins/cache/cc-cream/cc-cream/<version>/src/install.js --uninstall
+> # add --purge to also remove your config
+> ```
+> The npm bin does the same job, but **not always**: a *freshly published* version
+> is blocked by npm's min-package-age safe-chain guard (it reports "command not
+> found") until it ages in, so use it only if the cache route isn't handy:
 > ```bash
 > npx -y -p cc-cream cc-cream-setup --uninstall
 > ```
-> or remove the `statusLine` key from `~/.claude/settings.json` by hand.
+> You can always remove the `statusLine` key from `~/.claude/settings.json` by hand.
 
 npm / manual users:
 ```bash
-cc-cream-setup --uninstall                 # npm (add --purge to also remove runtime + config)
+cc-cream-setup --uninstall                 # npm (add --purge to also remove the config)
 node cc-cream/src/install.js --uninstall   # manual clone
 ```
 
 Uninstall removes the `statusLine` block **only if it is cc-cream's** — a
-statusLine you wired for something else is left untouched. In a terminal it asks
-before deleting the copied runtime and session-state files; run **non-interactively**
-(as the `/cc-cream:uninstall` slash command does) it leaves those artifacts in
-place — pass `--purge` to remove them and your `~/.claude/cc-cream.json` config.
-Restart Claude Code to clear the bar.
+statusLine you wired for something else is left untouched. It always cleans the
+regenerable scratch (the copied runtime and session state, both recreated on a
+reinstall); `--purge` additionally removes your `~/.claude/cc-cream.json` config.
+The bar clears on your next message (restart an already-open session to drop it now).
 
 Likewise, `cc-cream-setup` run non-interactively will overwrite an existing
 *cc-cream* statusLine but never a foreign one — pass `--force` to replace
 regardless.
 
+Not sure what's left behind? `cc-cream-setup --status` prints a read-only
+footprint report — the statusLine wiring, every cached plugin version (the host
+never garbage-collects these), the marketplace clone + registration, the auto-wire
+marker, session state, config, and the manual runtime copy — so you can confirm a
+clean slate or see exactly what to remove.
+
 ## Configuration
 
 Every display decision is read from `~/.claude/cc-cream.json`. Edit it by hand
@@ -173,6 +193,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 +312,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.3.0",
   "description": "Claude Code cache/context/cost status-line tool",
   "directories": {
     "doc": "docs"
@@ -16,6 +16,7 @@
     "coverage": "c8 cucumber-js",
     "watch": "cucumber-js --watch",
     "hooks": "simple-git-hooks",
+    "release": "node scripts/release.mjs",
     "prepublishOnly": "npm test"
   },
   "simple-git-hooks": {

package/src/cc-cream.js

@@ -3,11 +3,13 @@
 // 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 { fileURLToPath } from 'node:url';
 import { loadConfig, readConfigFile } from './config.js';
-import { render } from './render.js';
+import { buildSegments, render } from './render.js';
 import {
   getSessionState,
   nextSessionPatch,
@@ -15,7 +17,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 +53,139 @@ 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(',')}]`,
+  ]);
+}
+
+// --- Ghost-bar self-defense (CREAM-uchemxln) --------------------------------
+// No Claude Code host removal path deletes our statusLine OR the version cache:
+// `/plugin uninstall` and `/plugin marketplace remove` both leave the cache tree
+// AND the statusLine in settings.json. So a plugin-cache copy of this renderer
+// keeps executing every session after the plugin is gone — a zombie bar the user
+// has no in-product way to stop (`/cc-cream:uninstall` deregisters with the
+// plugin). The shell `[ -f entrypoint ] || exit 0` guard in install.js can't
+// cover this: the cache it checks for is never GC'd, so the file never goes
+// missing. The reliable signal is the host registry, not the filesystem — when we
+// detect we're running FROM the plugin cache, confirm cc-cream is still listed in
+// installed_plugins.json; if it's gone, exit 0 silently.
+
+function realpathOr(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+// If `selfPath` lives under `<root>/plugins/cache/<marketplace>/<plugin>/...`,
+// return { pluginsDir, pluginHome }; otherwise null (a manual/dev install, which
+// is never a cache orphan). Both paths are derived from the running location, so
+// the registry we consult is the one that actually governs THIS install — no
+// os.homedir()/CLAUDE_CONFIG_DIR assumption.
+function pluginCacheLocation(selfPath) {
+  const segs = realpathOr(selfPath).split(path.sep);
+  for (let i = 0; i + 3 < segs.length; i++) {
+    if (segs[i] === 'plugins' && segs[i + 1] === 'cache') {
+      return {
+        pluginsDir: segs.slice(0, i + 1).join(path.sep),
+        pluginHome: segs.slice(0, i + 4).join(path.sep),
+      };
+    }
+  }
+  return null;
+}
+
+function isWithin(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+// True when this renderer is a plugin-cache orphan: running from the cache while
+// cc-cream is absent from the host's installed_plugins.json. Cost is one tiny
+// read, and ONLY on the plugin-cache path — manual/dev installs return early
+// before touching the disk. A missing registry (ENOENT) counts as orphaned; any
+// other read/parse failure is treated as not-orphaned, so a transient glitch can
+// never suppress a legitimately wired bar.
+function isOrphanedPluginRun(selfPath) {
+  const loc = pluginCacheLocation(selfPath);
+  if (!loc) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(path.join(loc.pluginsDir, 'installed_plugins.json'), 'utf8'));
+  } catch (err) {
+    return err?.code === 'ENOENT';
+  }
+  const plugins = parsed && typeof parsed === 'object' ? parsed.plugins : null;
+  if (!plugins || typeof plugins !== 'object') return true;
+  const home = realpathOr(loc.pluginHome);
+  for (const entries of Object.values(plugins)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (entry && typeof entry.installPath === 'string' && isWithin(home, realpathOr(entry.installPath))) {
+        return false; // an installed cc-cream entry lives in our cache subtree
+      }
+    }
+  }
+  return true;
+}
+
 async function main() {
-  const data = parseSession(await readStdin());
+  // Self-suppress a zombie bar left behind by an uninstalled plugin (before any
+  // stdin read — matching the intent of install.js's now-dead `[ -f ]` guard).
+  if (isOrphanedPluginRun(fileURLToPath(import.meta.url))) process.exit(0);
+
+  const raw = await readStdin();
+  const data = parseSession(raw);
   const cfg = loadConfig(readConfigFile());
   const now = nowFromEnv(process.env);
 
@@ -61,9 +194,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 bar appears on your next message — restart only an already-open session, and the workspace must be trusted.';
 
-// 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) {
@@ -229,8 +217,13 @@ function ask(question) {
   }));
 }
 
-// Remove the cc-cream wiring (and, with consent, its install artifacts). Keeps
-// the user's config (~/.claude/cc-cream.json) unless `--purge` is passed.
+// Remove the cc-cream wiring and its throwaway scratch. The copied runtime
+// (~/.claude/cc-cream) and session state (~/.claude/cc-cream-state.json) are
+// regenerable — reinstalling recreates them — so they're always cleaned, no
+// prompt. (The old interactive artifact prompt was dead code: both the `!` bang
+// runner and the slash commands run non-TTY — CREAM-lznfgrap.) `--purge`
+// additionally removes the one file worth keeping by default: the user-authored
+// config (~/.claude/cc-cream.json).
 async function uninstall({ purge }) {
   const file = settingsPath();
   const settings = readSettings(file);
@@ -238,46 +231,192 @@ async function uninstall({ purge }) {
   for (const m of result.messages) console.log(m);
   if (result.changed) {
     writeFileAtomic(file, `${JSON.stringify(result.settings, null, 2)}\n`);
-    console.log(`\nUpdated ${file}.`);
+    console.log(`Updated ${file}.`);
   }
 
   const home = path.join(os.homedir(), '.claude');
-  const runtimeDir = path.join(home, 'cc-cream');
-  const stateFile = path.join(home, 'cc-cream-state.json');
   const configFile = path.join(home, 'cc-cream.json');
 
-  const artifacts = [runtimeDir, stateFile].filter((p) => fs.existsSync(p));
-  if (artifacts.length) {
-    let remove = purge;
-    if (!remove && process.stdin.isTTY) {
-      remove = await ask(`Also delete the copied runtime and session state?\n  ${artifacts.join('\n  ')}`);
-    }
-    if (remove) {
-      for (const p of artifacts) fs.rmSync(p, { recursive: true, force: true });
-      console.log('Removed runtime and state files.');
-    } else if (process.stdin.isTTY) {
-      console.log('Left runtime and state files in place.');
+  // Auto-clean regenerable scratch (not user data — no prompt).
+  const scratch = [path.join(home, 'cc-cream'), path.join(home, 'cc-cream-state.json')]
+    .filter((p) => fs.existsSync(p));
+  for (const p of scratch) fs.rmSync(p, { recursive: true, force: true });
+  if (scratch.length) console.log('Removed the copied runtime and session state.');
+
+  if (fs.existsSync(configFile)) {
+    if (purge) {
+      fs.rmSync(configFile, { force: true });
+      console.log(`Removed your config ${configFile}.`);
     } else {
-      // Non-interactive (e.g. run via the /cc-cream:uninstall slash command, which
-      // has no TTY): never block on a prompt. The statusLine — the thing that
-      // matters — is already removed; keep the artifacts (deletion is destructive)
-      // and say how to remove them.
-      console.log(`Left runtime and session state in place — no terminal to confirm deletion:\n  ${artifacts.join('\n  ')}`);
-      console.log('Re-run in a terminal, or pass --purge, to remove them.');
+      console.log(`Kept your config ${configFile} (pass --purge to remove it too).`);
     }
   }
-  if (purge && fs.existsSync(configFile)) {
-    fs.rmSync(configFile, { force: true });
-    console.log(`Removed config ${configFile}.`);
-  } else if (fs.existsSync(configFile)) {
-    console.log(`Kept your config ${configFile} (pass --purge to remove it too).`);
+
+  printUninstallReceipt();
+}
+
+// The closing receipt. No Claude Code host removal path drops our statusLine OR
+// the version cache, so spell out what's gone, what the host leaves behind, and
+// the npm-free escape hatch (the lingering cache always has a working install.js).
+// See project memory cc-cream-plugin-lifecycle-findings.
+function printUninstallReceipt() {
+  console.log('\nDone — the bar disappears on your next message (restart an already-open session to drop it now).');
+  console.log('The host leaves the rest behind; to fully remove cc-cream:');
+  console.log('  • Plugin: /plugin uninstall cc-cream  then  /plugin marketplace remove cc-cream');
+  console.log('  • Version cache (never auto-removed): rm -rf ~/.claude/plugins/cache/cc-cream');
+  console.log('  • The /cc-cream:* slash commands linger in this session until you restart Claude Code.');
+  console.log('Already removed the plugin? This same uninstall lives in the cache:');
+  console.log('  node ~/.claude/plugins/cache/cc-cream/cc-cream/<version>/src/install.js --uninstall [--purge]');
+}
+
+// `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);
+}
 
-  console.log('\nRestart Claude Code to drop the bar.');
+function listDirs(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// `cc-cream-setup --status`: a read-only report of cc-cream's entire on-disk
+// footprint. Because no Claude Code host removal path drops our statusLine or GCs
+// the version cache (project memory cc-cream-plugin-lifecycle-findings), users
+// can't otherwise tell whether cc-cream fully went away — this command answers
+// "clean slate?" in one shot, and points out what the host left behind.
+function statusCli() {
+  const home = path.join(os.homedir(), '.claude');
+  const plugins = path.join(home, 'plugins');
+  const items = [];
+  const add = (label, present, detail) => items.push({ label, present, detail });
+
+  // statusLine wiring
+  const { state, value } = readSettingsFile(settingsPath());
+  if (!isSafeToWrite(state)) {
+    add('statusLine wiring', false, `settings.json unreadable (${state}) — not inspected`);
+  } else if (isCcCreamStatusLine(value.statusLine)) {
+    const ep = (value.statusLine.command.match(/\[ -f "([^"]+)"/) || [])[1] || '';
+    const ok = ep && fs.existsSync(ep);
+    add('statusLine wiring', true, ok
+      ? `belongs to cc-cream, pinned to ${ep}`
+      : `belongs to cc-cream, pinned to ${ep || '(unknown)'} — entrypoint MISSING (stale/ghost wiring)`);
+  } else if (value.statusLine) {
+    add('statusLine wiring', false, 'present but not cc-cream’s (left untouched)');
+  } else {
+    add('statusLine wiring', false, 'none');
+  }
+
+  // plugin cache versions (the host never GCs these)
+  const versions = listDirs(path.join(plugins, 'cache', 'cc-cream', 'cc-cream'));
+  add('plugin cache', versions.length > 0, versions.length
+    ? `${versions.length} version(s) [${versions.join(', ')}] — host never GCs these; rm to reclaim`
+    : 'none');
+
+  // marketplace clone
+  const clone = path.join(plugins, 'marketplaces', 'cc-cream');
+  add('marketplace clone', fs.existsSync(clone), fs.existsSync(clone) ? clone : 'none');
+
+  // registrations
+  const installed = readJsonSafe(path.join(plugins, 'installed_plugins.json'));
+  const isRegistered = !!installed?.plugins && typeof installed.plugins === 'object'
+    && Object.keys(installed.plugins).some((k) => k.startsWith('cc-cream@'));
+  add('plugin registration', isRegistered, isRegistered
+    ? 'listed in installed_plugins.json'
+    : 'not listed in installed_plugins.json');
+
+  const known = readJsonSafe(path.join(plugins, 'known_marketplaces.json'));
+  const knownMkt = !!known && typeof known === 'object' && Object.hasOwn(known, 'cc-cream');
+  add('marketplace registration', knownMkt, knownMkt
+    ? 'listed in known_marketplaces.json'
+    : 'not listed in known_marketplaces.json');
+
+  // auto-wire marker (plugin data dir, falling back to the config dir)
+  const markerDir = process.env.CLAUDE_PLUGIN_DATA || path.join(plugins, 'data', 'cc-cream-cc-cream');
+  const marker = [path.join(markerDir, 'cc-cream-autowire-done'), path.join(home, 'cc-cream-autowire-done')]
+    .find((p) => fs.existsSync(p));
+  add('auto-wire marker', !!marker, marker || 'none');
+
+  // session state
+  const stateFile = path.join(home, 'cc-cream-state.json');
+  if (fs.existsSync(stateFile)) {
+    const obj = readJsonSafe(stateFile);
+    const n = obj && typeof obj === 'object' ? Object.keys(obj).length : '?';
+    add('session state', true, `${n} session(s) in cc-cream-state.json`);
+  } else {
+    add('session state', false, 'none');
+  }
+
+  // config
+  const configFile = path.join(home, 'cc-cream.json');
+  add('config', fs.existsSync(configFile), fs.existsSync(configFile) ? configFile : 'none (using defaults)');
+
+  // manual runtime copy
+  const runtimeDir = path.join(home, 'cc-cream');
+  add('manual runtime copy', fs.existsSync(runtimeDir), fs.existsSync(runtimeDir) ? runtimeDir : 'none');
+
+  console.log('cc-cream footprint:');
+  for (const it of items) console.log(`  [${it.present ? 'x' : ' '}] ${it.label}: ${it.detail}`);
+
+  if (items.every((i) => !i.present)) {
+    console.log('\nClean slate — no cc-cream footprint found.');
+    return;
+  }
+  console.log(`\n${items.filter((i) => i.present).length} component(s) present. To remove everything:`);
+  console.log('  /cc-cream:uninstall (or the cache-path install.js --uninstall) clears the statusLine + scratch;');
+  console.log('  then /plugin uninstall cc-cream + /plugin marketplace remove cc-cream;');
+  console.log('  then rm -rf ~/.claude/plugins/cache/cc-cream (the host never removes it).');
 }
 
 async function main() {
   const args = process.argv.slice(2);
+  if (args.includes('--status')) {
+    statusCli();
+    return;
+  }
+  if (args.includes('--check-config')) {
+    checkConfigCli();
+    return;
+  }
   if (args.includes('--uninstall')) {
     await uninstall({ purge: args.includes('--purge') });
     return;
@@ -290,18 +429,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,16 +455,19 @@ 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);
-  // If a replace needs consent, ask now and re-plan with the answer.
+  // A foreign statusLine needs consent before we replace it. This first plan()
+  // pass is detection only — do NOT print its messages: they include a
+  // speculative "Declined …" (consent was absent) that would contradict a
+  // subsequent --force replace. Resolve consent, re-plan, then print the single
+  // coherent second-pass result below (CREAM-hpjebzes).
   if (!result.changed && result.needsConsent) {
-    for (const m of result.messages) console.log(m);
     let yes;
     if (process.stdin.isTTY) {
-      yes = await ask('Replace it with cc-cream?');
+      yes = await ask('Replace your existing statusLine with cc-cream?');
     } else {
       // Non-interactive (e.g. run via the /cc-cream:setup slash command, which has
       // no TTY): never block on a prompt. Safe to overwrite our OWN wiring (an
@@ -330,7 +475,7 @@ async function main() {
       // statusLine without a terminal or an explicit --force.
       yes = force || isCcCreamStatusLine(settings.statusLine);
       console.log(yes
-        ? 'Non-interactive: replacing the existing cc-cream statusLine.'
+        ? 'Non-interactive: replacing the existing statusLine with cc-cream’s.'
         : 'Non-interactive: left your existing statusLine unchanged. Re-run in a terminal, or pass --force, to replace it.');
     }
     result = plan(settings, { ...planOpts, consent: yes });

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