claude-code-runrate 0.2.4 → 0.4.0

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

package/src/render/shared.js

@@ -21,12 +21,61 @@ function bar(/** @type {number} */ p, w = 10) {
   return '▓'.repeat(f) + '░'.repeat(w - f);
 }
 
+// Code-point ranges a terminal renders two columns wide (East Asian Wide and
+// Fullwidth, per UAX #11), condensed to the blocks that actually turn up in a
+// file path, a model name, or a tool argument: CJK, Hangul, Kana, fullwidth
+// forms, and the emoji planes. Not exhaustive — it does not need to be. Every
+// range here converts a "counted 1, occupies 2" error, which overflows the pane
+// and soft-wraps, into a correct count.
+const WIDE_RANGES = [
+  [0x1100, 0x115f],   // Hangul Jamo
+  [0x2e80, 0x303e],   // CJK radicals, Kangxi, CJK symbols/punctuation
+  [0x3041, 0x33ff],   // Kana, Bopomofo, Hangul Compat Jamo, CJK compat
+  [0x3400, 0x4dbf],   // CJK Ext A
+  [0x4e00, 0x9fff],   // CJK Unified
+  [0xa000, 0xa4cf],   // Yi
+  [0xac00, 0xd7a3],   // Hangul syllables
+  [0xf900, 0xfaff],   // CJK compat ideographs
+  [0xfe30, 0xfe6f],   // CJK compat forms, small form variants
+  [0xff00, 0xff60],   // Fullwidth forms
+  [0xffe0, 0xffe6],   // Fullwidth signs
+  [0x1f300, 0x1f64f], // Emoji: symbols/pictographs, emoticons
+  [0x1f900, 0x1f9ff], // Supplemental symbols/pictographs
+  [0x20000, 0x3fffd], // CJK Ext B+ (SIP)
+];
+
+/**
+ * Terminal columns occupied by one code point: 2 for East Asian Wide/Fullwidth,
+ * 0 for combining marks (they stack onto the previous glyph), else 1.
+ * @param {number} cp
+ * @returns {0|1|2}
+ */
+function charWidth(cp) {
+  // Combining diacriticals, and the Hebrew/Arabic/Devanagari combining blocks
+  // most likely to appear in fetched text. Zero-width formatting characters are
+  // already gone by here (src/sanitize.js strips them at ingestion).
+  if ((cp >= 0x0300 && cp <= 0x036f) || (cp >= 0x0483 && cp <= 0x0489)
+    || (cp >= 0x0591 && cp <= 0x05bd) || (cp >= 0x0610 && cp <= 0x061a)
+    || (cp >= 0x064b && cp <= 0x065f) || (cp >= 0x0900 && cp <= 0x0903)
+    || (cp >= 0x1ab0 && cp <= 0x1aff) || (cp >= 0x20d0 && cp <= 0x20f0)
+    || (cp >= 0xfe00 && cp <= 0xfe0f)) return 0;   // incl. variation selectors
+  for (const [lo, hi] of WIDE_RANGES) if (cp >= lo && cp <= hi) return 2;
+  return 1;
+}
+
 /**
- * Clamp one line to `cols` visible columns: SGR escapes (`\x1b[…m`) pass through
- * with zero width, printable chars count as 1. Appends a reset if it had to cut,
- * so a severed colour run doesn't bleed into the cleared tail. Prevents the soft
- * wrap that corrupts the sidecar's cursor-home redraw in a narrow pane. A
+ * Clamp one line to `cols` visible COLUMNS: SGR escapes (`\x1b[…m`) pass through
+ * with zero width; every other character counts for the columns a terminal will
+ * actually give it (see charWidth). Appends a reset if it had to cut, so a
+ * severed colour run doesn't bleed into the cleared tail. Prevents the soft wrap
+ * that corrupts the sidecar's cursor-home redraw in a narrow pane. A
  * non-positive `cols` (e.g. a non-TTY where columns is undefined) is a no-op.
+ *
+ * Iterates by CODE POINT, not by UTF-16 unit: the old per-unit walk counted a
+ * CJK glyph as one column (so 8 of them filled a 16-column pane and wrapped —
+ * the exact corruption this function exists to prevent) and could cut an astral
+ * character in half, emitting a lone surrogate.
+ *
  * @param {string} line
  * @param {number} [cols]
  * @returns {string}
@@ -41,17 +90,24 @@ function clampVisible(line, cols) {
     sgr.lastIndex = i;
     const m = sgr.exec(line);
     if (m) { out += m[0]; i = sgr.lastIndex; continue; }
-    if (width >= cols) return out + '\x1b[0m';
-    out += line[i];
-    width += 1;
-    i += 1;
+    const cp = /** @type {number} */ (line.codePointAt(i));
+    const ch = String.fromCodePoint(cp);
+    const w = charWidth(cp);
+    // Cut BEFORE a character that would not fit whole — a wide glyph straddling
+    // the last column is what wraps the line.
+    if (width + w > cols) return out + '\x1b[0m';
+    out += ch;
+    width += w;
+    i += ch.length;
   }
   return out;
 }
 
 function tok(/** @type {number|null} */ n) {
-  if (n == null) return '?';
-  if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M';
+  if (n == null || !Number.isFinite(n)) return '?';
+  // 999_500 rounds to 1000K, which is a unit the scale never uses — promote it
+  // to 1.0M rather than printing a fourth digit.
+  if (n >= 999500) return (n / 1e6).toFixed(1) + 'M';
   if (n >= 1e3) return Math.round(n / 1e3) + 'K';
   return String(Math.round(n));
 }
@@ -84,4 +140,52 @@ function fmtReset(/** @type {number|null} */ min) {
   return `${m}m`;
 }
 
-module.exports = { e, dim, bold, green, red, yellow, cyan, flash, pctColor, bar, clampVisible, tok, fmtMins, fmtReset };
+/**
+ * Terminal columns a PLAIN string occupies — the same accounting `clampVisible`
+ * does, exposed for the callers that must budget space before they build a line
+ * rather than clamp one afterwards. No SGR handling: the strings measured here
+ * are display text before any colour is applied.
+ * @param {string} s
+ * @returns {number}
+ */
+function visibleWidth(s) {
+  let w = 0;
+  for (const ch of s) w += charWidth(/** @type {number} */ (ch.codePointAt(0)));
+  return w;
+}
+
+/**
+ * Fit plain text into `cols` columns, marking the cut with an ellipsis so a
+ * shortened value never reads as a complete one. Cutting is by code point and
+ * by COLUMN (a wide glyph costs two), and the ellipsis is inside the budget —
+ * the result is never wider than `cols`.
+ *
+ * Distinct from `clampVisible`, which is the hard safety net applied to a
+ * finished line: this one is composition, so the caller can lay out around a
+ * value it knows will fit. Returns '' for a non-positive budget.
+ *
+ * @param {string} s
+ * @param {number} cols
+ * @returns {string}
+ */
+function ellipsize(s, cols) {
+  if (!(typeof cols === 'number' && cols > 0)) return '';
+  if (visibleWidth(s) <= cols) return s;
+  // One column is spent on the ellipsis, so the text gets cols-1. At cols === 1
+  // that leaves nothing, and the ellipsis alone is the honest answer.
+  const budget = cols - 1;
+  let out = '';
+  let w = 0;
+  for (const ch of s) {
+    const cw = charWidth(/** @type {number} */ (ch.codePointAt(0)));
+    if (w + cw > budget) break;
+    out += ch;
+    w += cw;
+  }
+  return out + '…';
+}
+
+module.exports = {
+  e, dim, bold, green, red, yellow, cyan, flash, pctColor, bar, clampVisible, tok, fmtMins, fmtReset,
+  charWidth, visibleWidth, ellipsize,
+};

package/src/render/statusline.js

@@ -6,14 +6,50 @@
 const { windowEstimate, binding } = require('../burn');
 const { fmtMins } = require('./shared');
 
+/**
+ * Deterministic middle ellipsis: the same input shortens the same way at
+ * every glance — the anti-marquee rule. (Animation was rejected outright:
+ * Claude re-renders this line per turn, not on a clock, so anything animated
+ * freezes exactly when the user is idle and orienting.)
+ * @param {string} s @param {number} max
+ */
+function midEllipsis(s, max) {
+  if (s.length <= max) return s;
+  const head = Math.ceil((max - 1) / 2);
+  const tail = max - 1 - head;
+  return s.slice(0, head) + '…' + (tail > 0 ? s.slice(-tail) : '');
+}
+
 /**
  * @param {any} view normalized economy data
- * @returns {string} one line, e.g. "Sonnet 4.6 · weekly · Sonnet ~5h · ctx 15% · $2.50"
+ * @param {{ name?: string|null, location?: string|null, cols?: number }} [identity]
+ *   The instance identity, shown FIRST so terminal end-truncation eats meters,
+ *   never orientation. The location half is LIVE (follows a mid-session cd)
+ *   and appears only when it differs from the name — "notes @ notes" says
+ *   nothing twice. `cols` bounds the identity: the location stays whole, the
+ *   name takes the ellipsis.
+ * @returns {string} one line, e.g. "a-is-awesome @ ccr · Opus 4.8 · 5h ~2h · ctx 15% · $2.50"
  */
-function renderStatusline(view) {
+function renderStatusline(view, identity = {}) {
   const parts = [];
+  const name = identity.name || null;
+  const loc = identity.location || null;
+  if (name) {
+    const withLoc = loc && loc !== name;
+    let shownName = name;
+    if (identity.cols && withLoc) {
+      const budget = identity.cols - (' @ '.length + (loc ? loc.length : 0));
+      if (name.length > budget) shownName = midEllipsis(name, Math.max(5, budget));
+    } else if (identity.cols && name.length > identity.cols) {
+      shownName = midEllipsis(name, Math.max(5, identity.cols));
+    }
+    parts.push(withLoc ? `${shownName} @ ${loc}` : shownName);
+  }
   if (view.model) parts.push(view.model);
 
+  // Annotated because Array.isArray does not narrow an `any`: without this the
+  // whole chain below decays to `any` and the row callbacks lose their types.
+  /** @type {any[]} */
   const windows = Array.isArray(view.windows) ? view.windows : [];
   if (!windows.length) {
     parts.push('API · no limits');
@@ -30,8 +66,13 @@ function renderStatusline(view) {
     const b = binding(live);
     if (b && b.minutesLeft != null) {
       const row = rows.find((r) => r.key === b.window);
-      const imminent = b.minutesLeft <= 30 ? '⚠ ' : '';
-      parts.push(`${imminent}${row ? row.label : b.window} ~${fmtMins(b.minutesLeft)}`);
+      if (b.minutesLeft <= 30) {
+        // "About to hit the wall" outranks orientation for the next thing the
+        // user types: the warning jumps ahead of everything, identity included.
+        parts.unshift(`⚠ ${row ? row.label : b.window} ~${fmtMins(b.minutesLeft)}`);
+      } else {
+        parts.push(`${row ? row.label : b.window} ~${fmtMins(b.minutesLeft)}`);
+      }
     } else {
       parts.push('within limits');
     }

package/src/safe-read.js

@@ -0,0 +1,82 @@
+// @ts-check
+'use strict';
+// src/safe-read.js — bounded, non-blocking reads of files ccr does not control.
+//
+// docs/PANE-CONTRACT.md states this rule for external pane blobs ("Safe reads":
+// lstat, regular file only, size cap enforced before the read completes). The
+// rule is not blob-specific — it belongs at every point where the sidecar reads
+// a file some other process writes, which includes ccr's OWN inputs:
+// last-status.json and the heartbeat file both live in a directory anything
+// running as the user can write.
+//
+// Two failure modes it closes, both verified against the pre-fix sidecar:
+//
+//   A FIFO at the path. `readFileSync` on a fifo BLOCKS until a writer appears.
+//   The sidecar's loop is single-threaded and synchronous, so one mkfifo froze
+//   the whole panel forever — no render, no heartbeat, no recovery. `lstat`
+//   answers "is this a regular file?" without opening anything, so the block
+//   never happens.
+//
+//   An unbounded file. The reader had no cap at all (the WRITER caps itself at
+//   1 MB, which says nothing about a planted file). A large planted snapshot
+//   drove quadratic label padding into a RangeError and blanked the panel.
+//
+// `lstat` also means a SYMLINK is refused rather than followed: this is state,
+// not configuration, and nothing legitimate links it elsewhere.
+
+const fs = require('node:fs');
+
+/** Default cap. Generous for a status snapshot (a real one is ~1-2 KB). */
+const DEFAULT_MAX_BYTES = 256 * 1024;
+
+/**
+ * Read a file as UTF-8 if — and only if — it is a regular file no larger than
+ * `maxBytes`. Returns null for every other case (missing, fifo, socket, device,
+ * symlink, directory, too large, unreadable). Never throws, never blocks.
+ *
+ * The size is re-checked from the open descriptor, not just the lstat: the file
+ * can be replaced between the two calls, and the fstat describes the bytes we
+ * actually hold. The read is capped regardless, so a file that grows after the
+ * check still yields at most `maxBytes`.
+ *
+ * @param {string} file
+ * @param {number} [maxBytes]
+ * @returns {string|null}
+ */
+function readTextCapped(file, maxBytes = DEFAULT_MAX_BYTES) {
+  const buf = readBytesCapped(file, maxBytes);
+  return buf === null ? null : buf.toString('utf8');
+}
+
+/**
+ * The binary form of the same rule, for files that are not text: the git pane
+ * reads `.git/index`, object files and packfiles, none of which survive a
+ * UTF-8 round trip. Identical guards — lstat first (regular file only, so a
+ * fifo never blocks and a symlink is never followed), size re-checked from the
+ * open descriptor, capped read, never throws.
+ *
+ * @param {string} file
+ * @param {number} [maxBytes]
+ * @returns {Buffer|null}
+ */
+function readBytesCapped(file, maxBytes = DEFAULT_MAX_BYTES) {
+  let st;
+  try { st = fs.lstatSync(file); } catch { return null; }
+  if (!st.isFile() || st.size > maxBytes) return null;
+
+  let fd;
+  try { fd = fs.openSync(file, 'r'); } catch { return null; }
+  try {
+    const fst = fs.fstatSync(fd);
+    if (!fst.isFile() || fst.size > maxBytes) return null;
+    const buf = Buffer.alloc(Math.min(fst.size, maxBytes));
+    const read = fs.readSync(fd, buf, 0, buf.length, 0);
+    return buf.subarray(0, read);
+  } catch {
+    return null;
+  } finally {
+    try { fs.closeSync(fd); } catch { /* already closed */ }
+  }
+}
+
+module.exports = { readTextCapped, readBytesCapped, DEFAULT_MAX_BYTES };

package/src/sanitize.js

@@ -17,15 +17,56 @@
 // alone is NOT sufficient — it escapes C0 but leaves DEL/C1 bytes raw — which is
 // exactly why we sanitize at ingestion rather than rely on the serializer.)
 
-// C0 controls (00-1F, incl. ESC/newline/tab), DEL (7F), and C1 controls (80-9F).
-const CONTROL_RE = /[\x00-\x1f\x7f-\x9f]/g;
+// The stripped set, as code-point ranges. Spelled numerically and assembled at
+// runtime rather than written as a literal character class: every character in
+// here is invisible or display-altering, so a literal class would be unreadable
+// in a diff — and could hide an added character in plain sight, in the very code
+// meant to remove such characters.
+const CONTROL_RANGES = [
+  [0x0000, 0x001f], // C0 controls — ESC, newline, tab
+  [0x007f, 0x009f], // DEL, then C1 controls: includes the 8-bit CSI (0x9b) and
+                    //   OSC (0x9d) introducers, not just their ESC-prefixed forms
+  [0x200b, 0x200f], // zero-width space/joiners + LRM/RLM — invisible, so two
+                    //   different byte strings can render identically
+  [0x2028, 0x2029], // line/paragraph separators — a line break by another name
+  [0x202a, 0x202e], // bidi embeddings and overrides
+  [0x2066, 0x2069], // bidi isolates — these two ranges reorder the glyphs a
+                    //   reader sees relative to the bytes actually present:
+                    //   "Trojan Source" (CVE-2021-42574) aimed at a status pane.
+                    //   Legitimate RTL text needs neither; scripts carry their
+                    //   own direction.
+  [0xfeff, 0xfeff], // zero-width no-break space (BOM) — invisible when not leading
+];
+
+const CONTROL_RE = new RegExp(
+  '[' + CONTROL_RANGES.map(([lo, hi]) =>
+    (lo === hi ? String.fromCodePoint(lo) : String.fromCodePoint(lo) + '-' + String.fromCodePoint(hi))
+  ).join('') + ']',
+  'g',
+);
 
 /**
+ * Strip control characters, COERCING any non-nullish input to a string first.
+ *
+ * The coercion is the security-relevant half. Every renderer downstream
+ * concatenates or `String()`s whatever it is handed, so returning a non-string
+ * unchanged does not keep it out of the terminal — it only skips the strip, and
+ * the escape bytes land on screen anyway once something stringifies them. A
+ * JSON file chooses its own value *types*, so "this field is a string" is never
+ * a safe assumption: `{"display_name": ["…"]}` parses just as well as a bare
+ * string, and an array of one string stringifies straight back to that string.
+ * Coerce once, here, at the choke point, rather than trusting a dozen call
+ * sites to remember.
+ *
+ * `null`/`undefined` still pass through, because callers use them as "absent"
+ * (`x || null`, `x != null`) and "null"/"undefined" are not display text.
+ *
  * @param {any} s
- * @returns {any} the string with control chars removed; non-strings pass through
+ * @returns {any} a control-char-free string, or null/undefined unchanged
  */
 function stripControl(s) {
-  return typeof s === 'string' ? s.replace(CONTROL_RE, '') : s;
+  if (s == null) return s;
+  return String(s).replace(CONTROL_RE, '');
 }
 
 module.exports = { stripControl };

package/src/session-log.js

@@ -0,0 +1,116 @@
+// @ts-check
+'use strict';
+// src/session-log.js — the forensic join key and history retention
+// (features/instance-persistence.feature).
+//
+// One file per session, `session-<sid>.jsonl`, at the container's top level
+// beside `burnlog-<sid>.jsonl` — same key, same lifecycle. TWO-PHASE, ruled
+// on the owner's words ("even partial information allows forensic
+// reconstruction of what happened"): the open record is written the moment
+// the session id first exists — deaths are exactly when writes cannot be
+// trusted to happen — and finalized by whoever sees the death: the exiting
+// process (`ended`) if polite, the sweep (`swept`, stamped with the last
+// heartbeat's mtime — the honest "ended around here") if not. A `swept`
+// marker is itself forensic signal: this session died badly.
+//
+// The join key gets its OWN file, never a line inside the burnlog: the
+// burnlog's size cap halves that file by DROPPING THE HEAD
+// (src/instrument.js capFile), which would silently destroy a head-of-file
+// key at 2MB.
+//
+// RETENTION, ruled shape-independent: content survives 30 full days after
+// its session ends and is gone at 31, counted from last write — and with
+// per-session files, last write IS death (the finalize marker), so file-age
+// pruning needs no date parsing.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RETAIN_DAYS = 31;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** @param {string} sid */
+const clean = (sid) => String(sid || '').replace(/[^A-Za-z0-9_-]/g, '');
+
+/** @param {string} home @param {string} sid */
+function logFile(home, sid) {
+  return path.join(home, '.ccr', `session-${clean(sid)}.jsonl`);
+}
+
+/**
+ * Phase one: the open record, written once, at the first status capture.
+ * @param {string} home
+ * @param {string} sid
+ * @param {{ name?: string|null, profile?: string|null, launch_cwd?: string|null, now?: number }} fields
+ */
+function openEntry(home, sid, fields = {}) {
+  if (!clean(sid)) return;
+  const file = logFile(home, sid);
+  try {
+    if (fs.existsSync(file)) return;
+    const rec = {
+      session_id: clean(sid),
+      name: fields.name || null,
+      profile: fields.profile || null,
+      launch_cwd: fields.launch_cwd || null,
+      started: fields.now != null ? fields.now : Date.now(),
+    };
+    fs.writeFileSync(file, JSON.stringify(rec) + '\n', { mode: 0o600 });
+  } catch { /* best effort — forensics must never break the status line */ }
+}
+
+/**
+ * Phase two: whoever sees the death appends the marker.
+ * @param {string} home
+ * @param {string} sid
+ * @param {{ ended?: number, swept?: number }} marker
+ */
+function finalize(home, sid, marker) {
+  if (!clean(sid)) return;
+  const file = logFile(home, sid);
+  try {
+    if (!fs.existsSync(file)) return; // died before the first tick — nothing to finalize
+    fs.appendFileSync(file, JSON.stringify(marker) + '\n');
+  } catch { /* best effort */ }
+}
+
+/**
+ * Finalize on behalf of an instance dir about to be deleted: the dir's own
+ * captured status is what still knows the session id.
+ * @param {string} home
+ * @param {string} dir the instance's state dir
+ * @param {'ended'|'swept'} how
+ * @param {number} [at]
+ */
+function finalizeFromDir(home, dir, how, at) {
+  try {
+    const raw = fs.readFileSync(path.join(dir, 'last-status.json'), 'utf8');
+    const sid = JSON.parse(raw).session_id;
+    if (!sid) return;
+    finalize(home, sid, { [how]: at != null ? at : Date.now() });
+  } catch { /* no capture — the accepted gap: nothing to join, nothing to debug */ }
+}
+
+/**
+ * The 31-day boundary: history is kept through 30 full days after its
+ * session's end and gone at 31 — burnlogs and session logs alike, whole
+ * files, by last-write mtime.
+ * @param {string} home
+ * @param {{ now?: number }} [opts]
+ */
+function pruneHistory(home, opts = {}) {
+  const now = opts.now != null ? opts.now : Date.now();
+  const root = path.join(home, '.ccr');
+  let names; try { names = fs.readdirSync(root); } catch { return; }
+  for (const n of names) {
+    if (!/^(burnlog|session)-[A-Za-z0-9_-]+\.jsonl$/.test(n)) continue;
+    const p = path.join(root, n);
+    try {
+      const st = fs.lstatSync(p);
+      if (!st.isFile()) continue;
+      if (now - st.mtimeMs >= RETAIN_DAYS * DAY_MS) fs.rmSync(p, { force: true });
+    } catch { /* best effort */ }
+  }
+}
+
+module.exports = { openEntry, finalize, finalizeFromDir, pruneHistory, logFile, RETAIN_DAYS };