cc-cream 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+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.1.0] — 2026-05-29
+
+Initial public release. cc-cream reads the JSON Claude Code pipes to its status
+line and prints a colored ≤3-row bar — zero tokens, the model never sees it.
+
+### Added
+- **Status-line engine** — fourteen configurable segments across up to three
+  rows: `ctx`, `cache`, `write`, `ttl`, `effort`, `thinking`, `api_ratio`,
+  `cost` (row 1); `5h`, `7d`, `burn`, `peak` (row 2, hidden for API users);
+  `model`, `session_name` (row 3). Node built-ins only, no runtime dependencies.
+- **Per-session state** keyed by `session_id` for burn-rate projection, cost
+  delta on `/clear`, and cache-drop detection.
+- **Configuration** via `~/.claude/cc-cream.json` — every display decision
+  (on/off, row, order, thresholds, colors) is data-driven, with per-field and
+  whole-file fallback. Degrades gracefully: malformed input never crashes.
+- **Distribution as a Claude Code plugin** — `.claude-plugin/plugin.json` and a
+  self-hosted `marketplace.json`. Install with
+  `/plugin marketplace add bart-turczynski/cc-cream` then `/plugin install cc-cream`.
+- **`/cc-cream:setup` command** that wires the status line into `settings.json`
+  with a self-resolving cache-glob command, so `/plugin update` applies new
+  versions automatically with no network calls and no re-run of setup.
+- **npm distribution** — `cc-cream` bin with a node shebang; installable via
+  `npx -y cc-cream@latest`.
+- **Consent-based installer** (`src/install.js`) for the manual / GitHub path:
+  copies the runtime into `~/.claude/cc-cream` and writes one `statusLine` block,
+  preserving any existing configuration and asking before replacing it.
+- **Docs & trust** — user-facing README, `SECURITY.md`, `CONTRIBUTING.md`, and a
+  prominent disclosure: no network calls, no telemetry, no runtime dependencies.
+
+### Notes
+- Supports **macOS and Linux**; Windows is a planned fast-follow.
+- Requires Claude Code **2.1.132+** (`effort` / `thinking` need 2.1.145+).
+
+[0.1.0]: https://github.com/bart-turczynski/cc-cream/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bart Turczynski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# cc-cream
+
+**C.R.E.A.M. — Cache Rules Everything Around Me.**
+
+A lightweight status-line tool for [Claude Code](https://claude.com/claude-code)
+that turns the JSON Claude Code pipes to its status line into a glanceable,
+colored ≤3-row bar. The model **never sees the output** — it costs **zero tokens**.
+
+## What it shows
+
+```
+ctx:3% [30k] | cache:55% | ~$0.10
+5h:22% ↺ 0m | 7d:36% ↺ Sat 21:00
+Opus 4.7 (1M context) | example session
+```
+
+> Rendered from a live Claude Code subscriber session (fixtures/subscriber.golden.json).
+> A proper screenshot or asciinema recording will appear here after public release.
+
+- **Row 1** — this session: context-window occupancy, cache hit rate, session cost
+- **Row 2** — rate-limit budget windows: 5h and 7d usage + reset countdown (subscribers only; API users get one row)
+- **Row 3** — identity: model name and optional session name
+
+The bar helps you avoid rate limits, keep the cache warm, and catch context fill
+before the model degrades — with cache economics as the organizing story.
+
+## Trust and data posture
+
+- **No network calls.** The engine is a pure stdin → stdout transformer. It never
+  opens a socket, fetches a URL, or calls home.
+- **No telemetry.** Nothing is collected, reported, or logged anywhere.
+- **No runtime dependencies.** Node built-ins only. `npm install` is for dev tools
+  (Cucumber, Biome) — nothing that runs at render time.
+- **Zero tokens.** Claude Code reads the bar output to display it; the model never
+  receives it.
+
+The only I/O is reading the JSON blob Claude Code pipes on stdin and writing one
+session-state file to `~/.claude/cc-cream-state.json` (keyed by session ID,
+contains cost and rate-limit samples used for the burn projection).
+
+## Requirements
+
+- **Node.js** — already present; Claude Code is a Node app.
+- **Claude Code ≥ 2.1.132** (released 2026-05-06). The cache figure requires
+  `context_window.current_usage`, which landed in that release.
+- The `effort` and `thinking` segments additionally require **Claude Code ≥ 2.1.145**;
+  they stay hidden below that version.
+
+## Platform support
+
+v1 supports **macOS and Linux**. Windows support is a planned fast-follow; the
+engine is pure Node and the only blocker is the statusLine shell-command wiring.
+
+## Install
+
+### Option 1 — Claude Code plugin (community catalog / self-hosted marketplace)
+
+If cc-cream is listed in the community catalog:
+```bash
+/plugin install cc-cream
+```
+
+To use the self-hosted marketplace directly:
+```bash
+/plugin marketplace add bart-turczynski/cc-cream
+/plugin install cc-cream
+```
+
+Then wire it into your settings in one step:
+```
+/cc-cream:setup
+```
+
+The `/cc-cream:setup` command runs the consent installer, which writes the
+`statusLine` block to `~/.claude/settings.json`. Updates are automatic: when
+`/plugin update` drops a new version into the cache, the next render picks it
+up without any further action.
+
+### Option 2 — npm / npx
+
+```bash
+npx -y cc-cream@latest
+```
+
+Or install globally:
+```bash
+npm install -g cc-cream
+```
+
+Then run the consent installer to wire it into Claude Code:
+```bash
+node $(npm root -g)/cc-cream/src/install.js
+```
+
+### Option 3 — Manual GitHub clone
+
+Download and install by cloning the repository, then run the consent installer:
+```bash
+git clone https://github.com/bart-turczynski/cc-cream.git
+node cc-cream/src/install.js
+```
+
+The installer:
+- Detects an existing `statusLine` and **asks before replacing it**
+- **Preserves any `padding`** you have set
+- Is **idempotent** — re-running when cc-cream is already installed changes nothing
+- States the trust and restart requirement
+
+After install, Claude Code must be **trusted** for the directory (if prompted),
+and you may need to **restart** it for the bar to appear.
+
+## Configuration
+
+Every display decision is read from `~/.claude/cc-cream.json`. Edit it by hand
+or ask Claude to. It is strict JSON with no comments. **Every field falls back to
+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.
+
+```json
+{
+  "numbers": "compact",
+  "ttl": "auto",
+  "percentage": "consumed",
+  "segments": {
+    "ctx":          { "on": true,  "row": 1, "order": 2, "amber": 30, "orange": 40, "red": 50, "basis": "window", "ceiling": 200000, "display": "basis" },
+    "cache":        { "on": true,  "row": 1, "order": 3 },
+    "write":        { "on": false, "row": 1, "order": 3.5 },
+    "ttl":          { "on": true,  "row": 1, "order": 4, "amber": 50, "red": 80 },
+    "cost":         { "on": true,  "row": 1, "order": 5 },
+    "effort":       { "on": false, "row": 1, "order": 6 },
+    "thinking":     { "on": false, "row": 1, "order": 7 },
+    "api_ratio":    { "on": false, "row": 1, "order": 8 },
+    "5h":           { "on": true,  "row": 2, "order": 1, "amber": 75, "red": 90 },
+    "burn":         { "on": true,  "row": 2, "order": 1.5 },
+    "7d":           { "on": true,  "row": 2, "order": 2, "amber": 75, "red": 90 },
+    "peak":         { "on": true,  "row": 2, "order": 3, "start": 5, "end": 11 },
+    "model":        { "on": true,  "row": 3, "order": 0.5 },
+    "session_name": { "on": false, "row": 3, "order": 1 }
+  }
+}
+```
+
+### Global keys
+
+- `numbers`: `compact` (e.g. `38k`) or `exact` (`38000`) for token magnitudes.
+- `ttl`: cache time-to-live used to color the `ttl` segment — `auto` (recommended),
+  `60`, or `5` minutes. `auto` infers from rate-limit data when available.
+- `percentage`: `consumed` (default) counts up — `ctx:19%` means 19% of the window
+  is used, `5h:67%` means 67% of the 5h budget is gone. `remaining` flips the
+  budget/occupancy segments to count down (`ctx:81%`, `5h:33%`). Only `ctx`, `5h`
+  and `7d` flip; `cache%` (a hit-rate, not a budget) and `ttl` (a countdown) are
+  unaffected. **Thresholds are always expressed in consumed terms regardless of
+  this setting.**
+
+### Per-segment keys
+
+Every segment accepts:
+- `on` (boolean) — whether to show the segment
+- `row` (1, 2, or 3) — which row to place it on
+- `order` (any number) — lower = further left within the row
+
+Colored segments additionally accept threshold keys. Thresholds mark the
+**lower bound** where that color begins.
+
+### Segment catalog
+
+| Segment | Default | Example | Meaning | Color |
+|---|---|---|---|---|
+| `ctx` | on, row 1 | `ctx:19% [38k]` | context-window occupancy + input-token magnitude | `<30` green · `30–40` amber · `40–50` orange · `≥50` red |
+| `cache` | on, row 1 | `cache:95%` | last-turn cache hit rate (reads / total tokens) | neutral |
+| `write` | **off**, row 1 | `write:4%` | last-turn cache creation rate (new writes / total tokens) | neutral |
+| `ttl` | on, row 1 | `ttl:00:52` | time remaining before cache expires (counts down to 00:00) | `<50%` green · `50–80%` amber · `≥80%` red |
+| `cost` | on, row 1 | `~$4.50` | session cost incl. subagents; `~` = CC's estimate | neutral; hidden when zero |
+| `effort` | **off**, row 1 | `effort:high` | reasoning effort level (requires CC ≥ 2.1.145) | neutral |
+| `thinking` | **off**, row 1 | `think:on` | thinking mode indicator (requires CC ≥ 2.1.145) | neutral |
+| `api_ratio` | **off**, row 1 | `∿ api:74%` | fraction of wall time spent on API calls | neutral |
+| `5h` | on, row 2 | `5h:23% ↺ 2h14m` | 5-hour rate-limit window + reset countdown | `≥75` amber · `≥90` red |
+| `burn` | on, row 2 | `~38m` | estimated minutes until 5h cap at current pace | neutral; hidden when ETA > 5h or no prior sample |
+| `7d` | on, row 2 | `7d:41% ↺ 4d` | weekly rate-limit window + reset countdown | same as 5h |
+| `peak` | on, row 2 | `peak` | weekday Pacific-time window where 5h drains faster | amber; hidden outside window |
+| `model` | on, row 3 | `Sonnet 4.6` | current model name | none |
+| `session_name` | **off**, row 3 | `My project session` | conversation name from CC | none |
+
+Any segment hides cleanly when its source field is absent — API users have no
+`rate_limits`; `current_usage` is null right after `/compact`; etc.
+
+Row 2 is hidden entirely for API users (no `rate_limits` in stdin).
+Row 3 suppresses itself when all its segments are hidden.
+
+### Row 1 layout
+
+Row 1 has two zones separated by ` | `:
+
+```
+[ctx · cache · write · ttl · effort · thinking · api_ratio] | [cost]
+```
+
+Segments within zone 1 are also separated by ` | `. Segments moved off their
+default row via config must land in a zone to appear on row 1.
+
+### `ctx`-specific keys
+
+- `basis`: `window` (default) colors based on `used_percentage` of the real context
+  window. `ceiling` colors based on `total_input_tokens / ceiling`, so the warning
+  fires at the same absolute token count on any window size. On a 1M-context model
+  the window basis stays green well past where quality degrades — set `ceiling` if
+  you want an early warning that doesn't scale with the window.
+- `ceiling`: token count the `ceiling` basis measures against. Default `200000`.
+- `display`: with `basis: "ceiling"`, `basis` (default) shows the % toward the
+  ceiling so number and color agree; `window` pins it to CC's window figure but
+  still colors by the ceiling. No effect under `basis: "window"`.
+
+### `ctx` thresholds
+
+Default: `amber: 30`, `orange: 40`, `red: 50` (percent consumed).
+
+### `ttl` thresholds
+
+Default: `amber: 50`, `red: 80` (percent of the resolved TTL consumed).
+
+### `5h` / `7d` thresholds
+
+Default: `amber: 75`, `red: 90` (absolute `used_percentage`).
+
+### `peak`-specific keys
+
+- `start` / `end`: hours in Pacific time (0–23, exclusive end) bounding
+  Anthropic's faster-drain window. Defaults `5`–`11`. Weekday-only (Mon–Fri) and
+  the `America/Los_Angeles` timezone are hardcoded policy facts, not config.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to run the tests. The runtime
+uses only Node built-ins — no runtime dependencies.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "cc-cream",
+  "version": "0.1.0",
+  "description": "Claude Code cache/context/cost status-line tool",
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "lint": "biome lint src/",
+    "knip": "knip",
+    "validate": "command -v claude >/dev/null 2>&1 && claude plugin validate . || echo 'cc-cream: claude CLI not found — skipping plugin validation'",
+    "pretest": "npm run lint && npm run knip && npm run validate",
+    "test": "cucumber-js",
+    "test:manual": "cucumber-js --profile manual",
+    "coverage": "c8 cucumber-js",
+    "watch": "cucumber-js --watch",
+    "prepare": "simple-git-hooks",
+    "prepublishOnly": "npm test"
+  },
+  "simple-git-hooks": {
+    "pre-push": "npm run coverage"
+  },
+  "bin": {
+    "cc-cream": "src/cc-cream.js"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "status-line",
+    "cache",
+    "context",
+    "cost",
+    "developer-tools"
+  ],
+  "author": "Bart Turczynski <support@spoonkeyworks.com>",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bart-turczynski/cc-cream.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bart-turczynski/cc-cream/issues"
+  },
+  "homepage": "https://github.com/bart-turczynski/cc-cream#readme",
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
+    "@cucumber/cucumber": "^12.9.0",
+    "c8": "^11.0.0",
+    "knip": "^6.14.2",
+    "simple-git-hooks": "^2.13.1"
+  }
+}

package/src/cc-cream.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// cc-cream — Claude Code status-line engine.
+// Reads the session JSON Claude Code pipes on stdin and prints a colored
+// <=3-row bar. Hard rule: degrade, never crash.
+
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { loadConfig, readConfigFile } from './config.js';
+import { render } from './render.js';
+import {
+  getSessionState,
+  nextSessionPatch,
+  patchSessionState,
+  readState,
+  writeState,
+} from './state.js';
+
+export { DEFAULTS } from './defaults.js';
+export { loadConfig } from './config.js';
+export { render } from './render.js';
+export { resolveTtl } from './ttl.js';
+export { countdown, isPeak } from './utils.js';
+export {
+  getSessionState,
+  nextSessionPatch,
+  patchSessionState,
+  readState,
+  writeState,
+} from './state.js';
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function parseSession(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch {
+    // malformed/empty stdin -> render with no data -> empty bar
+  }
+  return {};
+}
+
+function nowFromEnv(env) {
+  const rawNow = env.CC_CREAM_NOW;
+  return rawNow && Number.isFinite(Number(rawNow)) ? Number(rawNow) : Date.now();
+}
+
+async function main() {
+  const data = parseSession(await readStdin());
+  const cfg = loadConfig(readConfigFile());
+  const now = nowFromEnv(process.env);
+
+  const sessionId = typeof data.session_id === 'string' && data.session_id ? data.session_id : null;
+  const stateFile = path.join(os.homedir(), '.claude', 'cc-cream-state.json');
+  const state = sessionId ? readState(stateFile) : {};
+  const prevSessionState = getSessionState(state, sessionId);
+
+  const out = render(data, cfg, process.env, now, prevSessionState);
+  if (out) process.stdout.write(`${out}\n`);
+
+  if (sessionId) {
+    const patch = nextSessionPatch(data, prevSessionState, cfg, now);
+    writeState(stateFile, patchSessionState(state, sessionId, patch));
+  }
+
+  process.exit(0);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  main();
+}

package/src/config.js

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULTS } from './defaults.js';
+import { clone, isNum, numOr } from './utils.js';
+
+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
+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);
+
+function ttlOr(v, d) {
+  if (v === 'auto') return 'auto';
+  if (v === 60 || v === '60') return 60;
+  if (v === 5 || v === '5') return 5;
+  return d;
+}
+
+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);
+
+  const segs = parsed.segments;
+  if (segs && typeof segs === 'object' && !Array.isArray(segs)) {
+    for (const id of Object.keys(DEFAULTS.segments)) {
+      const def = DEFAULTS.segments[id];
+      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);
+      }
+      cfg.segments[id] = out;
+    }
+  }
+  return cfg;
+}
+
+// raw === null/undefined (no file) -> all defaults. Parse error -> all defaults.
+export function loadConfig(raw) {
+  if (raw == null) return clone(DEFAULTS);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return clone(DEFAULTS);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return clone(DEFAULTS);
+  return mergeConfig(parsed);
+}
+
+export function readConfigFile() {
+  try {
+    return fs.readFileSync(path.join(os.homedir(), '.claude', 'cc-cream.json'), 'utf8');
+  } catch {
+    return null;
+  }
+}

package/src/defaults.js

@@ -0,0 +1,44 @@
+// Built-in defaults (PRD §6, minus the dropped `width` key — §14.2).
+// Each colored segment names the LOWER BOUND where a color begins; the color
+// function tests `red` first, then `orange` (ctx only), then `amber`, else green.
+export const DEFAULTS = {
+  numbers: 'compact',     // 'compact' | 'exact'
+  ttl: 'auto',            // 'auto' | 60 | 5
+  percentage: 'consumed', // 'consumed' | 'remaining' — display-only flip of ctx/5h/7d (PRDv2 §3)
+  segments: {
+    model:    { on: true,  row: 3, order: 0.5 },
+    // `basis` picks the fullness reference the color (and, by default, the
+    // shown %) measures against: 'window' = used_percentage of the real window
+    // (no-regression default); 'ceiling' = total_input_tokens / `ceiling`, so
+    // the warning fires at a fixed absolute size on any window. `display`
+    // governs the shown %: 'basis' tracks the coloring basis (number and color
+    // agree), 'window' pins it to CC's window figure regardless (PRD §4.4).
+    ctx:      { on: true,  row: 1, order: 2, amber: 30, orange: 40, red: 50, basis: 'window', ceiling: 200000, display: 'basis' },
+    cache:    { on: true,  row: 1, order: 3, drop: 20, drop_recover: 80 },
+    ttl:      { on: true,  row: 1, order: 4, amber: 50, red: 80 },
+    cost:     { on: true,  row: 1, order: 5 },
+    '5h':     { on: true,  row: 2, order: 1, amber: 75, red: 90 },
+    '7d':     { on: true,  row: 2, order: 2, amber: 75, red: 90 },
+    // peak: amber "peak" word during Anthropic's faster-drain window (PRDv2 §2).
+    // start/end are Pacific-time hours (0–23, exclusive end); weekday (Mon–Fri)
+    // and the America/Los_Angeles timezone are hardcoded policy facts, not config.
+    peak:     { on: true,  row: 2, order: 3, start: 5, end: 11 },
+    burn:         { on: true,  row: 2, order: 1.5 },
+    effort:       { on: false, row: 1, order: 6 },
+    thinking:     { on: false, row: 1, order: 7 },
+    api_ratio:    { on: false, row: 1, order: 8 },
+    session_name: { on: false, row: 3, order: 1 },
+    write:        { on: false, row: 1, order: 3.5 },
+  },
+};
+
+// Row 1 renders as visual zones separated by " | " (PRD §4.3).
+// Empty zones drop out, so a model-only bar is just the name with no separators.
+export const ROW1_ZONES = [['ctx', 'cache', 'write', 'ttl', 'effort', 'thinking', 'api_ratio'], ['cost']];
+
+export const ANSI = {
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  amber: '\x1b[33m',
+  orange: '\x1b[38;5;208m',
+};

package/src/install.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// cc-cream consent-based installer (PRD §7, §14.1). It copies the runtime
+// modules into ~/.claude/cc-cream and writes one `statusLine` block into the
+// user's settings.json after showing the change. It detects and confirms before
+// replacing an existing line, preserves any user `padding`, and surfaces the
+// trust/restart requirement.
+//
+// The pure `plan()` function does all the decision-making (no I/O) so it is
+// testable; the CLI wrapper at the bottom handles reading/prompting/writing.
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import readline from 'node:readline';
+import { pathToFileURL } from 'node:url';
+
+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").
+// `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. `sort -V | tail -1` picks the highest
+// installed version, so `/plugin update` is applied live with no re-run of setup.
+export function autoUpdateCommand(nodePath) {
+  return `${nodePath} "$(ls -1d "\${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/cc-cream/*/ 2>/dev/null | sort -V | tail -1)src/cc-cream.js"`;
+}
+
+// `desired` is considered already installed if it matches the planned command
+// verbatim (so switching strategy or node path re-plans), at refreshInterval 60.
+function isInstalled(existing, command) {
+  return (
+    !!existing &&
+    typeof existing === 'object' &&
+    existing.type === 'command' &&
+    typeof existing.command === 'string' &&
+    existing.command === command &&
+    existing.refreshInterval === 60
+  );
+}
+
+// Decide what to do. Returns { settings, changed, messages, needsConsent }.
+// `consent` is the user's yes/no when an existing 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 } = {}) {
+  const s = settings && typeof settings === 'object' ? settings : {};
+  const existing = s.statusLine;
+  const messages = [];
+
+  const command = plugin
+    ? autoUpdateCommand(nodePath)
+    : `node ${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) {
+    desired.padding = existing.padding;
+  }
+
+  if (isInstalled(existing, command)) {
+    messages.push('cc-cream is already installed — no changes needed.');
+    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) {
+    messages.push(`An existing statusLine is configured:\n  ${JSON.stringify(existing)}`);
+    messages.push('Replace it with cc-cream?');
+    if (consent !== true) {
+      messages.push('Declined — your existing statusLine is unchanged.');
+      return { settings: s, changed: false, messages, needsConsent: true };
+    }
+  }
+
+  messages.push(`Will set statusLine to:\n  ${JSON.stringify(desired)}`);
+  messages.push(TRUST_NOTE);
+  return { settings: { ...s, statusLine: desired }, changed: true, messages, needsConsent: hasExisting };
+}
+
+// ---------------------------------------------------------------------------
+// CLI wrapper.
+// ---------------------------------------------------------------------------
+function settingsPath() {
+  return path.join(os.homedir(), '.claude', 'settings.json');
+}
+
+function destinationPath() {
+  return path.join(os.homedir(), '.claude', 'cc-cream', 'cc-cream.js');
+}
+
+function runtimeFiles(sourceFile) {
+  const sourceDir = path.dirname(sourceFile);
+  return fs.readdirSync(sourceDir)
+    .filter((name) => name.endsWith('.js') && name !== 'install.js')
+    .map((name) => path.join(sourceDir, name));
+}
+
+function copyRuntimeFiles(sourceFile, destDir) {
+  let copied = false;
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const file of runtimeFiles(sourceFile)) {
+    const dest = path.join(destDir, path.basename(file));
+    const needsCopy = !fs.existsSync(dest) || fs.statSync(file).mtime > fs.statSync(dest).mtime;
+    if (needsCopy) {
+      fs.copyFileSync(file, dest);
+      copied = true;
+    }
+  }
+  return copied;
+}
+
+// Resolve the absolute node binary to bake into the statusLine command. The
+// status line runs as a detached subprocess that may not inherit the user's
+// PATH, so a bare `node` is unsafe. We prefer the shell's `command -v node`
+// (the path the user's interactive shell would pick), falling back to
+// process.execPath (the node currently running setup) if that fails.
+function resolveNodePath() {
+  try {
+    const found = execFileSync('command', ['-v', 'node'], {
+      shell: true,
+      encoding: 'utf8',
+    }).trim();
+    if (found) return found;
+  } catch {
+    // fall through
+  }
+  return process.execPath;
+}
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(`${question} [y/N] `, (a) => {
+    rl.close();
+    resolve(/^y(es)?$/i.test(a.trim()));
+  }));
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const plugin = args.includes('--plugin');
+  // First non-flag arg is an optional local source path (manual mode only).
+  const positional = args.filter((a) => !a.startsWith('--'));
+
+  const file = settingsPath();
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(file, 'utf8')) || {};
+  } catch {
+    settings = {}; // missing or malformed -> start fresh, don't clobber blindly below
+  }
+
+  // planOpts holds whatever the chosen strategy needs to build its command.
+  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() };
+  } else {
+    // Manual / GitHub mode: copy the runtime into ~/.claude/cc-cream and point
+    // the statusLine at that copied entrypoint.
+    const sourceFile = positional[0]
+      ? path.resolve(positional[0])
+      : path.resolve(path.dirname(new URL(import.meta.url).pathname), 'cc-cream.js');
+
+    if (!fs.existsSync(sourceFile)) {
+      console.error(`Error: cc-cream.js not found at ${sourceFile}`);
+      process.exit(1);
+    }
+
+    const dest = destinationPath();
+    const destDir = path.dirname(dest);
+    if (copyRuntimeFiles(sourceFile, destDir)) {
+      console.log(`Copied cc-cream runtime files to ${destDir}`);
+    }
+    planOpts = { entrypoint: dest };
+  }
+
+  let result = plan(settings, planOpts);
+  // If a replace needs consent, ask now and re-plan with the answer.
+  if (!result.changed && result.needsConsent) {
+    for (const m of result.messages) console.log(m);
+    const yes = await ask('Replace it with cc-cream?');
+    result = plan(settings, { ...planOpts, consent: yes });
+  }
+
+  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`);
+    console.log(`\nWrote ${file}.`);
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  main();
+}

package/src/render.js

@@ -0,0 +1,34 @@
+import { ROW1_ZONES } from './defaults.js';
+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) {
+  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);
+
+  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;
+  const draw = (id) => paint(segs[id].text, segs[id].color);
+
+  const row1 = ROW1_ZONES.map((zone) => zone.filter((id) => visible(id, 1)).sort(byOrder).map(draw).join(' | '))
+    .filter((z) => z.length > 0)
+    .join(' | ');
+
+  const row2 = Object.keys(cfg.segments)
+    .filter((id) => visible(id, 2))
+    .sort(byOrder)
+    .map(draw)
+    .join(' | ');
+
+  const row3 = Object.keys(cfg.segments)
+    .filter((id) => visible(id, 3))
+    .sort(byOrder)
+    .map(draw)
+    .join(' | ');
+
+  return [row1, row2, row3].filter((r) => r.length > 0).join('\n');
+}

package/src/segments.js

@@ -0,0 +1,173 @@
+import fs from 'node:fs';
+import { band, countdown, flipPct, fmtNum, isNum, isPeak, numOr, pad2 } from './utils.js';
+import { hasWindow } from './ttl.js';
+
+function magnitudeTokens(cw) {
+  // PRD §4.1 assumes `total_input_tokens`; fall back to the input-only sum of
+  // current_usage so the magnitude survives a rename.
+  if (isNum(cw.total_input_tokens)) return cw.total_input_tokens;
+  const u = cw.current_usage;
+  if (u && typeof u === 'object') {
+    const sum = numOr(u.cache_read_input_tokens, 0) + numOr(u.cache_creation_input_tokens, 0) + numOr(u.input_tokens, 0);
+    if (sum > 0) return sum;
+  }
+  return undefined;
+}
+
+function segModel(data) {
+  const v = data?.model?.display_name;
+  if (typeof v !== 'string' || v === '') return null;
+  return { text: v, color: null };
+}
+
+function segCtx(data, cfg) {
+  const cw = data?.context_window;
+  if (!cw || typeof cw !== 'object') return null;
+  const winPct = cw.used_percentage;
+  if (!isNum(winPct)) return null;
+  const s = cfg.segments.ctx;
+  const mag = magnitudeTokens(cw);
+
+  let colorPct = winPct;
+  let ceilingPct;
+  if (s.basis === 'ceiling' && isNum(mag) && s.ceiling > 0) {
+    ceilingPct = (mag / s.ceiling) * 100;
+    colorPct = ceilingPct;
+  }
+
+  const shownPct = ceilingPct != null && s.display !== 'window' ? ceilingPct : winPct;
+
+  let text = `ctx:${flipPct(Math.round(shownPct), cfg)}%`;
+  if (isNum(mag)) text += ` [${fmtNum(mag, cfg.numbers)}]`;
+  return { text, color: band(colorPct, s.amber, s.orange, s.red) };
+}
+
+function segCache(data, cfg, prevCachePct, recovering) {
+  const u = data?.context_window?.current_usage;
+  if (!u || typeof u !== 'object') return null;
+  const read = numOr(u.cache_read_input_tokens, 0);
+  const denom = read + numOr(u.cache_creation_input_tokens, 0) + numOr(u.input_tokens, 0);
+  if (denom <= 0) return null;
+  const pct = Math.round((read / denom) * 100);
+  const s = cfg.segments.cache;
+  const freshDrop = isNum(prevCachePct) && (prevCachePct - pct) >= s.drop;
+  const stillRecovering = recovering === true && pct < s.drop_recover;
+  const color = (freshDrop || stillRecovering) ? 'red' : null;
+  return { text: `cache:${pct}%`, color };
+}
+
+function segTtl(data, cfg, ttlMin, now) {
+  const tp = data?.transcript_path;
+  if (typeof tp !== 'string' || tp === '') return null;
+  let mtimeMs;
+  try {
+    mtimeMs = fs.statSync(tp).mtimeMs;
+  } catch {
+    return null;
+  }
+  const elapsedMin = Math.floor(Math.max(0, now - mtimeMs) / 60000);
+  const remainingMin = Math.max(0, ttlMin - elapsedMin);
+  const text = `ttl:${pad2(Math.floor(remainingMin / 60))}:${pad2(remainingMin % 60)}`;
+  const s = cfg.segments.ttl;
+  const pctTtl = ttlMin > 0 ? (elapsedMin / ttlMin) * 100 : 0;
+  return { text, color: band(pctTtl, s.amber, s.red) };
+}
+
+function segCost(data) {
+  const c = data?.cost?.total_cost_usd;
+  if (!isNum(c) || c <= 0) return null;
+  return { text: `~$${c.toFixed(2)}`, color: null };
+}
+
+function segRate(window, label, cfg, segId, now) {
+  if (!window || typeof window !== 'object') return null;
+  const pct = window.used_percentage;
+  if (!isNum(pct)) return null;
+  const s = cfg.segments[segId];
+  const color = pct >= s.red ? 'red' : pct >= s.amber ? 'amber' : null;
+  const cd = countdown(window.resets_at, now);
+  const head = `${label}:${flipPct(Math.round(pct), cfg)}%`;
+  const text = cd ? `${head} ↺ ${cd}` : head;
+  return { text, color };
+}
+
+function segEffort(data) {
+  const lvl = data?.effort?.level;
+  if (typeof lvl !== 'string' || lvl === '') return null;
+  return { text: `effort:${lvl}`, color: null };
+}
+
+function segThinking(data) {
+  const t = data?.thinking?.enabled;
+  if (typeof t !== 'boolean') return null;
+  return { text: `think:${t ? 'on' : 'off'}`, color: null };
+}
+
+function segApiRatio(data) {
+  const api = data?.cost?.total_api_duration_ms;
+  const total = data?.cost?.total_duration_ms;
+  if (!isNum(api) || !isNum(total) || total <= 0) return null;
+  const pct = Math.round(Math.min(100, (api / total) * 100));
+  return { text: `∿ api:${pct}%`, color: null };
+}
+
+function segSessionName(data) {
+  const name = data?.session_name;
+  if (typeof name !== 'string' || name === '') return null;
+  return { text: name, color: null };
+}
+
+function segCacheWrite(data) {
+  const u = data?.context_window?.current_usage;
+  if (!u || typeof u !== 'object') return null;
+  const creation = numOr(u.cache_creation_input_tokens, 0);
+  const denom = creation + numOr(u.cache_read_input_tokens, 0) + numOr(u.input_tokens, 0);
+  if (denom <= 0) return null;
+  return { text: `write:${Math.round((creation / denom) * 100)}%`, color: null };
+}
+
+function segPeak(data, cfg, now, tz) {
+  // peak rides the account-budget row, so it shows only when that row has windows.
+  if (!hasWindow(data?.rate_limits)) return null;
+  if (!isPeak(now, cfg, tz)) return null;
+  return { text: 'peak', color: 'amber' };
+}
+
+function segBurn(fiveHour, prev, now) {
+  if (!fiveHour || !isNum(fiveHour.used_percentage)) return null;
+  if (!prev || !isNum(prev.five_hour_pct) || !isNum(prev.ts)) return null;
+  const deltaPct = fiveHour.used_percentage - prev.five_hour_pct;
+  const deltaMs = now - prev.ts;
+  if (deltaPct <= 0 || deltaMs <= 0) return null;
+  const remaining = 100 - fiveHour.used_percentage;
+  if (remaining <= 0) return null;
+  const minEta = Math.ceil((remaining / deltaPct) * deltaMs / 60000);
+  if (!Number.isFinite(minEta) || minEta >= 300) return null;
+  const h = Math.floor(minEta / 60);
+  const m = minEta % 60;
+  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') {
+  return {
+    model: segModel(data),
+    ctx: segCtx(data, cfg),
+    cache: segCache(
+      data,
+      cfg,
+      prevSessionState && isNum(prevSessionState.cache_pct) ? prevSessionState.cache_pct : undefined,
+      prevSessionState?.recovering === true,
+    ),
+    ttl: segTtl(data, cfg, ttlMin, now),
+    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),
+    peak: segPeak(data, cfg, now, tz),
+    burn: segBurn(data?.rate_limits?.five_hour, prevSessionState, now),
+    effort: segEffort(data),
+    thinking: segThinking(data),
+    api_ratio: segApiRatio(data),
+    session_name: segSessionName(data),
+    write: segCacheWrite(data),
+  };
+}

package/src/state.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import { isNum, numOr } from './utils.js';
+
+export function readState(stateFilePath) {
+  try {
+    const raw = fs.readFileSync(stateFilePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+export function writeState(stateFilePath, state) {
+  try {
+    fs.writeFileSync(stateFilePath, JSON.stringify(state));
+  } catch {
+    // degrade silently — stateless render is fine
+  }
+}
+
+export function getSessionState(state, sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') return null;
+  const sessions = state?.sessions;
+  if (!sessions || typeof sessions !== 'object') return null;
+  return sessions[sessionId] ?? null;
+}
+
+export function patchSessionState(state, sessionId, patch) {
+  if (!sessionId || typeof sessionId !== 'string') return state;
+  const sessions = { ...(state?.sessions ?? {}) };
+  sessions[sessionId] = { ...(sessions[sessionId] ?? {}), ...patch };
+  return { ...state, sessions };
+}
+
+export function nextSessionPatch(data, prevSessionState, cfg, now) {
+  const patch = { ts: now };
+  const cost = data?.cost?.total_cost_usd;
+  if (isNum(cost)) patch.cost = cost;
+  const cu = data?.context_window?.current_usage;
+  if (cu && typeof cu === 'object') {
+    const read = numOr(cu.cache_read_input_tokens, 0);
+    const denom = read + numOr(cu.cache_creation_input_tokens, 0) + numOr(cu.input_tokens, 0);
+    if (denom > 0) {
+      const currentCachePct = Math.round((read / denom) * 100);
+      patch.cache_pct = currentCachePct;
+      const prevCachePct = prevSessionState && isNum(prevSessionState.cache_pct) ? prevSessionState.cache_pct : undefined;
+      const wasRecovering = prevSessionState?.recovering === true;
+      const freshDrop = isNum(prevCachePct) && (prevCachePct - currentCachePct) >= cfg.segments.cache.drop;
+      patch.recovering = freshDrop || (wasRecovering && currentCachePct < cfg.segments.cache.drop_recover);
+    }
+  }
+  const fh = data?.rate_limits?.five_hour;
+  if (fh && isNum(fh.used_percentage)) patch.five_hour_pct = fh.used_percentage;
+  return patch;
+}

package/src/ttl.js

@@ -0,0 +1,26 @@
+import { numOr } from './utils.js';
+
+const envOn = (v) => typeof v === 'string' && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+
+export function hasWindow(rl) {
+  return !!(rl && typeof rl === 'object' && (rl.five_hour || rl.seven_day));
+}
+
+function overCap(rl) {
+  return [rl.five_hour, rl.seven_day].some((w) => w && numOr(w.used_percentage, 0) >= 100);
+}
+
+export function resolveTtl({ rateLimits, config, env }) {
+  const e = env || {};
+  // FORCE override wins over everything (PRD §10).
+  if (envOn(e.FORCE_PROMPT_CACHING_5M)) return 5;
+  // Explicit config pin.
+  const pin = config ? config.ttl : 'auto';
+  if (pin === 5) return 5;
+  if (pin === 60) return 60;
+  // auto resolution.
+  if (hasWindow(rateLimits)) {
+    return overCap(rateLimits) ? 5 : 60; // subscriber
+  }
+  return envOn(e.ENABLE_PROMPT_CACHING_1H) ? 60 : 5; // API user
+}

package/src/utils.js

@@ -0,0 +1,80 @@
+import { ANSI } from './defaults.js';
+
+export const clone = (o) => JSON.parse(JSON.stringify(o));
+export const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+export const numOr = (v, d) => (isNum(v) ? v : d);
+export const pad2 = (n) => String(n).padStart(2, '0');
+
+export function fmtNum(n, mode) {
+  if (mode === 'exact') return String(n);
+  if (n >= 1_000_000) return `${Math.round(n / 1_000_000)}M`;
+  if (n >= 1000) return `${Math.round(n / 1000)}k`;
+  return String(n);
+}
+
+export function paint(text, color) {
+  return color && ANSI[color] ? `${ANSI[color]}${text}\x1b[0m` : text;
+}
+
+// 3-arg form: band(value, amber, red) — used by ttl / rate limits.
+// 4-arg form: band(value, amber, orange, red) — used by ctx.
+// Orange is skipped when it falls at or below amber.
+export function band(value, amber, orangeOrRed, red) {
+  if (red === undefined) { red = orangeOrRed; orangeOrRed = undefined; }
+  if (value >= red) return 'red';
+  if (orangeOrRed !== undefined && orangeOrRed > amber && value >= orangeOrRed) return 'orange';
+  if (value >= amber) return 'amber';
+  return 'green';
+}
+
+// Normalize a resets_at value to epoch ms. Claude Code sends a Unix timestamp
+// in seconds; also tolerate ms and ISO.
+function toEpochMs(v) {
+  if (typeof v === 'number' && Number.isFinite(v)) return v < 1e11 ? v * 1000 : v;
+  if (typeof v === 'string') {
+    if (/^\d+$/.test(v)) return toEpochMs(Number(v));
+    const t = Date.parse(v);
+    return Number.isNaN(t) ? NaN : t;
+  }
+  return NaN;
+}
+
+// Display-only percentage flip (PRDv2 §3).
+export const flipPct = (consumedShown, cfg) => (
+  cfg.percentage === 'remaining' ? 100 - consumedShown : consumedShown
+);
+
+// True during Anthropic's faster-drain "peak" window (PRDv2 §2): a weekday
+// (Mon–Fri) within [start, end) Pacific-time hours.
+export function isPeak(now, cfg, tz = 'America/Los_Angeles') {
+  const s = cfg?.segments?.peak ?? {};
+  const start = isNum(s.start) ? s.start : 5;
+  const end = isNum(s.end) ? s.end : 11;
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz, hour: 'numeric', hour12: false, weekday: 'short',
+    }).formatToParts(new Date(now));
+    const p = Object.fromEntries(parts.map((x) => [x.type, x.value]));
+    const hour = Number(p.hour) % 24; // some ICU builds emit "24" for midnight
+    return !['Sat', 'Sun'].includes(p.weekday) && hour >= start && hour < end;
+  } catch {
+    return false;
+  }
+}
+
+// resets_at - now, on the §4.4 format ladder: >=1d -> "Fri 23:45", >=1h -> HhMMm, else MMm.
+export function countdown(resetsAt, now) {
+  const t = toEpochMs(resetsAt);
+  if (Number.isNaN(t)) return '';
+  const totalMin = Math.max(0, Math.floor((t - now) / 60000));
+  const days = Math.floor(totalMin / 1440);
+  if (days >= 1) {
+    const d = new Date(t);
+    const weekday = d.toLocaleDateString(undefined, { weekday: 'short' });
+    const time = d.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit', hour12: false });
+    return `${weekday} ${time}`;
+  }
+  const hours = Math.floor(totalMin / 60);
+  if (hours >= 1) return `${hours}h${pad2(totalMin % 60)}m`;
+  return `${totalMin}m`;
+}