claude-code-runrate 0.3.0 → 0.5.0

package/src/safe-read.js

@@ -44,6 +44,22 @@ const DEFAULT_MAX_BYTES = 256 * 1024;
  * @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;
@@ -55,7 +71,7 @@ function readTextCapped(file, maxBytes = DEFAULT_MAX_BYTES) {
     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');
+    return buf.subarray(0, read);
   } catch {
     return null;
   } finally {
@@ -63,4 +79,4 @@ function readTextCapped(file, maxBytes = DEFAULT_MAX_BYTES) {
   }
 }
 
-module.exports = { readTextCapped, DEFAULT_MAX_BYTES };
+module.exports = { readTextCapped, readBytesCapped, DEFAULT_MAX_BYTES };

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

package/src/sidecar-keys.js

@@ -0,0 +1,167 @@
+// @ts-check
+'use strict';
+// src/sidecar-keys.js — the hotkey host for terminals that have none.
+//
+// WHY THIS EXISTS. Cycling the sidebar's views is a HOST capability: under tmux
+// the launcher binds F3, tmux runs `ccr cycle-view`, and src/sidecar.js never
+// sees the key (docs/PANE-CONTRACT.md, "Hotkeys are a host capability"). VS Code
+// and its forks bind nothing, and their integrated terminal leaves BOTH panes
+// running a foreground process — Claude in one, the sidecar in the other — so
+// there is not even a free shell prompt to type `ccr cycle-view` into.
+//
+// Before the git pane that cost nothing: a user with no configured panes had a
+// one-view cycle, so a key that did not exist took nothing away. Every instance
+// now has two built-in views, and on those hosts no way at all to reach the
+// second one. This file is ccr playing host where the host declines to.
+//
+// WHY IT IS A SEPARATE PROCESS, and not a stdin listener bolted to the panel.
+// The structural invariant is that the sidecar has NO INPUT CHANNEL, so that
+// terminal-response channels and echoed keystrokes are structurally dead rather
+// than filtered. That invariant is about the process which RENDERS UNTRUSTED
+// TEXT, and it survives here intact: this file owns the terminal's stdin and
+// spawns `ccr sidecar` as a CHILD whose stdin is `'ignore'`. The renderer still
+// cannot read a key. It is exactly tmux's separation — host reads the key, the
+// renderer never participates — with ccr standing in for the host.
+//
+// Both directions are pinned structurally in test/sidecar-capabilities.test.js:
+// the renderer's module graph can never reach this file, and this file's graph
+// can never reach a renderer. Widening either is a deliberate act.
+//
+// WHAT AN ATTACKER GETS, stated rather than implied. A hostile blob can emit a
+// terminal query whose response the terminal delivers to whoever owns stdin —
+// which is now this process rather than nobody. That buys exactly what forging
+// <stateDir>/view-request already buys, and the contract prices it: "a different
+// pane on screen". This process draws nothing and writes one counter.
+//
+// THE KEY SET IS A COMPILE-TIME CONSTANT, per the contract's trust rule —
+// configuration may choose a key, ccr's own code chooses what it does. There is
+// no path from configuration, a blob, or a producer to anything here.
+
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { cycleView } = require('./cycle-view');
+
+// F3 in every encoding a terminal actually sends it, plus SPACE.
+//
+//   \x1bOR    SS3. What xterm, screen, tmux and vt220 all send (infocmp: kf3).
+//   \x1b[[C   The Linux console — infocmp gives `linux: kf3=\E[[C`, and it is
+//             the ONLY entry that differs. It is also what arrives on Windows
+//             from Node before v22.17.0 / v24.2.0: until "tty: use terminal VT
+//             mode on Windows" (db2aae802) setRawMode passed UV_TTY_MODE_RAW,
+//             where libuv translates the keypress itself rather than letting
+//             the terminal's own sequence through. From UV_TTY_MODE_RAW_VT on
+//             it sets ENABLE_VIRTUAL_TERMINAL_INPUT and Windows Terminal sends
+//             SS3 like everyone else. Which of the two arrives on Windows is
+//             therefore a property of the NODE VERSION, not the terminal.
+//   \x1b[13~  The CSI-tilde form VS Code's xterm.js sends. An earlier version
+//             of this comment called it the Linux console encoding; it is not,
+//             and the console form above was missing entirely.
+//
+// Space is not a fallback for tidiness: an editor that keeps F3 for its own
+// "find next" while the terminal is focused would otherwise leave this pane with
+// no key at all, and that behavior differs across VS Code, Cursor, Positron and
+// Antigravity. The pane is dedicated to the sidecar, so nothing else there is
+// waiting for a space.
+const CYCLE_KEYS = ['\x1bOR', '\x1b[[C', '\x1b[13~', ' '];
+
+// In raw mode Ctrl-C arrives as a BYTE, not a signal. Without handling it the
+// pane could not be closed from the keyboard at all.
+const INTERRUPT = '\x03';
+
+/**
+ * How many cycle keys are in this chunk. A burst advances by the number
+ * pressed, which is the request counter's own semantics (src/cycle-view.js):
+ * a press that lands while the pane is busy is never lost.
+ * @param {string} chunk
+ * @returns {number}
+ */
+function countCycleKeys(chunk) {
+  let n = 0;
+  for (const key of CYCLE_KEYS) n += chunk.split(key).length - 1;
+  return n;
+}
+
+/**
+ * Run the sidecar under a key-reading parent.
+ *
+ * Every side effect is injectable, because the interesting behavior here is
+ * ordering — raw mode restored on EVERY exit path, the child killed when the
+ * parent is signalled, the exit code carried back — and none of that is
+ * observable if the real tty and a real child process are in the way.
+ *
+ * @param {{ stateDir: string, argv?: string[], node?: string, ccrJs?: string,
+ *   spawnFn?: Function, stdin?: any, cycle?: (dir: string) => any,
+ *   exit?: (code: number) => void,
+ *   onSignal?: (sig: string, handler: () => void) => void }} opts
+ * @returns {{ stop: () => void, child: any }}
+ */
+function runWithKeys(opts) {
+  const stateDir = opts.stateDir;
+  const node = opts.node || process.execPath;
+  const ccrJs = opts.ccrJs || path.join(__dirname, '..', 'bin', 'ccr.js');
+  const spawnFn = opts.spawnFn || spawn;
+  const stdin = opts.stdin || process.stdin;
+  const cycle = opts.cycle || cycleView;
+  const exit = opts.exit || ((/** @type {number} */ code) => process.exit(code));
+  const onSignal = opts.onSignal || ((/** @type {string} */ sig, /** @type {() => void} */ h) => { process.on(sig, h); });
+
+  // The child is the panel, unchanged: same command, same flags, and stdin
+  // explicitly closed to it. stdout/stderr are inherited so the panel draws
+  // straight to this terminal — the parent prints nothing, ever.
+  const child = spawnFn(node, [ccrJs, 'sidecar', '--state-dir', stateDir, ...(opts.argv || [])], {
+    stdio: ['ignore', 'inherit', 'inherit'],
+  });
+
+  let restored = false;
+  /** Put the terminal back. Idempotent, and called on every path out. */
+  const restore = () => {
+    if (restored) return;
+    restored = true;
+    // A terminal left in raw mode outlives this process and is the worst
+    // failure this file could have: the user's shell stops echoing and stops
+    // handling Ctrl-C. Both calls are guarded because either can throw on a
+    // stream that has already gone away.
+    try { if (stdin.isTTY && typeof stdin.setRawMode === 'function') stdin.setRawMode(false); } catch { /* already gone */ }
+    try { stdin.pause(); } catch { /* already gone */ }
+  };
+
+  let stopping = false;
+  const stop = () => {
+    stopping = true;
+    restore();
+    try { child.kill('SIGTERM'); } catch { /* already dead */ }
+  };
+
+  // Raw mode only when there IS a terminal. `ccr sidecar --keys` with stdin
+  // redirected (a pipe, a service manager, a CI run) must degrade to a plain
+  // sidecar rather than throwing on setRawMode.
+  if (stdin.isTTY && typeof stdin.setRawMode === 'function') {
+    try {
+      stdin.setRawMode(true);
+      stdin.resume();
+      if (typeof stdin.setEncoding === 'function') stdin.setEncoding('utf8');
+      stdin.on('data', (/** @type {any} */ d) => {
+        const s = String(d);
+        if (s.includes(INTERRUPT)) { stop(); return; }
+        for (let i = countCycleKeys(s); i > 0; i -= 1) cycle(stateDir);
+      });
+    } catch {
+      // A terminal that refuses raw mode costs the key, never the panel.
+      restore();
+    }
+  }
+
+  child.on('exit', (/** @type {number|null} */ code, /** @type {string|null} */ signal) => {
+    restore();
+    // A stop WE asked for is a clean close, whatever signal did the work.
+    exit(stopping ? 0 : (signal ? 1 : (code == null ? 0 : code)));
+  });
+  // A child that never started must not leave the terminal in raw mode either.
+  child.on('error', () => { restore(); exit(1); });
+
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) onSignal(sig, stop);
+
+  return { stop, child };
+}
+
+module.exports = { runWithKeys, countCycleKeys, CYCLE_KEYS, INTERRUPT };

package/src/sidecar.js

@@ -20,6 +20,10 @@ const { stripControl } = require('./sanitize');
 const { loadPaneConfig } = require('./pane-config');
 const { loadPaneBlob } = require('./pane-blob');
 const { renderPane } = require('./render/pane');
+const { readGitRepo, discoverRepo } = require('./git-repo');
+const { computeWorkingTree } = require('./git-working-tree');
+const { readHistory } = require('./git-history');
+const { renderGitPane, laneBudget } = require('./render/git-pane');
 const { readViewRequests } = require('./cycle-view');
 
 const STATE_DIR = process.env.CCR_STATE_DIR || path.join(os.homedir(), '.ccr');
@@ -76,9 +80,13 @@ function heartbeatTick(stateDir, nonce, opts = {}) {
     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 */ }
+    // Never write THROUGH anything but a plain file at this path. A symlink
+    // would turn a heartbeat into an arbitrary-file write of "<pid>:<ms>"; a
+    // FIFO is worse in a quieter way — opening one for write BLOCKS until a
+    // reader appears, which hangs the draw loop outright and takes the whole
+    // sidebar down with no error. Both are plantable by anything running as the
+    // user, so anything that is not a regular file is removed first.
+    try { if (!fs.lstatSync(file).isFile()) fs.rmSync(file, { force: true }); } catch { /* absent */ }
     fs.writeFileSync(file, nonce);
   } catch { /* best-effort */ }
   return 'claimed';
@@ -159,6 +167,7 @@ function updateFeed(tpath) {
 
 const dim = (/** @type {string} */ s) => `\x1b[2m${s}\x1b[0m`;
 const bold = (/** @type {string} */ s) => `\x1b[1m${s}\x1b[0m`;
+const yellow = (/** @type {string} */ s) => `\x1b[33m${s}\x1b[0m`;
 
 let prev = '';
 function draw(/** @type {string} */ s) {
@@ -168,6 +177,58 @@ function draw(/** @type {string} */ s) {
   process.stdout.write('\x1b[H' + s.replace(/\n/g, '\x1b[K\n') + '\x1b[J');
 }
 
+/**
+ * The directory the SESSION is currently working in, as Claude Code last
+ * reported it. `workspace.current_dir` is the field that tracks a session that
+ * moved; `cwd` is the same value in older payloads and is the fallback rather
+ * than the primary for exactly that reason.
+ *
+ * Returns null when there is no snapshot yet, which the git pane renders as
+ * "not a git repository" — correct, because before the first status tick ccr
+ * genuinely does not know where the session is.
+ *
+ * @param {string} stateDir
+ * @returns {string|null}
+ */
+function sessionDir(stateDir) {
+  const raw = readTextCapped(path.join(stateDir, 'last-status.json'));
+  if (!raw) return null;
+  try {
+    const s = JSON.parse(raw);
+    if (!s || typeof s !== 'object') return null;
+    const w = s.workspace;
+    if (w && typeof w.current_dir === 'string' && w.current_dir) return w.current_dir;
+    return typeof s.cwd === 'string' && s.cwd ? s.cwd : null;
+  } catch { return null; }
+}
+
+/**
+ * The directory ccr was LAUNCHED in — the tab's stable identity. Written by the
+ * launcher (src/state-dir.js: recordLaunchDir); the sidecar's own cwd is the
+ * fallback.
+ *
+ * That fallback is right under tmux, where `new-session` inherits the caller's
+ * cwd. It is NOT free under wt.exe: a pane opens in the Windows Terminal
+ * profile's own startingDirectory unless the launcher passes `-d`, which it
+ * now does (src/launch-win.js: buildWtArgs). This comment previously claimed
+ * wt.exe inherited it, and that claim was the only place the assumption
+ * surfaced anywhere in the codebase — see features/windows-launcher.feature,
+ * "Claude Code opens in the directory ccr was launched from".
+ *
+ * `process.cwd()` throws when the directory it names has been deleted, which is
+ * not hypothetical here: it is the "repository is deleted while the pane is
+ * live" scenario, and the pane must keep drawing through it.
+ *
+ * @param {string} stateDir
+ * @returns {string|null}
+ */
+function launchDir(stateDir) {
+  const raw = readTextCapped(path.join(stateDir, 'launch-cwd'), 4096);
+  const line = raw ? raw.split('\n')[0].trim() : '';
+  if (line) return line;
+  try { return process.cwd(); } catch { return null; }
+}
+
 /**
  * Compose the screen for one tick — the ended / waiting / unreadable / live
  * states — and return it as a string (no I/O to stdout). Pure enough to test:
@@ -177,24 +238,32 @@ 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.
+ * `view` selects which whole-pane view to draw: 0 is ccr's own economy view, 1
+ * is the built-in git pane, and 2..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. Every view is FULL-HEIGHT,
+ * never stacked beside the economy panel — one pane, one subject.
  *
  * @param {string} stateDir
  * @param {{ now?: number, cols?: number, rows?: number, view?: number,
- *   panes?: Array<{path: string, source: string}> }} [opts]
+ *   panes?: Array<{path: string, source: string}>, home?: string }} [opts]
  * @returns {string}
  */
 function composeFrame(stateDir, opts = {}) {
   const now = opts.now != null ? opts.now : Date.now();
   const cols = opts.cols;
+  // The sidebar names its instance (features/instance-identity.feature): the
+  // name rides every frame — every view, the waiting line, the ended line —
+  // so a glance at any sidebar says which instance it belongs to.
+  let namePrefix = '';
+  try {
+    const name = fs.readFileSync(path.join(stateDir, 'name'), 'utf8').trim();
+    if (name) namePrefix = bold(name) + '\n';
+  } catch { /* unnamed — no line */ }
   const clamp = (/** @type {string} */ s) =>
     (typeof cols === 'number' && cols > 0
-      ? s.split('\n').map((l) => clampVisible(l, cols)).join('\n')
-      : s);
+      ? (namePrefix + s).split('\n').map((l) => clampVisible(l, cols)).join('\n')
+      : namePrefix + s);
   const snapshot = path.join(stateDir, 'last-status.json');
   const exited = path.join(stateDir, 'exited');
 
@@ -203,11 +272,59 @@ function composeFrame(stateDir, opts = {}) {
   // 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 cfg = opts.panes ? { panes: opts.panes, error: null } : loadPaneConfig();
+  const panes = cfg.panes;
+  // View order: 0 economy, 1 the git pane, 2… external panes. The git pane is
+  // BUILT IN and therefore always in the cycle — including in a directory that
+  // is not a repository at all, where it says so. A view that appeared and
+  // vanished with the session's cwd would renumber the cycle underneath the
+  // user's F3 key, and "not a git repository" is itself the answer to the
+  // question this pane exists to answer.
+  const viewCount = 2 + panes.length;
   const view = ((Math.trunc(opts.view || 0) % viewCount) + viewCount) % viewCount;
-  if (view > 0) {
-    const pane = panes[view - 1];
+  // The "n/N" position marker appears only once the cycle is longer than the two
+  // BUILT-IN views. Ruled 2026-08-05: adding the git pane made viewCount always
+  // ≥ 2, which would have put a marker on the economy panel of every user who
+  // has configured nothing — a visible change to a shipped surface, bought for
+  // nothing, since two self-identifying views need no numbering to tell apart.
+  // A user who has configured a pane keeps the markers they already had.
+  const showPosition = viewCount > 2;
+  const positionAt = (/** @type {number} */ i) => (showPosition ? `${i + 1}/${viewCount}` : '');
+  if (view === 1) {
+    // Guarded exactly like the external-pane branch: a bad repository must cost
+    // its own pane and nothing else (features/git-pane-safety.feature).
+    try {
+      const identity = readGitRepo({
+        currentDir: sessionDir(stateDir),
+        launchDir: launchDir(stateDir),
+      });
+      // The body sections exist only where a working tree does: a located,
+      // readable, non-bare repo. readGitRepo does not expose gitDir,
+      // deliberately (it is an identity model); re-discovering from the root it
+      // named costs one stat and keeps the model boundary clean.
+      let workingTree;
+      let history;
+      const paneCols = typeof cols === 'number' && cols > 0 ? cols : 48;
+      if (identity.state === 'ok' && !identity.bare && identity.root) {
+        const at = discoverRepo(identity.root);
+        if (at.found && at.gitDir) {
+          workingTree = computeWorkingTree({ root: identity.root, gitDir: at.gitDir });
+          history = readHistory(at.gitDir, { maxLanes: laneBudget(paneCols), maxRows: 32 });
+        }
+      }
+      return clamp(renderGitPane({ identity, workingTree, history }, {
+        width: paneCols,
+        rows: opts.rows || resolveRows() || 24,
+        now,
+        position: positionAt(view),
+      }) + '\n');
+    } catch (e) {
+      const msg = stripControl(e && e instanceof Error ? e.message : String(e)) || 'unknown';
+      return clamp(dim('ccr · git pane error: ' + msg.slice(0, 120)) + '\n');
+    }
+  }
+  if (view > 1) {
+    const pane = panes[view - 2];
     // 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.
@@ -215,7 +332,7 @@ function composeFrame(stateDir, opts = {}) {
       const res = loadPaneBlob(pane.path, { now });
       return clamp(renderPane(res, {
         source: pane.source,
-        position: `${view + 1}/${viewCount}`,
+        position: positionAt(view),
         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
@@ -234,17 +351,23 @@ function composeFrame(stateDir, opts = {}) {
   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'); }
+  // Snapshot age drives BOTH the dimming of the used figures inside the panel
+  // and the freshness marker appended below — read ONCE so the two can never
+  // disagree about whether what you are looking at is live. An unreadable mtime
+  // reads as fresh: a missing timestamp is not evidence of staleness.
+  let ageMs = 0;
+  try { ageMs = Math.max(0, now - fs.statSync(snapshot).mtimeMs); } catch { /* unknown → fresh */ }
   let out;
   try {
     // 5h/weekly are ACCOUNT-WIDE but captured per-profile, so an idle sibling's
     // panel lags a busy one. Reconcile the meters against sibling profiles on the
     // SAME account (see src/account-limits.js) before rendering — best-effort, and
     // 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');
+    const reconciled = { ...state, rate_limits: freshenAccountLimits(state.rate_limits, stateDir, opts.home ? { home: opts.home } : {}) };
+    out = renderEconomy(normalizeStatus(reconciled), { tick: Math.floor(now / 1000) % 2 === 0, ageMs });
+    // ccr's own view is position 1 of the cycle, named only when the cycle is
+    // long enough for the position to tell you something (see showPosition).
+    if (showPosition) out = out.replace(/\n/, dim(`   ${positionAt(0)}`) + '\n');
   } catch (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
@@ -268,11 +391,17 @@ function composeFrame(stateDir, opts = {}) {
   // quiet "updated Nm ago" so a stale panel reads as stale rather than broken —
   // otherwise a long agent run (or a CC statusLine that stopped firing) looks like
   // the sidecar just froze. See src/liveness.js + features/liveness.feature.
-  try {
-    const ageMs = now - fs.statSync(snapshot).mtimeMs;
-    const mark = liveness({ exited: false, ageMs }).marker;
-    if (mark) out += (out.endsWith('\n') ? '' : '\n') + '  ' + dim('· ' + mark);
-  } catch { /* snapshot mtime unknown → no marker */ }
+  const mark = liveness({ exited: false, ageMs }).marker;
+  if (mark) out += (out.endsWith('\n') ? '' : '\n') + '  ' + dim('· ' + mark);
+  // A config the user wrote and got wrong used to cost the panes in silence —
+  // the panel rendered exactly as it does for someone who configured nothing,
+  // so a typo was indistinguishable from never having tried. Name it here and
+  // send them to `ccr doctor`, which has room for the path and the reason.
+  // Still never fatal: the panel is whole, only the panes are missing.
+  if (cfg.error) {
+    out += (out.endsWith('\n') ? '' : '\n')
+      + '  ' + yellow('· config: ' + cfg.error) + dim(' — see `ccr doctor`');
+  }
   return clamp(out.endsWith('\n') ? out : out + '\n');
 }
 
@@ -360,7 +489,13 @@ function __resetViewState() { currentView = 0; seenRequests = null; }
  * 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,
+ * `view` sets which view the panel OPENS on (0 economy, 1 the git pane, 2…N the
+ * configured panes). It is a starting point, not a pin: the cycle key still
+ * advances from there. It cannot be used to put two panels side by side on one
+ * state dir — the heartbeat allows exactly one live sidecar per state dir, and
+ * the second to start makes the first stand down.
+ *
+ * @param {{ exitOnEnd?: boolean, stateDir?: string, graceMs?: number, view?: number,
  *   tick?: () => void, sentinelExists?: () => boolean,
  *   beat?: () => ('claimed' | 'yielded'), clearBeat?: () => void, onYield?: () => void,
  *   setIntervalFn?: Function, setTimeoutFn?: Function,
@@ -387,6 +522,13 @@ function run(opts = {}) {
   const exit = opts.exit || (() => process.exit(0));
   const onSignal = opts.onSignal || ((sig, handler) => process.on(sig, handler));
 
+  // The opening view. Set before the first tick so the panel never paints the
+  // economy panel for one frame on its way to the requested one.
+  if (opts.view != null) {
+    const v = Math.trunc(Number(opts.view));
+    if (Number.isFinite(v) && v >= 0) currentView = v;
+  }
+
   // Poll the sentinel fast when we have to detect the end; keep the redraw at ~1s.
   const RENDER_MS = 1000;
   const pollMs = exitOnEnd ? 120 : RENDER_MS;
@@ -442,4 +584,9 @@ function run(opts = {}) {
 module.exports = {
   run, updateFeed, composeFrame, heartbeatTick, clearHeartbeat, sidecarAlive,
   frame, __resetViewState,
+  // Exported so slot allocation (src/instance-slot.js) and its tests can reason
+  // about this file without duplicating its name or its freshness window. The
+  // launcher never WRITES it: the heartbeat is the sidecar's, and a newer nonce
+  // here is what makes a live sidebar stand down.
+  HEARTBEAT_FILE, HEARTBEAT_FRESH_MS,
 };