claude-code-runrate 0.2.3 → 0.3.0

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

package/src/render/statusline.js

@@ -14,6 +14,9 @@ function renderStatusline(view) {
   const parts = [];
   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');

package/src/safe-read.js

@@ -0,0 +1,66 @@
+// @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) {
+  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).toString('utf8');
+  } catch {
+    return null;
+  } finally {
+    try { fs.closeSync(fd); } catch { /* already closed */ }
+  }
+}
+
+module.exports = { readTextCapped, 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/sidecar.js

@@ -15,22 +15,132 @@ const { renderFeed } = require('./render/feed');
 const { clampVisible } = require('./render/shared');
 const { liveness } = require('./liveness');
 const { currentTranscriptPath, readNewLines, parseEvents } = require('./transcripts');
+const { readTextCapped } = require('./safe-read');
+const { stripControl } = require('./sanitize');
+const { loadPaneConfig } = require('./pane-config');
+const { loadPaneBlob } = require('./pane-blob');
+const { renderPane } = require('./render/pane');
+const { readViewRequests } = require('./cycle-view');
 
 const STATE_DIR = process.env.CCR_STATE_DIR || path.join(os.homedir(), '.ccr');
 
+// Single-instance heartbeat: each live sidecar re-claims <stateDir>/sidecar-alive
+// roughly once a second with a "<pid>:<startMs>" nonce. Two readers use it:
+//  - the VS Code launcher skips the split+paste banner while the file is fresh
+//    (an attached sidecar picks the new session up by itself once the launcher
+//    clears the exited sentinel — see launch-vscode.js), so relaunching stops
+//    minting duplicate panes;
+//  - an older sidecar that sees a NEWER nonce yields its pane (see run()), so
+//    pasting the one-liner twice still converges to a single live panel.
+const HEARTBEAT_FILE = 'sidecar-alive';
+// "Fresh" = beaten within this window. Beats land ~1s apart; 5s tolerates a
+// busy machine without ever mistaking a dead pane (minutes old) for live.
+const HEARTBEAT_FRESH_MS = 5000;
+
+/** @param {string} s @returns {{ pid: number, start: number } | null} */
+function parseNonce(s) {
+  const m = /^(\d+):(\d+)$/.exec(s.trim());
+  return m ? { pid: Number(m[1]), start: Number(m[2]) } : null;
+}
+
+/**
+ * One heartbeat: re-claim the file with our nonce, unless a NEWER sidecar
+ * (later start; higher pid breaks a same-millisecond tie) holds it — then
+ * yield WITHOUT writing, so the newer panel's claim is never clobbered and
+ * exactly one of the two keeps beating. Unreadable or unparseable content is
+ * claimed over (a garbage file must not wedge the panel), and any fs error
+ * claims rather than kills the loop — the heartbeat is strictly best-effort.
+ * @param {string} stateDir @param {string} nonce
+ * @param {{ now?: number, freshMs?: number }} [opts] injectable clock, for tests
+ * @returns {'claimed' | 'yielded'}
+ */
+function heartbeatTick(stateDir, nonce, opts = {}) {
+  const file = path.join(stateDir, HEARTBEAT_FILE);
+  const mine = parseNonce(nonce);
+  const now = opts.now != null ? opts.now : Date.now();
+  const freshMs = opts.freshMs != null ? opts.freshMs : HEARTBEAT_FRESH_MS;
+  try {
+    const cur = readTextCapped(file, 256) || '';
+    // Yield only to a nonce that is BOTH newer and still being beaten. Nonce
+    // order alone is a wall-clock comparison against a file that outlives its
+    // writer: a hard-killed sidecar leaves its nonce behind, and after any
+    // backwards clock step (NTP correction, VM restore) every sidecar launched
+    // since reads that dead nonce as "newer" and stands down — so the pane ends
+    // up with no live sidecar at all, repeatably, until the clock catches up.
+    // Mtime is what distinguishes a live rival from a corpse; sidecarAlive()
+    // has always used it, and the takeover decision needs it just as much.
+    const fresh = (() => {
+      try { return now - fs.lstatSync(file).mtimeMs <= freshMs; } catch { return false; }
+    })();
+    const other = fresh && cur && cur.trim() !== nonce ? parseNonce(cur) : null;
+    if (other && mine && (other.start > mine.start || (other.start === mine.start && other.pid > mine.pid))) {
+      return 'yielded';
+    }
+    // Never write THROUGH a symlink planted at this path — that turns a
+    // heartbeat into an arbitrary-file write of "<pid>:<ms>".
+    try { if (fs.lstatSync(file).isSymbolicLink()) fs.rmSync(file, { force: true }); } catch { /* absent */ }
+    fs.writeFileSync(file, nonce);
+  } catch { /* best-effort */ }
+  return 'claimed';
+}
+
+/**
+ * Remove the heartbeat on the way out — but only while it still holds OUR
+ * nonce; after a takeover the file belongs to the newer sidecar.
+ * @param {string} stateDir @param {string} nonce
+ */
+function clearHeartbeat(stateDir, nonce) {
+  const file = path.join(stateDir, HEARTBEAT_FILE);
+  try {
+    if ((readTextCapped(file, 256) || '').trim() === nonce) fs.rmSync(file, { force: true });
+  } catch { /* already gone / unreadable — nothing to clear */ }
+}
+
+/**
+ * Is a sidecar attached to this state dir right now? Mtime-based, so a killed
+ * pane (whose stale file nobody cleared) reads as dead within seconds. Used by
+ * the VS Code launcher to print "already attached" instead of the split banner.
+ * @param {string} stateDir @param {{ now?: number, freshMs?: number }} [opts]
+ * @returns {boolean}
+ */
+function sidecarAlive(stateDir, opts = {}) {
+  const now = opts.now != null ? opts.now : Date.now();
+  const freshMs = opts.freshMs != null ? opts.freshMs : HEARTBEAT_FRESH_MS;
+  try {
+    return now - fs.statSync(path.join(stateDir, HEARTBEAT_FILE)).mtimeMs <= freshMs;
+  } catch {
+    return false;
+  }
+}
+
 // Live feed accumulator: tail the current transcript incrementally (by byte
 // offset) and roll up tool/skill events + per-session stats. Reset on session
 // switch. Best-effort — must never break the economy panel.
 const FEED_CAP = 200;
-const feedState = { path: /** @type {string|null} */ (null), offset: 0, events: /** @type {any[]} */ ([]), tools: /** @type {Record<string,number>} */ ({}), commands: 0, tokens: { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 }, files: new Set() };
+const feedState = { path: /** @type {string|null} */ (null), offset: 0, events: /** @type {any[]} */ ([]), tools: /** @type {Record<string,number>} */ (Object.create(null)), commands: 0, tokens: { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 }, files: new Set() };
+
+/** Zero the rolling totals — on a session switch, and on a tail restart. */
+function resetFeedState(/** @type {string|null} */ tpath) {
+  feedState.path = tpath; feedState.offset = 0; feedState.events = [];
+  // Null-prototype: these keys are tool NAMES from the transcript, i.e. attacker
+  // -influenceable. On a plain object a tool called "constructor" reads back the
+  // inherited function (the feed header rendered its native source), and one
+  // called "__proto__" silently vanishes into a prototype write instead of
+  // counting. With no prototype there is nothing to inherit or to set.
+  feedState.tools = Object.create(null);
+  feedState.commands = 0;
+  feedState.tokens = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
+  feedState.files = new Set();
+}
 
 /** @param {string} tpath @returns {any} feed view for renderFeed */
 function updateFeed(tpath) {
-  if (feedState.path !== tpath) {           // new session → start clean
-    feedState.path = tpath; feedState.offset = 0; feedState.events = []; feedState.tools = {};
-    feedState.commands = 0; feedState.tokens = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 }; feedState.files = new Set();
-  }
-  const { offset, lines } = readNewLines(tpath, feedState.offset);
+  if (feedState.path !== tpath) resetFeedState(tpath);   // new session → start clean
+  const { offset, lines, restarted } = readNewLines(tpath, feedState.offset);
+  // The tail went back to 0 because the file shrank, so the lines below are ones
+  // we have already counted. Resetting the offset without resetting the totals
+  // double-counts every tool, file, and token for the rest of the session.
+  if (restarted) resetFeedState(tpath);
   feedState.offset = offset;
   if (lines.length) {
     const p = parseEvents(lines);
@@ -67,8 +177,15 @@ function draw(/** @type {string} */ s) {
  * is clamped to it so a wide row can't soft-wrap and corrupt the cursor-home
  * redraw in a narrow cmd/PowerShell/split pane. Omit it (non-TTY) for no clamp.
  *
+ * `view` selects which whole-pane view to draw: 0 is ccr's own economy view and
+ * 1..N are the configured external panes, in config order. It is taken modulo
+ * the number of views, so an index that outlives a shrinking config wraps rather
+ * than showing nothing. External panes are FULL-HEIGHT views, never stacked
+ * beside the economy panel — one pane, one subject.
+ *
  * @param {string} stateDir
- * @param {{ now?: number, cols?: number }} [opts]
+ * @param {{ now?: number, cols?: number, rows?: number, view?: number,
+ *   panes?: Array<{path: string, source: string}> }} [opts]
  * @returns {string}
  */
 function composeFrame(stateDir, opts = {}) {
@@ -82,8 +199,38 @@ function composeFrame(stateDir, opts = {}) {
   const exited = path.join(stateDir, 'exited');
 
   if (fs.existsSync(exited)) return clamp(bold('ccr') + '  ' + dim('session ended') + '\n');
-  let raw = '';
-  try { raw = fs.readFileSync(snapshot, 'utf8'); } catch { /* none yet */ }
+
+  // External panes. Config is re-read per tick so adding a pane needs no
+  // relaunch, and it is best-effort: a broken config costs the panes, never the
+  // panel (loadPaneConfig is total — see src/pane-config.js).
+  const panes = opts.panes || loadPaneConfig().panes;
+  const viewCount = 1 + panes.length;
+  const view = ((Math.trunc(opts.view || 0) % viewCount) + viewCount) % viewCount;
+  if (view > 0) {
+    const pane = panes[view - 1];
+    // Guarded like the economy branch below: "a malformed file must cost a pane
+    // state, never the sidecar" is the contract's rule, and leaving it to rest
+    // on the renderer never throwing would make it one careless edit from false.
+    try {
+      const res = loadPaneBlob(pane.path, { now });
+      return clamp(renderPane(res, {
+        source: pane.source,
+        position: `${view + 1}/${viewCount}`,
+        width: typeof cols === 'number' && cols > 0 ? cols : 48,
+        // Rows the body may use: the pane's height less the chrome (title,
+        // basis, blank) and a line of breathing room. Without this the overflow
+        // collapse in renderPane is unreachable, and a long blob silently
+        // scrolls the pane — which is exactly what obligation 8 forbids.
+        maxRows: Math.max(1, (opts.rows || resolveRows() || 24) - 4),
+      }) + '\n');
+    } catch (e) {
+      const msg = stripControl(e && e instanceof Error ? e.message : String(e)) || 'unknown';
+      return clamp(dim('ccr · pane render error: ' + msg.slice(0, 120)) + '\n');
+    }
+  }
+  // Capped, regular-files-only read: a fifo here would block this synchronous
+  // loop forever and an unbounded file can blank the panel (see src/safe-read.js).
+  const raw = readTextCapped(snapshot) || '';
   if (!raw.trim()) return clamp(dim('ccr · waiting for the first status tick…') + '\n');
   let state;
   try { state = JSON.parse(raw); } catch { return clamp(dim('ccr · status unreadable') + '\n'); }
@@ -95,8 +242,15 @@ function composeFrame(stateDir, opts = {}) {
     // strictly guarded so a different account is never mixed in.
     const reconciled = { ...state, rate_limits: freshenAccountLimits(state.rate_limits, stateDir) };
     out = renderEconomy(normalizeStatus(reconciled), { tick: Math.floor(now / 1000) % 2 === 0 });
+    // ccr's own view is position 1 of the cycle. Shown only when there is a
+    // cycle to be in — a lone economy view has no position worth naming.
+    if (viewCount > 1) out = out.replace(/\n/, dim(`   1/${viewCount}`) + '\n');
   } catch (e) {
-    out = dim('ccr render error: ' + (e && e instanceof Error ? e.message : String(e)));
+    // Sanitize and bound the message: it is the one error surface that prints
+    // text ccr did not author, and an exception string can quote the input that
+    // caused it. Everything else here is a named state naming a path only.
+    const msg = stripControl(e && e instanceof Error ? e.message : String(e)) || 'unknown';
+    out = dim('ccr render error: ' + msg.slice(0, 120));
   }
   // Live tool/skills feed below the panel — best-effort; never break the panel.
   // Its inner width tracks the pane so args truncate cleanly (the clamp below is
@@ -144,11 +298,47 @@ function resolveCols() {
   return haveLive ? live : undefined;
 }
 
-function frame() {
-  // Read columns each tick so a live resize re-flows on the next frame.
-  draw(composeFrame(STATE_DIR, { now: Date.now(), cols: resolveCols() }));
+/** The pane's height, for the row budget. Unknown (non-TTY) → undefined. */
+function resolveRows() {
+  const live = process.stdout.rows;
+  return typeof live === 'number' && live > 0 ? live : undefined;
 }
 
+// Which whole-pane view is showing. composeFrame takes it modulo the view
+// count, so it never needs clamping here.
+let currentView = 0;
+// Advance-requests already applied. The host's key writes a counter (see
+// src/cycle-view.js) and we consume the DIFFERENCE, so a burst of presses
+// advances by the number pressed and none is lost between ticks.
+/** @type {number|null} */
+let seenRequests = null;
+
+/**
+ * One tick: consume any pending advance-requests, then paint.
+ * The seams exist so a test can observe what reaches composeFrame — without
+ * them, "the view index actually reaches the frame" is unobservable, and both
+ * halves of the cycling wiring can be broken with the suite still green.
+ * @param {{ stateDir?: string, compose?: Function, paint?: Function }} [deps]
+ */
+function frame(deps = {}) {
+  const stateDir = deps.stateDir || STATE_DIR;
+  const compose = deps.compose || composeFrame;
+  const paint = deps.paint || draw;
+  const requests = readViewRequests(stateDir);
+  if (seenRequests == null) seenRequests = requests;      // adopt on first tick
+  else if (requests !== seenRequests) {
+    currentView += Math.max(0, requests - seenRequests);
+    seenRequests = requests;
+  }
+  // Read columns and rows each tick so a live resize re-flows on the next frame.
+  paint(compose(stateDir, {
+    now: Date.now(), cols: resolveCols(), rows: resolveRows(), view: currentView,
+  }));
+}
+
+/** Test seam: reset the cycling state between scenarios (module-level by design). */
+function __resetViewState() { currentView = 0; seenRequests = null; }
+
 /**
  * The live loop. With `exitOnEnd` (the Windows launcher passes `--exit-on-end`),
  * the sidecar closes its own pane as soon as the `exited` sentinel appears — so a
@@ -165,8 +355,14 @@ function frame() {
  * buildWtArgs) so this RIGHT pane closes first and the border sweeps left→right.
  * Side effects are injectable so the end-sweep is unit-testable.
  *
+ * A second sidecar pasted against the same state dir takes the heartbeat over
+ * (its nonce is newer); this one then paints a hand-off note and exits WITHOUT
+ * clearing the file — it now belongs to the newer panel. `beat`/`clearBeat`/
+ * `onYield` are injectable so the takeover is unit-testable too.
+ *
  * @param {{ exitOnEnd?: boolean, stateDir?: string, graceMs?: number,
  *   tick?: () => void, sentinelExists?: () => boolean,
+ *   beat?: () => ('claimed' | 'yielded'), clearBeat?: () => void, onYield?: () => void,
  *   setIntervalFn?: Function, setTimeoutFn?: Function,
  *   clearIntervalFn?: Function, clearTimeoutFn?: Function,
  *   exit?: () => void, onSignal?: (sig: string, handler: () => void) => void }} [opts]
@@ -180,6 +376,10 @@ function run(opts = {}) {
   const graceMs = opts.graceMs != null ? opts.graceMs : 200;
   const tick = opts.tick || frame;
   const sentinelExists = opts.sentinelExists || (() => fs.existsSync(path.join(stateDir, 'exited')));
+  const nonce = `${process.pid}:${Date.now()}`;
+  const beat = opts.beat || (() => heartbeatTick(stateDir, nonce));
+  const clearBeat = opts.clearBeat || (() => clearHeartbeat(stateDir, nonce));
+  const onYield = opts.onYield || (() => draw(bold('ccr') + '  ' + dim('another sidecar attached — this pane stood down') + '\n'));
   const setIntervalFn = opts.setIntervalFn || setInterval;
   const setTimeoutFn = opts.setTimeoutFn || setTimeout;
   const clearIntervalFn = opts.clearIntervalFn || clearInterval;
@@ -191,14 +391,18 @@ function run(opts = {}) {
   const RENDER_MS = 1000;
   const pollMs = exitOnEnd ? 120 : RENDER_MS;
 
+  /** @type {ReturnType<typeof setInterval>|null} */
   let id = null;
+  /** @type {ReturnType<typeof setTimeout>|null} */
   let endTimer = null;
   let sinceRender = RENDER_MS; // render on the first loop
-  const stop = () => {
+  const teardown = (/** @type {boolean} */ clearHb) => {
     if (id != null) clearIntervalFn(id);
     if (endTimer != null) clearTimeoutFn(endTimer);
+    if (clearHb) clearBeat();
     exit();
   };
+  const stop = () => teardown(true);
   const checkEnd = () => {
     // Once the session has ended, paint it once then sweep this pane closed.
     if (exitOnEnd && endTimer == null && sentinelExists()) {
@@ -208,11 +412,24 @@ function run(opts = {}) {
   };
   const loop = () => {
     sinceRender += pollMs;
-    if (sinceRender >= RENDER_MS) { sinceRender = 0; tick(); }
+    if (sinceRender >= RENDER_MS) {
+      sinceRender = 0;
+      tick();
+      // Beat at render cadence (~1s). A newer sidecar owns the dir now →
+      // hand the state dir over and fold this pane, leaving ITS heartbeat.
+      if (beat() === 'yielded') { onYield(); teardown(false); return; }
+    }
     checkEnd();
   };
   loop();
   id = setIntervalFn(loop, pollMs);
+  // SIGUSR1 also advances the view, for anyone who can already signal this
+  // process (`kill -USR1 $(pgrep -f 'ccr.js sidecar')`). The KEY binding does
+  // not use it: routing a keypress through a pid read out of a writable file
+  // turned a cosmetic hotkey into an arbitrary-kill primitive, so the host
+  // writes a request file instead (see src/cycle-view.js). Cycling still never
+  // reaches stdin, which is the invariant that matters.
+  onSignal('SIGUSR1', () => { currentView += 1; tick(); });
   onSignal('SIGINT', stop);
   onSignal('SIGTERM', stop);
   return stop;
@@ -220,5 +437,9 @@ function run(opts = {}) {
 
 // `updateFeed` + `composeFrame` are exported for tests (the incremental tail +
 // session-switch reset and the ended/waiting/render states are the subtle
-// parts); the live loop uses `run`.
-module.exports = { run, updateFeed, composeFrame };
+// parts); the live loop uses `run`. The heartbeat trio is exported for tests
+// and for the VS Code launcher's `sidecarAlive` check.
+module.exports = {
+  run, updateFeed, composeFrame, heartbeatTick, clearHeartbeat, sidecarAlive,
+  frame, __resetViewState,
+};