claude-code-runrate 0.1.0

package/src/doctor.js

@@ -0,0 +1,115 @@
+// @ts-check
+'use strict';
+// src/doctor.js — `ccr doctor`: check the local setup and capture status.
+// Pure Node; the few external checks use `command -v`. Diagnoses the common
+// "nothing happens" causes (ccr not linked, tmux/ccs missing, no capture yet).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { spawnSync } = require('node:child_process');
+const { stripControl } = require('./sanitize');
+
+const ok = (/** @type {string} */ s) => `\x1b[32m✓\x1b[0m ${s}`;
+const bad = (/** @type {string} */ s) => `\x1b[31m✗\x1b[0m ${s}`;
+const warn = (/** @type {string} */ s) => `\x1b[33m⚠\x1b[0m ${s}`;
+const dim = (/** @type {string} */ s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (/** @type {string} */ s) => `\x1b[1m${s}\x1b[0m`;
+
+/** @param {string} cmd → resolved path or null */
+function has(cmd) {
+  // Only ever called with literal tool names; refuse anything that isn't a bare
+  // command word so this can never become a shell-injection sink.
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(cmd)) return null;
+  try {
+    // Native Windows has no `sh`; `where` is the built-in PATH lookup there.
+    const r = process.platform === 'win32'
+      ? spawnSync('where', [cmd], { encoding: 'utf8' })
+      : spawnSync('sh', ['-c', `command -v ${cmd}`], { encoding: 'utf8' });
+    if (r.status !== 0) return null;
+    return r.stdout.trim().split(/\r?\n/)[0] || null; // `where` may list several
+  } catch { return null; }
+}
+function isExec(/** @type {string} */ f) {
+  try { return (fs.statSync(f).mode & 0o111) !== 0; } catch { return false; }
+}
+
+/** @returns {number} exit code (0 = healthy) */
+function run() {
+  const REPO = path.join(__dirname, '..');
+  const isWin = process.platform === 'win32';
+  const out = [bold('ccr doctor'), ''];
+  let problems = 0;
+
+  const [maj, min] = process.versions.node.split('.').map(Number);
+  const nodeOk = maj > 18 || (maj === 18 && min >= 3);
+  out.push(nodeOk ? ok(`node ${process.version}`) : bad(`node ${process.version} — need >= 18.3`));
+  if (!nodeOk) problems++;
+
+  const ccr = has('ccr');
+  out.push(ccr ? ok(`ccr on PATH (${stripControl(ccr)})`) : warn('ccr not on PATH — run `npm link` in the repo'));
+  if (!ccr) problems++;
+
+  if (isWin) {
+    // The live sidebar (tmux + bash) is WSL-only on native Windows — by design,
+    // not a problem. Say so plainly so a Windows user isn't told to "fix" it.
+    out.push(dim('· live sidebar (`ccr`) needs tmux + bash — for that, use WSL2.'));
+    out.push(dim('  The CLI (economy / statusline / resume / doctor) runs natively here.'));
+  } else {
+    const tmux = has('tmux');
+    out.push(tmux ? ok(`tmux (${stripControl(tmux)})`) : warn('tmux missing — needed for `ccr [profile]` sidebar (use WSL on Windows)'));
+    if (!tmux) problems++;
+    out.push(has('bash') ? ok('bash') : warn('bash missing — needed for the launcher'));
+
+    const sl = path.join(REPO, 'sidecar', 'ccr-statusline');
+    out.push(isExec(sl) ? ok('sidecar/ccr-statusline is executable') : warn('sidecar/ccr-statusline not executable (the launcher self-heals this)'));
+  }
+
+  const ccs = has('ccs');
+  if (ccs) {
+    let profiles = [];
+    try { profiles = fs.readdirSync(path.join(os.homedir(), '.ccs', 'instances')).filter((p) => !p.startsWith('.')); } catch { /* none */ }
+    // Profile + path come from the filesystem; sanitize before display.
+    out.push(ok(`ccs (${stripControl(ccs)}) · profiles: ${profiles.map(stripControl).join(', ') || '(none)'}`));
+  } else {
+    out.push(dim('· ccs not installed (optional — only for `ccr <profile>`)'));
+  }
+
+  // newest captured snapshot across ~/.ccr and its per-profile subdirs (state
+  // lives under the user's home now, never world-shared /tmp).
+  const ccrDir = path.join(os.homedir(), '.ccr');
+  const dirs = [ccrDir];
+  try {
+    for (const d of fs.readdirSync(ccrDir)) {
+      const sub = path.join(ccrDir, d);
+      try { if (fs.statSync(sub).isDirectory()) dirs.push(sub); } catch { /* ignore */ }
+    }
+  } catch { /* none */ }
+  let newest = null;
+  for (const d of dirs) {
+    try { const m = fs.statSync(path.join(d, 'last-status.json')).mtimeMs; if (!newest || m > newest.m) newest = { d, m }; } catch { /* none */ }
+  }
+  if (newest) {
+    const ageMin = Math.round((Date.now() - newest.m) / 60000);
+    let keys = [];
+    try { keys = Object.keys(JSON.parse(fs.readFileSync(path.join(newest.d, 'last-status.json'), 'utf8')).rate_limits || {}); } catch { /* ignore */ }
+    // Defense-in-depth: sanitize the dir + bucket keys before display even
+    // though state now lives under the user's own home.
+    out.push(ok(`status captured ${ageMin}m ago (${stripControl(newest.d)})`));
+    out.push(dim(`  buckets: ${keys.map(stripControl).join(', ') || '(none — API session?)'}`));
+  } else {
+    out.push(warn(isWin
+      ? 'no status captured yet — wire `ccr statusline` into Claude Code (settings.json) to start capturing'
+      : 'no status captured yet — launch with `ccr` (or `ccr <profile>`) to start capturing'));
+  }
+
+  out.push('');
+  const allGood = isWin
+    ? 'all good — `ccr economy` for the panel, `ccr statusline` to wire into CC'
+    : 'all good — `ccr` to launch, `ccr economy` for the panel';
+  out.push(problems ? warn(`${problems} thing(s) to address above`) : ok(allGood));
+  process.stdout.write(out.join('\n') + '\n');
+  return problems ? 1 : 0;
+}
+
+module.exports = { run };

package/src/economy-model.js

@@ -0,0 +1,122 @@
+// @ts-check
+'use strict';
+// src/economy-model.js — the computed economy model.
+//
+// This is the SINGLE SOURCE OF TRUTH for window classification, the binding
+// window, the status band, and clear-ROI. Both consumers read from it:
+//   - the text panel (src/render/economy.js) renders it
+//   - `ccr economy --json` serialises it (the stable machine-readable contract)
+// so the panel and the JSON can never disagree about which window binds.
+//
+// Pure function of a normalized `view` (see src/normalize.js). All numbers are
+// raw (unrounded) — consumers format. Units: pct = percent, rate = %/min,
+// minutes* = minutes, tokens = count, costUsd = US dollars.
+
+const { windowEstimate, clearROI, binding } = require('./burn');
+
+// Bump on any BREAKING change (renamed/removed field, changed semantics).
+// Additive changes (new fields) do NOT bump it — consumers must ignore unknowns.
+const SCHEMA_VERSION = 1;
+
+const IMMINENT_MIN = 30; // status band: red / flashing in the panel
+const WARN_MIN = 120;    // status band: yellow
+
+/** @param {number|null} min minutes-to-exhaust → at-a-glance status band */
+function band(min) {
+  if (min == null) return 'ok';
+  if (min <= IMMINENT_MIN) return 'imminent';
+  if (min <= WARN_MIN) return 'warn';
+  return 'ok';
+}
+
+/**
+ * Classify each rate-limit window: burn estimate, whether it binds (would
+ * exhaust BEFORE it resets), and which one you hit first. Tolerates any plan
+ * shape (5h, weekly, model-scoped, monthly, …); returns `next = null` for an
+ * API session with no reported windows.
+ * @param {any} view
+ * @returns {{ rows: any[], next: any }}
+ */
+function classifyWindows(view) {
+  const windows = Array.isArray(view.windows) ? view.windows : [];
+  const rows = windows.map((/** @type {any} */ wd) => {
+    const est = windowEstimate({ usedPct: wd.usedPct, rate: wd.rate, minutesToReset: wd.minutesToReset, windowMinutes: wd.windowMinutes });
+    const ml = est.minutesLeft;
+    return {
+      key: wd.key,
+      label: wd.label || wd.key,
+      est,
+      reset: wd.minutesToReset,
+      binding: false,
+      live: ml != null && wd.minutesToReset != null && ml < wd.minutesToReset,
+      resetsFirst: ml != null && wd.minutesToReset != null && ml >= wd.minutesToReset,
+    };
+  });
+  const live = rows.filter((r) => r.live).map((r) => ({ key: r.key, est: r.est, reset: r.reset }));
+  const b = binding(live);
+  const next = b ? rows.find((r) => r.key === b.window) : null;
+  if (next) next.binding = true;
+  return { rows, next };
+}
+
+/**
+ * Build the full economy model — the contract behind `ccr economy --json`.
+ * @param {any} view normalized economy data (see normalizeStatus)
+ * @returns {{
+ *   schemaVersion: number, model: string|null,
+ *   context: { tokens: number|null, windowSize: number|null, pct: number|null, cachedPct: number|null },
+ *   windows: Array<{ key:string, label:string, usedPct:number, rate:number|null, minutesLeft:number|null, minutesToReset:number|null, band:string, binding:boolean, resetsBeforeHit:boolean }>,
+ *   binding: { key:string, label:string, minutesLeft:number|null, band:string }|null,
+ *   clear: { worthwhile:boolean, boughtMinutes:number, contextTokens:number|null, baselineTokens:number },
+ *   session: { costUsd:number|null, durationMin:number|null, branch:string|null }
+ * }}
+ */
+function computeEconomy(view) {
+  const { rows, next } = classifyWindows(view);
+  const baselineTokens = view.baselineTok || 14000;
+  const ctxTokens = view.contextTokens ?? null;
+  const windowSize = view.windowSize ?? null;
+
+  const windows = rows.map((r) => ({
+    key: r.key,
+    label: r.label,
+    usedPct: r.est.usedPct,
+    rate: r.est.rate,
+    minutesLeft: r.est.minutesLeft,
+    minutesToReset: r.reset,
+    band: band(r.est.minutesLeft),
+    binding: r.binding,
+    resetsBeforeHit: r.resetsFirst,
+  }));
+
+  // Mirrors the panel's clear gate: only meaningful when a window binds, a rate
+  // is known, and context sits >20% above the post-clear baseline.
+  let clear = { worthwhile: false, boughtMinutes: 0, contextTokens: ctxTokens, baselineTokens };
+  if (next && next.est.rate != null && ctxTokens != null && ctxTokens > baselineTokens * 1.2) {
+    const roi = clearROI({ rate: next.est.rate, usedPct: next.est.usedPct, contextC: ctxTokens, baselineB: baselineTokens, calib: null, resetMinutes: next.reset });
+    clear = { worthwhile: roi.boughtMinutes > 0, boughtMinutes: roi.boughtMinutes, contextTokens: ctxTokens, baselineTokens };
+  }
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    model: view.model ?? null,
+    context: {
+      tokens: ctxTokens,
+      windowSize,
+      pct: (ctxTokens != null && windowSize) ? (ctxTokens / windowSize) * 100 : null,
+      cachedPct: view.cachedPct ?? null,
+    },
+    windows,
+    binding: next
+      ? { key: next.key, label: next.label, minutesLeft: next.est.minutesLeft, band: band(next.est.minutesLeft) }
+      : null,
+    clear,
+    session: {
+      costUsd: view.costUsd ?? null,
+      durationMin: view.durationMin ?? null,
+      branch: view.branch ?? null,
+    },
+  };
+}
+
+module.exports = { computeEconomy, classifyWindows, band, SCHEMA_VERSION };

package/src/instrument.js

@@ -0,0 +1,67 @@
+// @ts-check
+'use strict';
+// src/instrument.js — minimal LOCAL meter-sample logging for OFFLINE analysis.
+//
+// Data collection, NOT machine learning. The transcripts don't store the meter
+// %, so this is the only way to backtest the estimator on the real target (feed
+// scripts/backtest-burn.js). It captures EVERY rate-limit bucket the plan
+// exposes verbatim — so we learn each tier's real schema (5h, weekly, a
+// model-scoped "Sonnet only" weekly, a monthly one) rather than assuming two.
+// Append-only, size-capped, under ~/.ccr, never transmitted; a no-op when
+// CCR_NO_INSTRUMENT is set.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { ensureSecureDir } = require('./state-dir');
+
+const CAP_BYTES = 2_000_000; // halve the log when it exceeds this
+
+function capFile(/** @type {string} */ file) {
+  try {
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    fs.writeFileSync(file, lines.slice(-Math.floor(lines.length / 2)).join('\n') + '\n', { mode: 0o600 });
+  } catch { /* ignore */ }
+}
+
+/**
+ * Append one sample if this is a subscription session (≥1 rate-limit bucket).
+ * Never throws — logging must not break the status line.
+ * @param {any} state CC status-line JSON
+ * @param {{ dir?: string, now?: number }} [opts]
+ * @returns {boolean} whether a sample was written
+ */
+function logMeterSample(state, opts = {}) {
+  if (process.env.CCR_NO_INSTRUMENT) return false;
+  const rl = (state && state.rate_limits) || {};
+  /** @type {Record<string, { used: number, resets_at: any }>} */
+  const limits = {};
+  for (const k of Object.keys(rl)) {
+    const r = rl[k];
+    if (r && typeof r === 'object' && r.used_percentage != null) {
+      limits[k] = { used: r.used_percentage, resets_at: r.resets_at ?? null };
+    }
+  }
+  if (!Object.keys(limits).length) return false; // API session — nothing to log
+
+  const dir = opts.dir || path.join(os.homedir(), '.ccr');
+  const sid = String(state.session_id || 'default').replace(/[^A-Za-z0-9_-]/g, '');
+  const file = path.join(dir, `burnlog-${sid}.jsonl`);
+  const cw = state.context_window || {};
+  const rec = {
+    t: opts.now != null ? opts.now : Date.now(),
+    model: (state.model && state.model.id) || null,
+    ctx: cw.total_input_tokens ?? (cw.current_usage && cw.current_usage.cache_read_input_tokens) ?? null,
+    limits,
+  };
+  try {
+    ensureSecureDir(dir);
+    try { if (fs.statSync(file).size > CAP_BYTES) capFile(file); } catch { /* new file */ }
+    fs.appendFileSync(file, JSON.stringify(rec) + '\n', { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { logMeterSample };

package/src/liveness.js

@@ -0,0 +1,39 @@
+// @ts-check
+'use strict';
+// src/liveness.js
+// Decide how the sidecar should present session liveness.
+//
+// Core principle: status-line emission cadence is NOT a liveness signal. Claude
+// Code does not tick during a single long operation, so an old snapshot must
+// NEVER blank the dashboard. Staleness is a quiet annotation; only the explicit
+// exit sentinel means the session ended.
+//
+// Pure function of (exited, ageMs, staleMs) — no process probing (pstree/tmux),
+// which is exactly what makes naive liveness heuristics over-eager to timeout.
+
+/** Default age before a dim freshness note appears. Annotation only, never a wipe. */
+const DEFAULT_STALE_MS = 120000;
+
+/** @returns {number | null} */
+function envStaleMs() {
+  const v = Number(process.env.CCR_STALE_MS);
+  return Number.isFinite(v) && v > 0 ? v : null;
+}
+
+/**
+ * @param {{ exited?: boolean, ageMs?: number, staleMs?: number }} input
+ * @returns {{ mode: 'ended' | 'live', marker: string | null }}
+ *   mode 'live'  → render the dashboard (optionally with a freshness marker)
+ *   mode 'ended' → render the session-ended screen (sentinel-confirmed only)
+ */
+function liveness(input) {
+  const exited = !!input.exited;
+  if (exited) return { mode: 'ended', marker: null };
+
+  const ageMs = input.ageMs ?? 0;
+  const staleMs = input.staleMs ?? envStaleMs() ?? DEFAULT_STALE_MS;
+  const marker = ageMs >= staleMs ? `updated ${Math.floor(ageMs / 60000)}m ago` : null;
+  return { mode: 'live', marker };
+}
+
+module.exports = { liveness, DEFAULT_STALE_MS };

package/src/normalize.js

@@ -0,0 +1,32 @@
+// @ts-check
+'use strict';
+// src/normalize.js — map Claude Code's status-line JSON to the renderer's view.
+// Rate-limit buckets are DISCOVERED (not hardcoded) so any plan's bucket set —
+// grandfathered Pro, current Pro, Max, model-scoped "Sonnet only" — is handled.
+
+const { discoverWindows } = require('./rate-limits');
+const { stripControl } = require('./sanitize');
+
+/**
+ * @param {any} state CC status-line JSON
+ * @param {number} [nowSec] override for testing
+ * @returns {any} view consumed by renderEconomy
+ */
+function normalizeStatus(state, nowSec) {
+  const rl = (state && state.rate_limits) || {};
+  const cw = (state && state.context_window) || {};
+  return {
+    model: stripControl((state && state.model && state.model.display_name) || null),
+    windowSize: cw.context_window_size || 200000,
+    windows: discoverWindows(rl, nowSec),
+    contextTokens: cw.total_input_tokens
+      ?? (cw.current_usage && cw.current_usage.cache_read_input_tokens) ?? null,
+    cachedPct: null,
+    baselineTok: 14000,
+    costUsd: state && state.cost && state.cost.total_cost_usd != null ? state.cost.total_cost_usd : null,
+    durationMin: state && state.cost && state.cost.total_duration_ms != null ? state.cost.total_duration_ms / 60000 : null,
+    branch: null,
+  };
+}
+
+module.exports = { normalizeStatus };

package/src/rate-limits.js

@@ -0,0 +1,89 @@
+// @ts-check
+'use strict';
+// src/rate-limits.js — discover whatever rate-limit buckets a plan exposes.
+//
+// Subscription tiers differ: a grandfathered Pro account, a current Pro account,
+// and Max all report DIFFERENT buckets under `rate_limits` (5h, weekly, a
+// separate model-scoped "Sonnet only" weekly, possibly a monthly one). Rather
+// than hardcode key names, we read every bucket present and derive a label +
+// window length heuristically, so any current or future bucket is handled
+// gracefully. Unknown buckets still render (used % + reset); they just can't
+// project a time-to-limit until we know (or learn) their window length.
+
+const { parseResetsAt } = require('./burn');
+const { stripControl } = require('./sanitize');
+
+const FIVE = 300, WEEK = 10080, MONTH = 43200;
+
+// Known keys get exact labels/windows; everything else falls back to heuristics.
+const KNOWN = {
+  five_hour: { label: '5h', windowMinutes: FIVE },
+  seven_day: { label: 'weekly', windowMinutes: WEEK },
+};
+
+/** @param {string} key → 'Sonnet' | 'Opus' | 'Haiku' | null */
+function modelScope(key) {
+  if (/sonnet/i.test(key)) return 'Sonnet';
+  if (/opus/i.test(key)) return 'Opus';
+  if (/haiku/i.test(key)) return 'Haiku';
+  return null;
+}
+
+/** @param {string} key → window length in minutes, or null if not inferable */
+function inferWindowMinutes(key) {
+  const h = key.match(/(\d+)\s*_?\s*hour/i); if (h) return Number(h[1]) * 60;
+  if (/month/i.test(key)) return MONTH;
+  if (/week|seven[_-]?day|7[_-]?day/i.test(key)) return WEEK;
+  const d = key.match(/(\d+)\s*_?\s*day/i); if (d) return Number(d[1]) * 1440;
+  if (/hour/i.test(key)) return FIVE;   // bare "hour" → the 5h window
+  if (/day/i.test(key)) return 1440;
+  return null;
+}
+
+/** @param {string} key → human label (scope appended when present) */
+function labelFor(key) {
+  let base;
+  if (KNOWN[key]) base = KNOWN[key].label;
+  else if (/week|seven[_-]?day|7[_-]?day/i.test(key)) base = 'weekly';
+  else if (/month/i.test(key)) base = 'monthly';
+  else {
+    const h = key.match(/(\d+)\s*_?\s*hour/i);
+    const d = key.match(/(\d+)\s*_?\s*day/i);
+    base = h ? `${h[1]}h` : d ? `${d[1]}d` : key.replace(/_/g, ' ');
+  }
+  const scope = modelScope(key);
+  // Unknown keys flow into the label verbatim (`key.replace(...)`), so sanitize
+  // before it reaches the terminal.
+  return stripControl(scope ? `${base} · ${scope}` : base);
+}
+
+/**
+ * @param {any} rateLimits the status JSON `rate_limits` object
+ * @param {number} [nowSec]
+ * @returns {{ key:string, label:string, usedPct:number, minutesToReset:number|null, windowMinutes:number|null, modelScope:string|null }[]}
+ */
+function discoverWindows(rateLimits, nowSec) {
+  /** @type {any[]} */
+  const out = [];
+  if (!rateLimits || typeof rateLimits !== 'object') return out;
+  const now = nowSec != null ? nowSec : Date.now() / 1000;
+  for (const key of Object.keys(rateLimits)) {
+    const r = rateLimits[key];
+    if (!r || typeof r !== 'object' || r.used_percentage == null) continue;
+    const at = r.resets_at != null ? parseResetsAt(r.resets_at) : null;
+    out.push({
+      key,
+      label: labelFor(key),
+      usedPct: r.used_percentage,
+      minutesToReset: at != null ? Math.max(0, (at - now) / 60) : null,
+      windowMinutes: KNOWN[key] ? KNOWN[key].windowMinutes : inferWindowMinutes(key),
+      modelScope: modelScope(key),
+    });
+  }
+  // Shortest window first (5h → weekly → monthly); buckets with no inferable
+  // window sort last.
+  out.sort((a, b) => (a.windowMinutes || 1e9) - (b.windowMinutes || 1e9));
+  return out;
+}
+
+module.exports = { discoverWindows, labelFor, inferWindowMinutes, modelScope };

package/src/render/economy.js

@@ -0,0 +1,112 @@
+// @ts-check
+'use strict';
+// src/render/economy.js — the economy screen.
+//
+// Shows BOTH the 5h and weekly walls, marks which one you'll hit first ("the
+// wall" — only if it exhausts before it resets), states the clear decision in
+// plain language, and degrades gracefully on API sessions. Pure function of a
+// normalized `view`; colour/flash via opts.tick; vocabulary via opts.theme.
+
+const { clearROI } = require('../burn');
+const { classifyWindows, band } = require('../economy-model');
+const { resolveTheme, lexicon } = require('../theme');
+const { dim, bold, green, red, yellow, cyan, flash, pctColor, bar, tok, fmtMins, fmtReset } = require('./shared');
+
+const bandColor = { imminent: red, warn: yellow, ok: cyan };
+
+function wallRow(/** @type {any} */ row, /** @type {any} */ L, /** @type {boolean} */ tick, /** @type {number} */ labelW) {
+  const used = Math.round(row.est.usedPct);
+  const ml = row.est.minutesLeft;
+  const b = band(ml);
+  // Per-row colour dot: green when the window resets before you'd hit it,
+  // otherwise graded by how soon it would exhaust (cyan→yellow→red, flash when
+  // imminent on the binding window). The at-a-glance status signal.
+  const dotColor = row.resetsFirst ? green : bandColor[b];
+  const dot = (row.binding && b === 'imminent') ? flash(tick, '●') : dotColor('●');
+
+  const labelTxt = row.label.padEnd(labelW);
+  const label = row.binding ? bold(bandColor[b](labelTxt)) : dim(labelTxt);
+  // Time-to-exhaust carries no word: the sibling "resets …" is self-labelling,
+  // so a bare "~8h43m" reads unambiguously as remaining budget.
+  const leftTxt = (ml != null ? '~' + fmtMins(ml) : '—').padEnd(7);
+  const left = row.binding ? bold(leftTxt) : dim(leftTxt);
+  const resets = row.reset != null ? dim('resets ' + fmtReset(row.reset)) : '';
+  const meter = pctColor(used)(bar(used)) + ' ' + String(used).padStart(2) + '% used';
+  const main = '  ' + dot + ' ' + label + ' ' + left + ' ' + meter + '  ' + resets;
+
+  // The binding window's "wall" call-out drops to its own indented line below —
+  // so a long marker never trails off the narrow sidebar edge and wraps.
+  if (row.binding) {
+    const mark = '↑ ' + L.wall;
+    return main + '\n      ' + (b === 'imminent' ? flash(tick, mark) : bandColor[b](mark));
+  }
+  return main;
+}
+
+/**
+ * @param {any} view normalized economy data
+ * @param {{ theme?: 'plain'|'mary', now?: Date, tick?: boolean, env?: any }} [opts]
+ * @returns {string}
+ */
+function renderEconomy(view, opts = {}) {
+  const themeName = opts.theme || resolveTheme(opts.now, opts.env);
+  const L = lexicon(themeName);
+  const tick = !!opts.tick;
+  const out = [bold('economy') + dim('   ' + (view.model || '')), ''];
+
+  const { rows, next } = classifyWindows(view);
+  const labelW = Math.max(8, ...rows.map((/** @type {any} */ r) => r.label.length));
+
+  // HERO
+  if (!rows.length) {
+    out.push('  ' + dim('window limits are subscription-only — none reported (API session)'));
+  } else if (next) {
+    const b = band(next.est.minutesLeft);
+    const t = '~' + fmtMins(next.est.minutesLeft);
+    if (b === 'imminent') {
+      out.push('  ' + flash(tick, '▲ ' + L.imminent) + dim('  ·  ') + bold(next.label) + dim(' in ') + flash(tick, t));
+    } else {
+      const col = bandColor[b];
+      out.push('  ' + dim(L.looming) + '   ' + bold(col(next.label)) + dim(' in ') + bold(col(t)));
+    }
+  } else {
+    out.push('  ' + green(L.within) + dim('  ·  each window resets before you reach it'));
+  }
+  out.push('');
+
+  for (const r of rows) out.push(wallRow(r, L, tick, labelW));
+  if (rows.length) out.push('');
+
+  // CLEAR — plain language, framed against the binding wall, only when it looms.
+  const B = view.baselineTok || 14000;
+  if (next && next.est.rate != null) {
+    if (view.contextTokens > B * 1.2) {
+      const roi = clearROI({ rate: next.est.rate, usedPct: next.est.usedPct, contextC: view.contextTokens, baselineB: B, calib: null, resetMinutes: next.reset });
+      out.push('  ' + bold('clear now') + ' → ' + green('+' + fmtMins(roi.boughtMinutes)) + ' before ' + cyan(next.label) + dim(`   (${tok(view.contextTokens)} → ${tok(B)})`));
+    } else {
+      out.push('  ' + dim(`context near baseline (${tok(view.contextTokens)}) — little to gain from clearing`));
+    }
+    out.push('');
+  } else if (rows.length && view.contextTokens > B * 1.2) {
+    out.push('  ' + dim(`no limit pressure · clearing ${tok(view.contextTokens)}→${tok(B)} would only trim cost`));
+    out.push('');
+  }
+
+  // CONTEXT + footer
+  if (view.contextTokens != null) {
+    const cp = Math.round((view.contextTokens / view.windowSize) * 100);
+    const cached = view.cachedPct != null ? dim(`  cached ${view.cachedPct}%`) : '';
+    out.push('  ' + 'ctx'.padEnd(labelW) + ' ' + pctColor(cp)(bar(cp)) + ' ' + String(cp).padStart(2) + '%' + dim(`  ${tok(view.contextTokens)}/${tok(view.windowSize)}`) + cached);
+  }
+  if (view.rolling) out.push('  ' + dim(`last ${view.rolling.sessions} sessions · clears ${view.rolling.clears} · median clear @ ${Math.round(view.rolling.medClearPct * 100)}%`));
+  const foot = [];
+  if (view.costUsd != null) foot.push('$' + view.costUsd.toFixed(2));
+  if (view.durationMin != null) foot.push(fmtMins(view.durationMin));
+  if (view.branch) foot.push(view.branch);
+  foot.push(L.clearKey);
+  out.push('  ' + dim(foot.join(' · ')));
+
+  return out.join('\n');
+}
+
+module.exports = { renderEconomy };

package/src/render/feed.js

@@ -0,0 +1,64 @@
+// @ts-check
+'use strict';
+// src/render/feed.js — the live tool/skills feed shown under the economy panel in
+// the sidecar. Pure function of an accumulated feed object (events + rolling
+// stats); the sidecar does the incremental transcript tail and hands it here.
+
+const { dim, bold, cyan, tok } = require('./shared');
+
+/** @param {string} s @param {number} n */
+function trunc(s, n) {
+  s = String(s);
+  return s.length <= n ? s : s.slice(0, Math.max(0, n - 1)) + '…';
+}
+
+/**
+ * @typedef {{ ts: number|null, kind: 'tool'|'cmd', tool: string, arg: string }} FeedEvent
+ * @typedef {{ events: FeedEvent[], tools: Record<string, number>, commands: number,
+ *             tokens: { input: number, output: number, cacheRead: number, cacheCreate: number },
+ *             files: string[] }} Feed
+ */
+
+/**
+ * Render the feed block: a tool-count header, an optional rolling-stats line, and
+ * the last N events. Returns '' when there's nothing to show (so the sidecar can
+ * omit it cleanly).
+ * @param {Feed} feed
+ * @param {{ max?: number, width?: number }} [opts]
+ * @returns {string}
+ */
+function renderFeed(feed, opts = {}) {
+  if (!feed) return '';
+  const max = opts.max || 5;
+  const width = opts.width || 48;
+  const events = Array.isArray(feed.events) ? feed.events : [];
+  const tools = feed.tools || {};
+  const counts = Object.keys(tools).sort((a, b) => tools[b] - tools[a]);
+  // Rolling per-session stats: files touched + work generated (output tokens).
+  const nFiles = Array.isArray(feed.files) ? feed.files.length : 0;
+  const out = feed.tokens && feed.tokens.output;
+  // Nothing to show only when there are neither tool/command/event rows NOR any
+  // rolling stats — stats alone are still worth rendering.
+  if (!counts.length && !feed.commands && !events.length && !nFiles && !out) return '';
+
+  const parts = counts.map((k) => `${k} ${tools[k]}`);
+  if (feed.commands) parts.push(`cmd ${feed.commands}`);
+  const lines = ['  ' + bold('feed') + dim(parts.length ? '  ·  ' + trunc(parts.join(' · '), width - 8) : '  ·  (no tool calls yet)')];
+
+  const stat = [];
+  if (nFiles) stat.push(`${nFiles} file${nFiles === 1 ? '' : 's'}`);
+  if (out) stat.push(`${tok(out)} generated`);
+  if (stat.length) lines.push('  ' + dim('       ' + stat.join(' · ')));
+
+  for (const e of events.slice(-max)) {
+    if (e.kind === 'cmd') {
+      lines.push('    ' + cyan('⌘ ' + trunc(e.tool, width - 4)));
+    } else {
+      const arg = e.arg ? '  ' + dim(trunc(e.arg, width - 12)) : '';
+      lines.push('    ' + dim('↳ ') + e.tool.padEnd(8) + arg);
+    }
+  }
+  return lines.join('\n');
+}
+
+module.exports = { renderFeed, trunc };