claude-code-runrate 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+Every release also has a [GitHub release](https://github.com/bingh0/ccr/releases)
+and a release commit, and those carry the full notes — what was measured, what
+was rejected, and why. This file is the index: enough to decide whether a
+version is worth upgrading to, and where to read the rest.
+
+Dates are npm publish dates, because that is when a version reached anyone.
+
+## 0.5.0 — 2026-08-22
+
+The Windows release. The things that could not be reasoned about were measured
+on a real Windows 11 machine, because none of them are reachable from CI: every
+Windows test injects the launcher, so the suite proves the argv `ccr` builds and
+nothing about what Windows Terminal does when handed it.
+
+- **The panes open where `ccr` was run.** `wt.exe` does not inherit the working
+  directory the way `tmux new-session` does, so every pane opened in
+  `%USERPROFILE%` while the launch record claimed otherwise — and the sidecar
+  prefers that record, so the git pane described the project in full confidence
+  for a terminal that was not in it. One source now feeds both.
+- **Measured limits, and they are real.** Past 256 characters `wt` opens *no
+  tab at all*; a UNC path opens a tab and silently lands in `%SystemRoot%`; a
+  semicolon costs the whole tab; a backtick does not, so refusing it was wrong
+  and no longer happens. Each unusable path degrades — the panes open in the
+  default directory and stderr names which of the four reasons applied.
+- **The sidecar pane has a cycle key** on Windows Terminal. F3 or Space. F3 has
+  three encodings and on Windows which one arrives depends on the *Node*
+  version, so `ccr` answers all three rather than pinning a Node floor for a
+  keystroke.
+- **A pane config that says what is wrong.** A UTF-8 BOM is stripped; UTF-16 —
+  what PowerShell 5.1 writes for `>` and `Out-File` — is named as an encoding
+  problem instead of reported as bad JSON; `~\` expands as well as `~/`; and a
+  broken config says so on the panel and in `ccr doctor`, which reports pane
+  paths as *resolved*.
+- **`ccr sidecar` resolves the instance from the working directory**, which the
+  feature files and the README had both described for a while.
+- **The economy screen earns a decimal** where the next tenth is a decision: at
+  or past 95% used, one truncated digit, so `floor(shown)` still matches
+  `/usage`. A snapshot that stopped refreshing dims rather than blanks.
+
+## 0.4.0 — 2026-08-07
+
+[The instance layer and the git pane.](https://github.com/bingh0/ccr/releases/tag/v0.4.0)
+
+- **Instances.** Every launch is a named, slotted instance under one container
+  home; the name is derived from the project or given with `-i`, and travels
+  into the window title, status line and sidebar.
+- **A git pane** on F3: which repository the tab is in, the working tree, and
+  recent history in lanes. Read-only — it never writes to the repository.
+- The three launchers (tmux, Windows Terminal, VS Code) take naming, titles and
+  retention from one shared path rather than the tmux path owning them.
+
+## 0.3.0 — 2026-08-04
+
+[External tool panes in the sidebar.](https://github.com/bingh0/ccr/releases/tag/v0.3.0)
+
+- **Panes from other tools.** The sidebar hosts full-height read-only panes
+  rendered from small JSON blobs another tool writes beside its own artifacts.
+  You list the path in `~/.config/ccr/config.json`; F3 cycles.
+- A rate-limit correctness fix, and `strict` type checking across the codebase.
+
+## 0.2.4 — 2026-07-12
+
+[VS Code sidecars stop piling up; profile state-dir fix.](https://github.com/bingh0/ccr/releases/tag/v0.2.4)
+
+- One live sidecar per session: relaunching inside VS Code no longer
+  accumulates identical panes.
+- Profile sessions write their snapshots to the right state dir.
+
+## 0.2.3 — 2026-07-03
+
+[Sidecars agree on 5h/weekly across profiles.](https://github.com/bingh0/ccr/releases/tag/v0.2.3)
+
+- The 5h and weekly walls are one account-wide resource, but each profile only
+  captures its own; two sidecars on the same account could disagree. They
+  reconcile now.
+
+## 0.2.2 — 2026-07-02
+
+[Aligned meter bars + a staleness marker.](https://github.com/bingh0/ccr/releases/tag/v0.2.2)
+
+- A barely-used window projects an enormous time-to-exhaust, which overflowed
+  the fixed time column and shoved that row's bar out of line. Long horizons
+  are capped, so the bars stay aligned and the figure reads more honestly.
+- A stale snapshot is annotated (`· updated Nm ago`) rather than silently
+  frozen. Never a wipe — Claude Code legitimately stops ticking during a long
+  operation.
+
+## 0.2.1 — 2026-06-26
+
+[Windows Terminal teardown and sidecar width fixes.](https://github.com/bingh0/ccr/releases/tag/v0.2.1)
+
+- ConPTY makes a split pane's reported width unreliable, so the panel
+  soft-wrapped. The launcher injects the computed width and the sidecar clamps
+  to the smaller of the two.
+- On exit the sidecar pane collapses first and the border sweeps left to right,
+  fixing an ordering bug where Claude's pane could close first.
+
+## 0.2.0 — 2026-06-26
+
+[Native Windows and VS Code live sidecars.](https://github.com/bingh0/ccr/releases/tag/v0.2.0)
+
+- **Native Windows** — the live sidecar hosted in Windows Terminal split panes,
+  no tmux, bash or WSL, with a graceful fallback when `wt.exe` is absent.
+- **VS Code integrated terminal on any OS** — split-pane sidecar via a
+  clipboard one-liner.
+- `statusLine` injected per launch through a temp settings file, so `~/.claude`
+  is never mutated.
+
+## 0.1.0 — 2026-06-24
+
+First publish: the CLI and status line — `economy`, `resume`, `statusline` —
+with the live sidebar on tmux. Native Windows arrived in 0.2.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** at the host. **Windows
+Terminal** binds no key of its own, and neither do VS Code and its forks (Cursor,
+Positron, Antigravity) — so on those the sidecar pane carries its own key: click
+the 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
@@ -125,11 +191,24 @@ read from a repository:
 { "panes": [ { "path": "/home/you/project/.your-tool/sidecar.json" } ] }
 ```
 
+A leading `~` expands, with either separator (`~/tools/blob.json`,
+`~\tools\blob.json`), and a relative path resolves against the config file's own
+directory. **On Windows, save the file as UTF-8** — `>` and `Out-File` in Windows
+PowerShell 5.1 write UTF-16, which is not JSON as far as any parser is concerned:
+
+```powershell
+Set-Content -Encoding utf8 $env:USERPROFILE\.config\ccr\config.json $json
+```
+
+`ccr doctor` reports what it read out of the config — the paths as **resolved**,
+not as written — and names the problem when there is one, so a pane that never
+appears is a question you can answer rather than a silence.
+
 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 +226,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,11 +258,24 @@ 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)
+npm test              # node --test — harness self-tests + feature scenarios
+npm run typecheck     # tsc --noEmit over @ts-check'd JS (needs: npm i first)
+npm run install-hooks # copy .githooks/ into this clone (run once)
 ```
 
+`install-hooks` installs a fail-closed `pre-push` guard for the public remote:
+only `main`, fast-forward only, and a scan of the commits the push would make
+public. It is worth running in any clone you push from — a push is the moment
+history stops being private, and it is the last moment the check can help.
+
 - **No runtime dependencies**, ever — it's what lets `npx claude-code-runrate` install
   instantly on every OS, including native Windows.
 - **Dev-only** tooling (`typescript`, `@types/node`) exists solely for

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,54 @@ 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) {
+  // Resolve whether or not -i was typed, which is what `ccr cycle-view` has
+  // always done. Consulting the chain ONLY for -i meant a bare `ccr sidecar`
+  // skipped every other link in it — including the one that matters most here,
+  // "the live instance whose launch directory contains the cwd" — and landed on
+  // the CONTAINER (~/.ccr) instead. The container holds no session, so the pane
+  // sat empty next to a running instance, and the fix looked like naming the
+  // instance exactly right when the whole point of the chain is not having to.
+  //
+  // --hint is left out: it prints the VS Code split instructions, which are
+  // worth printing before any instance exists, so requiring a live one to
+  // explain how to start one would be backwards.
+  if (!stateDir && !showHint) {
+    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 +364,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;
 }