claude-code-runrate 0.2.3 → 0.3.0

package/README.md

@@ -24,6 +24,9 @@ shows you the **economy** of a session:
 - **Resume advisor** (`ccr resume`) — recent sessions ranked by what they'd cost
   to bring back (context size, share of the window, cold/warm cache), then it
   hands selection to `claude --resume`.
+- **External tool panes** — the sidebar can render read-only status panes from
+  other tools via a strict JSON contract; **F3** cycles between the economy
+  panel and each configured pane (see [External tool panes](#external-tool-panes-sidebar)).
 
 For scripting and external tools (status bars, menu-bar widgets), `ccr economy
 --json` emits a stable, versioned model — see
@@ -79,6 +82,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
@@ -100,14 +110,71 @@ In `~/.claude/settings.json`:
 Code calls the status line frequently, and a resolved binary avoids per-tick
 latency.)
 
+## External tool panes (sidebar)
+
+The live sidebar can host **read-only panes from other tools**. A tool writes a
+small JSON blob beside its own artifacts; you list that file's path in ccr's
+config; the sidebar cycles between the economy panel and each configured pane
+(**F3** under tmux — the launcher binds it; `ccr cycle-view` on any host).
+
+Config lives at `~/.config/ccr/config.json` (`$XDG_CONFIG_HOME` respected,
+`CCR_CONFIG` overrides) — deliberately *not* in ccr's state dir, and never
+read from a repository:
+
+```json
+{ "panes": [ { "path": "/home/you/project/.your-tool/sidecar.json" } ] }
+```
+
+A pane is a full-height view carrying the producing tool's own rows — here
+`gherkin-trace`, whose blob ships as the golden example:
+
+```
+trace  gherkin-trace   2/2
+  refresh · 2026-08-01 14:10 · blob written 0s
+
+  ● attention     3   1 breach, 2 orphans
+  ● reviewed      8
+  ◌ heat          withheld   no natural break
+  ◌ binding       dark   no run manifest
+  ● fence         clean  ▁▅▂█
+  ● exceptions    0
+  · experimental  off
+```
+
+- ccr **reads the file, validates it, renders it** — that is the entire
+  integration. No subprocess, no plugin code, no schema knowledge of the
+  producing tool: a pane is data all the way down, and every blob string is
+  stripped of control bytes before it touches your terminal.
+- **Producers never know ccr exists.** You wire the join by hand, exactly like
+  Claude Code's own `statusLine` — neither side takes a dependency on the other.
+- **Config order is cycle order.** F3 goes economy panel → first pane → second
+  pane → back to economy; the `2/2` above is that position. Entries are never
+  de-duplicated, so listing one path twice gives you two panes. The config is
+  re-read every tick — adding a pane takes effect without relaunching.
+- **The producer is trusted for content, never for behaviour.** ccr executes
+  nothing from a blob and draws no value it has not validated, so a hostile file
+  cannot crash the panel or escape into your terminal — but what a pane *says*
+  is the producing tool's word, not ccr's. Point it only at files you would read
+  yourself.
+- A malformed config yields no panes and a malformed blob renders as a **named
+  error state** — never a crash, never a misrender.
+- The blob format is specified in
+  [`docs/PANE-CONTRACT.md`](docs/PANE-CONTRACT.md), with a golden example at
+  [`docs/pane-blob.golden.json`](docs/pane-blob.golden.json). Anything that
+  writes a conforming blob is a producer — there is no registry.
+
 ## Development
 
 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/bin/ccr.js

@@ -83,11 +83,27 @@ function main(argv) {
     case 'statusline': return cmdStatusline();
     case 'sidecar': return cmdSidecar(values['state-dir'], !!values.hint, !!values['exit-on-end']);
     case 'doctor': return require('../src/doctor').run();
+    case 'cycle-view': return cmdCycleView(values['state-dir']);
     case 'launch': return cmdLaunch(positionals[1]);
     default: return cmdLaunch(cmd);               // anything else → treat as a CCS profile
   }
 }
 
+/**
+ * `ccr cycle-view` — show the running sidecar's next view. Bound to a key by
+ * the launcher; the sidecar itself reads no input (see src/cycle-view.js).
+ * Always exits 0: a keypress that finds no live sidecar is a no-op, not an
+ * error worth painting over the user's terminal.
+ * @param {string|undefined} stateDirFlag
+ * @returns {number}
+ */
+function cmdCycleView(stateDirFlag) {
+  const stateDir = stateDirFlag || process.env.CCR_STATE_DIR
+    || require('node:path').join(require('node:os').homedir(), '.ccr');
+  require('../src/cycle-view').cycleView(stateDir);
+  return 0;
+}
+
 function readStdin() {
   try { return process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf8'); } catch { return ''; }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-runrate",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "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

@@ -12,6 +12,8 @@
 # state dirs keep concurrent profiles from colliding.
 #
 # Env overrides: CC_BIN, CCR_SESSION, CCR_STATE_DIR, CCR_SIDEBAR_PCT (default 34).
+# The tmux socket name follows the session name — each instance runs its own
+# tmux server, so `tmux ls` won't list ccr sessions (`tmux -L ccr-<profile> ls`).
 
 set -euo pipefail
 
@@ -25,6 +27,11 @@ if [ -n "$PROFILE" ] && ! printf '%s' "$PROFILE" | grep -qE '^[A-Za-z0-9._-]+$';
   exit 1
 fi
 
+# Escape a value for a SINGLE-QUOTED shell context: ' becomes '\''.
+# Correct for anything we pass through `sh -c`, which is one parsing layer.
+# NOT sufficient inside a tmux config string — see the F3 binding below for why.
+sq() { printf "%s" "$1" | sed "s/'/'\\\\''/g"; }
+
 # State lives under the user's home, never world-shared /tmp; create it
 # owner-only so other local users can't read captured status.
 umask 077
@@ -56,6 +63,16 @@ else
   STATE="${CCR_STATE_DIR:-$HOME/.ccr}"
 fi
 
+# Every instance gets its OWN tmux server, on a socket named after the session
+# (-L puts it under /tmp/tmux-$UID/). On a shared server, one server death —
+# a kill-server (2026-08-02: an agent inside one instance ran exactly that as
+# "cleanup" after a config parse check), a crash, a cgroup teardown — takes
+# down every concurrent profile at once; and root-table bindings like F2 are
+# server-global, so the last launch would steal the hotkey for all instances.
+# Isolation costs one visible thing: `tmux ls` won't list ccr sessions —
+# use `tmux -L ccr-<profile> ls`.
+SOCKET="$SESSION"
+
 mkdir -p "$STATE"
 chmod 700 "$HOME/.ccr" "$STATE" 2>/dev/null || true
 rm -f "$STATE/exited"
@@ -69,19 +86,91 @@ trap 'rm -f "$RUN_CONF"' EXIT
 cp "$REPO/sidecar/ccr.tmux.conf" "$RUN_CONF"
 
 # Clean re-launch.
-tmux kill-session -t "$SESSION" 2>/dev/null || true
+tmux -L "$SOCKET" kill-session -t "$SESSION" 2>/dev/null || true
 
-ENV_PREAMBLE="export CCR_STATE_DIR='$STATE'"
+# These strings are handed to `sh -c` by tmux — ONE parsing layer, so ordinary
+# shell escaping is both necessary and sufficient. $STATE and $SESSION are not
+# validated the way a profile name is (they come from $HOME and the CCR_SESSION
+# / CCR_STATE_DIR overrides), and an apostrophe in either would otherwise end
+# the quoting and run the remainder as a command.
+STATE_Q="$(sq "$STATE")"
+SESSION_Q="$(sq "$SESSION")"
+SOCKET_Q="$(sq "$SOCKET")"
+ENV_PREAMBLE="export CCR_STATE_DIR='$STATE_Q'"
 
 # Pane 0: claude/ccs with --settings. On exit, drop the sentinel then close.
-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"
+# Capture its pane id: the F2 hotkey below must target %N, never a relative
+# index (see the binding comment further down).
+CLAUDE_PANE="$(tmux -L "$SOCKET" new-session -d -P -F '#{pane_id}' -s "$SESSION" \
+  "$ENV_PREAMBLE; $CC_CMD --settings '$SETTINGS'; touch '$STATE_Q/exited'; sleep 2; tmux -L '$SOCKET_Q' kill-session -t '$SESSION_Q' 2>/dev/null")"
+tmux -L "$SOCKET" set-environment -t "$SESSION" CCR_STATE_DIR "$STATE"
+
+# Pane 1: the live economy sidebar. Capture its pane id so we can scope a hook to it.
+SIDEBAR_PANE="$(tmux -L "$SOCKET" 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 -L "$SOCKET" 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
 
-# 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 '"
+# F2 → /clear: the one hotkey ccr ships. The text is a CONSTANT in this script —
+# never configuration, never a prompt file, never blob content (the pane
+# subsystem has no path to a key binding at all; docs/PANE-CONTRACT.md). It
+# targets the pane id captured above, because a relative index like `.0`
+# retargets after any split or swap. confirm-before makes a stray F2 cost one
+# keypress rather than a whole context. If no pane id came back (a tmux too old
+# for `new-session -P`), NO hotkey is bound — never an approximate target.
+if [ -n "$CLAUDE_PANE" ]; then
+  printf "bind-key -n F2 confirm-before -p 'send /clear to Claude? (y/n) ' \"send-keys -t %s '/clear' Enter\"\n" \
+    "$CLAUDE_PANE" >> "$RUN_CONF"
+fi
+
+# F3 → cycle the sidebar's view (economy ⇄ each configured external pane).
+# It runs `ccr cycle-view`, which records a request the sidecar picks up on its
+# next tick; the sidecar never reads a keystroke itself, because an input
+# channel is precisely the capability the pane threat model denies it
+# (docs/PANE-CONTRACT.md). No confirm gate: cycling costs nothing and is undone
+# by pressing again.
+#
+# The paths go in a generated SCRIPT, not into the binding. $STATE, $REPO and
+# $NODE derive from $HOME, $CCR_STATE_DIR and the checkout location — none of
+# which this script validates the way it validates a profile name — and a lone
+# apostrophe in any of them used to close the quoting so the rest ran as a
+# command (reproduced 2026-08-02, and again after a first "fix").
+#
+# Shell-escaping alone is NOT enough here, which is the subtle part: a binding
+# in this file passes through TWO parsers. tmux reads the config line first and
+# processes backslashes inside its double quotes, so a shell-level '\'' arrives
+# at sh already stripped to '' — closing the quote after all. Escaping correctly
+# for both layers at once is the kind of thing that looks right and isn't.
+#
+# So: one parsing layer each. The helper script holds the paths with ordinary
+# shell quoting (sq is exactly right for that), and the config line names only
+# the helper's own mktemp path inside tmux SINGLE quotes, where tmux performs no
+# escape processing at all. If that path could itself contain a quote we bind
+# nothing rather than emit a line we cannot reason about.
+CYCLE_SH="$(mktemp "${TMPDIR:-/tmp}/ccr-cycle.XXXXXX")"
+trap 'rm -f "$RUN_CONF" "$CYCLE_SH"' EXIT
+{
+  printf '#!/bin/sh\n'
+  printf "exec '%s' '%s' cycle-view --state-dir '%s'\n" \
+    "$(sq "$NODE")" "$(sq "$REPO/bin/ccr.js")" "$(sq "$STATE")"
+} > "$CYCLE_SH"
+chmod 700 "$CYCLE_SH"
+case "$CYCLE_SH" in
+  *\'*) echo "ccr: TMPDIR contains a quote — F3 (cycle view) not bound" >&2 ;;
+  *) printf "bind-key -n F3 run-shell '%s'\n" "$CYCLE_SH" >> "$RUN_CONF" ;;
+esac
 
-tmux select-pane -t "$SESSION:0.0"
-tmux source-file -t "$SESSION" "$RUN_CONF"
-tmux attach -t "$SESSION"
+tmux -L "$SOCKET" select-pane -t "$SESSION:0.0"
+tmux -L "$SOCKET" source-file -t "$SESSION" "$RUN_CONF"
+tmux -L "$SOCKET" attach -t "$SESSION"

package/sidecar/ccr.tmux.conf

@@ -1,8 +1,16 @@
-# sidecar/ccr.tmux.conf — applies ONLY to ccr's own tmux session, never your
-# global tmux config. Minimal bindings — just F2 → /clear.
+# sidecar/ccr.tmux.conf — sourced into ccr's OWN tmux server (each instance
+# runs on its own -L socket; scripts/launch.sh), so the `set -g` lines and the
+# root-table binding below can never touch your personal tmux server or
+# another ccr profile's. Minimal bindings.
 
-# F2 — send /clear to the Claude pane (reset context before compaction hits).
-bind-key -n F2 send-keys -t .0 '/clear' Enter
+# The F2 → /clear hotkey is deliberately NOT bound here. scripts/launch.sh
+# appends it to the per-session copy of this file, because that is the only
+# place that knows the Claude pane's id (%N), captured when the session is
+# created. A binding written here could only name a RELATIVE index like `.0`,
+# which silently retargets after any split or swap — sending /clear to
+# whichever pane happens to be first at the time. See docs/PANE-CONTRACT.md
+# ("Hotkeys are a host capability"): configuration chooses which key, ccr's
+# own code chooses the text, and the target is always the captured id.
 
 set -g mouse on
 set -g status off

package/src/burn.js

@@ -131,11 +131,15 @@ function clearROI(o) {
     return { boughtMinutes: 0, projectedBurn: o.rate };
   }
   let ratio;
-  if (o.calib) {
-    const w = (x) => Math.max(o.calib.a * x + o.calib.b, 1e-9);
+  // Bind the calibration outside the closure: narrowing does not survive into a
+  // function body (the callback could in principle run after o.calib changed),
+  // and binding it also means the reader need not reason about reentrancy.
+  const calib = o.calib;
+  if (calib) {
+    const w = (/** @type {number} */ x) => Math.max(calib.a * x + calib.b, 1e-9);
     ratio = w(o.baselineB) / w(o.contextC);
   } else {
-    const w = (x) => READ_WEIGHT * x + K_TAIL;
+    const w = (/** @type {number} */ x) => READ_WEIGHT * x + K_TAIL;
     ratio = w(o.baselineB) / w(o.contextC);
   }
   // A clear can't shed the output/write tail or the retained baseline, so burn

package/src/cycle-view.js

@@ -0,0 +1,78 @@
+// @ts-check
+'use strict';
+// src/cycle-view.js — ask the running sidecar to show its next view.
+//
+// The sidecar reads no stdin, by construction: an input channel is exactly the
+// capability the pane threat model refuses it (docs/PANE-CONTRACT.md,
+// "Structural invariants"). So the host binds a key, the key runs this, and
+// this leaves a REQUEST the sidecar picks up on its next tick.
+//
+// WHY A FILE AND NOT A SIGNAL. The first version of this read the sidecar's pid
+// from its heartbeat file and sent SIGUSR1. That was wrong, and an adversarial
+// review reproduced the consequence: the heartbeat lives in a directory
+// anything running as the user can write (src/safe-read.js says so in its own
+// header), so writing "<victim_pid>:<now>" into it redirected the signal at any
+// process of the user's choosing — and SIGUSR1's default disposition is
+// terminate. A cosmetic "show me the next pane" key was a kill primitive.
+//
+// No guard fixes that, because the pid and its freshness both come from the
+// attacker's own file: a liveness probe only proves the victim exists. The
+// mechanism had to change, not gain checks. Writing a request costs the same
+// attacker exactly what they should get — the ability to change which pane is
+// on screen — and nothing else.
+//
+// The cost is latency: the sidecar notices on its next tick, so up to ~1s. That
+// is the honest price for not holding a loaded weapon, and a keypress that
+// repaints within a second reads as responsive anyway.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readTextCapped } = require('./safe-read');
+
+/** The request file the sidecar polls. Content is a counter, not a command. */
+const REQUEST_FILE = 'view-request';
+
+/**
+ * Record a request to advance the view. Never throws: a keypress that cannot
+ * write is a no-op, not an error worth painting over the user's terminal.
+ * @param {string} stateDir
+ * @returns {{ ok: boolean, reason?: string, count?: number }}
+ */
+function cycleView(stateDir) {
+  const file = path.join(stateDir, REQUEST_FILE);
+  // Monotonic counter rather than a timestamp: two presses inside the same
+  // millisecond must still read as two requests.
+  // Capped, regular-files-only: a fifo planted here would otherwise block this
+  // process forever, and under tmux run-shell every keypress would leak another
+  // hung node. Same rule as every other file the sidecar reads.
+  let count = 0;
+  const cur = (readTextCapped(file, 64) || '').trim();
+  if (/^\d+$/.test(cur)) count = Number(cur);
+  if (!Number.isSafeInteger(count) || count < 0) count = 0;
+
+  try {
+    // Never write THROUGH a symlink planted at this path.
+    try { if (fs.lstatSync(file).isSymbolicLink()) fs.rmSync(file, { force: true }); } catch { /* absent */ }
+    fs.writeFileSync(file, String(count + 1));
+    return { ok: true, count: count + 1 };
+  } catch {
+    return { ok: false, reason: 'state dir not writable' };
+  }
+}
+
+/**
+ * How many advance-requests have been recorded. The sidecar calls this each
+ * tick and advances its view by the DIFFERENCE since the previous tick, so a
+ * request that arrives while the pane is busy is never lost, and a burst of
+ * presses advances by the number pressed.
+ * @param {string} stateDir
+ * @returns {number}
+ */
+function readViewRequests(stateDir) {
+  const cur = (readTextCapped(path.join(stateDir, REQUEST_FILE), 64) || '').trim();
+  if (!/^\d+$/.test(cur)) return 0;
+  const n = Number(cur);
+  return Number.isSafeInteger(n) && n >= 0 ? n : 0;
+}
+
+module.exports = { cycleView, readViewRequests, REQUEST_FILE };

package/src/doctor.js

@@ -82,6 +82,7 @@ function run(opts = {}) {
 
   const ccs = hasFn('ccs');
   if (ccs) {
+    /** @type {string[]} */
     let profiles = [];
     try { profiles = fs.readdirSync(path.join(homedir, '.ccs', 'instances')).filter((p) => !p.startsWith('.')); } catch { /* none */ }
     // Profile + path come from the filesystem; sanitize before display.
@@ -106,6 +107,7 @@ function run(opts = {}) {
   }
   if (newest) {
     const ageMin = Math.round((Date.now() - newest.m) / 60000);
+    /** @type {string[]} */
     let keys = [];
     try { keys = Object.keys(JSON.parse(fs.readFileSync(path.join(newest.d, 'last-status.json'), 'utf8')).rate_limits || {}); } catch { /* ignore */ }
     // Defense-in-depth: sanitize the dir + bucket keys before display even

package/src/economy-model.js

@@ -38,6 +38,9 @@ function band(min) {
  * @returns {{ rows: any[], next: any }}
  */
 function classifyWindows(view) {
+  // Annotated because Array.isArray does not narrow an `any`: without this the
+  // whole chain below decays to `any` and the row callbacks lose their types.
+  /** @type {any[]} */
   const windows = Array.isArray(view.windows) ? view.windows : [];
   const rows = windows.map((/** @type {any} */ wd) => {
     const est = windowEstimate({ usedPct: wd.usedPct, rate: wd.rate, minutesToReset: wd.minutesToReset, windowMinutes: wd.windowMinutes });

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/liveness.js

@@ -20,6 +20,23 @@ function envStaleMs() {
   return Number.isFinite(v) && v > 0 ? v : null;
 }
 
+/**
+ * Snapshot age for the freshness note. Minutes roll into hours and hours into
+ * days: an overnight-idle pane used to read "updated 1500m ago", which is
+ * accurate and unreadable.
+ * @param {number} ageMs
+ * @returns {string}
+ */
+function fmtAge(ageMs) {
+  const m = Math.floor(ageMs / 60000);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) { const r = m % 60; return r ? `${h}h${String(r).padStart(2, '0')}m` : `${h}h`; }
+  const d = Math.floor(h / 24);
+  const rh = h % 24;
+  return rh ? `${d}d${rh}h` : `${d}d`;
+}
+
 /**
  * @param {{ exited?: boolean, ageMs?: number, staleMs?: number }} input
  * @returns {{ mode: 'ended' | 'live', marker: string | null }}
@@ -32,7 +49,7 @@ function liveness(input) {
 
   const ageMs = input.ageMs ?? 0;
   const staleMs = input.staleMs ?? envStaleMs() ?? DEFAULT_STALE_MS;
-  const marker = ageMs >= staleMs ? `updated ${Math.floor(ageMs / 60000)}m ago` : null;
+  const marker = ageMs >= staleMs ? `updated ${fmtAge(ageMs)} ago` : null;
   return { mode: 'live', marker };
 }
 

package/src/normalize.js

@@ -7,6 +7,21 @@
 const { discoverWindows } = require('./rate-limits');
 const { stripControl } = require('./sanitize');
 
+/**
+ * A finite number, or null. The snapshot is a JSON file on disk: it chooses its
+ * own value types, and a `!= null` check accepts the string "1.5" as happily as
+ * 1.5. Downstream does arithmetic and calls `.toFixed()`, so one wrong type is
+ * a TypeError inside the draw loop — which the sidecar catches, but only by
+ * replacing the whole economy panel with an error line, every tick, until the
+ * file changes. Type-check at ingestion; a bad field costs itself and nothing
+ * else. (NaN/Infinity are excluded too — they render as "NaN%" meters.)
+ * @param {any} v
+ * @returns {number|null}
+ */
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
 /**
  * @param {any} state CC status-line JSON
  * @param {number} [nowSec] override for testing
@@ -15,16 +30,20 @@ const { stripControl } = require('./sanitize');
 function normalizeStatus(state, nowSec) {
   const rl = (state && state.rate_limits) || {};
   const cw = (state && state.context_window) || {};
+  const cost = (state && state.cost) || {};
+  const durationMs = num(cost.total_duration_ms);
   return {
     model: stripControl((state && state.model && state.model.display_name) || null),
-    windowSize: cw.context_window_size || 200000,
+    // Must be positive: it is a divisor for the ctx meter, and `?? ` (unlike the
+    // `||` this replaced) would let a literal 0 through to divide by zero.
+    windowSize: (num(cw.context_window_size) || 0) > 0 ? cw.context_window_size : 200000,
     windows: discoverWindows(rl, nowSec),
-    contextTokens: cw.total_input_tokens
-      ?? (cw.current_usage && cw.current_usage.cache_read_input_tokens) ?? null,
+    contextTokens: num(cw.total_input_tokens)
+      ?? num(cw.current_usage && cw.current_usage.cache_read_input_tokens),
     cachedPct: null,
     baselineTok: 14000,
-    costUsd: state && state.cost && state.cost.total_cost_usd != null ? state.cost.total_cost_usd : null,
-    durationMin: state && state.cost && state.cost.total_duration_ms != null ? state.cost.total_duration_ms / 60000 : null,
+    costUsd: num(cost.total_cost_usd),
+    durationMin: durationMs != null ? durationMs / 60000 : null,
     branch: null,
   };
 }