claude-code-runrate 0.2.4 → 0.3.0

package/src/pane-blob.js

@@ -0,0 +1,249 @@
+// @ts-check
+'use strict';
+// src/pane-blob.js — THE verifier. Between a blob file's bytes and any renderer
+// sits exactly this function, and it returns either a validated v1 blob or one
+// named failure. No renderer ever sees unvalidated input.
+// Contract: docs/PANE-CONTRACT.md § The verifier.
+//
+// Three properties this file is built around, all of them load-bearing:
+//
+//   TOTAL. Nothing here throws. The sidebar is ONE pane: an exception raised
+//   into the draw loop would take the burn-rate display down with it, so a
+//   malformed blob must cost a pane state and never the sidecar.
+//
+//   WHITELIST-CONSTRUCT. Every returned object is built fresh from the fields
+//   v1 names. The parsed input is never spread, never Object.assign'd, never
+//   merged. That is the prototype-pollution path, and it is the one
+//   injection-style attack a JSON consumer in Node gets handed for free.
+//
+//   TYPES CHECKED, NOT COERCED. A JSON file chooses its own value types, so
+//   `typeof` is the only thing that makes "this field is a string" true. (The
+//   sidecar learned this the hard way elsewhere: an array where a string was
+//   expected put raw terminal escapes on screen. See src/sanitize.js.)
+
+const fs = require('node:fs');
+const { stripControl } = require('./sanitize');
+
+const BLOB_VERSION = 1;
+const MAX_BLOB_BYTES = 256 * 1024;
+const MAX_ROWS = 256;
+const MAX_FIELD_CHARS = 512;
+const MAX_SPARK = 32;
+
+/** The closed row-status enum. Anything else renders as `dark` (never green). */
+const ROW_STATUSES = new Set(['ok', 'warn', 'alert', 'dark', 'off']);
+
+/**
+ * A display string: sanitized, then truncated. Order matters — validation
+ * checks shape, never bytes, so the strip is unconditional and comes after.
+ * @param {string} s
+ * @returns {string}
+ */
+const display = (s) => {
+  const clean = String(stripControl(s) ?? '');
+  return clean.length > MAX_FIELD_CHARS ? clean.slice(0, MAX_FIELD_CHARS) : clean;
+};
+
+const isStr = (/** @type {any} */ v) => typeof v === 'string';
+
+/**
+ * Read the blob file safely enough to name WHY it could not be read.
+ *
+ * This does not use readTextCapped: that collapses every failure to null, and
+ * the contract requires "cannot-read" (a chmod mistake, a fifo, a symlink) to
+ * be visibly distinct from "waiting" (the producer simply hasn't run yet).
+ * Conflating them would make a permissions bug look like patience.
+ *
+ * @param {string} file
+ * @returns {{ ok: true, text: string, mtimeMs: number }
+ *           | { ok: false, state: 'waiting' }
+ *           | { ok: false, state: 'cannot-read', reason: string }
+ *           | { ok: false, state: 'oversized' }}
+ */
+function readBlobFile(file) {
+  let st;
+  try {
+    // lstat, not stat: a symlink must be REFUSED rather than followed, and a
+    // fifo must be identified without opening it (opening one blocks forever).
+    st = fs.lstatSync(file);
+  } catch (e) {
+    const code = e && /** @type {any} */ (e).code;
+    if (code === 'ENOENT') return { ok: false, state: 'waiting' };
+    return { ok: false, state: 'cannot-read', reason: code === 'EACCES' ? 'permission' : 'unavailable' };
+  }
+  if (st.isSymbolicLink()) return { ok: false, state: 'cannot-read', reason: 'symlink' };
+  if (st.isDirectory()) return { ok: false, state: 'cannot-read', reason: 'directory' };
+  if (!st.isFile()) return { ok: false, state: 'cannot-read', reason: 'not a regular file' };
+  if (st.size > MAX_BLOB_BYTES) return { ok: false, state: 'oversized' };
+
+  // The lstat above is ADVISORY, not a guarantee: the path can be replaced
+  // between the check and the open, and a producer that writes atomically is
+  // renaming over this path constantly, so a swap looks like normal operation.
+  // The open itself must therefore be safe on its own terms:
+  //   O_NOFOLLOW  — refuse a symlink at open time, so "symlinks are refused"
+  //                 is enforced by the kernel rather than by a stale stat.
+  //   O_NONBLOCK  — a FIFO opened for reading blocks until a writer appears,
+  //                 which in this single-threaded draw loop means FOREVER: no
+  //                 render, no heartbeat, no recovery. With O_NONBLOCK the open
+  //                 returns immediately (ENXIO) instead of hanging.
+  // Both flags are absent on Windows; `|| 0` degrades to the old behaviour
+  // there, where neither fifos nor symlinks-without-privilege are a concern.
+  const O_NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+  const O_NONBLOCK = fs.constants.O_NONBLOCK || 0;
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+  } catch (e) {
+    const code = e && /** @type {any} */ (e).code;
+    if (code === 'ELOOP') return { ok: false, state: 'cannot-read', reason: 'symlink' };
+    if (code === 'ENXIO' || code === 'EWOULDBLOCK' || code === 'EAGAIN') {
+      return { ok: false, state: 'cannot-read', reason: 'not a regular file' };
+    }
+    if (code === 'ENOENT') return { ok: false, state: 'waiting' };
+    return { ok: false, state: 'cannot-read', reason: code === 'EACCES' ? 'permission' : 'unavailable' };
+  }
+  try {
+    // Re-stat from the descriptor: the file may have been replaced since the
+    // lstat, and this describes the bytes actually held open.
+    const fst = fs.fstatSync(fd);
+    if (!fst.isFile()) return { ok: false, state: 'cannot-read', reason: 'not a regular file' };
+    if (fst.size > MAX_BLOB_BYTES) return { ok: false, state: 'oversized' };
+    const buf = Buffer.alloc(Math.min(fst.size, MAX_BLOB_BYTES));
+    const n = fs.readSync(fd, buf, 0, buf.length, 0);
+    return { ok: true, text: buf.subarray(0, n).toString('utf8'), mtimeMs: fst.mtimeMs };
+  } catch {
+    return { ok: false, state: 'cannot-read', reason: 'unavailable' };
+  } finally {
+    try { fs.closeSync(fd); } catch { /* already closed */ }
+  }
+}
+
+/**
+ * Validate one row. Returns null when the row itself is malformed (which makes
+ * the whole blob invalid — a row without a value is a shape violation, not a
+ * decoration). An UNRECOGNIZED status is not a violation: it renders as `dark`,
+ * because a producer naming a state ccr doesn't know must never come out green.
+ * @param {any} r
+ * @returns {{ label: string, value: string, status: string, detail: string|null, spark: number[]|null }|null}
+ */
+function validateRow(r) {
+  if (!r || typeof r !== 'object' || Array.isArray(r)) return null;
+  if (!isStr(r.label) || !isStr(r.value) || !isStr(r.status)) return null;
+
+  // Spark is DECORATION, so it degrades locally: a non-conforming spark drops
+  // the sparkline and keeps the row. Ruled 2026-08-02 — a decoration never
+  // costs more than itself, the same principle as clamping an overlong field.
+  /** @type {number[]|null} */
+  let spark = null;
+  if (Array.isArray(r.spark) && r.spark.length && r.spark.length <= MAX_SPARK
+    && r.spark.every((/** @type {any} */ n) => typeof n === 'number' && Number.isFinite(n))) {
+    spark = r.spark.slice();
+  }
+
+  return {
+    label: display(r.label),
+    value: display(r.value),
+    status: ROW_STATUSES.has(r.status) ? r.status : 'dark',
+    detail: isStr(r.detail) ? display(r.detail) : null,
+    spark,
+  };
+}
+
+/**
+ * Turn a parsed blob into a validated v1 blob, or name the single failure.
+ * Split out from the file read so it is directly testable and so the render
+ * path can never reach a shape that skipped it.
+ * @param {any} input
+ * @returns {{ state: 'ok', blob: any } | { state: 'invalid' }
+ *           | { state: 'unsupported', version: number|null } | { state: 'oversized-rows' }}
+ */
+function validateBlob(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return { state: 'invalid' };
+
+  // Version first: an unrecognized `v` is its own named state, so it must be
+  // decided before any other field can call the blob "invalid".
+  if (!Number.isInteger(input.v)) return { state: 'invalid' };
+  if (input.v !== BLOB_VERSION) return { state: 'unsupported', version: input.v };
+
+  if (!isStr(input.tool) || !isStr(input.title) || !isStr(input.status)) return { state: 'invalid' };
+  if (input.status !== 'ok' && input.status !== 'broken') return { state: 'invalid' };
+
+  const basis = input.basis;
+  if (!basis || typeof basis !== 'object' || Array.isArray(basis)) return { state: 'invalid' };
+  if (!isStr(basis.label) || !isStr(basis.at)) return { state: 'invalid' };
+
+  // A broken blob must carry a non-empty message. Without one it would render
+  // as a failure with nothing to say, which is indistinguishable from a bug in
+  // ccr — so it is invalid rather than a silent half-render.
+  const broken = input.status === 'broken';
+  if (broken && !(isStr(input.message) && input.message.trim())) return { state: 'invalid' };
+
+  if (!Array.isArray(input.rows)) return { state: 'invalid' };
+  if (input.rows.length > MAX_ROWS) return { state: 'oversized-rows' };
+
+  /** @type {any[]} */
+  const rows = [];
+  // A broken blob's rows are IGNORED per the contract — not validated, not
+  // rendered. Validating them anyway would let a stray row turn a producer's
+  // honest failure report into "invalid", burying the message it exists to show.
+  if (!broken) {
+    for (const r of input.rows) {
+      const row = validateRow(r);
+      if (!row) return { state: 'invalid' };
+      rows.push(row);
+    }
+  }
+
+  return {
+    state: 'ok',
+    blob: {
+      v: BLOB_VERSION,
+      tool: display(input.tool),
+      title: display(input.title),
+      status: input.status,
+      basis: { label: display(basis.label), at: display(basis.at) },
+      message: isStr(input.message) ? display(input.message) : null,
+      rows,
+    },
+  };
+}
+
+/**
+ * The whole pipeline for one configured pane, once per tick.
+ * @param {string} file absolute path from config
+ * @param {{ now?: number }} [opts]
+ * @returns {{ state: string, blob?: any, version?: number|null, reason?: string, ageMs?: number }}
+ */
+function loadPaneBlob(file, opts = {}) {
+  const read = readBlobFile(file);
+  if (!read.ok) {
+    // `strict` is off in jsconfig.json, and without strictNullChecks TypeScript
+    // will not narrow this union by its boolean `ok` discriminant — the whole
+    // union survives into this branch. So name the failure shape once here
+    // instead of re-testing it at runtime: the runtime predicate stays `ok`,
+    // which is the property readBlobFile actually guarantees, and this replaces
+    // the `any` cast that was already covering the same gap for `reason`.
+    const fail = /** @type {{ ok: false, state: string, reason?: string }} */ (read);
+    return fail.state === 'cannot-read'
+      ? { state: 'cannot-read', reason: fail.reason }
+      : { state: fail.state };
+  }
+  if (!read.text.trim()) return { state: 'waiting' };
+
+  let parsed;
+  try { parsed = JSON.parse(read.text); } catch { return { state: 'unreadable' }; }
+
+  const now = opts.now != null ? opts.now : Date.now();
+  const ageMs = Math.max(0, now - read.mtimeMs);
+
+  const v = validateBlob(parsed);
+  if (v.state === 'ok') return { state: 'ok', blob: v.blob, ageMs };
+  if (v.state === 'unsupported') return { state: 'unsupported', version: v.version, ageMs };
+  if (v.state === 'oversized-rows') return { state: 'oversized', ageMs };
+  return { state: 'invalid', ageMs };
+}
+
+module.exports = {
+  loadPaneBlob, validateBlob, readBlobFile,
+  BLOB_VERSION, MAX_BLOB_BYTES, MAX_ROWS, MAX_FIELD_CHARS, MAX_SPARK, ROW_STATUSES,
+};

package/src/pane-config.js

@@ -0,0 +1,109 @@
+// @ts-check
+'use strict';
+// src/pane-config.js — where the list of pane blob paths comes from.
+//
+// RULED 2026-08-02 (the question left open since session e2994e0d):
+//
+//   Location: $XDG_CONFIG_HOME/ccr/config.json, defaulting to
+//   ~/.config/ccr/config.json. Overridable by CCR_CONFIG for tests and for
+//   users who keep dotfiles elsewhere.
+//
+//   NOT ccr's state dir (~/.ccr): that holds state ccr writes, and mixing
+//   user-authored configuration into a directory the program rewrites invites
+//   exactly one accident — clobbering it. NOT repo-local, ever: a config file
+//   discovered by walking up from the working directory would let anyone who
+//   can land a PR add a pane path to a teammate's sidecar. That is the same
+//   reasoning that removed configurable prompt files (see the contract's
+//   ruling log); config is the user's, and only the user's.
+//
+//   Format: JSON. ccr already parses JSON at every ingestion point, so this
+//   adds no new parser and no new attack surface, and the verifier discipline
+//   (whitelist-construct, types checked not coerced, total function) applies
+//   here unchanged. A bespoke line format would need all of that written again.
+//
+//   Shape (v1):
+//     { "panes": [ { "path": "~/code/app/.gherkin-trace/sidecar.json" } ] }
+//
+//   Entries are OBJECTS rather than bare strings so a later optional key is an
+//   additive change rather than a format break. Order is significant (it is the
+//   cycle order). Two entries naming the same path are two panes, per the
+//   contract — this never de-duplicates.
+//
+// Config is trusted more than a blob (the user wrote it) but is still parsed
+// defensively: a malformed config yields NO panes rather than throwing into
+// the draw loop. The sidecar's own panel must survive a typo in a config file.
+
+const path = require('node:path');
+const os = require('node:os');
+const { readTextCapped } = require('./safe-read');
+
+/** Config is small; this is a sanity bound, not a policy. */
+const MAX_CONFIG_BYTES = 64 * 1024;
+
+/**
+ * The config file path, without touching the filesystem.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string}
+ */
+function configPath(env) {
+  const e = env || process.env;
+  if (e.CCR_CONFIG) return e.CCR_CONFIG;
+  const xdg = e.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(xdg, 'ccr', 'config.json');
+}
+
+/**
+ * Expand a leading `~`, then resolve relative paths against `baseDir` — the
+ * config file's own directory, per the contract ("a relative path resolves
+ * against the config file's directory"). Resolving against the CWD instead
+ * would make a pane's identity depend on where the sidecar happened to start.
+ * @param {string} p
+ * @param {string} baseDir
+ * @param {string} home
+ * @returns {string}
+ */
+function resolvePanePath(p, baseDir, home) {
+  let out = p;
+  if (out === '~') out = home;
+  else if (out.startsWith('~/')) out = path.join(home, out.slice(2));
+  return path.resolve(baseDir, out);
+}
+
+/**
+ * Load the configured pane list. Never throws: a missing, unreadable, or
+ * malformed config is "no panes configured", which renders as the plain
+ * economy sidebar exactly as before this feature existed.
+ *
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {{ panes: Array<{ path: string, source: string }>, configPath: string }}
+ *   `path` is absolute and ready to read; `source` is the string the user wrote
+ *   (what error states name, so the message matches their config, not ours).
+ */
+function loadPaneConfig(opts = {}) {
+  const env = opts.env || process.env;
+  const home = opts.home || os.homedir();
+  const file = configPath(env);
+  const empty = { panes: [], configPath: file };
+
+  const raw = readTextCapped(file, MAX_CONFIG_BYTES);
+  if (raw == null || !raw.trim()) return empty;
+
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return empty; }
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.panes)) return empty;
+
+  const baseDir = path.dirname(file);
+  /** @type {Array<{ path: string, source: string }>} */
+  const panes = [];
+  for (const entry of parsed.panes) {
+    // Whitelist-construct: read the one field v1 names, off a fresh object.
+    // Never spread the entry — same rule the blob verifier follows.
+    if (!entry || typeof entry !== 'object' || typeof entry.path !== 'string') continue;
+    const source = entry.path;
+    if (!source.trim()) continue;
+    panes.push({ path: resolvePanePath(source, baseDir, home), source });
+  }
+  return { panes, configPath: file };
+}
+
+module.exports = { loadPaneConfig, configPath, resolvePanePath, MAX_CONFIG_BYTES };

package/src/rate-limits.js

@@ -16,10 +16,20 @@ 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 = {
+//
+// NULL PROTOTYPE, deliberately: bucket names arrive from the status JSON, so a
+// bucket named `toString`, `constructor`, or `__proto__` must MISS this table
+// and fall through to the heuristics below. A plain object literal inherits
+// those names from Object.prototype and hands back a function, whose `.label`
+// is undefined — so labelFor would return undefined while its own contract
+// promises a string. That only stayed harmless because every consumer happens
+// to write `wd.label || wd.key`; a consumer trusting the declared type would
+// break. Structural fix rather than a guard at each lookup.
+/** @type {Record<string, { label: string, windowMinutes: number }>} */
+const KNOWN = Object.assign(Object.create(null), {
   five_hour: { label: '5h', windowMinutes: FIVE },
   seven_day: { label: 'weekly', windowMinutes: WEEK },
-};
+});
 
 /** @param {string} key → 'Sonnet' | 'Opus' | 'Haiku' | null */
 function modelScope(key) {

package/src/render/economy.js

@@ -28,7 +28,9 @@ function wallRow(/** @type {any} */ row, /** @type {any} */ L, /** @type {boolea
   const dotColor = row.resetsFirst ? green : bandColor[b];
   const dot = (row.binding && b === 'imminent') ? flash(tick, '●') : dotColor('●');
 
-  const labelTxt = row.label.padEnd(labelW);
+  // Truncate as well as pad: labelW is capped, so a longer label must be cut to
+  // the column rather than pushing every sibling row out of alignment.
+  const labelTxt = (row.label.length > labelW ? row.label.slice(0, labelW - 1) + '…' : 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.
@@ -59,7 +61,13 @@ function renderEconomy(view, opts = {}) {
   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));
+  // Cap the label column. `labelW` multiplies: every row pads to it, so cost is
+  // rows × longest-label, and BOTH come from the snapshot's rate_limits keys. A
+  // planted file with many buckets and one very long key built a string large
+  // enough to throw RangeError and blank the panel — an amplifier, not a leak,
+  // but it costs the whole display. 18 columns fits every real bucket name.
+  const LABEL_MAX = 18;
+  const labelW = Math.min(LABEL_MAX, Math.max(8, ...rows.map((/** @type {any} */ r) => r.label.length)));
 
   // HERO
   if (!rows.length) {

package/src/render/pane.js

@@ -0,0 +1,186 @@
+// @ts-check
+'use strict';
+// src/render/pane.js — draw one external tool pane from a VALIDATED blob.
+// Contract: docs/PANE-CONTRACT.md § ccr (consumer) obligations.
+//
+// This renderer only ever sees output from src/pane-blob.js, so it does no
+// validation and no sanitizing of its own: every string reaching it has already
+// been stripped and truncated at the choke point. It does clamp to the cell,
+// which is layout, not safety.
+//
+// The honesty rules live here, and they are the reason the pane is worth
+// looking at: `dark` renders as visibly not-green, `off` renders as present-but
+// -disabled, a broken blob shows its producer's message instead of stale rows,
+// hidden rows collapse into a line that inherits the WORST status they carried,
+// and every pane — healthy or not — carries its tool, its basis, and its age.
+
+const { dim, bold, green, red, yellow, cyan, clampVisible } = require('./shared');
+const { stripControl } = require('../sanitize');
+
+/** Per-status marker. `dark` must never be green and never blank; `off` is dim. */
+const MARKERS = {
+  ok: () => green('●'),
+  warn: () => yellow('●'),
+  alert: () => red('●'),
+  dark: () => cyan('◌'),   // hollow: "cannot tell", visibly not a light
+  off: () => dim('·'),     // present, deliberately disabled
+};
+
+/** Worst-first precedence for the overflow line (contract § in-pane overflow). */
+const SEVERITY = ['alert', 'dark', 'warn', 'ok', 'off'];
+
+const SPARK_GLYPHS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+
+/**
+ * File write age on the contract's unit ladder: Xs / Xm / Xh / Xd.
+ * @param {number} ms
+ * @returns {string}
+ */
+function writeAge(ms) {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+/**
+ * Normalize a row's spark to its OWN min-max (never a cross-row or cross-run
+ * scale — that would make one row's shape depend on another's data).
+ * @param {number[]} spark
+ * @returns {string}
+ */
+function sparkline(spark) {
+  const lo = Math.min(...spark);
+  const hi = Math.max(...spark);
+  const span = hi - lo;
+  return spark.map((n) => {
+    // A flat series has no shape to show; put it on the floor rather than
+    // inventing a peak by dividing by zero.
+    const idx = span === 0 ? 0 : Math.round(((n - lo) / span) * (SPARK_GLYPHS.length - 1));
+    return SPARK_GLYPHS[Math.max(0, Math.min(SPARK_GLYPHS.length - 1, idx))];
+  }).join('');
+}
+
+/** @param {string} status */
+const marker = (status) => (MARKERS[/** @type {keyof MARKERS} */ (status)] || MARKERS.dark)();
+
+/**
+ * The chrome every pane carries, in every state. `tool` and `basis` are what
+ * make a claim attributable; the age is what makes it dateable. A pane missing
+ * any of them manufactures currency, which is why they are not optional even on
+ * the error states.
+ * @param {{ title?: string, tool?: string, basis?: any, ageMs?: number, position?: string }} p
+ * @returns {string[]}
+ */
+function chromeLines(p) {
+  const head = bold(p.title || 'pane') + (p.tool ? dim('  ' + p.tool) : '')
+    + (p.position ? dim('   ' + p.position) : '');
+  const lines = [head];
+  const bits = [];
+  // basis.at is OPAQUE — displayed verbatim, never parsed. Currency comes from
+  // the file's mtime below, not from anything the producer wrote.
+  if (p.basis && p.basis.label) bits.push(p.basis.label);
+  if (p.basis && p.basis.at) bits.push(p.basis.at);
+  if (p.ageMs != null) bits.push(`blob written ${writeAge(p.ageMs)} ago`);
+  if (bits.length) lines.push('  ' + dim(bits.join(' · ')));
+  return lines;
+}
+
+/**
+ * Render one row: marker, label, value, then optional spark and detail.
+ * @param {any} row
+ * @param {number} labelW
+ * @returns {string}
+ */
+function rowLine(row, labelW) {
+  // Cut by CODE POINT: slicing UTF-16 units splits an astral character in half
+  // and emits a lone surrogate — the same bug clampVisible documents fixing,
+  // and this text is untrusted blob content.
+  const cps = [...row.label];
+  const label = cps.length > labelW ? cps.slice(0, labelW - 1).join('') + '…' : row.label;
+  const body = '  ' + marker(row.status) + ' ' + label.padEnd(labelW) + '  '
+    + (row.status === 'off' ? dim(row.value) : row.value);
+  const spark = row.spark ? '  ' + cyan(sparkline(row.spark)) : '';
+  const detail = row.detail ? dim('   ' + row.detail) : '';
+  return body + spark + detail;
+}
+
+/**
+ * Render a validated pane blob, or a named non-healthy state, as a whole pane.
+ *
+ * Error states name the configured PATH and nothing else — never file bytes,
+ * never a parser message, because a parser message quotes the input that caused
+ * it and the input is exactly what must not reach the terminal.
+ *
+ * @param {{ state: string, blob?: any, version?: number|null, reason?: string, ageMs?: number }} res
+ *   the verifier's result for this pane
+ * @param {{ source: string, position?: string, width?: number, maxRows?: number }} opts
+ *   `source` is the path AS THE USER WROTE IT in config — error states quote
+ *   their config, not ccr's resolution of it.
+ * @returns {string}
+ */
+function renderPane(res, opts) {
+  const width = opts.width && opts.width > 0 ? opts.width : 48;
+  const src = opts.source;
+  /** @type {string[]} */
+  let lines;
+
+  if (res.state === 'ok' && res.blob) {
+    const b = res.blob;
+    lines = chromeLines({ title: b.title, tool: b.tool, basis: b.basis, ageMs: res.ageMs, position: opts.position });
+    lines.push('');
+
+    if (b.status === 'broken') {
+      // Confession, not stale health: the message, prominently, with the chrome.
+      // Rows are ignored — showing them would present data the producer has just
+      // told us it could not stand behind.
+      lines.push('  ' + red(bold('broken')));
+      lines.push('  ' + (b.message || ''));
+    } else if (!b.rows.length) {
+      lines.push('  ' + dim('no rows reported'));
+    } else {
+      const labelW = Math.min(20, Math.max(6, ...b.rows.map((/** @type {any} */ r) => r.label.length)));
+      // Reserve a line for the overflow notice only when one is actually needed.
+      const budget = opts.maxRows && opts.maxRows > 0 ? opts.maxRows : b.rows.length;
+      const overflow = b.rows.length > budget;
+      const shownCount = overflow ? Math.max(0, budget - 1) : b.rows.length;
+      for (const r of b.rows.slice(0, shownCount)) lines.push(rowLine(r, labelW));
+      if (overflow) {
+        const hidden = b.rows.slice(shownCount);
+        // The collapsed line inherits the WORST hidden status, so a hidden
+        // `dark` row still reads as darkness rather than vanishing into a count.
+        const worst = SEVERITY.find((s) => hidden.some((/** @type {any} */ r) => r.status === s)) || 'off';
+        lines.push('  ' + marker(worst) + ' ' + dim(`+${hidden.length} more`));
+      }
+    }
+  } else {
+    /** @type {Record<string, string>} */
+    const named = {
+      waiting: 'waiting for first blob',
+      unreadable: 'blob unreadable',
+      invalid: 'blob invalid',
+      oversized: 'blob oversized',
+      'cannot-read': `cannot read blob${res.reason ? ' (' + res.reason + ')' : ''}`,
+      unsupported: `unsupported blob version ${res.version == null ? '?' : res.version}`,
+    };
+    // Age chrome belongs on the error states too. A pane stuck on `invalid` for
+    // three days must not look like one that broke a second ago — that is the
+    // "manufactures currency" failure obligation 3 names, and dropping the age
+    // here contradicted this file's own docstring. `waiting`/`cannot-read` have
+    // no readable file and so legitimately have no age.
+    lines = chromeLines({ title: 'pane', position: opts.position, ageMs: res.ageMs });
+    lines.push('');
+    lines.push('  ' + (res.state === 'waiting' ? dim(named.waiting) : yellow(named[res.state] || 'blob unavailable')));
+    // The configured path is USER-authored, not blob-authored — but it is still
+    // text from a file on disk, and a config carrying an escape sequence would
+    // otherwise put it straight on the terminal from six different states.
+    lines.push('  ' + dim(String(stripControl(src) ?? '')));
+  }
+
+  return lines.map((l) => clampVisible(l, width)).join('\n');
+}
+
+module.exports = { renderPane, writeAge, sparkline, SEVERITY, MARKERS };