claude-code-runrate 0.1.0 → 0.2.0

package/README.md

@@ -51,15 +51,42 @@ npm i -g claude-code-runrate
 | `ccr economy --json` | Stable machine-readable model (scripting) | ✅ | ✅ | ✅ |
 | `ccr resume` | Recent sessions ranked by cost to resume | ✅ | ✅ | ✅ |
 | `ccr statusline` | One-line summary wired into CC's `statusLine` | ✅ | ✅ | ✅ |
-| `ccr sidecar` | Live tmux dashboard + tool/skills feed | ✅ | ✅ | ⛔ (tmux; use WSL) |
+| `ccr sidecar` | Live dashboard + tool/skills feed | ✅ tmux | ✅ tmux | ✅ Windows Terminal / VS Code |
 
-The CLI and statusline are pure Node — they run on native Windows. The rich live
-sidebar needs `tmux`, so on Windows use WSL.
+The CLI and statusline are pure Node — they run on native Windows. The live
+sidebar runs on **Windows Terminal** (`ccr` splits it automatically) or inside
+**VS Code's integrated terminal** on any OS (see [VS Code](#vs-code-split-terminal)).
+On Linux/macOS the default host is `tmux`. No WSL required.
 
 ## Requirements
 
 - **Node ≥ 18.3** — that's it for the core. **Zero runtime dependencies.**
-- `tmux` — only for the optional `ccr sidecar`.
+- For the optional live `ccr sidecar`: `tmux` on Linux/macOS, or **Windows
+  Terminal** / **VS Code's integrated terminal** on Windows (no WSL).
+
+## VS Code (split terminal)
+
+`ccr` detects VS Code's integrated terminal (`TERM_PROGRAM=vscode`) and wires the
+live sidebar into a **split pane** — no separate window, no WSL. A shell can't
+trigger the split itself, so `ccr` does everything around it:
+
+1. Run `ccr` (or `ccr <profile>`). Claude starts in the **current** pane and a
+   bright banner shows the steps. The sidecar command is **copied to your
+   clipboard** automatically (via an OSC 52 escape — works over SSH/remote too).
+2. **Split the terminal** — `Ctrl+Shift+5` (Windows/Linux) or `Cmd+\` (macOS).
+3. **Paste** into the new pane and press Enter — the live sidebar runs there.
+
+Lost the banner once Claude takes the screen? Run `ccr sidecar --hint` to reprint
+the steps and re-copy the command.
+
+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
+`CCR_VSCODE=1` to use the split-terminal flow there instead.
+
+> Automating the split keystroke itself would need a VS Code extension (the `code`
+> CLI has no "run command" verb) — out of scope for the zero-dependency core. The
+> clipboard + `--hint` reduce it to split-and-paste.
 
 ## Wiring the statusline into Claude Code
 
@@ -77,7 +104,10 @@ 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.
+Node's built-in test runner — a ~250-line 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.
 
 ```bash
 npm test            # node --test — harness self-tests + feature scenarios

package/bin/ccr.js

@@ -40,7 +40,8 @@ Examples:
 
 Options:
   -h, --help     Show this help
-  -v, --version  Show version`;
+  -v, --version  Show version
+      --mary     Enable the mary interface`;
 
 /**
  * @param {string[]} argv
@@ -56,6 +57,9 @@ function main(argv) {
         help: { type: 'boolean', short: 'h' },
         version: { type: 'boolean', short: 'v' },
         json: { type: 'boolean' },
+        'state-dir': { type: 'string' },
+        hint: { type: 'boolean' },
+        mary: { type: 'boolean' },
       },
     });
   } catch (err) {
@@ -66,6 +70,9 @@ function main(argv) {
   const { values, positionals } = parsed;
   if (values.version) { process.stdout.write(`${pkg.version}\n`); return 0; }
   if (values.help) { process.stdout.write(`${HELP}\n`); return 0; }
+  // The mary interface is an env toggle under the hood; surface it as a flag so
+  // in-process panels (economy/statusline/resume) pick it up for this run.
+  if (values.mary) process.env.CCR_ENABLE_MARY_INTERFACE = '1';
 
   const cmd = positionals[0];
   if (!cmd) return cmdLaunch(undefined);          // bare `ccr` → launch
@@ -73,7 +80,7 @@ function main(argv) {
     case 'economy': return cmdEconomy(!!values.json);
     case 'resume': return cmdResume(positionals[1]);
     case 'statusline': return cmdStatusline();
-    case 'sidecar': return cmdSidecar();
+    case 'sidecar': return cmdSidecar(values['state-dir'], !!values.hint);
     case 'doctor': return require('../src/doctor').run();
     case 'launch': return cmdLaunch(positionals[1]);
     default: return cmdLaunch(cmd);               // anything else → treat as a CCS profile
@@ -151,26 +158,37 @@ function cmdResume(arg) {
   return 0;
 }
 
-/** `ccr sidecar` — live economy panel; keeps the process alive (no exit code). */
-function cmdSidecar() {
+/**
+ * `ccr sidecar` — live economy panel; keeps the process alive (no exit code).
+ * `--state-dir <dir>` targets a specific session (used by the VS Code split-pane
+ * one-liner, which is shell-agnostic). `--hint` reprints the VS Code split
+ * instructions + re-copies the one-liner instead of running the panel.
+ * @param {string | undefined} stateDir
+ * @param {boolean} [showHint]
+ * @returns {number | undefined}
+ */
+function cmdSidecar(stateDir, showHint) {
+  if (stateDir) process.env.CCR_STATE_DIR = stateDir;
+  if (showHint) return require('../src/launch-vscode').hint(process.env.CCR_STATE_DIR || STATE_DIR);
   require('../src/sidecar').run();
   return undefined;
 }
 
 /**
- * `ccr [profile]` — launch the tmux session (claude/ccs + sidebar) via launch.sh.
+ * `ccr [profile]` — launch the live sidecar. Inside VS Code's integrated terminal
+ * we split it in place (Windows always; other OSes via CCR_VSCODE=1, since tmux
+ * already works there); on native Windows we drive Windows Terminal; otherwise
+ * the tmux launcher (scripts/launch.sh).
  * @param {string | undefined} profile
  * @returns {number}
  */
 function cmdLaunch(profile) {
+  const inVscode = process.env.TERM_PROGRAM === 'vscode';
+  if (inVscode && (process.platform === 'win32' || process.env.CCR_VSCODE === '1')) {
+    return require('../src/launch-vscode').run(profile);
+  }
   if (process.platform === 'win32') {
-    process.stderr.write(
-      'ccr: the live sidebar needs tmux + bash, which native Windows lacks.\n' +
-      '     Use WSL for the sidebar, or run these directly (they work natively):\n' +
-      '       ccr economy      one-off economy panel\n' +
-      "       ccr statusline   wire into Claude Code's statusLine\n" +
-      '       ccr doctor       check your setup\n');
-    return 1;
+    return require('../src/launch-win').run(profile);
   }
   const { spawnSync } = require('node:child_process');
   const launcher = path.join(__dirname, '..', 'scripts', 'launch.sh');

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "claude-code-runrate",
-  "version": "0.1.0",
+  "version": "0.2.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>",
-  "repository": { "type": "git", "url": "git+https://github.com/bingh0/ccr.git" },
-  "bugs": { "url": "https://github.com/bingh0/ccr/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bingh0/ccr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bingh0/ccr/issues"
+  },
   "homepage": "https://github.com/bingh0/ccr#readme",
   "type": "commonjs",
   "bin": {
@@ -24,7 +29,8 @@
   ],
   "scripts": {
     "test": "node --test",
-    "typecheck": "tsc --noEmit -p jsconfig.json"
+    "typecheck": "tsc --noEmit -p jsconfig.json",
+    "lint": "oxlint"
   },
   "keywords": [
     "claude-code",
@@ -36,6 +42,7 @@
   "dependencies": {},
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "oxlint": "^1.71.0",
     "typescript": "^5.7.0"
   }
 }

package/src/doctor.js

@@ -34,10 +34,19 @@ function isExec(/** @type {string} */ f) {
   try { return (fs.statSync(f).mode & 0o111) !== 0; } catch { return false; }
 }
 
-/** @returns {number} exit code (0 = healthy) */
-function run() {
-  const REPO = path.join(__dirname, '..');
-  const isWin = process.platform === 'win32';
+/**
+ * @param {{ platform?: string, has?: (cmd: string) => (string|null),
+ *   homedir?: string, repo?: string, write?: (s: string) => void }} [opts]
+ *   side effects are injectable for testing; defaults hit the real environment
+ * @returns {number} exit code (0 = healthy)
+ */
+function run(opts = {}) {
+  const platform = opts.platform || process.platform;
+  const hasFn = opts.has || has;
+  const homedir = opts.homedir || os.homedir();
+  const REPO = opts.repo || path.join(__dirname, '..');
+  const write = opts.write || ((s) => { process.stdout.write(s); });
+  const isWin = platform === 'win32';
   const out = [bold('ccr doctor'), ''];
   let problems = 0;
 
@@ -46,29 +55,35 @@ function run() {
   out.push(nodeOk ? ok(`node ${process.version}`) : bad(`node ${process.version} — need >= 18.3`));
   if (!nodeOk) problems++;
 
-  const ccr = has('ccr');
+  const ccr = hasFn('ccr');
   out.push(ccr ? ok(`ccr on PATH (${stripControl(ccr)})`) : warn('ccr not on PATH — run `npm link` in the repo'));
   if (!ccr) problems++;
 
   if (isWin) {
-    // The live sidebar (tmux + bash) is WSL-only on native Windows — by design,
-    // not a problem. Say so plainly so a Windows user isn't told to "fix" it.
-    out.push(dim('· live sidebar (`ccr`) needs tmux + bash — for that, use WSL2.'));
-    out.push(dim('  The CLI (economy / statusline / resume / doctor) runs natively here.'));
+    // Native Windows hosts the sidecar in Windows Terminal — no tmux/bash/WSL.
+    const wt = hasFn('wt');
+    if (wt) {
+      out.push(ok(`Windows Terminal (sidecar host) (${stripControl(wt)})`));
+    } else {
+      out.push(warn('Windows Terminal not found — the sidecar needs it (winget install Microsoft.WindowsTerminal); the CLI still works'));
+      problems++;
+    }
+    // statusLine is injected inline (node + bin/ccr.js by path) via the per-launch
+    // temp settings file, so there's no shipped shim asset to check on Windows.
   } else {
-    const tmux = has('tmux');
-    out.push(tmux ? ok(`tmux (${stripControl(tmux)})`) : warn('tmux missing — needed for `ccr [profile]` sidebar (use WSL on Windows)'));
+    const tmux = hasFn('tmux');
+    out.push(tmux ? ok(`tmux (${stripControl(tmux)})`) : warn('tmux missing — needed for the `ccr [profile]` sidebar'));
     if (!tmux) problems++;
-    out.push(has('bash') ? ok('bash') : warn('bash missing — needed for the launcher'));
+    out.push(hasFn('bash') ? ok('bash') : warn('bash missing — needed for the launcher'));
 
     const sl = path.join(REPO, 'sidecar', 'ccr-statusline');
     out.push(isExec(sl) ? ok('sidecar/ccr-statusline is executable') : warn('sidecar/ccr-statusline not executable (the launcher self-heals this)'));
   }
 
-  const ccs = has('ccs');
+  const ccs = hasFn('ccs');
   if (ccs) {
     let profiles = [];
-    try { profiles = fs.readdirSync(path.join(os.homedir(), '.ccs', 'instances')).filter((p) => !p.startsWith('.')); } catch { /* none */ }
+    try { profiles = fs.readdirSync(path.join(homedir, '.ccs', 'instances')).filter((p) => !p.startsWith('.')); } catch { /* none */ }
     // Profile + path come from the filesystem; sanitize before display.
     out.push(ok(`ccs (${stripControl(ccs)}) · profiles: ${profiles.map(stripControl).join(', ') || '(none)'}`));
   } else {
@@ -77,7 +92,7 @@ function run() {
 
   // newest captured snapshot across ~/.ccr and its per-profile subdirs (state
   // lives under the user's home now, never world-shared /tmp).
-  const ccrDir = path.join(os.homedir(), '.ccr');
+  const ccrDir = path.join(homedir, '.ccr');
   const dirs = [ccrDir];
   try {
     for (const d of fs.readdirSync(ccrDir)) {
@@ -98,17 +113,12 @@ function run() {
     out.push(ok(`status captured ${ageMin}m ago (${stripControl(newest.d)})`));
     out.push(dim(`  buckets: ${keys.map(stripControl).join(', ') || '(none — API session?)'}`));
   } else {
-    out.push(warn(isWin
-      ? 'no status captured yet — wire `ccr statusline` into Claude Code (settings.json) to start capturing'
-      : 'no status captured yet — launch with `ccr` (or `ccr <profile>`) to start capturing'));
+    out.push(warn('no status captured yet — launch with `ccr` (or `ccr <profile>`) to start capturing'));
   }
 
   out.push('');
-  const allGood = isWin
-    ? 'all good — `ccr economy` for the panel, `ccr statusline` to wire into CC'
-    : 'all good — `ccr` to launch, `ccr economy` for the panel';
-  out.push(problems ? warn(`${problems} thing(s) to address above`) : ok(allGood));
-  process.stdout.write(out.join('\n') + '\n');
+  out.push(problems ? warn(`${problems} thing(s) to address above`) : ok('all good — `ccr` to launch, `ccr economy` for the panel'));
+  write(out.join('\n') + '\n');
   return problems ? 1 : 0;
 }
 

package/src/launch-vscode.js

@@ -0,0 +1,288 @@
+// @ts-check
+'use strict';
+// src/launch-vscode.js — split-terminal launcher for VS Code's integrated
+// terminal (any OS). Unlike the wt.exe path (a separate window) or tmux (a real
+// multiplexer), a shell process CANNOT split the VS Code terminal itself — the
+// `code` CLI exposes no "run command" verb. So we automate everything AROUND the
+// split: do all the state/statusLine wiring, run Claude in the CURRENT pane, and
+// hand the user a prominent, clipboard-copied one-liner for the new pane.
+//
+//   run(profile)  → banner + clipboard + Claude in this pane; sidecar one-liner
+//                   for the split pane (Ctrl+Shift+5 / Cmd+\).
+//   hint(dir)     → reprint that banner + re-copy the one-liner (no Claude).
+//
+// The zero-dependency / no-config-mutation contracts are preserved exactly as in
+// launch-win: statusLine is injected via a per-launch temp settings file.
+
+const path = require('node:path');
+const os = require('node:os');
+const launchWin = require('./launch-win');
+const inject = require('./settings-inject');
+const { ensureSecureDir } = require('./state-dir');
+
+/**
+ * VS Code's "Split Terminal" default keybinding, per platform.
+ * @param {string} [platform]
+ * @returns {string}
+ */
+function splitKeybinding(platform) {
+  return (platform || process.platform) === 'darwin' ? 'Cmd+\\' : 'Ctrl+Shift+5';
+}
+
+/**
+ * The command the user runs in the split pane. Carries the resolved state dir as
+ * an explicit arg (shell-agnostic: no per-shell `set`/`$env:`/`export` needed).
+ * Prefers the `ccr` binary when on PATH; falls back to node + ccr.js by path.
+ * @param {{ stateDir: string, ccrBin?: string|null, node: string, ccrJs: string, hint?: boolean }} o
+ * @returns {string}
+ */
+function sidecarPasteCommand(o) {
+  const head = o.ccrBin ? 'ccr' : `"${o.node}" "${o.ccrJs}"`;
+  const tail = o.hint ? ' --hint' : ` --state-dir "${o.stateDir}"`;
+  return `${head} sidecar${tail}`;
+}
+
+/**
+ * OSC 52 clipboard-set escape — zero-dep, works over SSH/remote/dev-containers,
+ * and honored by VS Code's terminal. Setting the clipboard needs no native tool.
+ * @param {string} text
+ * @returns {string}
+ */
+function osc52(text) {
+  return `\x1b]52;c;${Buffer.from(text, 'utf8').toString('base64')}\x07`;
+}
+
+/**
+ * The prominent, scrollback-findable banner. A bright reverse-video header plus a
+ * blinking ▶/◀ marker is the "animated cue" — terminals honoring blink animate
+ * it (live AND when scrolled to); elsewhere it degrades to a bold static banner.
+ * @param {{ sidecarCmd: string, splitKey: string, hintCmd: string, color: boolean }} o
+ * @returns {string}
+ */
+function buildBanner(o) {
+  const c = o.color ? (/** @type {string} */ code, /** @type {string} */ s) => `\x1b[${code}m${s}\x1b[0m` : (/** @type {string} */ _code, /** @type {string} */ s) => s;
+  const blink = o.color ? (/** @type {string} */ s) => `\x1b[5m${s}\x1b[25m` : (/** @type {string} */ s) => s;
+  return [
+    '',
+    c('1;30;103', `  ${blink('▶')}  ccr · live sidecar — split your VS Code terminal  ${blink('◀')}  `),
+    '',
+    `  ${c('1;96', '1.')} Split this terminal:  ${c('1;97', o.splitKey)}`,
+    `  ${c('1;96', '2.')} In the new pane, run ${c('2', '(already on your clipboard — just paste)')}:`,
+    '',
+    `       ${c('1;92', o.sidecarCmd)}`,
+    '',
+    c('2', `  Claude is starting in THIS pane. Lost these steps? Run:  ${o.hintCmd}`),
+    '',
+  ].join('\n') + '\n';
+}
+
+/**
+ * Best-effort copy: OSC 52 first (covers VS Code + remote), then a native tool
+ * for terminals with OSC 52 disabled. Never throws; silent if nothing is found.
+ * @param {string} text
+ * @param {{ platform: string, out: (s: string) => void, spawnCopy: (cmd: string, args: string[], input: string) => { status: number|null, error?: Error } }} d
+ */
+function copyToClipboard(text, d) {
+  try { d.out(osc52(text)); } catch { /* terminal may not support OSC 52 */ }
+  const p = d.platform;
+  const attempts = p === 'win32' ? [['clip', []]]
+    : p === 'darwin' ? [['pbcopy', []]]
+    : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']]];
+  for (const [cmd, args] of attempts) {
+    try {
+      const r = d.spawnCopy(String(cmd), /** @type {string[]} */ (args), text);
+      if (r && !r.error && (r.status === 0 || r.status == null)) return;
+    } catch { /* try the next tool */ }
+  }
+}
+
+/**
+ * `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.
+ * @param {string} [profile]
+ * @param {Partial<Deps>} [deps]
+ * @returns {number}
+ */
+function run(profile, deps = {}) {
+  const d = withDefaults(deps);
+
+  if (profile !== undefined && !launchWin.validateProfile(profile)) {
+    d.err(`ccr: invalid profile name '${profile}' (allowed: letters, digits, . _ -)\n`);
+    return 1;
+  }
+
+  const st = launchWin.resolveProfileState(profile, { env: d.env, home: d.home });
+  if (st.usesCcs) {
+    if (!d.which('ccs')) {
+      d.err("ccr: 'ccs' not found on PATH — pass a profile only if CCS is installed.\n");
+      return 1;
+    }
+    if (st.instanceDir && !d.existsDir(st.instanceDir)) {
+      d.err(`ccr: CCS profile '${profile}' not found (${st.instanceDir}).\n`);
+      d.err(`     available: ${d.listDir(path.join(d.home, '.ccs', 'instances')).join(' ')}\n`);
+      return 1;
+    }
+  } else {
+    const bin = st.ccCmd.split(' ')[0];
+    if (!d.which(bin)) { d.err(`ccr: '${bin}' not found on PATH.\n`); return 1; }
+  }
+
+  try { d.ensureDir(st.stateDir); } catch { /* best effort */ }
+  d.removeExited(st.stateDir);
+
+  // statusLine via a per-launch temp settings file (no ~/.claude mutation).
+  const command = inject.buildStatusLineCommandInline({ node: d.node, ccrJs: d.ccrJs });
+  const settingsFile = d.writeSettings(inject.buildSettings(command));
+
+  // 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).
+  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);
+
+  // 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".
+  const parts = st.ccCmd.split(' ');
+  const r = d.spawnClaude(parts[0], [...parts.slice(1), '--settings', settingsFile]);
+  d.cleanup(settingsFile);
+  if (r && r.error) { d.err(`ccr: failed to launch Claude: ${r.error.message}\n`); return 1; }
+  d.dropExited(st.stateDir);
+  return r && typeof r.status === 'number' ? r.status : 0;
+}
+
+/**
+ * Reprint the split instructions and re-copy the sidecar one-liner for an
+ * already-resolved state dir. Backs `ccr sidecar --hint`. Never launches Claude.
+ * @param {string} stateDir
+ * @param {Partial<Deps>} [deps]
+ * @returns {number}
+ */
+function hint(stateDir, deps = {}) {
+  const d = withDefaults(deps);
+  const ccrBin = d.which('ccr');
+  const sidecarCmd = sidecarPasteCommand({ stateDir, ccrBin, node: d.node, ccrJs: d.ccrJs });
+  const hintCmd = sidecarPasteCommand({ 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);
+  return 0;
+}
+
+/**
+ * Build the spawn invocation for launching Claude in the CURRENT pane.
+ *
+ * On POSIX this is a direct exec of `bin`. On Windows the resolved binary is
+ * typically `claude.cmd` / `ccs.cmd`, which Node's spawnSync refuses to run by
+ * bare name without a shell (it would ENOENT) — so we resolve the real path via
+ * `which` and run it through cmd.exe with our own quoting, which keeps a temp
+ * path containing spaces working. We reject the two characters cmd quoting
+ * cannot neutralize — `"` (ends the quote) and `%` (cmd expansion), plus CR/LF —
+ * with a clear error rather than spawn a broken or hijackable line. This mirrors
+ * the WT_UNSAFE policy in launch-win.js; trust boundary is the user's own env.
+ *
+ * Returns either a spawn descriptor or, on a rejected character, an `{ error }`
+ * that run() surfaces exactly like a spawn failure.
+ *
+ * @param {string} bin
+ * @param {string[]} args
+ * @param {{ platform: string, which: (name: string) => (string|null) }} o
+ * @returns {{ command: string, args: string[]|null, shell: boolean } | { error: Error }}
+ */
+function buildClaudeSpawn(bin, args, o) {
+  if (o.platform !== 'win32') {
+    return { command: bin, args, shell: false };
+  }
+  const resolved = o.which(bin) || bin;
+  const all = [resolved, ...args.map(String)];
+  const bad = all.find((p) => /["%\r\n]/.test(p));
+  if (bad !== undefined) {
+    return { error: new Error(
+      `argument contains an unsupported character (", %, or newline) for the Windows shell: ${JSON.stringify(bad)}`,
+    ) };
+  }
+  // cmd.exe strips the outer quote pair Node adds around the /c payload, leaving
+  // each value individually quoted — spaces are safe, `"`/`%` are pre-rejected.
+  return { command: all.map((p) => `"${p}"`).join(' '), args: null, shell: true };
+}
+
+/**
+ * Real-environment Claude launcher: resolve+route through cmd.exe on Windows
+ * (see buildClaudeSpawn), direct exec elsewhere. Stays injectable so tests drive
+ * run() without spawning — but the Windows resolution itself is unit-tested via
+ * buildClaudeSpawn so this seam can't silently regress to a bare-name spawn.
+ *
+ * @param {string} bin
+ * @param {string[]} args
+ * @returns {{ status: number|null, error?: Error }}
+ */
+function defaultSpawnClaude(bin, args) {
+  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');
+  return built.shell
+    ? spawnSync(built.command, { stdio: 'inherit', shell: true })
+    : spawnSync(built.command, built.args || [], { stdio: 'inherit' });
+}
+
+/** @param {string} name @returns {string|null} */
+function defaultWhich(name) {
+  const { spawnSync } = require('node:child_process');
+  const finder = process.platform === 'win32' ? 'where' : 'which';
+  const r = spawnSync(finder, [name], { encoding: 'utf8' });
+  if (r.status !== 0 || !r.stdout) return null;
+  return r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0] || null;
+}
+
+/**
+ * @param {Partial<Deps>} deps
+ * @returns {Deps}
+ */
+function withDefaults(deps) {
+  const env = deps.env || process.env;
+  return {
+    env,
+    home: deps.home || os.homedir(),
+    node: deps.node || process.execPath,
+    ccrJs: deps.ccrJs || path.join(__dirname, '..', 'bin', 'ccr.js'),
+    platform: deps.platform || process.platform,
+    color: deps.color != null ? deps.color : (!!process.stdout.isTTY && !env.NO_COLOR),
+    out: deps.out || ((s) => { process.stdout.write(s); }),
+    err: deps.err || ((s) => { process.stderr.write(s); }),
+    which: deps.which || defaultWhich,
+    existsDir: deps.existsDir || ((dir) => { try { return require('node:fs').statSync(dir).isDirectory(); } catch { return false; } }),
+    listDir: deps.listDir || ((dir) => { try { return require('node:fs').readdirSync(dir); } catch { return []; } }),
+    ensureDir: deps.ensureDir || ensureSecureDir,
+    removeExited: deps.removeExited || ((dir) => { try { require('node:fs').rmSync(path.join(dir, 'exited'), { force: true }); } catch { /* best effort */ } }),
+    dropExited: deps.dropExited || ((dir) => { try { require('node:fs').writeFileSync(path.join(dir, 'exited'), ''); } catch { /* best effort */ } }),
+    writeSettings: deps.writeSettings || ((s) => inject.writeSettingsFile(s)),
+    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'] })),
+  };
+}
+
+/**
+ * @typedef {object} Deps
+ * @property {NodeJS.ProcessEnv} env
+ * @property {string} home
+ * @property {string} node
+ * @property {string} ccrJs
+ * @property {string} platform
+ * @property {boolean} color
+ * @property {(s: string) => void} out
+ * @property {(s: string) => void} err
+ * @property {(name: string) => (string|null)} which
+ * @property {(dir: string) => boolean} existsDir
+ * @property {(dir: string) => string[]} listDir
+ * @property {(dir: string) => void} ensureDir
+ * @property {(dir: string) => void} removeExited
+ * @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 {(cmd: string, args: string[], input: string) => {status: number|null, error?: Error}} spawnCopy
+ */
+
+module.exports = { splitKeybinding, sidecarPasteCommand, osc52, buildBanner, copyToClipboard, buildClaudeSpawn, run, hint };

package/src/launch-win.js

@@ -0,0 +1,401 @@
+// @ts-check
+'use strict';
+
+// src/launch-win.js — native-Windows launcher for `ccr` / `ccr <profile>`.
+//
+// Replaces the bash+tmux launch layer (scripts/launch.sh) on win32 by driving
+// Windows Terminal (wt.exe) split panes: pane 0 runs Claude Code, pane 1 runs
+// `ccr sidecar`, with CCR_STATE_DIR injected into both. See SPEC §4.2/§5.2.
+//
+// The pure, side-effect-free helpers (profile validation, state resolution,
+// wt.exe argv construction, the injected wt.exe lookup) are unit-tested without
+// spawning anything; run()/fallbackNoWt() drive the real side effects through
+// the injectable Deps in withDefaults().
+
+const path = require('node:path');
+const os = require('node:os');
+
+// Profile names land in filesystem paths and a spawned command, so allow only a
+// safe identifier — identical to the allow-list in scripts/launch.sh.
+const PROFILE_RE = /^[A-Za-z0-9._-]+$/;
+
+// Characters we cannot safely embed in the per-pane `cmd /k` payload, even with
+// every path wrapped in double quotes:
+//   "       ends the quoted string;
+//   %       triggers cmd.exe variable expansion (it fires even inside quotes);
+//   \r \n   break the command line.
+// By contrast & | < > ^ ( ) ARE literal inside the double quotes we wrap every
+// value in, so they need no special handling. The trust boundary here is the
+// user's own env/paths (self-injection, not RCE), so the goal is to turn a
+// silently-broken — or, with %, a maliciously-expandable — command into a clear,
+// actionable error rather than to defend against an attacker.
+const WT_UNSAFE_RE = /["%\r\n]/;
+
+/**
+ * @param {string} value
+ * @returns {boolean} true if `value` can be safely interpolated into the cmd /k payload
+ */
+function isWtArgSafe(value) {
+  return !WT_UNSAFE_RE.test(String(value));
+}
+
+// Upstream default split: the sidecar gets ~34% of the width.
+const DEFAULT_SIDEBAR_PCT = 34;
+
+// Where the sidecar pane sits relative to Claude. 'right' is a vertical split
+// (wt split-pane -V, the default — matches the width-based sizing above);
+// 'bottom' is a horizontal split (-H). Set via CCR_SIDEBAR_SIDE.
+const DEFAULT_SIDEBAR_SIDE = 'right';
+
+/**
+ * Map a sidebar side ('right' | 'bottom') to the wt.exe split-pane flag.
+ * 'right' → '-V' (new pane to the right), 'bottom' → '-H' (new pane below).
+ * Anything unrecognized falls back to the default side.
+ *
+ * @param {string} [side]
+ * @returns {'-V'|'-H'}
+ */
+function sidebarSplitFlag(side) {
+  const s = String(side || DEFAULT_SIDEBAR_SIDE).toLowerCase();
+  return s === 'bottom' ? '-H' : '-V';
+}
+
+/**
+ * @param {unknown} profile
+ * @returns {boolean} true if the profile name is a safe identifier
+ */
+function validateProfile(profile) {
+  return typeof profile === 'string' && PROFILE_RE.test(profile);
+}
+
+/**
+ * Resolve the Claude command, tmux-equivalent session name, state dir, and (for
+ * profiles) the expected CCS instance dir. Mirrors scripts/launch.sh, honoring
+ * the CC_BIN / CCR_SESSION / CCR_STATE_DIR overrides.
+ *
+ * @param {string} [profile] CCS profile name, or undefined for plain `claude`
+ * @param {{ env?: NodeJS.ProcessEnv, home?: string }} [opts]
+ * @returns {{ ccCmd: string, session: string, stateDir: string,
+ *   instanceDir: string|null, usesCcs: boolean }}
+ */
+function resolveProfileState(profile, opts = {}) {
+  const env = opts.env || process.env;
+  const home = opts.home || os.homedir();
+
+  if (profile) {
+    return {
+      ccCmd: `ccs ${profile}`,
+      session: env.CCR_SESSION || `ccr-${profile}`,
+      stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr', profile),
+      instanceDir: path.join(home, '.ccs', 'instances', profile),
+      usesCcs: true,
+    };
+  }
+  return {
+    ccCmd: env.CC_BIN || 'claude',
+    session: env.CCR_SESSION || 'ccr',
+    stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr'),
+    instanceDir: null,
+    usesCcs: false,
+  };
+}
+
+/**
+ * Convert a width percentage (e.g. 34) into the fraction string wt.exe's
+ * `split-pane -s` expects (e.g. "0.34"). Clamps to a sane 5..95 range.
+ *
+ * @param {number} [pct]
+ * @returns {string}
+ */
+function sidebarFraction(pct) {
+  let p = Number(pct);
+  if (!Number.isFinite(p)) p = DEFAULT_SIDEBAR_PCT;
+  p = Math.min(95, Math.max(5, Math.round(p)));
+  // Strip any float noise: 34 -> "0.34", 50 -> "0.5".
+  return String(Math.round(p) / 100);
+}
+
+/**
+ * Build the per-pane cmd.exe payload. Env is injected with `set "VAR=val"` so a
+ * path with spaces (or & | < >, which are literal inside the quotes) is fine and
+ * no trailing space is captured. Callers MUST pre-validate `stateDir` with
+ * isWtArgSafe — `"` and `%` are NOT made safe by these quotes (see WT_UNSAFE_RE).
+ *
+ * @param {string} stateDir
+ * @param {string} body the command(s) to run after the env is set
+ * @returns {string}
+ */
+function paneCommand(stateDir, body) {
+  return `set "CCR_STATE_DIR=${stateDir}"&& ${body}`;
+}
+
+/**
+ * Build the argv passed to wt.exe (excluding the wt.exe path itself):
+ *   new-tab --title Claude cmd /k "<pane0>" ; split-pane -H -s <frac> cmd /k "<pane1>"
+ *
+ * The ";" pane separator is its own argv token (wt re-parses it). Per-pane env
+ * is injected via `cmd /k set ...` rather than wt global env. After Claude
+ * exits, pane 0 (unconditional `&`) drops the `exited` sentinel (so the sidecar
+ * can show a clean "session ended" state) and deletes the temp settings file
+ * (cleanup-after-window-closes; the file was only needed at Claude startup).
+ *
+ * Throws if any interpolated value contains a character that would break (or, in
+ * the case of %, hijack) the cmd /k payload — see isWtArgSafe. run() catches
+ * this and reports a clean error instead of spawning a broken command.
+ *
+ * @param {{ ccCmd: string, settingsFile: string, stateDir: string,
+ *   node: string, ccrJs: string, sidebarPct?: number, sidebarSide?: string }} o
+ * @returns {string[]}
+ */
+function buildWtArgs(o) {
+  const { ccCmd, settingsFile, stateDir, node, ccrJs } = o;
+  for (const [label, value] of [
+    ['profile/state dir', stateDir],
+    ['settings file path', settingsFile],
+    ['claude command', ccCmd],
+    ['node path', node],
+    ['ccr.js path', ccrJs],
+  ]) {
+    if (!isWtArgSafe(value)) {
+      throw new Error(
+        `cannot launch: ${label} contains an unsupported character (" or %) for the ` +
+        `Windows Terminal launcher: ${value}`,
+      );
+    }
+  }
+  const frac = sidebarFraction(o.sidebarPct);
+  const splitFlag = sidebarSplitFlag(o.sidebarSide);
+  const exited = path.win32.join(stateDir, 'exited');
+
+  const pane0 = paneCommand(
+    stateDir,
+    `${ccCmd} --settings "${settingsFile}" & type nul > "${exited}" & del /q "${settingsFile}"`,
+  );
+  const pane1 = paneCommand(stateDir, `"${node}" "${ccrJs}" sidecar`);
+
+  return [
+    'new-tab', '--title', 'Claude', 'cmd', '/k', pane0,
+    ';',
+    'split-pane', splitFlag, '-s', frac, 'cmd', '/k', pane1,
+  ];
+}
+
+/**
+ * Resolve wt.exe via `where`, or return null if absent. The lookup is injected
+ * so this stays unit-testable; the default shells out to `where`.
+ *
+ * @param {{ runWhere?: (name: string) => (string|null) }} [opts]
+ * @returns {string|null}
+ */
+function findWindowsTerminal(opts = {}) {
+  const lookup = opts.runWhere || defaultWhere;
+  return lookup('wt') || lookup('wt.exe') || null;
+}
+
+/**
+ * @param {string} name
+ * @returns {string|null} first match path, or null
+ */
+function defaultWhere(name) {
+  const { spawnSync } = require('node:child_process');
+  const r = spawnSync('where', [name], { encoding: 'utf8' });
+  if (r.status !== 0 || !r.stdout) return null;
+  const first = r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0];
+  return first || null;
+}
+
+const inject = require('./settings-inject');
+const { ensureSecureDir } = require('./state-dir');
+
+/**
+ * Fill in real-environment implementations for anything the caller didn't
+ * inject. Every external effect (PATH lookups, fs, spawn, output) flows through
+ * here so run() can be unit-tested with pure stand-ins.
+ *
+ * @param {Partial<Deps>} deps
+ * @returns {Deps}
+ */
+function withDefaults(deps) {
+  const env = deps.env || process.env;
+  const home = deps.home || os.homedir();
+  return {
+    env,
+    home,
+    node: deps.node || process.execPath,
+    ccrJs: deps.ccrJs || path.join(__dirname, '..', 'bin', 'ccr.js'),
+    out: deps.out || ((s) => { process.stdout.write(s); }),
+    err: deps.err || ((s) => { process.stderr.write(s); }),
+    findWt: deps.findWt || (() => findWindowsTerminal()),
+    which: deps.which || defaultWhere,
+    existsDir: deps.existsDir || defaultExistsDir,
+    listDir: deps.listDir || defaultListDir,
+    ensureDir: deps.ensureDir || ensureSecureDir,
+    removeExited: deps.removeExited || defaultRemoveExited,
+    writeSettings: deps.writeSettings || ((s) => inject.writeSettingsFile(s)),
+    cleanup: deps.cleanup || ((f) => inject.cleanupSettingsFile(f)),
+    spawnWt: deps.spawnWt || defaultSpawnWt,
+  };
+}
+
+/** @param {string} dir @returns {boolean} */
+function defaultExistsDir(dir) {
+  try {
+    return require('node:fs').statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** @param {string} dir @returns {string[]} */
+function defaultListDir(dir) {
+  try {
+    return require('node:fs').readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/** @param {string} stateDir @returns {void} */
+function defaultRemoveExited(stateDir) {
+  try {
+    require('node:fs').rmSync(path.join(stateDir, 'exited'), { force: true });
+  } catch {
+    // best effort
+  }
+}
+
+/** @param {string} wt @param {string[]} args @returns {{status:number|null, error?:Error}} */
+function defaultSpawnWt(wt, args) {
+  return require('node:child_process').spawnSync(wt, args, { stdio: 'ignore' });
+}
+
+/**
+ * The graceful no-Windows-Terminal fallback: keep the working native CLI usable
+ * instead of dead-ending. Returns 1 (no crash, no stack trace). SPEC §6 / §8.7.
+ *
+ * @param {{ err: (s: string) => void }} d
+ * @returns {number}
+ */
+function fallbackNoWt(d) {
+  d.err(
+    'ccr: Windows Terminal (wt.exe) not found — it hosts the live sidecar.\n' +
+    '     Install it:  winget install Microsoft.WindowsTerminal\n' +
+    '     Until then these native commands work without it:\n' +
+    '       ccr economy      one-off economy panel\n' +
+    "       ccr statusline   wire into Claude Code's statusLine\n" +
+    '       ccr doctor       check your setup\n');
+  return 1;
+}
+
+/**
+ * `ccr [profile]` on native Windows: split a Windows Terminal window into
+ * Claude Code + ccr sidecar. Implements SPEC §4.2 steps 1–7. Returns an exit
+ * code. All side effects are injectable for testing (see withDefaults).
+ *
+ * @param {string} [profile]
+ * @param {Partial<Deps>} [deps]
+ * @returns {number}
+ */
+function run(profile, deps = {}) {
+  const d = withDefaults(deps);
+
+  // 1. Validate the profile (it lands in paths and a spawned command).
+  if (profile !== undefined && !validateProfile(profile)) {
+    d.err(`ccr: invalid profile name '${profile}' (allowed: letters, digits, . _ -)\n`);
+    return 1;
+  }
+
+  // 2. Require Windows Terminal, else fall back gracefully.
+  const wt = d.findWt();
+  if (!wt) return fallbackNoWt(d);
+
+  // 3. Resolve profile state + required binaries.
+  const st = resolveProfileState(profile, { env: d.env, home: d.home });
+  if (st.usesCcs) {
+    if (!d.which('ccs')) {
+      d.err("ccr: 'ccs' not found on PATH — pass a profile only if CCS is installed.\n");
+      return 1;
+    }
+    if (st.instanceDir && !d.existsDir(st.instanceDir)) {
+      d.err(`ccr: CCS profile '${profile}' not found (${st.instanceDir}).\n`);
+      const avail = d.listDir(path.join(d.home, '.ccs', 'instances')).join(' ');
+      d.err(`     available: ${avail}\n`);
+      return 1;
+    }
+  } else {
+    const bin = st.ccCmd.split(' ')[0];
+    if (!d.which(bin)) {
+      d.err(`ccr: '${bin}' not found on PATH.\n`);
+      return 1;
+    }
+  }
+
+  // 4. Prepare the per-profile state dir; clear a stale sentinel.
+  try { d.ensureDir(st.stateDir); } catch { /* best effort */ }
+  d.removeExited(st.stateDir);
+
+  // 5. Inject statusLine via a temp settings FILE (avoids CLI JSON quoting).
+  const command = inject.buildStatusLineCommandInline({ node: d.node, ccrJs: d.ccrJs });
+  const settingsFile = d.writeSettings(inject.buildSettings(command));
+
+  // 6. Build + spawn the wt.exe command (CCR_STATE_DIR injected per-pane).
+  const pct = parseInt(String(d.env.CCR_SIDEBAR_PCT), 10);
+  let args;
+  try {
+    args = buildWtArgs({
+      ccCmd: st.ccCmd,
+      settingsFile,
+      stateDir: st.stateDir,
+      node: d.node,
+      ccrJs: d.ccrJs,
+      sidebarPct: Number.isFinite(pct) ? pct : DEFAULT_SIDEBAR_PCT,
+      sidebarSide: d.env.CCR_SIDEBAR_SIDE || DEFAULT_SIDEBAR_SIDE,
+    });
+  } catch (e) {
+    d.err(`ccr: ${e instanceof Error ? e.message : String(e)}\n`);
+    d.cleanup(settingsFile); // window never opened → nothing else will clean up
+    return 1;
+  }
+  const r = d.spawnWt(wt, args);
+  if (r.error) {
+    d.err(`ccr: failed to launch Windows Terminal: ${r.error.message}\n`);
+    d.cleanup(settingsFile); // window never opened → pane 0 can't clean up
+    return 1;
+  }
+  // 7. On success the settings file is cleaned up by pane 0 when Claude exits.
+  return typeof r.status === 'number' ? r.status : 0;
+}
+
+/**
+ * @typedef {object} Deps
+ * @property {NodeJS.ProcessEnv} env
+ * @property {string} home
+ * @property {string} node
+ * @property {string} ccrJs
+ * @property {(s: string) => void} out
+ * @property {(s: string) => void} err
+ * @property {() => (string|null)} findWt
+ * @property {(name: string) => (string|null)} which
+ * @property {(dir: string) => boolean} existsDir
+ * @property {(dir: string) => string[]} listDir
+ * @property {(dir: string) => void} ensureDir
+ * @property {(dir: string) => void} removeExited
+ * @property {(settings: object) => string} writeSettings
+ * @property {(file: string) => void} cleanup
+ * @property {(wt: string, args: string[]) => {status: number|null, error?: Error}} spawnWt
+ */
+
+module.exports = {
+  PROFILE_RE,
+  DEFAULT_SIDEBAR_PCT,
+  DEFAULT_SIDEBAR_SIDE,
+  validateProfile,
+  isWtArgSafe,
+  resolveProfileState,
+  sidebarFraction,
+  sidebarSplitFlag,
+  buildWtArgs,
+  findWindowsTerminal,
+  run,
+  fallbackNoWt,
+};

package/src/render/economy.js

@@ -15,7 +15,11 @@ const { dim, bold, green, red, yellow, cyan, flash, pctColor, bar, tok, fmtMins,
 const bandColor = { imminent: red, warn: yellow, ok: cyan };
 
 function wallRow(/** @type {any} */ row, /** @type {any} */ L, /** @type {boolean} */ tick, /** @type {number} */ labelW) {
-  const used = Math.round(row.est.usedPct);
+  // Truncate, don't round: Claude's own surfaces (`/usage`, claude.ai usage)
+  // floor the fractional `used_percentage` (e.g. 41.6 → "41%"). Math.round here
+  // read ~1pt high on values past the half-point. Display only — the burn/ROI
+  // math below still uses the raw fractional `row.est.usedPct`.
+  const used = Math.floor(row.est.usedPct);
   const ml = row.est.minutesLeft;
   const b = band(ml);
   // Per-row colour dot: green when the window resets before you'd hit it,

package/src/render/shared.js

@@ -21,6 +21,34 @@ function bar(/** @type {number} */ p, w = 10) {
   return '▓'.repeat(f) + '░'.repeat(w - f);
 }
 
+/**
+ * Clamp one line to `cols` visible columns: SGR escapes (`\x1b[…m`) pass through
+ * with zero width, printable chars count as 1. Appends a reset if it had to cut,
+ * so a severed colour run doesn't bleed into the cleared tail. Prevents the soft
+ * wrap that corrupts the sidecar's cursor-home redraw in a narrow pane. A
+ * non-positive `cols` (e.g. a non-TTY where columns is undefined) is a no-op.
+ * @param {string} line
+ * @param {number} [cols]
+ * @returns {string}
+ */
+function clampVisible(line, cols) {
+  if (!(typeof cols === 'number' && cols > 0)) return line;
+  const sgr = /\x1b\[[0-9;]*m/y;
+  let out = '';
+  let width = 0;
+  let i = 0;
+  while (i < line.length) {
+    sgr.lastIndex = i;
+    const m = sgr.exec(line);
+    if (m) { out += m[0]; i = sgr.lastIndex; continue; }
+    if (width >= cols) return out + '\x1b[0m';
+    out += line[i];
+    width += 1;
+    i += 1;
+  }
+  return out;
+}
+
 function tok(/** @type {number|null} */ n) {
   if (n == null) return '?';
   if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M';
@@ -46,4 +74,4 @@ function fmtReset(/** @type {number|null} */ min) {
   return `${m}m`;
 }
 
-module.exports = { e, dim, bold, green, red, yellow, cyan, flash, pctColor, bar, tok, fmtMins, fmtReset };
+module.exports = { e, dim, bold, green, red, yellow, cyan, flash, pctColor, bar, clampVisible, tok, fmtMins, fmtReset };

package/src/settings-inject.js

@@ -0,0 +1,77 @@
+// @ts-check
+'use strict';
+
+// src/settings-inject.js — per-launch statusLine injection (SPEC §4.2 step 5, §5.3).
+//
+// Claude Code must call `ccr statusline` on every status tick WITHOUT mutating
+// any file under ~/.claude. We achieve that exactly like upstream launch.sh:
+// write a throwaway settings object to a temp file and pass it to
+// `claude --settings <file>`. A FILE (not inline --settings '{...}') sidesteps
+// the Windows command-line JSON-quoting minefield.
+//
+// The statusLine `command` value is the inline form: node + bin/ccr.js resolved
+// by absolute path. Because it lives inside the JSON settings file (never on a
+// shell line), no shell-quoting is involved and no separate shim file is needed.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+/**
+ * Inline statusLine command: resolve node + ccr.js by path. Quoting is safe
+ * because this value lives inside the JSON settings FILE, not on a shell line.
+ *
+ * @param {{ node: string, ccrJs: string }} o
+ * @returns {string}
+ */
+function buildStatusLineCommandInline(o) {
+  return `"${o.node}" "${o.ccrJs}" statusline`;
+}
+
+/**
+ * The settings object Claude Code consumes via --settings.
+ *
+ * @param {string} command the statusLine command value
+ * @returns {{ statusLine: { type: 'command', command: string } }}
+ */
+function buildSettings(command) {
+  return { statusLine: { type: 'command', command } };
+}
+
+/**
+ * Write the settings object to a uniquely-named temp file and return its path.
+ * The file lives under the temp dir only — never under ~/.claude.
+ *
+ * @param {object} settings
+ * @param {{ tmpDir?: string, rand?: string }} [opts]
+ * @returns {string} absolute path to the written settings file
+ */
+function writeSettingsFile(settings, opts = {}) {
+  const dir = opts.tmpDir || os.tmpdir();
+  const rand = opts.rand || crypto.randomBytes(4).toString('hex');
+  const file = path.join(dir, `ccr-settings-${rand}.json`);
+  fs.writeFileSync(file, JSON.stringify(settings), { encoding: 'utf8' });
+  return file;
+}
+
+/**
+ * Best-effort removal of the temp settings file. Never throws.
+ *
+ * @param {string} file
+ * @returns {void}
+ */
+function cleanupSettingsFile(file) {
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+    // best-effort: a leftover temp file is harmless.
+  }
+}
+
+module.exports = {
+  buildStatusLineCommandInline,
+  buildSettings,
+  writeSettingsFile,
+  cleanupSettingsFile,
+};

package/src/sidecar.js

@@ -3,7 +3,7 @@
 // src/sidecar.js — the live economy panel that runs in the tmux sidebar.
 // Reads the per-session snapshot that `ccr statusline` writes (CCR_STATE_DIR),
 // re-renders the economy screen every second (so the imminent band flashes),
-// and shows a clean ended/​waiting state. Pure Node, zero dependencies.
+// and shows a clean ended/waiting state. Pure Node, zero dependencies.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -11,11 +11,10 @@ const os = require('node:os');
 const { normalizeStatus } = require('./normalize');
 const { renderEconomy } = require('./render/economy');
 const { renderFeed } = require('./render/feed');
+const { clampVisible } = require('./render/shared');
 const { currentTranscriptPath, readNewLines, parseEvents } = require('./transcripts');
 
 const STATE_DIR = process.env.CCR_STATE_DIR || path.join(os.homedir(), '.ccr');
-const SNAPSHOT = path.join(STATE_DIR, 'last-status.json');
-const EXITED = path.join(STATE_DIR, 'exited');
 
 // Live feed accumulator: tail the current transcript incrementally (by byte
 // offset) and roll up tool/skill events + per-session stats. Reset on session
@@ -57,28 +56,58 @@ function draw(/** @type {string} */ s) {
   process.stdout.write('\x1b[H' + s.replace(/\n/g, '\x1b[K\n') + '\x1b[J');
 }
 
-function frame() {
-  if (fs.existsSync(EXITED)) { draw(bold('ccr') + '  ' + dim('session ended') + '\n'); return; }
+/**
+ * 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:
+ * the only inputs are the state dir on disk, `now`, and the pane width `cols`.
+ *
+ * `cols` is the pane's visible column count (process.stdout.columns); every line
+ * 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.
+ *
+ * @param {string} stateDir
+ * @param {{ now?: number, cols?: number }} [opts]
+ * @returns {string}
+ */
+function composeFrame(stateDir, opts = {}) {
+  const now = opts.now != null ? opts.now : Date.now();
+  const cols = opts.cols;
+  const clamp = (/** @type {string} */ s) =>
+    (typeof cols === 'number' && cols > 0
+      ? s.split('\n').map((l) => clampVisible(l, cols)).join('\n')
+      : 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 */ }
-  if (!raw.trim()) { draw(dim('ccr · waiting for the first status tick…') + '\n'); return; }
+  try { raw = fs.readFileSync(snapshot, 'utf8'); } catch { /* none yet */ }
+  if (!raw.trim()) return clamp(dim('ccr · waiting for the first status tick…') + '\n');
   let state;
-  try { state = JSON.parse(raw); } catch { draw(dim('ccr · status unreadable') + '\n'); return; }
+  try { state = JSON.parse(raw); } catch { return clamp(dim('ccr · status unreadable') + '\n'); }
   let out;
   try {
-    out = renderEconomy(normalizeStatus(state), { tick: Math.floor(Date.now() / 1000) % 2 === 0 });
+    out = renderEconomy(normalizeStatus(state), { tick: Math.floor(now / 1000) % 2 === 0 });
   } catch (e) {
     out = dim('ccr render error: ' + (e && e instanceof Error ? e.message : String(e)));
   }
   // 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
+  // the hard safety net regardless).
   try {
     const tpath = currentTranscriptPath(state);
     if (tpath) {
-      const feedStr = renderFeed(updateFeed(tpath), { max: 6 });
+      const feedWidth = typeof cols === 'number' && cols > 0 ? Math.max(20, Math.min(48, cols - 2)) : 48;
+      const feedStr = renderFeed(updateFeed(tpath), { max: 6, width: feedWidth });
       if (feedStr) out += '\n\n' + feedStr;
     }
   } catch { /* feed is optional */ }
-  draw(out.endsWith('\n') ? out : out + '\n');
+  return clamp(out.endsWith('\n') ? out : out + '\n');
+}
+
+function frame() {
+  // Read columns each tick so a live resize re-flows on the next frame.
+  draw(composeFrame(STATE_DIR, { now: Date.now(), cols: process.stdout.columns }));
 }
 
 function run() {
@@ -89,6 +118,7 @@ function run() {
   process.on('SIGTERM', stop);
 }
 
-// `updateFeed` is exported for tests (the incremental tail + session-switch
-// reset is the subtle part); the live loop uses `run`.
-module.exports = { run, updateFeed };
+// `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 };