claude-code-runrate 0.2.4 → 0.4.0

package/README.md

@@ -24,6 +24,15 @@ 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`.
+- **Git pane** — press **F3** in the sidebar for the repo each tab is in: the
+  repo and branch, what's staged / modified / untracked / conflicted, and
+  recent commits drawn in lanes like an IDE git graph. Read from `.git`
+  directly (packfiles included) — no `git` binary is ever run, and the pane
+  can't write or execute anything, structurally.
+- **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, the built-in git pane, 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
@@ -83,8 +92,8 @@ 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.
+session. Instances stay independent — see
+[Running more than one](#running-more-than-one) below.
 
 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**,
@@ -95,6 +104,56 @@ opens a separate window, so the in-editor split is nicer). On **Linux/macOS**,
 > CLI has no "run command" verb) — out of scope for the zero-dependency core. The
 > clipboard + `--hint` reduce it to split-and-paste.
 
+## Running more than one
+
+Open a second terminal and run `ccr` again. That's the whole procedure — nothing
+to name, no flag. Each instance gets its own state dir, its own sidebar, and its
+own tmux session and socket, so starting, clearing or quitting one never touches
+the other. This holds for CCS profiles too: two `ccr cq` at once are two
+independent instances of the same account.
+
+**Instances are ephemeral.** State lives under `~/.ccr/instances/<n>` for the
+session's lifetime and is deleted when it ends. Slots are **reused** — quit the
+second instance and the next `ccr` takes slot 2 back rather than counting upward
+forever. What outlives an instance lives at the top of `~/.ccr`: account burn
+history, and a small per-session join log (`session-<id>.jsonl` — which
+instance, profile and directory a Claude session ran as, for when you're
+reconstructing what happened) — both pruned 31 days after their session ends.
+Up to 32 instances can be live at once; a 33rd launch refuses rather than
+sharing state. Account-wide meters (the 5h and weekly walls) are reconciled
+across live instances, so two sidebars agree even when one has been idle.
+
+**Every instance has a name.** By default it's the repository (or directory)
+you launched from — a second instance from the same repo becomes `gitrepo2` —
+or pick one with `ccr --name side-project`. Characters outside `A-Za-z0-9._-`
+become `-`; an explicit `--name` is rejected rather than repaired, and refused
+if that name is already live. The name is how you see and address an instance:
+
+- the **terminal tab title** is `name` (or `profile / name`), set once at
+  launch and never changed mid-session — it is the tab's address;
+- the **status line** leads with `name @ location`, and the location is live —
+  it follows a mid-session `cd`, and is dropped when it would only repeat the
+  name;
+- the **sidebar** heads every view with the name;
+- **`-i <name>`** targets a live instance from anywhere: `ccr economy -i
+  side-project`, `ccr sidecar -i …`, `ccr cycle-view -i …`. Without `-i`,
+  those three commands resolve the instance from your working directory (the
+  live instance whose launch directory contains it) — and when that's
+  ambiguous they list the candidates instead of guessing. Every panel is
+  headed by the name it resolved to.
+
+Setting `CCR_STATE_DIR` (and/or `CCR_SESSION`) still pins an instance wherever
+you want it, and always wins over the automatic choice.
+
+**Upgrading from 0.3:** the first launch migrates `~/.ccr` once — burn history
+moves to the top of the container and old per-profile state dirs are swept
+(they held nothing else that outlives a session). Migration refuses while any
+old session is still running, and names what to close.
+
+> `tmux ls` won't list ccr's sessions — each runs on its own socket. Use
+> `tmux -L ccr ls` (or `-L ccr-2` for slot 2 — profile launches ride slot
+> sockets too now).
+
 ## Wiring the statusline into Claude Code
 
 In `~/.claude/settings.json`:
@@ -107,6 +166,72 @@ 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, the built-in git pane, and
+each configured pane.
+
+**Cycling views.** Under tmux the launcher binds **F3**. VS Code and its forks
+(Cursor, Positron, Antigravity) bind no key and leave both split panes running a
+foreground process, so the pasted sidecar one-liner carries `--keys`: click that
+pane and press **Space** (or **F3**). The renderer still reads no input — the key
+lives in a separate parent process that runs the panel as a child, the same
+separation tmux enforces. Anywhere else, `ccr cycle-view -i <name>` (or
+`--state-dir <dir>`); a bare `ccr cycle-view` resolves the instance from your
+working directory, like `ccr economy` does.
+`ccr sidecar --view <n>` opens on a chosen view (0 economy, 1 git, 2+ panes).
+
+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   3/3
+  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 → git pane → first pane
+  → second pane → back to economy; the `3/3` above is that position, for the one
+  configured pane in the example. The position marker appears only once you have
+  configured a pane — the two built-in views identify themselves, so numbering
+  them buys nothing. 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
@@ -120,6 +245,13 @@ 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.
 
+The *practice* is documented separately in [`docs/BDD.md`](docs/BDD.md): what
+these scenarios (271 of them, at 0.4.0) took from conventional BDD, where they departed — refusals
+as a quarter of the specification, tags that are gates rather than filters,
+comments that carry rulings — and why. It also places ccr in the lineage the
+method has followed since, and is honest about which point on that line this
+repository represents.
+
 ```bash
 npm test            # node --test — harness self-tests + feature scenarios
 npm run typecheck   # tsc --noEmit over @ts-check'd JS (needs: npm i first)

package/bin/ccr.js

@@ -34,14 +34,21 @@ Usage:
   ccr doctor       Check your local setup (node, tmux, CCS, capture status)
 
 Examples:
-  ccr              plain \`claude\` + sidebar
-  ccr c1           CCS profile c1 + sidebar
-  ccr economy      one-off panel
+  ccr                        plain \`claude\` + sidebar
+  ccr c1                     CCS profile c1 + sidebar
+  ccr --name side-project    named instance (default name: the repo/dir)
+  ccr economy -i side-project  panel for a live instance, by name
 
 Options:
-  -h, --help     Show this help
-  -v, --version  Show version
-      --mary     Enable the mary interface`;
+  -h, --help         Show this help
+  -v, --version      Show version
+      --name <name>  Name this instance (letters, digits, . _ -)
+  -i <name>          Target a live instance (economy, sidecar, cycle-view)
+      --mary         Enable the mary interface
+
+Sidecar options:
+      --view <n>  Open on a view: 0 economy, 1 git, 2+ configured panes
+      --keys      Cycle views with F3 or Space, for terminals that bind no key`;
 
 /**
  * @param {string[]} argv
@@ -60,6 +67,10 @@ function main(argv) {
         'state-dir': { type: 'string' },
         hint: { type: 'boolean' },
         'exit-on-end': { type: 'boolean' },
+        name: { type: 'string' },
+        instance: { type: 'string', short: 'i' },
+        keys: { type: 'boolean' },
+        view: { type: 'string' },
         mary: { type: 'boolean' },
       },
     });
@@ -75,19 +86,63 @@ function main(argv) {
   // in-process panels (economy/statusline/resume) pick it up for this run.
   if (values.mary) process.env.CCR_ENABLE_MARY_INTERFACE = '1';
 
+  // `--view` names a view index, so a non-integer is a typo worth naming rather
+  // than a value to coerce: NaN would silently open the economy panel and look
+  // like the flag was ignored.
+  let view;
+  if (values.view != null) {
+    view = Number(values.view);
+    if (!Number.isInteger(view) || view < 0) {
+      process.stderr.write(`ccr: --view takes a view index (0 = economy, 1 = git), got "${values.view}"\n`);
+      return 2;
+    }
+  }
+
   const cmd = positionals[0];
-  if (!cmd) return cmdLaunch(undefined);          // bare `ccr` → launch
+  // -i is a THREE-command flag: honored where a command must answer "which
+  // live instance?", refused LOUDLY everywhere else — the option parser is
+  // global, so a silently swallowed -i would let `ccr resume -i x` look
+  // targeted while targeting nothing (features/instance-resolution.feature).
+  const iTarget = values.instance != null ? values.instance : null;
+  if (iTarget != null && !['economy', 'sidecar', 'cycle-view'].includes(cmd || '')) {
+    const known = ['economy', 'resume', 'statusline', 'sidecar', 'doctor', 'cycle-view', 'launch'];
+    const cname = cmd && known.includes(cmd) ? cmd : 'launch';
+    process.stderr.write(`ccr: -i applies to economy, sidecar, cycle-view — ${cname} does not target an instance\n`);
+    return 2;
+  }
+  if (!cmd) return cmdLaunch(undefined, values.name);   // bare `ccr` → launch
   switch (cmd) {
-    case 'economy': return cmdEconomy(!!values.json);
+    case 'economy': return cmdEconomy(!!values.json, iTarget);
     case 'resume': return cmdResume(positionals[1]);
     case 'statusline': return cmdStatusline();
-    case 'sidecar': return cmdSidecar(values['state-dir'], !!values.hint, !!values['exit-on-end']);
+    case 'sidecar': return cmdSidecar(values['state-dir'], !!values.hint, !!values['exit-on-end'], !!values.keys, view, iTarget);
     case 'doctor': return require('../src/doctor').run();
-    case 'launch': return cmdLaunch(positionals[1]);
-    default: return cmdLaunch(cmd);               // anything else → treat as a CCS profile
+    case 'cycle-view': return cmdCycleView(values['state-dir'], iTarget);
+    case 'launch': return cmdLaunch(positionals[1], values.name);
+    default: return cmdLaunch(cmd, values.name);  // 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
+ * @param {string|null} [target]  -i name, resolved through the chain
+ * @returns {number}
+ */
+function cmdCycleView(stateDirFlag, target = null) {
+  let stateDir = stateDirFlag || null;
+  if (!stateDir) {
+    const res = require('../src/instance-resolve').resolveInstance({ target, command: 'cycle-view' });
+    if (!res.ok) { process.stderr.write(res.error + '\n'); return 1; }
+    stateDir = res.stateDir;
+  }
+  require('../src/cycle-view').cycleView(stateDir);
+  return 0;
+}
+
 function readStdin() {
   try { return process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf8'); } catch { return ''; }
 }
@@ -109,9 +164,32 @@ function cmdStatusline() {
     const { renderStatusline } = require('../src/render/statusline');
     const { logMeterSample } = require('../src/instrument');
     const { ensureSecureDir } = require('../src/state-dir');
-    line = renderStatusline(normalizeStatus(state));
+    // The identity half: the name this instance chose at launch, and the LIVE
+    // location from the status tick's own cwd (features/instance-identity.feature).
+    /** @type {{ name?: string|null, location?: string|null }} */
+    let identity = {};
+    try {
+      const naming = require('../src/instance-name');
+      const name = fs.readFileSync(path.join(STATE_DIR, naming.NAME_FILE), 'utf8').trim();
+      if (name) identity = { name, location: naming.locationFrom(state.cwd) };
+    } catch { /* unnamed (explicit override dirs) — no identity segment */ }
+    line = renderStatusline(normalizeStatus(state), identity);
     try { ensureSecureDir(STATE_DIR); fs.writeFileSync(SNAPSHOT, raw, { mode: 0o600 }); } catch { /* ignore */ }
-    try { logMeterSample(state, { dir: STATE_DIR }); } catch { /* ignore */ }
+    // Burn history is ACCOUNT-scoped and slots are reused, so it lives at the
+    // container's top level, never inside an instance dir it would die with.
+    try { logMeterSample(state, { dir: path.join(os.homedir(), '.ccr') }); } catch { /* ignore */ }
+    // The two-phase join key opens the moment the session id first exists
+    // (src/session-log.js) — deaths are when writes can't be trusted.
+    try {
+      if (state.session_id) {
+        const readLocal = (/** @type {string} */ f) => {
+          try { return fs.readFileSync(path.join(STATE_DIR, f), 'utf8').trim() || null; } catch { return null; }
+        };
+        require('../src/session-log').openEntry(os.homedir(), state.session_id, {
+          name: readLocal('name'), profile: readLocal('profile'), launch_cwd: readLocal('launch-cwd'),
+        });
+      }
+    } catch { /* ignore */ }
   } catch { /* keep fallback line */ }
   process.stdout.write(line + '\n');
   return 0;
@@ -122,11 +200,29 @@ function cmdStatusline() {
  * stable machine-readable economy model (the integration contract). Reads stdin,
  * else the captured snapshot.
  * @param {boolean} [json]
+ * @param {string|null} [target]  -i name, resolved through the chain
  * @returns {number}
  */
-function cmdEconomy(json) {
+function cmdEconomy(json, target = null) {
   let raw = readStdin();
-  if (!raw.trim()) { try { raw = fs.readFileSync(SNAPSHOT, 'utf8'); } catch { /* none yet */ } }
+  /** @type {string|null} */
+  let heading = null;
+  if (!raw.trim()) {
+    // Which instance? The resolution chain answers, and the panel is headed
+    // with the name it resolved to — the safeguard against reading the right
+    // panel about the wrong instance.
+    const res = require('../src/instance-resolve').resolveInstance({ target, command: 'economy' });
+    if (!res.ok) {
+      // Zero instances live is not an error: the account's meters and burn
+      // history are container-level and still print — only the per-instance
+      // panel is gone (features/instance-persistence.feature).
+      if ('none' in res && res.none && !json) return printAccountPanel();
+      process.stderr.write(res.error + '\n');
+      return 1;
+    }
+    heading = res.name;
+    try { raw = fs.readFileSync(path.join(res.stateDir, 'last-status.json'), 'utf8'); } catch { /* none yet */ }
+  }
   let state = null;
   if (raw.trim()) { try { state = JSON.parse(raw); } catch { /* bad json */ } }
   if (!state) {
@@ -135,12 +231,57 @@ function cmdEconomy(json) {
   }
   const { normalizeStatus } = require('../src/normalize');
   if (json) {
+    // The machine contract (docs/JSON-CONTRACT.md) is unchanged: no heading.
     const { computeEconomy } = require('../src/economy-model');
     process.stdout.write(JSON.stringify(computeEconomy(normalizeStatus(state)), null, 2) + '\n');
     return 0;
   }
   const { renderEconomy } = require('../src/render/economy');
-  process.stdout.write(renderEconomy(normalizeStatus(state)) + '\n');
+  const panel = renderEconomy(normalizeStatus(state));
+  process.stdout.write((heading ? heading + '\n' : '') + panel + '\n');
+  return 0;
+}
+
+/**
+ * The zero-instance account view: meters from the newest burn history sample,
+ * plus how much history the container retains. No per-instance panel — there
+ * is no instance.
+ * @returns {number}
+ */
+function printAccountPanel() {
+  const root = path.join(os.homedir(), '.ccr');
+  /** @type {{file: string, m: number} | null} */
+  let newest = null;
+  let sessions = 0;
+  try {
+    for (const n of fs.readdirSync(root)) {
+      if (/^session-[A-Za-z0-9_-]+\.jsonl$/.test(n)) { sessions += 1; continue; }
+      if (!/^burnlog-[A-Za-z0-9_-]+\.jsonl$/.test(n)) continue;
+      try {
+        const m = fs.statSync(path.join(root, n)).mtimeMs;
+        if (!newest || m > newest.m) newest = { file: path.join(root, n), m };
+      } catch { /* skip */ }
+    }
+  } catch { /* empty container */ }
+  const out = ['account (no live instance)'];
+  if (newest) {
+    try {
+      const lines = fs.readFileSync(newest.file, 'utf8').trim().split('\n');
+      const last = JSON.parse(lines[lines.length - 1]);
+      /** @type {any} */
+      const rl = {};
+      for (const [k, v] of Object.entries(last.limits || {})) {
+        rl[k] = { used_percentage: /** @type {any} */ (v).used, resets_at: /** @type {any} */ (v).resets_at };
+      }
+      const { normalizeStatus } = require('../src/normalize');
+      const { renderEconomy } = require('../src/render/economy');
+      out.push(renderEconomy(normalizeStatus({ rate_limits: rl })));
+    } catch { out.push('meters unreadable'); }
+  } else {
+    out.push('no burn history captured yet');
+  }
+  out.push(`history: ${sessions} session${sessions === 1 ? '' : 's'} retained`);
+  process.stdout.write(out.join('\n') + '\n');
   return 0;
 }
 
@@ -166,15 +307,44 @@ function cmdResume(arg) {
  * 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).
+ * `--view <n>` opens on a chosen view (0 economy, 1 git, 2…N configured panes).
+ *
+ * `--keys` makes THIS process the hotkey host and runs the panel as a child, for
+ * terminals that bind no key of their own (VS Code and its forks). The renderer
+ * still never reads input — see the header of src/sidecar-keys.js for why that
+ * separation is the whole point, and why it is a child rather than a listener.
+ *
  * @param {string | undefined} stateDir
  * @param {boolean} [showHint]
  * @param {boolean} [exitOnEnd]
+ * @param {boolean} [useKeys]
+ * @param {number} [view]
+ * @param {string|null} [target]  -i name, resolved through the chain
  * @returns {number | undefined}
  */
-function cmdSidecar(stateDir, showHint, exitOnEnd) {
+function cmdSidecar(stateDir, showHint, exitOnEnd, useKeys, view, target = null) {
+  if (!stateDir && target != null) {
+    // -i: attach to a live instance by name, through the resolution chain.
+    const res = require('../src/instance-resolve').resolveInstance({ target, command: 'sidecar' });
+    if (!res.ok) { process.stderr.write(res.error + '\n'); return 1; }
+    stateDir = res.stateDir;
+  }
   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 });
+  if (useKeys) {
+    require('../src/sidecar-keys').runWithKeys({
+      stateDir: process.env.CCR_STATE_DIR || STATE_DIR,
+      // This very file, so the child is the same ccr the user invoked — not
+      // whatever `ccr` happens to resolve to on the child's PATH.
+      ccrJs: __filename,
+      argv: [
+        ...(exitOnEnd ? ['--exit-on-end'] : []),
+        ...(view != null ? ['--view', String(view)] : []),
+      ],
+    });
+    return undefined;
+  }
+  require('../src/sidecar').run({ exitOnEnd: !!exitOnEnd, view });
   return undefined;
 }
 
@@ -184,19 +354,62 @@ function cmdSidecar(stateDir, showHint, exitOnEnd) {
  * already works there); on native Windows we drive Windows Terminal; otherwise
  * the tmux launcher (scripts/launch.sh).
  * @param {string | undefined} profile
+ * @param {string} [name]  explicit instance name (--name); validated here
  * @returns {number}
  */
-function cmdLaunch(profile) {
+function cmdLaunch(profile, name) {
+  // An explicit name is REJECTED, never repaired: the user typed it and a
+  // human is right there — matching the launcher's profile-name message shape
+  // (features/instance-naming.feature).
+  const naming = require('../src/instance-name');
+  if (name != null && !naming.NAME_RE.test(name)) {
+    process.stderr.write(`ccr: invalid instance name '${name}' (allowed: letters, digits, . _ -)\n`);
+    return 1;
+  }
+  // Migration runs AT LAUNCH ONLY — never from `ccr statusline`, which Claude
+  // invokes headlessly mid-session (src/migrate.js). A refused migration is a
+  // refused launch: proceeding would write new-layout state into an old home.
+  const mig = require('../src/migrate').ensureLayout();
+  if (!mig.ok) { process.stderr.write(mig.error + '\n'); return 1; }
+  // Shared across ALL launchers (a platform must never ship half-lit): the
+  // explicit-name collision refusal, and the retention boundary.
+  const live = naming.liveNames({ home: os.homedir() });
+  if (name != null && live.has(name)) {
+    process.stderr.write(`ccr: instance name '${name}' is already live — pick another\n`);
+    return 1;
+  }
+  try { require('../src/session-log').pruneHistory(os.homedir()); } catch { /* best effort */ }
   const inVscode = process.env.TERM_PROGRAM === 'vscode';
   if (inVscode && (process.platform === 'win32' || process.env.CCR_VSCODE === '1')) {
-    return require('../src/launch-vscode').run(profile);
+    return require('../src/launch-vscode').run(profile, undefined, { name });
   }
   if (process.platform === 'win32') {
-    return require('../src/launch-win').run(profile);
+    return require('../src/launch-win').run(profile, undefined, { name });
   }
   const { spawnSync } = require('node:child_process');
   const launcher = path.join(__dirname, '..', 'scripts', 'launch.sh');
-  const r = spawnSync('bash', profile ? [launcher, profile] : [launcher], { stdio: 'inherit' });
+  // Every launch gets a free instance slot — bare or profiled — so a second
+  // terminal never collides with the first (src/instance-slot.js). The
+  // launcher needs no knowledge of slots: it already derives session, socket
+  // and state dir from these two vars.
+  const slots = require('../src/instance-slot');
+  const slot = slots.allocateSlot({ profile });
+  if (slot && 'exhausted' in slot) {
+    process.stderr.write(`ccr: every slot is in use (${slots.MAX_SLOTS} live instances) — close one first\n`);
+    return 1;
+  }
+  // Name + profile record + title, the same way every launcher does it.
+  const inst = slot && !('exhausted' in slot)
+    ? naming.prepareInstance(slot, { profile, name }) : null;
+  let env = slots.applySlotEnv(process.env, slot);
+  // The tab's ADDRESS, composed once here and never retitled mid-session.
+  if (inst) env = { ...env, CCR_TITLE: inst.title };
+  // This call blocks for the session's whole lifetime (launch.sh ends in `tmux
+  // attach`), which is exactly why this process is what owns the slot.
+  const r = spawnSync('bash', profile ? [launcher, profile] : [launcher], { stdio: 'inherit', env });
+  // Ephemeral instances: a polite exit deletes the instance dir, unless an
+  // attached sidebar is still reading it (then the dir waits for reuse).
+  if (slot && !('exhausted' in slot)) slots.retireInstance(slot.stateDir);
   if (r.error) { process.stderr.write(`ccr: launch failed: ${r.error.message}\n`); return 1; }
   return typeof r.status === 'number' ? r.status : 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-runrate",
-  "version": "0.2.4",
+  "version": "0.4.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>",
@@ -30,7 +30,9 @@
   "scripts": {
     "test": "node --test",
     "typecheck": "tsc --noEmit -p jsconfig.json",
-    "lint": "oxlint"
+    "lint": "oxlint",
+    "release-gate": "node scripts/release-gate.js",
+    "prepublishOnly": "npm run release-gate && npm run lint && npm run typecheck && npm test"
   },
   "keywords": [
     "claude-code",