claude-code-runrate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bing Ho
+
+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,116 @@
+# ccr — Claude Code run-rate
+
+> Know how fast you're burning your Claude Code subscription window — and whether
+> clearing context now is worth it — without doing token math in your head.
+
+**A solo side project, shared as-is** — built to scratch my own itch and
+daily-driven. See [Status & support](#status--support) for what to expect, and
+the acceptance criteria in [`features/`](features/) for exactly how the
+burn-rate and clear-ROI math behaves.
+
+---
+
+## What it does
+
+ccr reads Claude Code's own status-line JSON and your session transcripts and
+shows you the **economy** of a session:
+
+- **Burn rate** on your 5-hour (and weekly) rate-limit window — `%/min` and, more
+  usefully, **how long until you hit the wall**.
+- **Clear ROI** — in plain language, how many more minutes clearing context now
+  would buy you.
+- **Live tool/skills feed** — in the sidebar, a rolling view of recent tool and
+  slash-command calls plus per-session stats (files touched, tokens generated).
+- **Resume advisor** (`ccr resume`) — recent sessions ranked by what they'd cost
+  to bring back (context size, share of the window, cold/warm cache), then it
+  hands selection to `claude --resume`.
+
+For scripting and external tools (status bars, menu-bar widgets), `ccr economy
+--json` emits a stable, versioned model — see
+[`docs/JSON-CONTRACT.md`](docs/JSON-CONTRACT.md).
+
+It is **read-only**: it never modifies `~/.claude/settings.json`, your
+credentials, or any config. It targets **subscription** plans (Pro / Max); on
+API/pay-as-you-go it degrades gracefully and just shows Claude Code's own cost.
+
+## Quickstart
+
+```bash
+# zero-install, on-demand report (any OS):
+npx claude-code-runrate economy
+
+# or install the `ccr` command for the live statusline / sidebar:
+npm i -g claude-code-runrate
+```
+
+## Surfaces
+
+| Surface | What | Linux | macOS | Windows |
+|---|---|:--:|:--:|:--:|
+| `ccr economy` (CLI report) | Full panel on demand | ✅ | ✅ | ✅ |
+| `ccr economy --json` | Stable machine-readable model (scripting) | ✅ | ✅ | ✅ |
+| `ccr resume` | Recent sessions ranked by cost to resume | ✅ | ✅ | ✅ |
+| `ccr statusline` | One-line summary wired into CC's `statusLine` | ✅ | ✅ | ✅ |
+| `ccr sidecar` | Live tmux dashboard + tool/skills feed | ✅ | ✅ | ⛔ (tmux; use WSL) |
+
+The CLI and statusline are pure Node — they run on native Windows. The rich live
+sidebar needs `tmux`, so on Windows use WSL.
+
+## Requirements
+
+- **Node ≥ 18.3** — that's it for the core. **Zero runtime dependencies.**
+- `tmux` — only for the optional `ccr sidecar`.
+
+## Wiring the statusline into Claude Code
+
+In `~/.claude/settings.json`:
+
+```json
+{ "statusLine": { "type": "command", "command": "ccr statusline" } }
+```
+
+(Install the binary with `npm i -g claude-code-runrate` rather than using `npx` here — Claude
+Code calls the status line frequently, and a resolved binary avoids per-tick
+latency.)
+
+## Development
+
+This project is built **BDD-first**: the Gherkin in [`features/`](features/) is
+the source of truth, executed by a hand-rolled zero-dependency harness on top of
+Node's built-in test runner.
+
+```bash
+npm test            # node --test — harness self-tests + feature scenarios
+npm run typecheck   # tsc --noEmit over @ts-check'd JS (needs: npm i first)
+```
+
+- **No runtime dependencies**, ever — it's what lets `npx claude-code-runrate` install
+  instantly on every OS, including native Windows.
+- **Dev-only** tooling (`typescript`, `@types/node`) exists solely for
+  `npm run typecheck`; it is never installed for consumers, so the runtime
+  promise is untouched.
+- All source uses `// @ts-check` + JSDoc — type-checked, but shipped as plain JS
+  that runs straight from source (no build step, no `dist/`).
+
+## Status & support
+
+ccr is a **solo side project**. I built it to answer one question for myself —
+*am I about to hit my Claude Code limit, and is clearing context worth it?* — and
+I'm sharing it in case it's useful to you too. I use it daily, but please treat it
+as **best-effort and as-is**:
+
+- **Issues** — I read them all. Triage is usually within a week or two, faster for
+  anything that breaks the core (the economy/statusline math, or a platform that
+  won't run). A minimal repro and your OS + Node version help a lot.
+- **Fixes** — core bugs get priority; nice-to-haves may sit for a while.
+- **Pull requests** — welcome, especially small, focused ones with a test. I review
+  on the same best-effort cadence. For anything large, please open an issue first so
+  we don't both sink time into something I'd want shaped differently.
+- **No SLA and no roadmap promises.** Things land when I have the itch or a good PR
+  shows up. If ccr stops being maintained I'll say so plainly at the top of this file.
+
+If it saved you some token math, that's the whole goal. 🎸
+
+## License
+
+[MIT](LICENSE) © 2026 Bing Ho

package/bin/ccr.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// @ts-check
+'use strict';
+// bin/ccr.js — ccr CLI + launcher. Pure Node, zero runtime deps.
+//
+//   ccr            launch `claude` + economy sidebar (tmux)
+//   ccr <profile>  launch CCS profile + sidebar (e.g. `ccr c1`)
+//   ccr economy    print the economy panel from the latest captured status
+//   ccr economy --json  emit the machine-readable economy model (see docs/JSON-CONTRACT.md)
+//   ccr statusline emit one-line status (wired via --settings at launch)
+//   ccr sidecar    run the live economy panel (used inside the tmux session)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { parseArgs } = require('node:util');
+const pkg = require('../package.json');
+
+// Per-session state dir (the launcher sets CCR_STATE_DIR per profile); default
+// ~/.ccr for ad-hoc use. Always under the user's home — never world-shared /tmp.
+const STATE_DIR = process.env.CCR_STATE_DIR || path.join(os.homedir(), '.ccr');
+const SNAPSHOT = path.join(STATE_DIR, 'last-status.json');
+const MAX_SNAPSHOT_BYTES = 1_000_000; // a status JSON is a few KB; cap to bound parse/disk
+
+const HELP = `ccr — Claude Code run-rate (v${pkg.version})
+
+Usage:
+  ccr [profile]    Launch Claude (or a CCS profile) with the live economy sidebar
+  ccr economy      Print the economy panel from the latest captured status
+  ccr economy --json   Emit the machine-readable economy model (stable contract)
+  ccr resume       Recent sessions ranked by cost to resume (advisor)
+  ccr statusline   Emit one-line status (wired automatically at launch)
+  ccr sidecar      Run the live economy panel (used inside the tmux session)
+  ccr doctor       Check your local setup (node, tmux, CCS, capture status)
+
+Examples:
+  ccr              plain \`claude\` + sidebar
+  ccr c1           CCS profile c1 + sidebar
+  ccr economy      one-off panel
+
+Options:
+  -h, --help     Show this help
+  -v, --version  Show version`;
+
+/**
+ * @param {string[]} argv
+ * @returns {number | undefined} exit code; undefined keeps the process alive (sidecar)
+ */
+function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+        json: { type: 'boolean' },
+      },
+    });
+  } catch (err) {
+    process.stderr.write(`ccr: ${err instanceof Error ? err.message : String(err)}\n\n${HELP}\n`);
+    return 2;
+  }
+
+  const { values, positionals } = parsed;
+  if (values.version) { process.stdout.write(`${pkg.version}\n`); return 0; }
+  if (values.help) { process.stdout.write(`${HELP}\n`); return 0; }
+
+  const cmd = positionals[0];
+  if (!cmd) return cmdLaunch(undefined);          // bare `ccr` → launch
+  switch (cmd) {
+    case 'economy': return cmdEconomy(!!values.json);
+    case 'resume': return cmdResume(positionals[1]);
+    case 'statusline': return cmdStatusline();
+    case 'sidecar': return cmdSidecar();
+    case 'doctor': return require('../src/doctor').run();
+    case 'launch': return cmdLaunch(positionals[1]);
+    default: return cmdLaunch(cmd);               // anything else → treat as a CCS profile
+  }
+}
+
+function readStdin() {
+  try { return process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+/**
+ * `ccr statusline` — reads status JSON on stdin, persists the snapshot, logs a
+ * meter sample, prints a compact line. MUST never throw.
+ * @returns {number}
+ */
+function cmdStatusline() {
+  const raw = readStdin();
+  let line = 'ccr';
+  // Bound input: a real status JSON is a few KB. Refuse to parse/persist an
+  // absurdly large blob (keeps the status line cheap and the snapshot small).
+  if (raw.length > MAX_SNAPSHOT_BYTES) { process.stdout.write(line + '\n'); return 0; }
+  try {
+    const state = JSON.parse(raw);
+    const { normalizeStatus } = require('../src/normalize');
+    const { renderStatusline } = require('../src/render/statusline');
+    const { logMeterSample } = require('../src/instrument');
+    const { ensureSecureDir } = require('../src/state-dir');
+    line = renderStatusline(normalizeStatus(state));
+    try { ensureSecureDir(STATE_DIR); fs.writeFileSync(SNAPSHOT, raw, { mode: 0o600 }); } catch { /* ignore */ }
+    try { logMeterSample(state, { dir: STATE_DIR }); } catch { /* ignore */ }
+  } catch { /* keep fallback line */ }
+  process.stdout.write(line + '\n');
+  return 0;
+}
+
+/**
+ * `ccr economy [--json]` — render the full panel, or with `--json` emit the
+ * stable machine-readable economy model (the integration contract). Reads stdin,
+ * else the captured snapshot.
+ * @param {boolean} [json]
+ * @returns {number}
+ */
+function cmdEconomy(json) {
+  let raw = readStdin();
+  if (!raw.trim()) { try { raw = fs.readFileSync(SNAPSHOT, 'utf8'); } catch { /* none yet */ } }
+  let state = null;
+  if (raw.trim()) { try { state = JSON.parse(raw); } catch { /* bad json */ } }
+  if (!state) {
+    process.stderr.write('ccr economy: no status captured yet. Run `ccr` (or `ccr <profile>`) to launch + capture.\n');
+    return 1;
+  }
+  const { normalizeStatus } = require('../src/normalize');
+  if (json) {
+    const { computeEconomy } = require('../src/economy-model');
+    process.stdout.write(JSON.stringify(computeEconomy(normalizeStatus(state)), null, 2) + '\n');
+    return 0;
+  }
+  const { renderEconomy } = require('../src/render/economy');
+  process.stdout.write(renderEconomy(normalizeStatus(state)) + '\n');
+  return 0;
+}
+
+/**
+ * `ccr resume [all]` — advisor: recent sessions ranked by cost to resume. Default
+ * scope is the current project; `all` widens to every project. Read-only; you pick
+ * with `claude --resume`.
+ * @param {string | undefined} arg
+ * @returns {number}
+ */
+function cmdResume(arg) {
+  const scope = (arg === 'all' || arg === '--all') ? 'all' : 'cwd';
+  const { gather } = require('../src/resume');
+  const { renderResume } = require('../src/render/resume');
+  process.stdout.write(renderResume(gather({ scope, cwd: process.cwd() }), { scope }) + '\n');
+  return 0;
+}
+
+/** `ccr sidecar` — live economy panel; keeps the process alive (no exit code). */
+function cmdSidecar() {
+  require('../src/sidecar').run();
+  return undefined;
+}
+
+/**
+ * `ccr [profile]` — launch the tmux session (claude/ccs + sidebar) via launch.sh.
+ * @param {string | undefined} profile
+ * @returns {number}
+ */
+function cmdLaunch(profile) {
+  if (process.platform === 'win32') {
+    process.stderr.write(
+      'ccr: the live sidebar needs tmux + bash, which native Windows lacks.\n' +
+      '     Use WSL for the sidebar, or run these directly (they work natively):\n' +
+      '       ccr economy      one-off economy panel\n' +
+      "       ccr statusline   wire into Claude Code's statusLine\n" +
+      '       ccr doctor       check your setup\n');
+    return 1;
+  }
+  const { spawnSync } = require('node:child_process');
+  const launcher = path.join(__dirname, '..', 'scripts', 'launch.sh');
+  const r = spawnSync('bash', profile ? [launcher, profile] : [launcher], { stdio: 'inherit' });
+  if (r.error) { process.stderr.write(`ccr: launch failed: ${r.error.message}\n`); return 1; }
+  return typeof r.status === 'number' ? r.status : 1;
+}
+
+const code = main(process.argv.slice(2));
+if (typeof code === 'number') process.exit(code);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "claude-code-runrate",
+  "version": "0.1.0",
+  "description": "Claude Code run-rate — subscription burn-rate & economy for your Claude Code sessions.",
+  "license": "MIT",
+  "author": "Bing Ho <reps-attic-riot@duck.com>",
+  "repository": { "type": "git", "url": "git+https://github.com/bingh0/ccr.git" },
+  "bugs": { "url": "https://github.com/bingh0/ccr/issues" },
+  "homepage": "https://github.com/bingh0/ccr#readme",
+  "type": "commonjs",
+  "bin": {
+    "ccr": "bin/ccr.js"
+  },
+  "engines": {
+    "node": ">=18.3"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts/launch.sh",
+    "sidecar",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit -p jsconfig.json"
+  },
+  "keywords": [
+    "claude-code",
+    "burn-rate",
+    "rate-limit",
+    "economy",
+    "cli"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/scripts/launch.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# scripts/launch.sh — bring up a tmux session with:
+#   pane 0 — claude (or `ccs <profile>`) with statusLine injected via --settings
+#   pane 1 — the live economy sidebar (ccr sidecar)
+#
+# Usage (normally via the `ccr` CLI):
+#   ccr            → plain `claude` + sidebar
+#   ccr c1         → CCS profile c1 + sidebar
+#
+# No config files are modified: statusLine is passed per-launch with --settings,
+# so CCS symlinks, shared settings, and credentials are untouched. Per-profile
+# state dirs keep concurrent profiles from colliding.
+#
+# Env overrides: CC_BIN, CCR_SESSION, CCR_STATE_DIR, CCR_SIDEBAR_PCT (default 34).
+
+set -euo pipefail
+
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+PROFILE="${1:-}"
+
+# Validate the profile name: it goes into filesystem paths and the launched
+# command, so allow only a safe identifier (letters, digits, . _ -).
+if [ -n "$PROFILE" ] && ! printf '%s' "$PROFILE" | grep -qE '^[A-Za-z0-9._-]+$'; then
+  echo "ccr: invalid profile name '$PROFILE' (allowed: letters, digits, . _ -)" >&2
+  exit 1
+fi
+
+# State lives under the user's home, never world-shared /tmp; create it
+# owner-only so other local users can't read captured status.
+umask 077
+
+# Belt-and-suspenders: CC executes the statusLine command directly, so it must
+# be executable even if git/npm didn't preserve the bit.
+chmod +x "$REPO/sidecar/ccr-statusline" 2>/dev/null || true
+
+# Prefer the newest nvm-installed node; `sort -V` is a GNU-ism, so suppress its
+# error on BSD/macOS and fall back to PATH node below.
+NODE="$(ls -d "$HOME"/.nvm/versions/node/*/bin/node 2>/dev/null | sort -V 2>/dev/null | tail -1)"
+[ -x "$NODE" ] || NODE="$(command -v node || true)"
+[ -n "$NODE" ] || { echo "ccr: node not found" >&2; exit 1; }
+command -v tmux >/dev/null 2>&1 || { echo "ccr: tmux not found (required for the sidebar)" >&2; exit 1; }
+
+if [ -n "$PROFILE" ]; then
+  command -v ccs >/dev/null 2>&1 || { echo "ccr: 'ccs' not found on PATH — pass a profile only if CCS is installed." >&2; exit 1; }
+  if [ ! -d "$HOME/.ccs/instances/$PROFILE" ]; then
+    echo "ccr: CCS profile '$PROFILE' not found ($HOME/.ccs/instances/$PROFILE)." >&2
+    echo "     available: $(ls -1 "$HOME/.ccs/instances" 2>/dev/null | tr '\n' ' ')" >&2
+    exit 1
+  fi
+  CC_CMD="ccs $PROFILE"
+  SESSION="${CCR_SESSION:-ccr-$PROFILE}"
+  STATE="${CCR_STATE_DIR:-$HOME/.ccr/$PROFILE}"
+else
+  CC_CMD="${CC_BIN:-claude}"
+  SESSION="${CCR_SESSION:-ccr}"
+  STATE="${CCR_STATE_DIR:-$HOME/.ccr}"
+fi
+
+mkdir -p "$STATE"
+chmod 700 "$HOME/.ccr" "$STATE" 2>/dev/null || true
+rm -f "$STATE/exited"
+
+SETTINGS='{"statusLine":{"type":"command","command":"'"$REPO/sidecar/ccr-statusline"'"}}'
+
+# Portable across GNU and BSD/macOS mktemp (the `-t PREFIX` form differs between
+# them); also lands in the per-user $TMPDIR on macOS rather than shared /tmp.
+RUN_CONF="$(mktemp "${TMPDIR:-/tmp}/ccr-tmux.XXXXXX")"
+trap 'rm -f "$RUN_CONF"' EXIT
+cp "$REPO/sidecar/ccr.tmux.conf" "$RUN_CONF"
+
+# Clean re-launch.
+tmux kill-session -t "$SESSION" 2>/dev/null || true
+
+ENV_PREAMBLE="export CCR_STATE_DIR='$STATE'"
+
+# Pane 0: claude/ccs with --settings. On exit, drop the sentinel then close.
+tmux new-session -d -s "$SESSION" \
+  "$ENV_PREAMBLE; $CC_CMD --settings '$SETTINGS'; touch '$STATE/exited'; sleep 2; tmux kill-session -t '$SESSION' 2>/dev/null"
+tmux set-environment -t "$SESSION" CCR_STATE_DIR "$STATE"
+
+# Pane 1: the live economy sidebar.
+tmux split-window -t "$SESSION:0" -h -p "${CCR_SIDEBAR_PCT:-34}" \
+  "$ENV_PREAMBLE; \"$NODE\" \"$REPO/bin/ccr.js\" sidecar; read -r -p 'sidebar exited — Enter to close '"
+
+tmux select-pane -t "$SESSION:0.0"
+tmux source-file -t "$SESSION" "$RUN_CONF"
+tmux attach -t "$SESSION"

package/sidecar/ccr-statusline

@@ -0,0 +1,9 @@
+#!/bin/sh
+# sidecar/ccr-statusline — the statusLine command injected via `claude --settings`
+# at launch. A single no-space path so it embeds cleanly in the settings JSON.
+# Resolves node itself (survives nvm upgrades) and runs `ccr statusline`, which
+# reads CCR_STATE_DIR from the environment the launcher exports.
+DIR="$(cd "$(dirname "$0")/.." && pwd)"
+NODE="$(ls -d "$HOME"/.nvm/versions/node/*/bin/node 2>/dev/null | sort -V | tail -1)"
+[ -x "$NODE" ] || NODE="$(command -v node)"
+exec "$NODE" "$DIR/bin/ccr.js" statusline

package/sidecar/ccr.tmux.conf

@@ -0,0 +1,16 @@
+# sidecar/ccr.tmux.conf — applies ONLY to ccr's own tmux session, never your
+# global tmux config. Minimal bindings — just F2 → /clear.
+
+# F2 — send /clear to the Claude pane (reset context before compaction hits).
+bind-key -n F2 send-keys -t .0 '/clear' Enter
+
+set -g mouse on
+set -g status off
+
+# Generous scrollback + OSC52 clipboard so copy works across long output.
+# (When Claude Code grabs the mouse: prefix + [ enters copy-mode, then wheel/PageUp.)
+set -g history-limit 50000
+set -g set-clipboard on
+
+# prefix + P — dump the whole pane scrollback to a file, regardless of length.
+bind-key P command-prompt -p 'save pane to:' 'capture-pane -S - ; save-buffer %1'

package/src/burn.js

@@ -0,0 +1,183 @@
+// @ts-check
+'use strict';
+// src/burn.js
+// Burn-rate and clear-ROI math, scoped to subscription plans.
+//
+// Key design points:
+//  - Rate is derived from the plan's own percentage meter (du/dt), so it is
+//    correct on Pro and Max without knowing the absolute token cap.
+//  - Rate is scoped to the active model — a prior model's samples must not
+//    pollute it.
+//  - BOTH the 5h and weekly windows are modelled; the binding (smaller) horizon
+//    is what "time to limit" reports. On Max the weekly window often binds.
+//  - clear-ROI is bounded: floored projected burn + capped at the nearest reset.
+
+const FIVE_HOUR_MIN = 5 * 60;        // 300
+const SEVEN_DAY_MIN = 7 * 24 * 60;   // 10080
+const WINDOW_TIERS = [200000, 400000, 512000, 1000000];
+
+// Pricing-ratio fallback for w(C) when no empirical calibration exists.
+const READ_WEIGHT = 0.1;
+const K_TAIL = 3000;
+
+/** @param {string} [model] */
+function modelWindowGuess(model) {
+  if (!model) return 0;
+  const m = model.toLowerCase();
+  if (m.includes('opus-4-8')) return 1000000;
+  if (m.includes('opus-4-6') || m.includes('opus-4-7')) return 200000;
+  if (m.includes('haiku')) return 200000;
+  return 0; // unknown → fall back to the observed-tier lower bound
+}
+
+/** @param {number} maxCtx */
+function inferWindowFromMax(maxCtx) {
+  for (const t of WINDOW_TIERS) if (maxCtx <= t) return t;
+  return 1000000;
+}
+
+/**
+ * Effective window for normalizing context to "% of window". Prefer the live
+ * reported size when present; otherwise best-effort from model name + observed max.
+ * @param {{ model?: string, maxCtx?: number, reportedWindowSize?: number }} input
+ * @returns {number}
+ */
+function inferWindow(input) {
+  if (input.reportedWindowSize) return input.reportedWindowSize;
+  return Math.max(modelWindowGuess(input.model), inferWindowFromMax(input.maxCtx || 0)) || 200000;
+}
+
+/**
+ * Accept a reset value as epoch seconds (number or numeric string) OR an ISO
+ * string, returning epoch seconds. Robust to CC changing the field's format.
+ * @param {number | string | null | undefined} value
+ * @returns {number | null}
+ */
+function parseResetsAt(value) {
+  if (value == null) return null;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  const s = String(value).trim();
+  if (/^\d+(\.\d+)?$/.test(s)) return Number(s);
+  const ms = Date.parse(s);
+  return Number.isNaN(ms) ? null : ms / 1000;
+}
+
+/**
+ * Model-scoped burn rate from a sample buffer. Uses only the contiguous tail of
+ * samples on the active model (since the last model switch).
+ * @param {{ t: number, u: number, m?: string }[]} samples  t in minutes, u = used %
+ * @param {string} activeModel
+ * @returns {{ rate: number | null, switched: boolean, count: number }}
+ */
+function rateFromSamples(samples, activeModel) {
+  let start = 0;
+  for (let i = samples.length - 1; i >= 0; i--) {
+    if ((samples[i].m || '') !== activeModel) { start = i + 1; break; }
+  }
+  const tail = samples.slice(start);
+  let rate = null;
+  if (tail.length >= 2) {
+    const dt = tail[tail.length - 1].t - tail[0].t;
+    const du = tail[tail.length - 1].u - tail[0].u;
+    if (dt > 0 && du >= 0) rate = du / dt;
+  }
+  return { rate, switched: tail.length < samples.length, count: tail.length };
+}
+
+/**
+ * Estimate one window's burn + minutes-left. If no live `rate` is given, derive
+ * the average burn over the window so far: used% / elapsed, where elapsed is the
+ * window length minus the time remaining until it resets.
+ * @param {{ usedPct: number, minutesToReset?: number, windowMinutes?: number, rate?: number }} w
+ * @returns {{ usedPct: number, rate: number | null, minutesLeft: number | null, minutesToReset: number | null }}
+ */
+function windowEstimate(w) {
+  let rate = w.rate ?? null;
+  if (rate == null && w.minutesToReset != null && w.windowMinutes != null) {
+    const elapsed = w.windowMinutes - w.minutesToReset;
+    if (elapsed > 0) rate = w.usedPct / elapsed;
+  }
+  const minutesLeft = (rate != null && rate > 0) ? (100 - w.usedPct) / rate : null;
+  return { usedPct: w.usedPct, rate, minutesLeft, minutesToReset: w.minutesToReset ?? null };
+}
+
+/**
+ * Pick the binding window — the one you'll hit first (smallest minutes-left) —
+ * from an arbitrary set of buckets (5h, weekly, model-scoped, monthly, …).
+ * Tolerates any plan shape without blanking; returns null for no windows.
+ * @param {{ key: string, est: any, reset?: number|null }[]} windows
+ * @returns {{ window: string, minutesLeft: number | null, all: any[] } | null}
+ */
+function binding(windows) {
+  if (!Array.isArray(windows) || !windows.length) return null;
+  /** @param {any} w */
+  const ml = (w) => {
+    const m = w && w.est && w.est.minutesLeft;
+    return (m == null || !isFinite(m)) ? Infinity : m;
+  };
+  const sorted = [...windows].sort((a, b) => ml(a) - ml(b));
+  const top = sorted[0];
+  return { window: top.key, minutesLeft: top.est ? top.est.minutesLeft : null, all: windows };
+}
+
+/**
+ * Minutes of budget a /clear would buy. Floors the projected post-clear burn and
+ * caps the gain at the nearest reset horizon, so it can never explode.
+ * @param {{ rate: number | null, usedPct: number, contextC: number, baselineB: number, calib?: {a:number,b:number} | null, resetMinutes?: number }} o
+ * @returns {{ boughtMinutes: number, projectedBurn: number | null }}
+ */
+function clearROI(o) {
+  if (o.rate == null || !(o.contextC > o.baselineB * 1.2)) {
+    return { boughtMinutes: 0, projectedBurn: o.rate };
+  }
+  let ratio;
+  if (o.calib) {
+    const w = (x) => Math.max(o.calib.a * x + o.calib.b, 1e-9);
+    ratio = w(o.baselineB) / w(o.contextC);
+  } else {
+    const w = (x) => READ_WEIGHT * x + K_TAIL;
+    ratio = w(o.baselineB) / w(o.contextC);
+  }
+  // A clear can't shed the output/write tail or the retained baseline, so burn
+  // can't realistically drop below ~5% of current (or an absolute 0.01%/min).
+  const rNew = Math.max(o.rate * ratio, o.rate * 0.05, 0.01);
+  const remaining = 100 - o.usedPct;
+  const horizon = (o.resetMinutes != null && isFinite(o.resetMinutes)) ? o.resetMinutes : Infinity;
+  const lifeOld = Math.min(remaining / o.rate, horizon);
+  const lifeNew = Math.min(remaining / rNew, horizon);
+  return { boughtMinutes: Math.max(lifeNew - lifeOld, 0), projectedBurn: rNew };
+}
+
+/**
+ * Interpretable burn-rate estimate: an EWMA of recent per-interval rates, scoped
+ * to the active model. "A running average of your recent burn, weighting the last
+ * few minutes most." Chosen over Kalman/window after backtesting real transcripts
+ * (scripts/backtest-burn.js): trend overfits, raw-instantaneous jitters ~5x more,
+ * and a recency-weighted average is as accurate while far steadier — and any
+ * reviewer can verify the calculation. Forecast the sustained rate, not the tick.
+ * @param {{ t: number, u: number, m?: string }[]} samples  t in minutes, u = used %
+ * @param {string} activeModel
+ * @param {number} [alpha] smoothing in (0,1]; higher = more responsive. Default 0.3.
+ * @returns {{ rate: number | null, samples: number, switched: boolean }}
+ */
+function smoothedRate(samples, activeModel, alpha = 0.3) {
+  let start = 0;
+  for (let i = samples.length - 1; i >= 0; i--) {
+    if ((samples[i].m || '') !== activeModel) { start = i + 1; break; }
+  }
+  const tail = samples.slice(start);
+  let ewma = NaN;                               // NaN = "no rate yet" (avoids null typing)
+  for (let i = 1; i < tail.length; i++) {
+    const dt = tail[i].t - tail[i - 1].t;
+    const du = tail[i].u - tail[i - 1].u;
+    if (dt <= 0 || du < 0) continue;            // skip idle gaps / meter resets
+    const r = du / dt;
+    ewma = isNaN(ewma) ? r : alpha * r + (1 - alpha) * ewma;
+  }
+  return { rate: isNaN(ewma) ? null : ewma, samples: tail.length, switched: tail.length < samples.length };
+}
+
+module.exports = {
+  FIVE_HOUR_MIN, SEVEN_DAY_MIN,
+  inferWindow, parseResetsAt, rateFromSamples, smoothedRate, windowEstimate, binding, clearROI,
+};