claude-code-runrate 0.1.0 → 0.2.1

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,10 @@ function main(argv) {
         help: { type: 'boolean', short: 'h' },
         version: { type: 'boolean', short: 'v' },
         json: { type: 'boolean' },
+        'state-dir': { type: 'string' },
+        hint: { type: 'boolean' },
+        'exit-on-end': { type: 'boolean' },
+        mary: { type: 'boolean' },
       },
     });
   } catch (err) {
@@ -66,6 +71,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 +81,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, !!values['exit-on-end']);
     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 +159,40 @@ function cmdResume(arg) {
   return 0;
 }
 
-/** `ccr sidecar` — live economy panel; keeps the process alive (no exit code). */
-function cmdSidecar() {
-  require('../src/sidecar').run();
+/**
+ * `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.
+ * `--exit-on-end` closes the panel shortly after the session ends (the Windows
+ * Terminal launcher passes it so its `cmd /c` pane sweeps closed like tmux).
+ * @param {string | undefined} stateDir
+ * @param {boolean} [showHint]
+ * @param {boolean} [exitOnEnd]
+ * @returns {number | undefined}
+ */
+function cmdSidecar(stateDir, showHint, exitOnEnd) {
+  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({ exitOnEnd: !!exitOnEnd });
   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.1",
   "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 };