claude-code-runrate 0.2.3 → 0.2.4

package/README.md

@@ -79,6 +79,13 @@ trigger the split itself, so `ccr` does everything around it:
 Lost the banner once Claude takes the screen? Run `ccr sidecar --hint` to reprint
 the steps and re-copy the command.
 
+The split is a **one-time** setup per VS Code window: an attached sidecar picks
+each new `ccr` session up automatically, so relaunching prints a short note
+instead of the banner. And if you do paste the one-liner into a second pane, the
+older pane stands down by itself — there is never more than one live sidebar per
+session. Profiles stay independent: a personal `ccr` and a work `ccr <profile>`
+run side by side, each with its own state dir and its own sidebar.
+
 On **Windows** this is the default inside VS Code (Windows Terminal otherwise
 opens a separate window, so the in-editor split is nicer). On **Linux/macOS**,
 `ccr` defaults to `tmux` (which works inside the VS Code terminal too); set
@@ -104,10 +111,14 @@ latency.)
 
 This project is built **BDD-first**: the Gherkin in [`features/`](features/) is
 the source of truth, executed by a hand-rolled zero-dependency harness on top of
-Node's built-in test runner — a ~250-line Gherkin parser + runner that supports
+Node's built-in test runner — a single-file Gherkin parser + runner that supports
 the practical core of the grammar and rejects everything else loudly rather than
-mis-parsing it. See [`docs/GHERKIN.md`](docs/GHERKIN.md) for the grammar, the
-deliberate limits, and the API.
+mis-parsing it. The harness is available standalone as
+[`gherkin-node-test`](https://github.com/bingh0/gherkin-node-test) on
+[npm](https://www.npmjs.com/package/gherkin-node-test) (that repo is the
+canonical source; `test/gherkin.js` is a vendored copy). See
+[`docs/GHERKIN.md`](docs/GHERKIN.md) for the grammar, the deliberate limits,
+and the API.
 
 ```bash
 npm test            # node --test — harness self-tests + feature scenarios

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-runrate",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Claude Code run-rate — subscription burn-rate & economy for your Claude Code sessions.",
   "license": "MIT",
   "author": "Bing Ho <reps-attic-riot@duck.com>",

package/scripts/launch.sh

@@ -78,9 +78,22 @@ tmux new-session -d -s "$SESSION" \
   "$ENV_PREAMBLE; $CC_CMD --settings '$SETTINGS'; touch '$STATE/exited'; sleep 2; tmux kill-session -t '$SESSION' 2>/dev/null"
 tmux set-environment -t "$SESSION" CCR_STATE_DIR "$STATE"
 
-# Pane 1: the live economy sidebar.
-tmux split-window -t "$SESSION:0" -h -p "${CCR_SIDEBAR_PCT:-34}" \
-  "$ENV_PREAMBLE; \"$NODE\" \"$REPO/bin/ccr.js\" sidecar; read -r -p 'sidebar exited — Enter to close '"
+# Pane 1: the live economy sidebar. Capture its pane id so we can scope a hook to it.
+SIDEBAR_PANE="$(tmux split-window -t "$SESSION:0" -h -p "${CCR_SIDEBAR_PCT:-34}" -P -F '#{pane_id}' \
+  "$ENV_PREAMBLE; \"$NODE\" \"$REPO/bin/ccr.js\" sidecar; read -r -p 'sidebar exited — Enter to close '")"
+
+# The sidebar is a live dashboard — there is nothing to scroll. A stray mouse-wheel
+# or PageUp over its narrow pane drops tmux into copy-mode, which freezes the pane
+# at a snapshot and swallows the sidecar's per-second redraws — it looks like the
+# sidebar "got lost" (the grid keeps updating underneath; only the view is frozen).
+# Auto-cancel copy-mode the instant this pane enters it. PANE-scoped, so every other
+# pane — and the Claude pane's scrollback — keeps normal copy-mode. The cancel
+# re-fires this hook with pane_in_mode=0, so the guard stops it recursing. Best-effort:
+# pane-scoped hooks need tmux >= 3.2; older tmux just skips the guard (|| true).
+if [ -n "$SIDEBAR_PANE" ]; then
+  tmux set-hook -p -t "$SIDEBAR_PANE" pane-mode-changed \
+    "if-shell -F '#{pane_in_mode}' 'send-keys -t $SIDEBAR_PANE -X cancel'" 2>/dev/null || true
+fi
 
 tmux select-pane -t "$SESSION:0.0"
 tmux source-file -t "$SESSION" "$RUN_CONF"

package/src/launch-vscode.js

@@ -96,6 +96,21 @@ function copyToClipboard(text, d) {
   }
 }
 
+/**
+ * The quiet replacement for the banner when a sidecar is ALREADY attached to
+ * this state dir (heartbeat fresh — see src/sidecar.js). Relaunching used to
+ * prompt for a new split+paste every time while every old pane on the same
+ * state dir came back to life too, so panes accumulated; an attached sidecar
+ * picks the new session up by itself, so all the user needs is one line.
+ * @param {{ hintCmd: string, color: boolean }} o
+ * @returns {string}
+ */
+function buildAttachedNote(o) {
+  const c = o.color ? (/** @type {string} */ code, /** @type {string} */ s) => `\x1b[${code}m${s}\x1b[0m` : (/** @type {string} */ _code, /** @type {string} */ s) => s;
+  return '\n' + c('1', '  ccr') + c('2', ` · live sidecar already attached — it picks this session up automatically.`)
+    + '\n' + c('2', `        (split steps again: ${o.hintCmd})`) + '\n\n';
+}
+
 /**
  * `ccr [profile]` inside a VS Code integrated terminal: wire the split-view
  * sidecar, then run Claude in the current pane. Returns Claude's exit code.
@@ -136,17 +151,29 @@ function run(profile, deps = {}) {
 
   // Show the split instructions + copy the sidecar one-liner BEFORE Claude takes
   // over the pane (the clipboard + hint make it recoverable once it scrolls off).
+  // Unless a sidecar is already attached to this state dir: it revives on its
+  // own once the exited sentinel is cleared above, and re-prompting the split
+  // every relaunch is exactly what piled up duplicate panes.
   const ccrBin = d.which('ccr');
   const sidecarCmd = sidecarPasteCommand({ stateDir: st.stateDir, ccrBin, node: d.node, ccrJs: d.ccrJs });
   const hintCmd = sidecarPasteCommand({ stateDir: st.stateDir, ccrBin, node: d.node, ccrJs: d.ccrJs, hint: true });
-  d.out(buildBanner({ sidecarCmd, splitKey: splitKeybinding(d.platform), hintCmd, color: d.color }));
-  copyToClipboard(sidecarCmd, d);
+  if (d.sidecarAlive(st.stateDir)) {
+    d.out(buildAttachedNote({ hintCmd, color: d.color }));
+  } else {
+    d.out(buildBanner({ sidecarCmd, splitKey: splitKeybinding(d.platform), hintCmd, color: d.color }));
+    copyToClipboard(sidecarCmd, d);
+  }
 
-  // Run Claude in the current pane (blocks until exit). The temp settings file is
-  // always removed; the "session ended" sentinel is only dropped if Claude
-  // actually ran — a failed spawn must NOT flip the sidecar to "ended".
+  // Run Claude in the current pane (blocks until exit). CCR_STATE_DIR rides the
+  // spawn env so the statusline subprocess (a grandchild via Claude) snapshots
+  // into THIS profile's state dir — without it a profile session writes to the
+  // default ~/.ccr, starving its own sidecar and clobbering a concurrently
+  // running bare session's (the wt.exe launcher injects the same var per pane).
+  // The temp settings file is always removed; the "session ended" sentinel is
+  // only dropped if Claude actually ran — a failed spawn must NOT flip the
+  // sidecar to "ended".
   const parts = st.ccCmd.split(' ');
-  const r = d.spawnClaude(parts[0], [...parts.slice(1), '--settings', settingsFile]);
+  const r = d.spawnClaude(parts[0], [...parts.slice(1), '--settings', settingsFile], { CCR_STATE_DIR: st.stateDir });
   d.cleanup(settingsFile);
   if (r && r.error) { d.err(`ccr: failed to launch Claude: ${r.error.message}\n`); return 1; }
   d.dropExited(st.stateDir);
@@ -215,15 +242,17 @@ function buildClaudeSpawn(bin, args, o) {
  *
  * @param {string} bin
  * @param {string[]} args
+ * @param {Record<string, string>} [extraEnv] merged over process.env (CCR_STATE_DIR)
  * @returns {{ status: number|null, error?: Error }}
  */
-function defaultSpawnClaude(bin, args) {
+function defaultSpawnClaude(bin, args, extraEnv) {
   const built = buildClaudeSpawn(bin, args, { platform: process.platform, which: defaultWhich });
   if ('error' in built) return { status: null, error: built.error };
   const { spawnSync } = require('node:child_process');
+  const env = { ...process.env, ...extraEnv };
   return built.shell
-    ? spawnSync(built.command, { stdio: 'inherit', shell: true })
-    : spawnSync(built.command, built.args || [], { stdio: 'inherit' });
+    ? spawnSync(built.command, { stdio: 'inherit', shell: true, env })
+    : spawnSync(built.command, built.args || [], { stdio: 'inherit', env });
 }
 
 /** @param {string} name @returns {string|null} */
@@ -260,6 +289,9 @@ function withDefaults(deps) {
     cleanup: deps.cleanup || ((f) => inject.cleanupSettingsFile(f)),
     spawnClaude: deps.spawnClaude || defaultSpawnClaude,
     spawnCopy: deps.spawnCopy || ((cmd, args, input) => require('node:child_process').spawnSync(cmd, args, { input, stdio: ['pipe', 'ignore', 'ignore'] })),
+    // Lazy require: the heartbeat check single-sources file name + freshness in
+    // src/sidecar.js without loading the render stack on the launch path.
+    sidecarAlive: deps.sidecarAlive || ((dir) => require('./sidecar').sidecarAlive(dir)),
   };
 }
 
@@ -281,8 +313,9 @@ function withDefaults(deps) {
  * @property {(dir: string) => void} dropExited
  * @property {(settings: object) => string} writeSettings
  * @property {(file: string) => void} cleanup
- * @property {(bin: string, args: string[]) => {status: number|null, error?: Error}} spawnClaude
+ * @property {(bin: string, args: string[], extraEnv?: Record<string, string>) => {status: number|null, error?: Error}} spawnClaude
  * @property {(cmd: string, args: string[], input: string) => {status: number|null, error?: Error}} spawnCopy
+ * @property {(stateDir: string) => boolean} sidecarAlive
  */
 
-module.exports = { splitKeybinding, sidecarPasteCommand, osc52, buildBanner, copyToClipboard, buildClaudeSpawn, run, hint };
+module.exports = { splitKeybinding, sidecarPasteCommand, osc52, buildBanner, buildAttachedNote, copyToClipboard, buildClaudeSpawn, run, hint };

package/src/sidecar.js

@@ -18,6 +18,79 @@ const { currentTranscriptPath, readNewLines, parseEvents } = require('./transcri
 
 const STATE_DIR = process.env.CCR_STATE_DIR || path.join(os.homedir(), '.ccr');
 
+// Single-instance heartbeat: each live sidecar re-claims <stateDir>/sidecar-alive
+// roughly once a second with a "<pid>:<startMs>" nonce. Two readers use it:
+//  - the VS Code launcher skips the split+paste banner while the file is fresh
+//    (an attached sidecar picks the new session up by itself once the launcher
+//    clears the exited sentinel — see launch-vscode.js), so relaunching stops
+//    minting duplicate panes;
+//  - an older sidecar that sees a NEWER nonce yields its pane (see run()), so
+//    pasting the one-liner twice still converges to a single live panel.
+const HEARTBEAT_FILE = 'sidecar-alive';
+// "Fresh" = beaten within this window. Beats land ~1s apart; 5s tolerates a
+// busy machine without ever mistaking a dead pane (minutes old) for live.
+const HEARTBEAT_FRESH_MS = 5000;
+
+/** @param {string} s @returns {{ pid: number, start: number } | null} */
+function parseNonce(s) {
+  const m = /^(\d+):(\d+)$/.exec(s.trim());
+  return m ? { pid: Number(m[1]), start: Number(m[2]) } : null;
+}
+
+/**
+ * One heartbeat: re-claim the file with our nonce, unless a NEWER sidecar
+ * (later start; higher pid breaks a same-millisecond tie) holds it — then
+ * yield WITHOUT writing, so the newer panel's claim is never clobbered and
+ * exactly one of the two keeps beating. Unreadable or unparseable content is
+ * claimed over (a garbage file must not wedge the panel), and any fs error
+ * claims rather than kills the loop — the heartbeat is strictly best-effort.
+ * @param {string} stateDir @param {string} nonce
+ * @returns {'claimed' | 'yielded'}
+ */
+function heartbeatTick(stateDir, nonce) {
+  const file = path.join(stateDir, HEARTBEAT_FILE);
+  const mine = parseNonce(nonce);
+  try {
+    let cur = '';
+    try { cur = fs.readFileSync(file, 'utf8'); } catch { /* no heartbeat yet */ }
+    const other = cur && cur.trim() !== nonce ? parseNonce(cur) : null;
+    if (other && mine && (other.start > mine.start || (other.start === mine.start && other.pid > mine.pid))) {
+      return 'yielded';
+    }
+    fs.writeFileSync(file, nonce);
+  } catch { /* best-effort */ }
+  return 'claimed';
+}
+
+/**
+ * Remove the heartbeat on the way out — but only while it still holds OUR
+ * nonce; after a takeover the file belongs to the newer sidecar.
+ * @param {string} stateDir @param {string} nonce
+ */
+function clearHeartbeat(stateDir, nonce) {
+  const file = path.join(stateDir, HEARTBEAT_FILE);
+  try {
+    if (fs.readFileSync(file, 'utf8').trim() === nonce) fs.rmSync(file, { force: true });
+  } catch { /* already gone / unreadable — nothing to clear */ }
+}
+
+/**
+ * Is a sidecar attached to this state dir right now? Mtime-based, so a killed
+ * pane (whose stale file nobody cleared) reads as dead within seconds. Used by
+ * the VS Code launcher to print "already attached" instead of the split banner.
+ * @param {string} stateDir @param {{ now?: number, freshMs?: number }} [opts]
+ * @returns {boolean}
+ */
+function sidecarAlive(stateDir, opts = {}) {
+  const now = opts.now != null ? opts.now : Date.now();
+  const freshMs = opts.freshMs != null ? opts.freshMs : HEARTBEAT_FRESH_MS;
+  try {
+    return now - fs.statSync(path.join(stateDir, HEARTBEAT_FILE)).mtimeMs <= freshMs;
+  } catch {
+    return false;
+  }
+}
+
 // Live feed accumulator: tail the current transcript incrementally (by byte
 // offset) and roll up tool/skill events + per-session stats. Reset on session
 // switch. Best-effort — must never break the economy panel.
@@ -165,8 +238,14 @@ function frame() {
  * buildWtArgs) so this RIGHT pane closes first and the border sweeps left→right.
  * Side effects are injectable so the end-sweep is unit-testable.
  *
+ * A second sidecar pasted against the same state dir takes the heartbeat over
+ * (its nonce is newer); this one then paints a hand-off note and exits WITHOUT
+ * clearing the file — it now belongs to the newer panel. `beat`/`clearBeat`/
+ * `onYield` are injectable so the takeover is unit-testable too.
+ *
  * @param {{ exitOnEnd?: boolean, stateDir?: string, graceMs?: number,
  *   tick?: () => void, sentinelExists?: () => boolean,
+ *   beat?: () => ('claimed' | 'yielded'), clearBeat?: () => void, onYield?: () => void,
  *   setIntervalFn?: Function, setTimeoutFn?: Function,
  *   clearIntervalFn?: Function, clearTimeoutFn?: Function,
  *   exit?: () => void, onSignal?: (sig: string, handler: () => void) => void }} [opts]
@@ -180,6 +259,10 @@ function run(opts = {}) {
   const graceMs = opts.graceMs != null ? opts.graceMs : 200;
   const tick = opts.tick || frame;
   const sentinelExists = opts.sentinelExists || (() => fs.existsSync(path.join(stateDir, 'exited')));
+  const nonce = `${process.pid}:${Date.now()}`;
+  const beat = opts.beat || (() => heartbeatTick(stateDir, nonce));
+  const clearBeat = opts.clearBeat || (() => clearHeartbeat(stateDir, nonce));
+  const onYield = opts.onYield || (() => draw(bold('ccr') + '  ' + dim('another sidecar attached — this pane stood down') + '\n'));
   const setIntervalFn = opts.setIntervalFn || setInterval;
   const setTimeoutFn = opts.setTimeoutFn || setTimeout;
   const clearIntervalFn = opts.clearIntervalFn || clearInterval;
@@ -194,11 +277,13 @@ function run(opts = {}) {
   let id = null;
   let endTimer = null;
   let sinceRender = RENDER_MS; // render on the first loop
-  const stop = () => {
+  const teardown = (/** @type {boolean} */ clearHb) => {
     if (id != null) clearIntervalFn(id);
     if (endTimer != null) clearTimeoutFn(endTimer);
+    if (clearHb) clearBeat();
     exit();
   };
+  const stop = () => teardown(true);
   const checkEnd = () => {
     // Once the session has ended, paint it once then sweep this pane closed.
     if (exitOnEnd && endTimer == null && sentinelExists()) {
@@ -208,7 +293,13 @@ function run(opts = {}) {
   };
   const loop = () => {
     sinceRender += pollMs;
-    if (sinceRender >= RENDER_MS) { sinceRender = 0; tick(); }
+    if (sinceRender >= RENDER_MS) {
+      sinceRender = 0;
+      tick();
+      // Beat at render cadence (~1s). A newer sidecar owns the dir now →
+      // hand the state dir over and fold this pane, leaving ITS heartbeat.
+      if (beat() === 'yielded') { onYield(); teardown(false); return; }
+    }
     checkEnd();
   };
   loop();
@@ -220,5 +311,6 @@ function run(opts = {}) {
 
 // `updateFeed` + `composeFrame` are exported for tests (the incremental tail +
 // session-switch reset and the ended/waiting/render states are the subtle
-// parts); the live loop uses `run`.
-module.exports = { run, updateFeed, composeFrame };
+// parts); the live loop uses `run`. The heartbeat trio is exported for tests
+// and for the VS Code launcher's `sidecarAlive` check.
+module.exports = { run, updateFeed, composeFrame, heartbeatTick, clearHeartbeat, sidecarAlive };