claude-code-runrate 0.3.0 → 0.4.0

package/src/render/shared.js

@@ -140,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,12 +6,45 @@
 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
@@ -33,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

@@ -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,154 @@
+// @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 the two encodings terminals actually send — SS3 on xterm and VS Code's
+// xterm.js, CSI on the Linux console — plus SPACE.
+//
+// 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[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';
@@ -168,6 +176,50 @@ 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, which is right under tmux and wt.exe where the pane inherits it.
+ *
+ * `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 +229,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');
 
@@ -204,10 +264,57 @@ function composeFrame(stateDir, opts = {}) {
   // 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;
+  // 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 +322,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
@@ -240,11 +347,11 @@ function composeFrame(stateDir, opts = {}) {
     // 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) };
+    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 });
-    // 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');
+    // 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
@@ -360,7 +467,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 +500,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 +562,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,
 };