claude-code-runrate 0.2.4 → 0.4.0

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

@@ -15,6 +15,16 @@ 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 { 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');
 
@@ -45,18 +55,38 @@ function parseNonce(s) {
  * 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) {
+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 {
-    let cur = '';
-    try { cur = fs.readFileSync(file, 'utf8'); } catch { /* no heartbeat yet */ }
-    const other = cur && cur.trim() !== nonce ? parseNonce(cur) : null;
+    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 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';
@@ -70,7 +100,7 @@ function heartbeatTick(stateDir, nonce) {
 function clearHeartbeat(stateDir, nonce) {
   const file = path.join(stateDir, HEARTBEAT_FILE);
   try {
-    if (fs.readFileSync(file, 'utf8').trim() === nonce) fs.rmSync(file, { force: true });
+    if ((readTextCapped(file, 256) || '').trim() === nonce) fs.rmSync(file, { force: true });
   } catch { /* already gone / unreadable — nothing to clear */ }
 }
 
@@ -95,15 +125,30 @@ function sidecarAlive(stateDir, opts = {}) {
 // 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);
@@ -131,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:
@@ -140,23 +229,115 @@ 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, 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 }} [opts]
+ * @param {{ now?: number, cols?: number, rows?: number, view?: number,
+ *   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');
 
   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;
+  // 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;
+  // 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.
+    try {
+      const res = loadPaneBlob(pane.path, { now });
+      return clamp(renderPane(res, {
+        source: pane.source,
+        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
+        // 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'); }
@@ -166,10 +347,17 @@ 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, 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) {
-    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
@@ -217,11 +405,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
@@ -243,7 +467,13 @@ function frame() {
  * 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,
@@ -270,11 +500,20 @@ 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;
 
+  /** @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 teardown = (/** @type {boolean} */ clearHb) => {
@@ -304,6 +543,13 @@ function run(opts = {}) {
   };
   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;
@@ -313,4 +559,12 @@ function run(opts = {}) {
 // session-switch reset and the ended/waiting/render states are the subtle
 // 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 };
+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,
+};

package/src/state-dir.js

@@ -18,4 +18,47 @@ function ensureSecureDir(dir) {
   try { fs.chmodSync(dir, 0o700); } catch { /* best effort */ }
 }
 
-module.exports = { ensureSecureDir };
+/**
+ * Record the directory ccr was launched in, for the git pane's launch-repo
+ * identity (features/git-repo-identity.feature: the launch repo is the tab's
+ * stable identity, while the current repo follows the session).
+ *
+ * It is written rather than inferred because only the LAUNCHER knows it. The
+ * sidecar's own `process.cwd()` happens to be the launch directory under tmux
+ * and wt.exe, where the pane inherits it — but not in VS Code, where the user
+ * pastes the sidecar one-liner into a terminal that opened wherever the editor
+ * felt like. Inferring would be right most of the time and quietly wrong in the
+ * host that needed it most, so the launcher states it.
+ *
+ * Best-effort by the same rule as everything else in this file: a tab that
+ * cannot record its launch directory falls back to naming only the current
+ * repo, which is a smaller loss than a launcher that fails.
+ *
+ * @param {string} dir  The state directory.
+ * @param {string} cwd  The launch directory.
+ */
+function recordLaunchDir(dir, cwd) {
+  const path = require('node:path');
+  const file = path.join(dir, 'launch-cwd');
+  try {
+    // Never write THROUGH anything but a plain file, for the two reasons the
+    // heartbeat write (src/sidecar.js) and the cycle counter (src/cycle-view.js)
+    // already guard against at their own paths in this same directory:
+    //
+    //   A SYMLINK turns this into an arbitrary-file overwrite of a directory
+    //   name — verified: a link planted at launch-cwd had its target replaced.
+    //
+    //   A FIFO is worse and quieter. Opening one for write BLOCKS until a reader
+    //   appears, and this runs in all three launchers BEFORE Claude is spawned —
+    //   verified: `ccr` hangs forever with no output at all. That is the silent
+    //   -abort failure this project already shipped once (scripts/launch.sh's
+    //   nvm glob under `set -e`), arriving by a different door.
+    //
+    // Anything under <stateDir> is writable by anything running as the user, so
+    // this is the same trust boundary, not a new one.
+    try { if (!fs.lstatSync(file).isFile()) fs.rmSync(file, { force: true }); } catch { /* absent */ }
+    fs.writeFileSync(file, String(cwd) + '\n', { mode: 0o600 });
+  } catch { /* best effort */ }
+}
+
+module.exports = { ensureSecureDir, recordLaunchDir };