claude-code-runrate 0.2.2 → 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.2",
+  "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/account-limits.js

@@ -0,0 +1,165 @@
+// @ts-check
+'use strict';
+// src/account-limits.js — reconcile the ACCOUNT-WIDE rate-limit meters across the
+// live ccr profiles (cq/cw/ce/cr, …) so their sidecars agree.
+//
+// THE PROBLEM. The 5h and weekly walls are one shared account resource, but each
+// ccr profile only captures them when ITS OWN Claude session renders the status
+// line. Claude Code re-emits the status line per turn, not on a clock, so an idle
+// profile keeps showing the numbers from its last turn. Two sidecars open
+// side-by-side therefore disagree purely by capture time — the busy one is ahead,
+// the idle one lags. (The model in use is irrelevant: 5h/weekly are not
+// model-scoped.) We fix this by raising each meter the LOCAL profile already knows
+// to the freshest value seen across sibling profiles.
+//
+// THE GUARD — never mix accounts. The snapshot carries no account/org id, so we
+// cannot ask "same account?" directly. Instead we trust bucket IDENTITY: the
+// account-wide windows (5h, weekly — the buckets with no model scope) reset on a
+// per-account schedule, so at any instant every session on one account reports the
+// same resets_at for them. We build an "account fingerprint" from exactly those
+// buckets (key + reset instant) and merge a sibling ONLY when its fingerprint is
+// byte-for-byte the local one. A different account would have to collide on every
+// one of those independent reset timestamps at once (5h AND weekly) — negligible.
+// A sibling from an already-rolled window has a different reset instant, so it is
+// distrusted too (its used% is stale, not fresher). We never import a bucket the
+// local snapshot lacks and never adopt a sibling's resets_at — we only ever raise
+// the used% of a bucket the local profile is already showing. So a profile logged
+// into its own account is never contaminated by another.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { parseResetsAt } = require('./burn');
+const { modelScope } = require('./rate-limits');
+
+const MAX_SNAPSHOT_BYTES = 1_000_000; // a status JSON is a few KB; bound parse/disk
+const MAX_PROFILES = 32;              // sanity cap on how many siblings we scan
+
+/**
+ * Canonical reset instant for fingerprinting/matching — tolerant of CC reporting
+ * resets_at as epoch seconds or an ISO string. `null` when absent/unparseable.
+ * @param {any} bucket
+ * @returns {number | null}
+ */
+function resetInstant(bucket) {
+  return bucket && bucket.resets_at != null ? parseResetsAt(bucket.resets_at) : null;
+}
+
+/**
+ * The same-account signal: a stable string built from the ACCOUNT-WIDE buckets
+ * only (no model scope), each as `key@reset`. Buckets missing a used% or a reset
+ * are excluded — they can't anchor trust. Returns `null` when there is nothing to
+ * anchor on (no usable account-wide bucket), which callers treat as "don't merge".
+ * @param {any} rateLimits
+ * @returns {string | null}
+ */
+function accountFingerprint(rateLimits) {
+  if (!rateLimits || typeof rateLimits !== 'object') return null;
+  const parts = [];
+  for (const key of Object.keys(rateLimits)) {
+    if (modelScope(key)) continue;                 // model-scoped ≠ account-wide anchor
+    const r = rateLimits[key];
+    if (!r || typeof r !== 'object' || r.used_percentage == null) continue;
+    const at = resetInstant(r);
+    if (at == null) continue;
+    parts.push(`${key}@${at}`);
+  }
+  return parts.length ? parts.sort().join('|') : null;
+}
+
+/**
+ * Raise each of the local profile's meters to the freshest value seen across
+ * sibling profiles ON THE SAME ACCOUNT. Pure: no I/O. Returns the local rate_limits
+ * unchanged (same reference) when there is nothing trustworthy to merge.
+ *
+ * @param {any} localRl the local snapshot's `rate_limits`
+ * @param {any[]} siblingRls other profiles' `rate_limits` objects (account-untrusted)
+ * @returns {any} a shallow clone with used_percentage bumped where warranted, or `localRl`
+ */
+function mergeAccountLimits(localRl, siblingRls) {
+  const fp = accountFingerprint(localRl);
+  if (!fp) return localRl;                         // nothing to anchor trust on
+  const trusted = (siblingRls || []).filter((rl) => accountFingerprint(rl) === fp);
+  if (!trusted.length) return localRl;
+
+  let changed = false;
+  /** @type {any} */
+  const out = {};
+  for (const key of Object.keys(localRl)) {
+    const local = localRl[key];
+    out[key] = local;
+    if (!local || typeof local !== 'object' || local.used_percentage == null) continue;
+    let best = Number(local.used_percentage);
+    if (!Number.isFinite(best)) continue;
+    const at = resetInstant(local);
+    for (const rl of trusted) {
+      const s = rl[key];
+      if (!s || typeof s !== 'object') continue;
+      // Same window only — a sibling whose bucket reset at a different instant is
+      // from a rolled (or foreign) window; its used% does not describe this one.
+      if (resetInstant(s) !== at) continue;
+      const v = Number(s.used_percentage);
+      if (Number.isFinite(v) && v > best) best = v;
+    }
+    if (best !== local.used_percentage) { out[key] = { ...local, used_percentage: best }; changed = true; }
+  }
+  return changed ? out : localRl;
+}
+
+/**
+ * Read a sibling snapshot's `rate_limits`, best-effort. Bounded read; any error
+ * (missing, oversized, unparseable) yields `null` so a bad sibling is simply
+ * skipped rather than breaking the panel.
+ * @param {string} file
+ * @returns {any | null}
+ */
+function readSiblingRateLimits(file) {
+  try {
+    const st = fs.statSync(file);
+    if (!st.isFile() || st.size > MAX_SNAPSHOT_BYTES) return null;
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return (j && j.rate_limits) || null;
+  } catch { return null; }
+}
+
+/**
+ * Disk wrapper: gather sibling profiles' rate limits from the ccr profile root and
+ * reconcile the local meters against them. Best-effort — returns `localRl` on any
+ * problem so it can wrap the render path without a guard at the call site.
+ *
+ * Engages ONLY for the launcher's profile layout (`~/.ccr/<profile>`): the state
+ * dir's parent must be `~/.ccr`. For ad-hoc `~/.ccr` or a custom CCR_STATE_DIR we
+ * have no sibling set to trust, so we behave exactly as before (no merge).
+ *
+ * @param {any} localRl the local snapshot's `rate_limits`
+ * @param {string} stateDir the local profile's state dir (CCR_STATE_DIR)
+ * @param {{ home?: string }} [opts]
+ * @returns {any}
+ */
+function freshenAccountLimits(localRl, stateDir, opts = {}) {
+  try {
+    if (!localRl || typeof localRl !== 'object') return localRl;
+    const home = opts.home || os.homedir();
+    const root = path.dirname(path.resolve(stateDir));
+    if (root !== path.resolve(path.join(home, '.ccr'))) return localRl; // not a profile layout
+    const selfFile = path.resolve(path.join(stateDir, 'last-status.json'));
+
+    /** @type {any[]} */
+    const siblings = [];
+    for (const name of fs.readdirSync(root)) {
+      if (siblings.length >= MAX_PROFILES) break;
+      const p = path.join(root, name);
+      let st; try { st = fs.statSync(p); } catch { continue; }
+      // A sibling profile dir (~/.ccr/<name>/last-status.json) or the ad-hoc
+      // ~/.ccr/last-status.json file itself.
+      const file = st.isDirectory() ? path.join(p, 'last-status.json')
+        : (name === 'last-status.json' ? p : null);
+      if (!file || path.resolve(file) === selfFile) continue;
+      const rl = readSiblingRateLimits(file);
+      if (rl) siblings.push(rl);
+    }
+    return mergeAccountLimits(localRl, siblings);
+  } catch { return localRl; }
+}
+
+module.exports = { accountFingerprint, mergeAccountLimits, freshenAccountLimits };

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

@@ -9,6 +9,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { normalizeStatus } = require('./normalize');
+const { freshenAccountLimits } = require('./account-limits');
 const { renderEconomy } = require('./render/economy');
 const { renderFeed } = require('./render/feed');
 const { clampVisible } = require('./render/shared');
@@ -17,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.
@@ -88,7 +162,12 @@ function composeFrame(stateDir, opts = {}) {
   try { state = JSON.parse(raw); } catch { return clamp(dim('ccr · status unreadable') + '\n'); }
   let out;
   try {
-    out = renderEconomy(normalizeStatus(state), { tick: Math.floor(now / 1000) % 2 === 0 });
+    // 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 });
   } catch (e) {
     out = dim('ccr render error: ' + (e && e instanceof Error ? e.message : String(e)));
   }
@@ -159,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]
@@ -174,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;
@@ -188,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()) {
@@ -202,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();
@@ -214,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 };