claude-code-runrate 0.3.0 → 0.4.0

package/README.md

@@ -24,9 +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 and each configured pane (see [External tool panes](#external-tool-panes-sidebar)).
+  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
@@ -86,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**,
@@ -98,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`:
@@ -114,8 +170,18 @@ latency.)
 
 The live sidebar can host **read-only panes from other tools**. A tool writes a
 small JSON blob beside its own artifacts; you list that file's path in ccr's
-config; the sidebar cycles between the economy panel and each configured pane
-(**F3** under tmux — the launcher binds it; `ccr cycle-view` on any host).
+config; 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
@@ -129,7 +195,7 @@ A pane is a full-height view carrying the producing tool's own rows — here
 `gherkin-trace`, whose blob ships as the golden example:
 
 ```
-trace  gherkin-trace   2/2
+trace  gherkin-trace   3/3
   refresh · 2026-08-01 14:10 · blob written 0s
 
   ● attention     3   1 breach, 2 orphans
@@ -147,10 +213,13 @@ trace  gherkin-trace   2/2
   stripped of control bytes before it touches your terminal.
 - **Producers never know ccr exists.** You wire the join by hand, exactly like
   Claude Code's own `statusLine` — neither side takes a dependency on the other.
-- **Config order is cycle order.** F3 goes economy panel → first pane → second
-  pane → back to economy; the `2/2` above is that position. Entries are never
-  de-duplicated, so listing one path twice gives you two panes. The config is
-  re-read every tick — adding a pane takes effect without relaunching.
+- **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*
@@ -176,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,17 +86,40 @@ 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 'cycle-view': return cmdCycleView(values['state-dir']);
-    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
   }
 }
 
@@ -95,11 +129,16 @@ function main(argv) {
  * 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) {
-  const stateDir = stateDirFlag || process.env.CCR_STATE_DIR
-    || require('node:path').join(require('node:os').homedir(), '.ccr');
+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;
 }
@@ -125,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;
@@ -138,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) {
@@ -151,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;
 }
 
@@ -182,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;
 }
 
@@ -200,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.3.0",
+  "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",

package/scripts/launch.sh

@@ -42,7 +42,14 @@ chmod +x "$REPO/sidecar/ccr-statusline" 2>/dev/null || true
 
 # Prefer the newest nvm-installed node; `sort -V` is a GNU-ism, so suppress its
 # error on BSD/macOS and fall back to PATH node below.
-NODE="$(ls -d "$HOME"/.nvm/versions/node/*/bin/node 2>/dev/null | sort -V 2>/dev/null | tail -1)"
+#
+# The `|| true` is load-bearing, not defensive habit: with `set -e` and
+# `pipefail`, `ls` failing on a machine with no ~/.nvm makes the whole pipeline
+# non-zero, and a failing command substitution in an assignment aborts the
+# script. That killed the launcher outright — exit 2, no message, no sidebar —
+# for exactly the user who has plain Claude Code and no nvm, who then never
+# reaches the PATH fallback two lines below. Reproduced 2026-08-04.
+NODE="$(ls -d "$HOME"/.nvm/versions/node/*/bin/node 2>/dev/null | sort -V 2>/dev/null | tail -1 || true)"
 [ -x "$NODE" ] || NODE="$(command -v node || true)"
 [ -n "$NODE" ] || { echo "ccr: node not found" >&2; exit 1; }
 command -v tmux >/dev/null 2>&1 || { echo "ccr: tmux not found (required for the sidebar)" >&2; exit 1; }
@@ -55,13 +62,15 @@ if [ -n "$PROFILE" ]; then
     exit 1
   fi
   CC_CMD="ccs $PROFILE"
-  SESSION="${CCR_SESSION:-ccr-$PROFILE}"
-  STATE="${CCR_STATE_DIR:-$HOME/.ccr/$PROFILE}"
 else
   CC_CMD="${CC_BIN:-claude}"
-  SESSION="${CCR_SESSION:-ccr}"
-  STATE="${CCR_STATE_DIR:-$HOME/.ccr}"
 fi
+# The launcher normally arrives with CCR_SESSION/CCR_STATE_DIR already set by
+# the slot allocator (bin/ccr.js — every launch slots, profiled or bare). The
+# fallbacks cover only a direct invocation of this script, and they point at
+# slot 1's member dir: ~/.ccr itself is a container now, never a state dir.
+SESSION="${CCR_SESSION:-ccr}"
+STATE="${CCR_STATE_DIR:-$HOME/.ccr/instances/1}"
 
 # Every instance gets its OWN tmux server, on a socket named after the session
 # (-L puts it under /tmp/tmux-$UID/). On a shared server, one server death —
@@ -76,6 +85,17 @@ SOCKET="$SESSION"
 mkdir -p "$STATE"
 chmod 700 "$HOME/.ccr" "$STATE" 2>/dev/null || true
 rm -f "$STATE/exited"
+# The directory ccr was launched in — the tab's stable identity for the git
+# pane (src/state-dir.js: recordLaunchDir does the same for the other two
+# launchers). Best-effort: a tab that cannot record it falls back to naming
+# only the repo the session is in.
+# The rm is load-bearing, not tidiness: `>` on a planted FIFO blocks until a
+# reader appears and hangs the launcher here, before Claude is ever spawned, and
+# on a planted symlink it overwrites the link's target. Removing first turns both
+# into an ordinary create. src/state-dir.js does the same for the other two
+# launchers, and both sibling writers in <stateDir> already guard this way.
+rm -f "$STATE/launch-cwd" 2>/dev/null || true
+printf '%s\n' "$PWD" > "$STATE/launch-cwd" 2>/dev/null || true
 
 SETTINGS='{"statusLine":{"type":"command","command":"'"$REPO/sidecar/ccr-statusline"'"}}'
 
@@ -105,6 +125,15 @@ CLAUDE_PANE="$(tmux -L "$SOCKET" new-session -d -P -F '#{pane_id}' -s "$SESSION"
   "$ENV_PREAMBLE; $CC_CMD --settings '$SETTINGS'; touch '$STATE_Q/exited'; sleep 2; tmux -L '$SOCKET_Q' kill-session -t '$SESSION_Q' 2>/dev/null")"
 tmux -L "$SOCKET" set-environment -t "$SESSION" CCR_STATE_DIR "$STATE"
 
+# The tab's ADDRESS: composed once by the launcher (CCR_TITLE = "[profile / ]name",
+# both halves allow-listed), never retitled mid-session. set-titles-string is a
+# literal — deliberately NOT a tmux format that would follow the session; the
+# pane and the status line are the surfaces honest about movement.
+if [ -n "${CCR_TITLE:-}" ]; then
+  tmux -L "$SOCKET" set-option -t "$SESSION" set-titles on
+  tmux -L "$SOCKET" set-option -t "$SESSION" set-titles-string "$CCR_TITLE"
+fi
+
 # Pane 1: the live economy sidebar. Capture its pane id so we can scope a hook to it.
 SIDEBAR_PANE="$(tmux -L "$SOCKET" split-window -t "$SESSION:0" -h -p "${CCR_SIDEBAR_PCT:-34}" -P -F '#{pane_id}' \
   "$ENV_PREAMBLE; \"$NODE\" \"$REPO/bin/ccr.js\" sidecar; read -r -p 'sidebar exited — Enter to close '")"

package/src/account-limits.js

@@ -33,7 +33,8 @@ const { parseResetsAt } = require('./burn');
 const { modelScope } = require('./rate-limits');
 
 const MAX_SNAPSHOT_BYTES = 1_000_000; // a status JSON is a few KB; bound parse/disk
-const MAX_PROFILES = 32;              // sanity cap on how many siblings we scan
+const MAX_PROFILES = 32;              // sanity cap on how many siblings we merge
+const MAX_SCAN_ENTRIES = 512;         // sanity cap on how many dir entries we inspect
 
 /**
  * Canonical reset instant for fingerprinting/matching — tolerant of CC reporting
@@ -127,12 +128,14 @@ function readSiblingRateLimits(file) {
  * reconcile the local meters against them. Best-effort — returns `localRl` on any
  * problem so it can wrap the render path without a guard at the call site.
  *
- * Engages ONLY for the launcher's profile layout (`~/.ccr/<profile>`): the state
- * dir's parent must be `~/.ccr`. For ad-hoc `~/.ccr` or a custom CCR_STATE_DIR we
- * have no sibling set to trust, so we behave exactly as before (no merge).
+ * Engages ONLY for the launcher's layout: instances under `~/.ccr/instances/`
+ * (the 0.4.0 container/member split — src/instance-slot.js). A custom
+ * CCR_STATE_DIR elsewhere has no sibling set to trust, so it behaves as
+ * before (no merge). There is no slot-1 special case any more: slot 1 is an
+ * ordinary member of instances/, which is exactly why the layout changed.
  *
  * @param {any} localRl the local snapshot's `rate_limits`
- * @param {string} stateDir the local profile's state dir (CCR_STATE_DIR)
+ * @param {string} stateDir the local instance's state dir (CCR_STATE_DIR)
  * @param {{ home?: string }} [opts]
  * @returns {any}
  */
@@ -140,21 +143,26 @@ function freshenAccountLimits(localRl, stateDir, opts = {}) {
   try {
     if (!localRl || typeof localRl !== 'object') return localRl;
     const home = opts.home || os.homedir();
-    const root = path.dirname(path.resolve(stateDir));
-    if (root !== path.resolve(path.join(home, '.ccr'))) return localRl; // not a profile layout
+    const root = path.resolve(path.join(home, '.ccr', 'instances'));
+    const self = path.resolve(stateDir);
+    if (path.dirname(self) !== root) return localRl; // not the launcher's layout
     const selfFile = path.resolve(path.join(stateDir, 'last-status.json'));
 
     /** @type {any[]} */
     const siblings = [];
+    // Bound the WALK, not just the harvest: MAX_PROFILES alone counts collected
+    // siblings, so entries that yield nothing — slot dirs with no snapshot yet,
+    // junk — would all be stat'd on every tick. This runs inside the sidecar's
+    // ~1s draw loop, so the scan stays capped by entries seen even though
+    // instances/ holds only instance dirs under the 0.4.0 layout.
+    let seen = 0;
     for (const name of fs.readdirSync(root)) {
-      if (siblings.length >= MAX_PROFILES) break;
+      if (siblings.length >= MAX_PROFILES || ++seen > MAX_SCAN_ENTRIES) break;
       const p = path.join(root, name);
       let st; try { st = fs.statSync(p); } catch { continue; }
-      // A sibling profile dir (~/.ccr/<name>/last-status.json) or the ad-hoc
-      // ~/.ccr/last-status.json file itself.
-      const file = st.isDirectory() ? path.join(p, 'last-status.json')
-        : (name === 'last-status.json' ? p : null);
-      if (!file || path.resolve(file) === selfFile) continue;
+      if (!st.isDirectory()) continue;
+      const file = path.join(p, 'last-status.json');
+      if (path.resolve(file) === selfFile) continue;
       const rl = readSiblingRateLimits(file);
       if (rl) siblings.push(rl);
     }