claude-code-runrate 0.2.4 → 0.4.0

package/src/launch-win.js

@@ -82,11 +82,15 @@ function resolveProfileState(profile, opts = {}) {
   const env = opts.env || process.env;
   const home = opts.home || os.homedir();
 
+  // The stateDir fallbacks are reachable only when called with neither a slot's
+  // env nor the user's own override — never from the launchers, which refuse an
+  // exhausted allocation before this. They point at slot 1's member dir so no
+  // path here can ever name the container itself as a state dir.
   if (profile) {
     return {
       ccCmd: `ccs ${profile}`,
-      session: env.CCR_SESSION || `ccr-${profile}`,
-      stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr', profile),
+      session: env.CCR_SESSION || 'ccr',
+      stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr', 'instances', '1'),
       instanceDir: path.join(home, '.ccs', 'instances', profile),
       usesCcs: true,
     };
@@ -94,7 +98,7 @@ function resolveProfileState(profile, opts = {}) {
   return {
     ccCmd: env.CC_BIN || 'claude',
     session: env.CCR_SESSION || 'ccr',
-    stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr'),
+    stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr', 'instances', '1'),
     instanceDir: null,
     usesCcs: false,
   };
@@ -179,7 +183,7 @@ function sidecarCols(termCols, fracNum, splitFlag) {
  *
  * @param {{ ccCmd: string, settingsFile: string, stateDir: string,
  *   node: string, ccrJs: string, sidebarPct?: number, sidebarSide?: string,
- *   termCols?: number }} o
+ *   termCols?: number, title?: string }} o
  * @returns {string[]}
  */
 function buildWtArgs(o) {
@@ -200,6 +204,9 @@ function buildWtArgs(o) {
   }
   const frac = sidebarFraction(o.sidebarPct);
   const splitFlag = sidebarSplitFlag(o.sidebarSide);
+  // The tab's ADDRESS ("[profile / ]name") when the instance has one — both
+  // halves allow-listed, so it is wt-arg-safe by construction.
+  const title = o.title || 'Claude';
   const exited = path.win32.join(stateDir, 'exited');
 
   // After Claude exits we drop the sentinel + clean the settings file, then idle
@@ -224,7 +231,7 @@ function buildWtArgs(o) {
   const pane1 = paneCommand(stateDir, sidecarBody);
 
   return [
-    '-w', '0', 'new-tab', '--title', 'Claude', 'cmd', '/c', pane0,
+    '-w', '0', 'new-tab', '--title', title, 'cmd', '/c', pane0,
     ';',
     'split-pane', splitFlag, '-s', frac, 'cmd', '/c', pane1,
   ];
@@ -255,7 +262,8 @@ function defaultWhere(name) {
 }
 
 const inject = require('./settings-inject');
-const { ensureSecureDir } = require('./state-dir');
+const slots = require('./instance-slot');
+const { ensureSecureDir, recordLaunchDir } = require('./state-dir');
 
 /**
  * Fill in real-environment implementations for anything the caller didn't
@@ -283,6 +291,11 @@ function withDefaults(deps) {
     existsDir: deps.existsDir || defaultExistsDir,
     listDir: deps.listDir || defaultListDir,
     ensureDir: deps.ensureDir || ensureSecureDir,
+    recordLaunchDir: deps.recordLaunchDir || recordLaunchDir,
+    allocateSlot: deps.allocateSlot || ((o) => slots.allocateSlot(o)),
+    prepareInstance: deps.prepareInstance
+      || ((/** @type {{slot:number,stateDir:string}} */ s, /** @type {any} */ o) =>
+        require('./instance-name').prepareInstance(s, { ...o, home: deps.home || os.homedir() })),
     removeExited: deps.removeExited || defaultRemoveExited,
     writeSettings: deps.writeSettings || ((s) => inject.writeSettingsFile(s)),
     cleanup: deps.cleanup || ((f) => inject.cleanupSettingsFile(f)),
@@ -347,9 +360,10 @@ function fallbackNoWt(d) {
  *
  * @param {string} [profile]
  * @param {Partial<Deps>} [deps]
+ * @param {{ name?: string|null }} [opts]  explicit --name, already validated
  * @returns {number}
  */
-function run(profile, deps = {}) {
+function run(profile, deps = {}, opts = {}) {
   const d = withDefaults(deps);
 
   // 1. Validate the profile (it lands in paths and a spawned command).
@@ -362,8 +376,18 @@ function run(profile, deps = {}) {
   const wt = d.findWt();
   if (!wt) return fallbackNoWt(d);
 
-  // 3. Resolve profile state + required binaries.
-  const st = resolveProfileState(profile, { env: d.env, home: d.home });
+  // 3. Resolve profile state + required binaries. Every launch first claims a
+  // free instance slot (src/instance-slot.js) so a second window never shares
+  // another's state dir; only an explicit override skips it.
+  const slot = d.allocateSlot({ profile, env: d.env, home: d.home });
+  if (slot && 'exhausted' in slot) {
+    d.err(`ccr: every slot is in use (${slots.MAX_SLOTS} live instances) — close one first\n`);
+    return 1;
+  }
+  // The instance's name, profile record and title — same on every platform.
+  const inst = slot && !('exhausted' in slot)
+    ? d.prepareInstance(slot, { profile, name: opts.name }) : null;
+  const st = resolveProfileState(profile, { env: slots.applySlotEnv(d.env, slot), home: d.home });
   if (st.usesCcs) {
     if (!d.which('ccs')) {
       d.err("ccr: 'ccs' not found on PATH — pass a profile only if CCS is installed.\n");
@@ -385,6 +409,9 @@ function run(profile, deps = {}) {
 
   // 4. Prepare the per-profile state dir; clear a stale sentinel.
   try { d.ensureDir(st.stateDir); } catch { /* best effort */ }
+  // The tab's stable identity for the git pane. Recorded here because only the
+  // launcher knows where ccr was started (src/state-dir.js).
+  try { d.recordLaunchDir(st.stateDir, process.cwd()); } catch { /* best effort */ }
   d.removeExited(st.stateDir);
 
   // 5. Inject statusLine via a temp settings FILE (avoids CLI JSON quoting).
@@ -404,6 +431,7 @@ function run(profile, deps = {}) {
       sidebarPct: Number.isFinite(pct) ? pct : DEFAULT_SIDEBAR_PCT,
       sidebarSide: d.env.CCR_SIDEBAR_SIDE || DEFAULT_SIDEBAR_SIDE,
       termCols: d.cols,
+      title: inst ? inst.title : undefined,
     });
   } catch (e) {
     d.err(`ccr: ${e instanceof Error ? e.message : String(e)}\n`);
@@ -434,6 +462,9 @@ function run(profile, deps = {}) {
  * @property {(dir: string) => boolean} existsDir
  * @property {(dir: string) => string[]} listDir
  * @property {(dir: string) => void} ensureDir
+ * @property {(dir: string, cwd: string) => void} recordLaunchDir
+ * @property {(o: {profile?: string, env: NodeJS.ProcessEnv, home: string}) => ({slot: number, session: string, stateDir: string, attached: boolean}|{exhausted: true}|null)} allocateSlot
+ * @property {(slot: {slot: number, stateDir: string}, o: {profile?: string, name?: string|null}) => {name: string, title: string}} prepareInstance
  * @property {(dir: string) => void} removeExited
  * @property {(settings: object) => string} writeSettings
  * @property {(file: string) => void} cleanup

package/src/liveness.js

@@ -20,6 +20,23 @@ function envStaleMs() {
   return Number.isFinite(v) && v > 0 ? v : null;
 }
 
+/**
+ * Snapshot age for the freshness note. Minutes roll into hours and hours into
+ * days: an overnight-idle pane used to read "updated 1500m ago", which is
+ * accurate and unreadable.
+ * @param {number} ageMs
+ * @returns {string}
+ */
+function fmtAge(ageMs) {
+  const m = Math.floor(ageMs / 60000);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) { const r = m % 60; return r ? `${h}h${String(r).padStart(2, '0')}m` : `${h}h`; }
+  const d = Math.floor(h / 24);
+  const rh = h % 24;
+  return rh ? `${d}d${rh}h` : `${d}d`;
+}
+
 /**
  * @param {{ exited?: boolean, ageMs?: number, staleMs?: number }} input
  * @returns {{ mode: 'ended' | 'live', marker: string | null }}
@@ -32,7 +49,7 @@ function liveness(input) {
 
   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;
+  const marker = ageMs >= staleMs ? `updated ${fmtAge(ageMs)} ago` : null;
   return { mode: 'live', marker };
 }
 

package/src/migrate.js

@@ -0,0 +1,155 @@
+// @ts-check
+'use strict';
+// src/migrate.js — move a 0.3 ccr home to the 0.4 container layout, once,
+// safely (features/instance-migration.feature).
+//
+// There is nothing to relocate but HISTORY: the only persistent content the
+// 0.3 layout ever held was account burn history, misplaced inside profile
+// dirs because the logger wrote to whatever the state dir was. So migration
+// HARVESTS burnlogs to the container's top level, SWEEPS the profile dirs and
+// the loose ephemeral droppings (a dead session's captured status, heartbeat,
+// sentinel), and writes the ".layout" marker LAST — an interrupted migration
+// is indistinguishable from one that has not started, and every move is
+// move-if-present, so the next launch simply completes it.
+//
+// THE GENERAL SAFETY PROPERTY, ruled: if the source is not what migration
+// expects, it STOPS AND CHANGES NOTHING. That is also the entire handling of
+// an entry named "instances" or "profiles" (reserved by the new layout) and
+// of a CCS profile literally named either — declined as real scope ("no other
+// users will have this problem"); the stop makes it fail loudly for free.
+//
+// Runs AT LAUNCH ONLY. `ccr statusline` — invoked headlessly by Claude
+// mid-session — never calls this. Removed at 1.0.0.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const MARKER = '.layout';
+
+// The 0.3 layout's loose per-session droppings — dead state the ephemeral
+// rule says dies. Everything here may appear at the container root (bare
+// launches) or inside a profile dir.
+const DROPPINGS = ['last-status.json', 'launch-cwd', 'exited', 'sidecar-alive', 'slot-owner', 'view-request'];
+
+const BURNLOG_RE = /^burnlog-[A-Za-z0-9_-]+\.jsonl$/;
+// 0.4's own session join key (src/session-log.js). An upgrade while a session
+// is open leaves the new statusline ticking against an unmigrated home, so
+// these appear at the root BEFORE any launch migrates it — already at their
+// final location, they are kept, not a surprise.
+const SESSION_RE = /^session-[A-Za-z0-9_-]+\.jsonl$/;
+// Same allow-list the launcher enforces for profile names.
+const PROFILE_DIR_RE = /^[A-Za-z0-9._-]+$/;
+// Names the new layout owns; their presence in an unmigrated home is exactly
+// the surprise the safety property exists for.
+const RESERVED = new Set(['instances', 'profiles']);
+
+/**
+ * Is a 0.3 session still running in this dir, as far as 0.3 state can say?
+ * The published 0.3 recorded no owning pid, so the freshest signal it left is
+ * the sidecar heartbeat. Refusing on a live heartbeat is the safe direction:
+ * a false "live" delays migration by seconds; a false "dead" would harvest
+ * burnlogs out from under a writing session.
+ * @param {string} dir
+ */
+function legacyLive(dir) {
+  try {
+    if (fs.existsSync(path.join(dir, 'exited'))) return false;
+    return require('./sidecar').sidecarAlive(dir);
+  } catch { return false; }
+}
+
+/**
+ * Move a burnlog to the container root, first-wins on a name collision (the
+ * name carries the Claude session id, so a collision is the same session's
+ * data twice — the copy already at the root is kept).
+ * @param {string} from @param {string} rootDir @param {string} name
+ */
+function harvestBurnlog(from, rootDir, name) {
+  const dest = path.join(rootDir, name);
+  try {
+    if (fs.existsSync(dest)) { fs.rmSync(from, { force: true }); return; }
+    fs.renameSync(from, dest);
+  } catch { /* best effort — a later launch completes it */ }
+}
+
+/**
+ * Bring <home>/.ccr to the 0.4 layout. Total: never throws.
+ *
+ * @param {{ home?: string }} [opts]
+ * @returns {{ ok: true } | { ok: false, error: string }}
+ */
+function ensureLayout(opts = {}) {
+  const home = opts.home || os.homedir();
+  const root = path.join(home, '.ccr');
+  const marker = path.join(root, MARKER);
+
+  try {
+    if (!fs.existsSync(root)) {
+      // Fresh install: create the container already migrated.
+      fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+      fs.writeFileSync(marker, '1\n', { mode: 0o600 });
+      return { ok: true };
+    }
+    if (fs.existsSync(marker)) {
+      sweepLegacyDroppings(root);
+      return { ok: true };
+    }
+
+    // ---- Classify EVERYTHING before touching ANYTHING. ----
+    /** @type {{ dir: string, name: string }[]} */
+    const profileDirs = [];
+    /** @type {string[]} */
+    const looseBurnlogs = [];
+    let rootHasDroppings = false;
+    for (const name of fs.readdirSync(root)) {
+      const p = path.join(root, name);
+      if (RESERVED.has(name)) return { ok: false, error: `ccr: cannot migrate ~/.ccr — unexpected entry '${name}' (reserved by the new layout); move it aside and relaunch` };
+      if (name.startsWith('.')) continue;                      // dotted container entries are left alone
+      if (BURNLOG_RE.test(name)) { looseBurnlogs.push(name); continue; }
+      if (SESSION_RE.test(name)) continue;                     // 0.4 join key — already at its final home
+      if (DROPPINGS.includes(name)) { rootHasDroppings = true; continue; }
+      let st; try { st = fs.lstatSync(p); } catch { continue; }
+      if (st.isDirectory() && PROFILE_DIR_RE.test(name)) { profileDirs.push({ dir: p, name }); continue; }
+      return { ok: false, error: `ccr: cannot migrate ~/.ccr — unexpected entry '${name}'; move it aside and relaunch` };
+    }
+
+    // A live 0.3 session anywhere refuses the whole migration, by name.
+    if (legacyLive(root)) return { ok: false, error: 'ccr: cannot migrate ~/.ccr while a session is running there — close it first' };
+    for (const { dir, name } of profileDirs) {
+      if (legacyLive(dir)) return { ok: false, error: `ccr: cannot migrate ~/.ccr while an instance is running — close '${name}' first` };
+    }
+
+    // ---- Harvest, then sweep, then mark. ----
+    for (const { dir } of profileDirs) {
+      let names; try { names = fs.readdirSync(dir); } catch { continue; }
+      for (const n of names) if (BURNLOG_RE.test(n)) harvestBurnlog(path.join(dir, n), root, n);
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* next launch retries */ }
+    }
+    if (rootHasDroppings) for (const n of DROPPINGS) { try { fs.rmSync(path.join(root, n), { force: true }); } catch { /* best effort */ } }
+    try { fs.chmodSync(root, 0o700); } catch { /* best effort */ }
+    fs.writeFileSync(marker, '1\n', { mode: 0o600 });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: `ccr: migration failed: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+/**
+ * A DOWNGRADE-then-re-upgrade leaves a migrated container plus a 0.3 session's
+ * loose droppings at the root — a dead instance's live state, which the
+ * ephemeral rule says dies. Its burnlogs already live where the pool is, so
+ * the day's history merges for free. Swept only once that session shows no
+ * heartbeat (the safe direction, same as everywhere else).
+ * @param {string} root
+ */
+function sweepLegacyDroppings(root) {
+  try {
+    if (!fs.existsSync(path.join(root, 'last-status.json'))
+      && !fs.existsSync(path.join(root, 'sidecar-alive'))) return;
+    if (legacyLive(root)) return;
+    for (const n of DROPPINGS) { try { fs.rmSync(path.join(root, n), { force: true }); } catch { /* best effort */ } }
+  } catch { /* best effort */ }
+}
+
+module.exports = { ensureLayout, MARKER };

package/src/normalize.js

@@ -7,6 +7,21 @@
 const { discoverWindows } = require('./rate-limits');
 const { stripControl } = require('./sanitize');
 
+/**
+ * A finite number, or null. The snapshot is a JSON file on disk: it chooses its
+ * own value types, and a `!= null` check accepts the string "1.5" as happily as
+ * 1.5. Downstream does arithmetic and calls `.toFixed()`, so one wrong type is
+ * a TypeError inside the draw loop — which the sidecar catches, but only by
+ * replacing the whole economy panel with an error line, every tick, until the
+ * file changes. Type-check at ingestion; a bad field costs itself and nothing
+ * else. (NaN/Infinity are excluded too — they render as "NaN%" meters.)
+ * @param {any} v
+ * @returns {number|null}
+ */
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
 /**
  * @param {any} state CC status-line JSON
  * @param {number} [nowSec] override for testing
@@ -15,16 +30,20 @@ const { stripControl } = require('./sanitize');
 function normalizeStatus(state, nowSec) {
   const rl = (state && state.rate_limits) || {};
   const cw = (state && state.context_window) || {};
+  const cost = (state && state.cost) || {};
+  const durationMs = num(cost.total_duration_ms);
   return {
     model: stripControl((state && state.model && state.model.display_name) || null),
-    windowSize: cw.context_window_size || 200000,
+    // Must be positive: it is a divisor for the ctx meter, and `?? ` (unlike the
+    // `||` this replaced) would let a literal 0 through to divide by zero.
+    windowSize: (num(cw.context_window_size) || 0) > 0 ? 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,
+    contextTokens: num(cw.total_input_tokens)
+      ?? num(cw.current_usage && cw.current_usage.cache_read_input_tokens),
     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,
+    costUsd: num(cost.total_cost_usd),
+    durationMin: durationMs != null ? durationMs / 60000 : null,
     branch: null,
   };
 }

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