claude-code-runrate 0.3.0 → 0.5.0

package/src/launch-vscode.js

@@ -18,7 +18,8 @@ const path = require('node:path');
 const os = require('node:os');
 const launchWin = require('./launch-win');
 const inject = require('./settings-inject');
-const { ensureSecureDir } = require('./state-dir');
+const slots = require('./instance-slot');
+const { ensureSecureDir, recordLaunchDir } = require('./state-dir');
 
 /**
  * VS Code's "Split Terminal" default keybinding, per platform.
@@ -33,12 +34,20 @@ function splitKeybinding(platform) {
  * The command the user runs in the split pane. Carries the resolved state dir as
  * an explicit arg (shell-agnostic: no per-shell `set`/`$env:`/`export` needed).
  * Prefers the `ccr` binary when on PATH; falls back to node + ccr.js by path.
+ *
+ * `--keys` rides along because THIS host binds no key. Under tmux the launcher
+ * binds F3 and tmux runs `ccr cycle-view`; VS Code offers no equivalent, and its
+ * split leaves both panes running a foreground process, so there is not even a
+ * shell prompt free to type the command into. `--keys` makes the pasted process
+ * the hotkey host and runs the panel as its child — the renderer still reads no
+ * input (src/sidecar-keys.js).
+ *
  * @param {{ stateDir: string, ccrBin?: string|null, node: string, ccrJs: string, hint?: boolean }} o
  * @returns {string}
  */
 function sidecarPasteCommand(o) {
   const head = o.ccrBin ? 'ccr' : `"${o.node}" "${o.ccrJs}"`;
-  const tail = o.hint ? ' --hint' : ` --state-dir "${o.stateDir}"`;
+  const tail = o.hint ? ' --hint' : ` --state-dir "${o.stateDir}" --keys`;
   return `${head} sidecar${tail}`;
 }
 
@@ -71,6 +80,10 @@ function buildBanner(o) {
     '',
     `       ${c('1;92', o.sidecarCmd)}`,
     '',
+    // The key is named here because this host binds none of its own: nothing
+    // else on screen would tell the user the second view exists.
+    c('2', '  Then click that pane and press ') + c('1;97', 'Space') + c('2', ' (or ') + c('1;97', 'F3') + c('2', ') to cycle its views.'),
+    '',
     c('2', `  Claude is starting in THIS pane. Lost these steps? Run:  ${o.hintCmd}`),
     '',
   ].join('\n') + '\n';
@@ -116,9 +129,10 @@ function buildAttachedNote(o) {
  * sidecar, then run Claude in the current pane. Returns Claude's exit code.
  * @param {string} [profile]
  * @param {Partial<Deps>} [deps]
+ * @param {{ name?: string|null }} [opts]  explicit --name, already validated
  * @returns {number}
  */
-function run(profile, deps = {}) {
+function run(profile, deps = {}, opts = {}) {
   const d = withDefaults(deps);
 
   if (profile !== undefined && !launchWin.validateProfile(profile)) {
@@ -126,7 +140,20 @@ function run(profile, deps = {}) {
     return 1;
   }
 
-  const st = launchWin.resolveProfileState(profile, { env: d.env, home: d.home });
+  // Every launch claims a free instance slot first, so a second VS Code window
+  // never shares another's state dir (src/instance-slot.js). A slot is only
+  // busy while a LIVE session holds it — an attached-but-idle sidebar (the note
+  // below) leaves its slot reusable, so relaunching here still lands on the same
+  // state dir and that pane picks the new session up, exactly as before.
+  const slot = d.allocateSlot({ profile, env: d.env, home: d.home });
+  if (slot && 'exhausted' in slot) {
+    d.err(`ccr: every slot is in use (${slots.MAX_SLOTS} live instances) — close one first\n`);
+    return 1;
+  }
+  // The instance's name and profile record — same on every platform. (The
+  // editor owns its tab titles, so there is no title surface here.)
+  if (slot && !('exhausted' in slot)) d.prepareInstance(slot, { profile, name: opts.name });
+  const st = launchWin.resolveProfileState(profile, { env: slots.applySlotEnv(d.env, slot), home: d.home });
   if (st.usesCcs) {
     if (!d.which('ccs')) {
       d.err("ccr: 'ccs' not found on PATH — pass a profile only if CCS is installed.\n");
@@ -143,6 +170,9 @@ function run(profile, deps = {}) {
   }
 
   try { d.ensureDir(st.stateDir); } catch { /* best effort */ }
+  // The tab's stable identity for the git pane. Recorded here because only the
+  // launcher knows where ccr was started (src/state-dir.js).
+  try { d.recordLaunchDir(st.stateDir, process.cwd()); } catch { /* best effort */ }
   d.removeExited(st.stateDir);
 
   // statusLine via a per-launch temp settings file (no ~/.claude mutation).
@@ -157,7 +187,13 @@ function run(profile, deps = {}) {
   const ccrBin = d.which('ccr');
   const sidecarCmd = sidecarPasteCommand({ stateDir: st.stateDir, ccrBin, node: d.node, ccrJs: d.ccrJs });
   const hintCmd = sidecarPasteCommand({ stateDir: st.stateDir, ccrBin, node: d.node, ccrJs: d.ccrJs, hint: true });
-  if (d.sidecarAlive(st.stateDir)) {
+  // "Already attached?" comes from the allocator when it chose this slot: it
+  // inspected the heartbeat BEFORE reserving, and reserving a free slot writes a
+  // placeholder heartbeat of our own — so re-reading it here would see our own
+  // write and wrongly skip the split banner. Only a launch with no slot (a named
+  // profile, an explicit override) asks the heartbeat directly.
+  const attached = slot && !('exhausted' in slot) ? slot.attached : d.sidecarAlive(st.stateDir);
+  if (attached) {
     d.out(buildAttachedNote({ hintCmd, color: d.color }));
   } else {
     d.out(buildBanner({ sidecarCmd, splitKey: splitKeybinding(d.platform), hintCmd, color: d.color }));
@@ -175,8 +211,19 @@ function run(profile, deps = {}) {
   const parts = st.ccCmd.split(' ');
   const r = d.spawnClaude(parts[0], [...parts.slice(1), '--settings', settingsFile], { CCR_STATE_DIR: st.stateDir });
   d.cleanup(settingsFile);
-  if (r && r.error) { d.err(`ccr: failed to launch Claude: ${r.error.message}\n`); return 1; }
+  if (r && r.error) {
+    // A failed spawn must NOT flip the sidecar to "ended" or delete anything;
+    // just hand the reservation back.
+    if (slot && !('exhausted' in slot)) d.releaseSlot(slot.stateDir);
+    d.err(`ccr: failed to launch Claude: ${r.error.message}\n`);
+    return 1;
+  }
+  // Session over: drop the sentinel FIRST (an attached sidebar reads it to show
+  // "session ended" and wait for reuse), then retire the instance — ephemeral,
+  // so the dir is deleted unless that sidebar is still attached, in which case
+  // only the reservation is released and a later sweep collects the dir.
   d.dropExited(st.stateDir);
+  if (slot && !('exhausted' in slot)) d.retireInstance(slot.stateDir);
   return r && typeof r.status === 'number' ? r.status : 0;
 }
 
@@ -283,6 +330,13 @@ function withDefaults(deps) {
     existsDir: deps.existsDir || ((dir) => { try { return require('node:fs').statSync(dir).isDirectory(); } catch { return false; } }),
     listDir: deps.listDir || ((dir) => { try { return require('node:fs').readdirSync(dir); } catch { return []; } }),
     ensureDir: deps.ensureDir || ensureSecureDir,
+    recordLaunchDir: deps.recordLaunchDir || recordLaunchDir,
+    allocateSlot: deps.allocateSlot || ((o) => slots.allocateSlot(o)),
+    releaseSlot: deps.releaseSlot || ((dir) => slots.releaseSlot(dir)),
+    retireInstance: deps.retireInstance || ((dir) => slots.retireInstance(dir)),
+    prepareInstance: deps.prepareInstance
+      || ((/** @type {{slot:number,stateDir:string}} */ s, /** @type {any} */ o) =>
+        require('./instance-name').prepareInstance(s, { ...o, home: deps.home || os.homedir() })),
     removeExited: deps.removeExited || ((dir) => { try { require('node:fs').rmSync(path.join(dir, 'exited'), { force: true }); } catch { /* best effort */ } }),
     dropExited: deps.dropExited || ((dir) => { try { require('node:fs').writeFileSync(path.join(dir, 'exited'), ''); } catch { /* best effort */ } }),
     writeSettings: deps.writeSettings || ((s) => inject.writeSettingsFile(s)),
@@ -309,6 +363,11 @@ function withDefaults(deps) {
  * @property {(dir: string) => boolean} existsDir
  * @property {(dir: string) => string[]} listDir
  * @property {(dir: string) => void} ensureDir
+ * @property {(dir: string, cwd: string) => void} recordLaunchDir
+ * @property {(o: {profile?: string, env: NodeJS.ProcessEnv, home: string}) => ({slot: number, session: string, stateDir: string, attached: boolean}|{exhausted: true}|null)} allocateSlot
+ * @property {(dir: string) => void} releaseSlot
+ * @property {(dir: string) => void} retireInstance
+ * @property {(slot: {slot: number, stateDir: string}, o: {profile?: string, name?: string|null}) => {name: string, title: string}} prepareInstance
  * @property {(dir: string) => void} removeExited
  * @property {(dir: string) => void} dropExited
  * @property {(settings: object) => string} writeSettings

package/src/launch-win.js

@@ -39,6 +39,109 @@ function isWtArgSafe(value) {
   return !WT_UNSAFE_RE.test(String(value));
 }
 
+// The starting directory is a DIFFERENT problem from the values above, and
+// reusing WT_UNSAFE_RE for it would be a bug in both directions.
+//
+//   `%` is LEGAL in a Windows path (C:\100%done) and harmless here: -d's value
+//   is its own argv token handed to wt, never interpolated into a cmd /c
+//   payload, so cmd's variable expansion never sees it. WT_UNSAFE_RE rejects
+//   `%`, so reusing it would refuse a perfectly valid directory.
+//
+//   `;` is legal in a Windows path AND is wt's own command separator — wt
+//   re-parses its command line, and Node only quotes an argv token that
+//   contains whitespace, so `C:\my;dir` would arrive unquoted and split the
+//   command. WT_UNSAFE_RE does NOT reject `;`, so it misses the one character
+//   that actually matters here.
+//
+// A directory that fails this does not fail the launch: run() drops -d and
+// says where the panes landed (features/windows-launcher.feature, "A launch
+// directory Windows Terminal cannot be given still launches"). Refusing to
+// start over a legal directory name would trade one broken launch for another.
+//
+// MEASURED on Windows 11 (10.0.26200) with scripts/probe-wt.js, because none of
+// this was knowable from the documentation and none of it is covered by CI —
+// every test injects spawnWt, so the suite proves the argv and nothing about
+// what Windows Terminal does with it.
+const WT_PATH_UNSAFE_RE = /[";\r\n]/;
+
+// The backtick used to be in that class and is NOT: a path containing one was
+// passed through and the tab landed exactly where it was asked to. wt is not
+// PowerShell. Refusing it cost a launch that would have worked.
+//
+// The semicolon earns its place — wt splits its own command line on it, and a
+// path containing one opens NO TAB AT ALL.
+
+// Longest path wt will accept as `-d`. Measured: 256 characters opens a tab,
+// 259 opens none — so the true limit is 257 or 258, and 256 is the longest
+// length known to work. Two characters of headroom is not worth another round
+// trip on someone else's machine.
+//
+// This is NOT the filesystem's limit. The machine that measured it has long
+// paths enabled: a 299-character directory was created successfully and then
+// refused a tab. The refusal is Windows Terminal's.
+const WT_PATH_MAX = 256;
+
+// Naming the character rather than echoing it. Two reasons: a raw CR or LF
+// interpolated into a diagnostic would break the diagnostic, and "a semicolon"
+// is what the reader needs anyway — they are looking at the path already.
+/** @type {Record<string, string>} */
+const WT_PATH_CHAR_NAMES = {
+  '"': 'a double quote',
+  ';': 'a semicolon',
+  '\r': 'a carriage return',
+  '\n': 'a newline',
+};
+
+/**
+ * Why `dir` cannot be given to wt as `-d`, or null when it can.
+ *
+ * Every branch here degrades rather than refuses to launch: the panes open in
+ * Windows Terminal's default directory and stderr says so. The point of the
+ * REASON is that "we would not pass this one" is a different sentence for each
+ * cause, and the previous single message named characters the path did not
+ * contain.
+ *
+ * @param {string|null|undefined} dir
+ * @returns {string|null} a clause completing "the path …", or null if usable
+ */
+function wtPathProblem(dir) {
+  if (typeof dir !== 'string' || dir.length === 0) return 'is not a directory ccr could read';
+  // UNC is the dangerous one, and the only case here that is SILENT. The tab
+  // OPENS — cmd.exe simply refuses a UNC working directory and starts in
+  // %SystemRoot% without a word. Measured: \\localhost\c$\Users reported
+  // C:\Windows. Left unhandled, the git pane would describe the project in
+  // full confidence for a terminal sitting in C:\Windows.
+  if (/^[\\/]{2}/.test(dir)) return 'is a UNC path — cmd.exe refuses those and starts in %SystemRoot% without saying so';
+  if (dir.length > WT_PATH_MAX) return `is ${dir.length} characters — Windows Terminal opens no tab at all past ${WT_PATH_MAX}`;
+  const m = WT_PATH_UNSAFE_RE.exec(dir);
+  if (m) return `contains ${WT_PATH_CHAR_NAMES[m[0]] || 'a character'} — Windows Terminal parses it and opens no tab at all`;
+  return null;
+}
+
+/**
+ * What the user could DO about it, when there is anything.
+ *
+ * Only the UNC case has an answer: cmd.exe will take a mapped drive letter
+ * where it refuses the UNC form, so the directory is reachable — just not by
+ * that name. The other causes are the path they have, and telling someone to
+ * rename their project or shorten it below 256 characters is not advice.
+ *
+ * @param {string|null|undefined} dir
+ * @returns {string|null}
+ */
+function wtPathHint(dir) {
+  if (typeof dir !== 'string' || !/^[\\/]{2}/.test(dir)) return null;
+  return 'map the share to a drive letter (net use Z: \\\\server\\share) and run ccr from there';
+}
+
+/**
+ * @param {string|null|undefined} dir
+ * @returns {boolean} true if `dir` can be passed to wt.exe as `-d <dir>`
+ */
+function isWtPathSafe(dir) {
+  return wtPathProblem(dir) === null;
+}
+
 // Upstream default split: the sidecar gets ~34% of the width.
 const DEFAULT_SIDEBAR_PCT = 34;
 
@@ -82,11 +185,15 @@ function resolveProfileState(profile, opts = {}) {
   const env = opts.env || process.env;
   const home = opts.home || os.homedir();
 
+  // The stateDir fallbacks are reachable only when called with neither a slot's
+  // env nor the user's own override — never from the launchers, which refuse an
+  // exhausted allocation before this. They point at slot 1's member dir so no
+  // path here can ever name the container itself as a state dir.
   if (profile) {
     return {
       ccCmd: `ccs ${profile}`,
-      session: env.CCR_SESSION || `ccr-${profile}`,
-      stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr', profile),
+      session: env.CCR_SESSION || 'ccr',
+      stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr', 'instances', '1'),
       instanceDir: path.join(home, '.ccs', 'instances', profile),
       usesCcs: true,
     };
@@ -94,7 +201,7 @@ function resolveProfileState(profile, opts = {}) {
   return {
     ccCmd: env.CC_BIN || 'claude',
     session: env.CCR_SESSION || 'ccr',
-    stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr'),
+    stateDir: env.CCR_STATE_DIR || path.join(home, '.ccr', 'instances', '1'),
     instanceDir: null,
     usesCcs: false,
   };
@@ -177,9 +284,16 @@ function sidecarCols(termCols, fracNum, splitFlag) {
  * the case of %, hijack) the cmd /c payload — see isWtArgSafe. run() catches
  * this and reports a clean error instead of spawning a broken command.
  *
+ * `cwd` is the directory BOTH panes start in. Windows Terminal does not
+ * inherit it the way `tmux new-session` does: without `-d` a pane opens in the
+ * WT profile's own `startingDirectory`, which defaults to %USERPROFILE% — so
+ * omitting it silently moved Claude Code out of the user's project. Absent or
+ * unpassable (see isWtPathSafe), `-d` is left off entirely and the panes fall
+ * back to that profile default; run() is what tells the user.
+ *
  * @param {{ ccCmd: string, settingsFile: string, stateDir: string,
  *   node: string, ccrJs: string, sidebarPct?: number, sidebarSide?: string,
- *   termCols?: number }} o
+ *   termCols?: number, title?: string, cwd?: string|null }} o
  * @returns {string[]}
  */
 function buildWtArgs(o) {
@@ -200,6 +314,9 @@ function buildWtArgs(o) {
   }
   const frac = sidebarFraction(o.sidebarPct);
   const splitFlag = sidebarSplitFlag(o.sidebarSide);
+  // The tab's ADDRESS ("[profile / ]name") when the instance has one — both
+  // halves allow-listed, so it is wt-arg-safe by construction.
+  const title = o.title || 'Claude';
   const exited = path.win32.join(stateDir, 'exited');
 
   // After Claude exits we drop the sentinel + clean the settings file, then idle
@@ -220,13 +337,17 @@ function buildWtArgs(o) {
   const cols = sidecarCols(o.termCols, Number(frac), splitFlag);
   const sidecarBody =
     (cols != null ? `set "CCR_SIDECAR_COLS=${cols}"&& ` : '') +
-    `"${node}" "${ccrJs}" sidecar --exit-on-end`;
+    `"${node}" "${ccrJs}" sidecar --exit-on-end --keys`;
   const pane1 = paneCommand(stateDir, sidecarBody);
 
+  // Both panes get the same starting directory, or neither does. `-d` sits
+  // with the other options, before each pane's `cmd` payload.
+  const startIn = isWtPathSafe(o.cwd) ? ['-d', String(o.cwd)] : [];
+
   return [
-    '-w', '0', 'new-tab', '--title', 'Claude', 'cmd', '/c', pane0,
+    '-w', '0', 'new-tab', '--title', title, ...startIn, 'cmd', '/c', pane0,
     ';',
-    'split-pane', splitFlag, '-s', frac, 'cmd', '/c', pane1,
+    'split-pane', splitFlag, '-s', frac, ...startIn, 'cmd', '/c', pane1,
   ];
 }
 
@@ -255,7 +376,8 @@ function defaultWhere(name) {
 }
 
 const inject = require('./settings-inject');
-const { ensureSecureDir } = require('./state-dir');
+const slots = require('./instance-slot');
+const { ensureSecureDir, recordLaunchDir, clearLaunchDir } = require('./state-dir');
 
 /**
  * Fill in real-environment implementations for anything the caller didn't
@@ -274,6 +396,15 @@ function withDefaults(deps) {
     // The launcher's own stdout reports the live terminal width — the sidecar's
     // does not, inside its cmd /c pane (see sidecarCols). undefined on non-TTY.
     cols: deps.cols != null ? deps.cols : process.stdout.columns,
+    // The launch directory, injected like every other external effect. It is
+    // the INPUT to that decision, not the answer: run() narrows it to paneCwd —
+    // the directory wt will actually be given — and both the record and `-d`
+    // read that, so the pane and the record cannot disagree about where this
+    // session is. This comment claimed the invariant before the code held it.
+    // process.cwd() throws only if the cwd has been deleted.
+    cwd: deps.cwd != null ? deps.cwd : (() => {
+      try { return process.cwd(); } catch { return null; }
+    })(),
     node: deps.node || process.execPath,
     ccrJs: deps.ccrJs || path.join(__dirname, '..', 'bin', 'ccr.js'),
     out: deps.out || ((s) => { process.stdout.write(s); }),
@@ -283,6 +414,12 @@ function withDefaults(deps) {
     existsDir: deps.existsDir || defaultExistsDir,
     listDir: deps.listDir || defaultListDir,
     ensureDir: deps.ensureDir || ensureSecureDir,
+    recordLaunchDir: deps.recordLaunchDir || recordLaunchDir,
+    clearLaunchDir: deps.clearLaunchDir || clearLaunchDir,
+    allocateSlot: deps.allocateSlot || ((o) => slots.allocateSlot(o)),
+    prepareInstance: deps.prepareInstance
+      || ((/** @type {{slot:number,stateDir:string}} */ s, /** @type {any} */ o) =>
+        require('./instance-name').prepareInstance(s, { ...o, home: deps.home || os.homedir() })),
     removeExited: deps.removeExited || defaultRemoveExited,
     writeSettings: deps.writeSettings || ((s) => inject.writeSettingsFile(s)),
     cleanup: deps.cleanup || ((f) => inject.cleanupSettingsFile(f)),
@@ -347,9 +484,10 @@ function fallbackNoWt(d) {
  *
  * @param {string} [profile]
  * @param {Partial<Deps>} [deps]
+ * @param {{ name?: string|null }} [opts]  explicit --name, already validated
  * @returns {number}
  */
-function run(profile, deps = {}) {
+function run(profile, deps = {}, opts = {}) {
   const d = withDefaults(deps);
 
   // 1. Validate the profile (it lands in paths and a spawned command).
@@ -362,8 +500,18 @@ function run(profile, deps = {}) {
   const wt = d.findWt();
   if (!wt) return fallbackNoWt(d);
 
-  // 3. Resolve profile state + required binaries.
-  const st = resolveProfileState(profile, { env: d.env, home: d.home });
+  // 3. Resolve profile state + required binaries. Every launch first claims a
+  // free instance slot (src/instance-slot.js) so a second window never shares
+  // another's state dir; only an explicit override skips it.
+  const slot = d.allocateSlot({ profile, env: d.env, home: d.home });
+  if (slot && 'exhausted' in slot) {
+    d.err(`ccr: every slot is in use (${slots.MAX_SLOTS} live instances) — close one first\n`);
+    return 1;
+  }
+  // The instance's name, profile record and title — same on every platform.
+  const inst = slot && !('exhausted' in slot)
+    ? d.prepareInstance(slot, { profile, name: opts.name }) : null;
+  const st = resolveProfileState(profile, { env: slots.applySlotEnv(d.env, slot), home: d.home });
   if (st.usesCcs) {
     if (!d.which('ccs')) {
       d.err("ccr: 'ccs' not found on PATH — pass a profile only if CCS is installed.\n");
@@ -385,8 +533,39 @@ function run(profile, deps = {}) {
 
   // 4. Prepare the per-profile state dir; clear a stale sentinel.
   try { d.ensureDir(st.stateDir); } catch { /* best effort */ }
+  // ONE source for both consumers: the directory the panes will ACTUALLY start
+  // in. Everything below reads paneCwd — the record that gives the git pane its
+  // identity, and wt's `-d` — so the two cannot describe different directories.
+  //
+  // Recording d.cwd unconditionally is what CREATED the divergence rather than
+  // merely failing to prevent it: src/sidecar.js launchDir() PREFERS the record
+  // over the pane's own cwd. readGitRepo self-heals after Claude's first status
+  // tick, but before that tick — the state every tab starts in — the pane draws
+  // the project's repo, branch, tree and history in full confidence for a
+  // session sitting somewhere else entirely.
+  const paneCwd = isWtPathSafe(d.cwd) ? d.cwd : null;
+  if (paneCwd) {
+    try { d.recordLaunchDir(st.stateDir, paneCwd); } catch { /* best effort */ }
+  } else {
+    // Clearing, not skipping. Slots are reused, so the record from whatever ran
+    // in this slot before would otherwise win (src/state-dir.js clearLaunchDir).
+    try { d.clearLaunchDir(st.stateDir); } catch { /* best effort */ }
+  }
   d.removeExited(st.stateDir);
 
+  // The panes must open where `ccr` was run. wt does not inherit that, so it
+  // is passed explicitly below; when the directory cannot be passed the launch
+  // still goes ahead, and saying so is the whole difference between a surprise
+  // and a known limitation.
+  const pathProblem = d.cwd ? wtPathProblem(d.cwd) : null;
+  if (pathProblem) {
+    d.err(`ccr: cannot open the panes in ${d.cwd}\n`);
+    d.err(`     the path ${pathProblem}\n`);
+    d.err("     — they will open in Windows Terminal's default directory instead.\n");
+    const hint = wtPathHint(d.cwd);
+    if (hint) d.err(`     ${hint}.\n`);
+  }
+
   // 5. Inject statusLine via a temp settings FILE (avoids CLI JSON quoting).
   const command = inject.buildStatusLineCommandInline({ node: d.node, ccrJs: d.ccrJs });
   const settingsFile = d.writeSettings(inject.buildSettings(command));
@@ -404,6 +583,8 @@ function run(profile, deps = {}) {
       sidebarPct: Number.isFinite(pct) ? pct : DEFAULT_SIDEBAR_PCT,
       sidebarSide: d.env.CCR_SIDEBAR_SIDE || DEFAULT_SIDEBAR_SIDE,
       termCols: d.cols,
+      title: inst ? inst.title : undefined,
+      cwd: paneCwd,
     });
   } catch (e) {
     d.err(`ccr: ${e instanceof Error ? e.message : String(e)}\n`);
@@ -425,6 +606,8 @@ function run(profile, deps = {}) {
  * @property {NodeJS.ProcessEnv} env
  * @property {string} home
  * @property {number|undefined} cols
+ * @property {string|null} cwd the directory `ccr` was run in — recorded as the
+ *   tab's launch dir AND passed to wt as the panes' starting directory
  * @property {string} node
  * @property {string} ccrJs
  * @property {(s: string) => void} out
@@ -434,6 +617,10 @@ function run(profile, deps = {}) {
  * @property {(dir: string) => boolean} existsDir
  * @property {(dir: string) => string[]} listDir
  * @property {(dir: string) => void} ensureDir
+ * @property {(dir: string, cwd: string) => void} recordLaunchDir
+ * @property {(dir: string) => void} clearLaunchDir
+ * @property {(o: {profile?: string, env: NodeJS.ProcessEnv, home: string}) => ({slot: number, session: string, stateDir: string, attached: boolean}|{exhausted: true}|null)} allocateSlot
+ * @property {(slot: {slot: number, stateDir: string}, o: {profile?: string, name?: string|null}) => {name: string, title: string}} prepareInstance
  * @property {(dir: string) => void} removeExited
  * @property {(settings: object) => string} writeSettings
  * @property {(file: string) => void} cleanup
@@ -446,6 +633,10 @@ module.exports = {
   DEFAULT_SIDEBAR_SIDE,
   validateProfile,
   isWtArgSafe,
+  isWtPathSafe,
+  wtPathProblem,
+  wtPathHint,
+  WT_PATH_MAX,
   resolveProfileState,
   sidebarFraction,
   sidebarSplitFlag,

package/src/migrate.js

@@ -0,0 +1,155 @@
+// @ts-check
+'use strict';
+// src/migrate.js — move a 0.3 ccr home to the 0.4 container layout, once,
+// safely (features/instance-migration.feature).
+//
+// There is nothing to relocate but HISTORY: the only persistent content the
+// 0.3 layout ever held was account burn history, misplaced inside profile
+// dirs because the logger wrote to whatever the state dir was. So migration
+// HARVESTS burnlogs to the container's top level, SWEEPS the profile dirs and
+// the loose ephemeral droppings (a dead session's captured status, heartbeat,
+// sentinel), and writes the ".layout" marker LAST — an interrupted migration
+// is indistinguishable from one that has not started, and every move is
+// move-if-present, so the next launch simply completes it.
+//
+// THE GENERAL SAFETY PROPERTY, ruled: if the source is not what migration
+// expects, it STOPS AND CHANGES NOTHING. That is also the entire handling of
+// an entry named "instances" or "profiles" (reserved by the new layout) and
+// of a CCS profile literally named either — declined as real scope ("no other
+// users will have this problem"); the stop makes it fail loudly for free.
+//
+// Runs AT LAUNCH ONLY. `ccr statusline` — invoked headlessly by Claude
+// mid-session — never calls this. Removed at 1.0.0.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const MARKER = '.layout';
+
+// The 0.3 layout's loose per-session droppings — dead state the ephemeral
+// rule says dies. Everything here may appear at the container root (bare
+// launches) or inside a profile dir.
+const DROPPINGS = ['last-status.json', 'launch-cwd', 'exited', 'sidecar-alive', 'slot-owner', 'view-request'];
+
+const BURNLOG_RE = /^burnlog-[A-Za-z0-9_-]+\.jsonl$/;
+// 0.4's own session join key (src/session-log.js). An upgrade while a session
+// is open leaves the new statusline ticking against an unmigrated home, so
+// these appear at the root BEFORE any launch migrates it — already at their
+// final location, they are kept, not a surprise.
+const SESSION_RE = /^session-[A-Za-z0-9_-]+\.jsonl$/;
+// Same allow-list the launcher enforces for profile names.
+const PROFILE_DIR_RE = /^[A-Za-z0-9._-]+$/;
+// Names the new layout owns; their presence in an unmigrated home is exactly
+// the surprise the safety property exists for.
+const RESERVED = new Set(['instances', 'profiles']);
+
+/**
+ * Is a 0.3 session still running in this dir, as far as 0.3 state can say?
+ * The published 0.3 recorded no owning pid, so the freshest signal it left is
+ * the sidecar heartbeat. Refusing on a live heartbeat is the safe direction:
+ * a false "live" delays migration by seconds; a false "dead" would harvest
+ * burnlogs out from under a writing session.
+ * @param {string} dir
+ */
+function legacyLive(dir) {
+  try {
+    if (fs.existsSync(path.join(dir, 'exited'))) return false;
+    return require('./sidecar').sidecarAlive(dir);
+  } catch { return false; }
+}
+
+/**
+ * Move a burnlog to the container root, first-wins on a name collision (the
+ * name carries the Claude session id, so a collision is the same session's
+ * data twice — the copy already at the root is kept).
+ * @param {string} from @param {string} rootDir @param {string} name
+ */
+function harvestBurnlog(from, rootDir, name) {
+  const dest = path.join(rootDir, name);
+  try {
+    if (fs.existsSync(dest)) { fs.rmSync(from, { force: true }); return; }
+    fs.renameSync(from, dest);
+  } catch { /* best effort — a later launch completes it */ }
+}
+
+/**
+ * Bring <home>/.ccr to the 0.4 layout. Total: never throws.
+ *
+ * @param {{ home?: string }} [opts]
+ * @returns {{ ok: true } | { ok: false, error: string }}
+ */
+function ensureLayout(opts = {}) {
+  const home = opts.home || os.homedir();
+  const root = path.join(home, '.ccr');
+  const marker = path.join(root, MARKER);
+
+  try {
+    if (!fs.existsSync(root)) {
+      // Fresh install: create the container already migrated.
+      fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+      fs.writeFileSync(marker, '1\n', { mode: 0o600 });
+      return { ok: true };
+    }
+    if (fs.existsSync(marker)) {
+      sweepLegacyDroppings(root);
+      return { ok: true };
+    }
+
+    // ---- Classify EVERYTHING before touching ANYTHING. ----
+    /** @type {{ dir: string, name: string }[]} */
+    const profileDirs = [];
+    /** @type {string[]} */
+    const looseBurnlogs = [];
+    let rootHasDroppings = false;
+    for (const name of fs.readdirSync(root)) {
+      const p = path.join(root, name);
+      if (RESERVED.has(name)) return { ok: false, error: `ccr: cannot migrate ~/.ccr — unexpected entry '${name}' (reserved by the new layout); move it aside and relaunch` };
+      if (name.startsWith('.')) continue;                      // dotted container entries are left alone
+      if (BURNLOG_RE.test(name)) { looseBurnlogs.push(name); continue; }
+      if (SESSION_RE.test(name)) continue;                     // 0.4 join key — already at its final home
+      if (DROPPINGS.includes(name)) { rootHasDroppings = true; continue; }
+      let st; try { st = fs.lstatSync(p); } catch { continue; }
+      if (st.isDirectory() && PROFILE_DIR_RE.test(name)) { profileDirs.push({ dir: p, name }); continue; }
+      return { ok: false, error: `ccr: cannot migrate ~/.ccr — unexpected entry '${name}'; move it aside and relaunch` };
+    }
+
+    // A live 0.3 session anywhere refuses the whole migration, by name.
+    if (legacyLive(root)) return { ok: false, error: 'ccr: cannot migrate ~/.ccr while a session is running there — close it first' };
+    for (const { dir, name } of profileDirs) {
+      if (legacyLive(dir)) return { ok: false, error: `ccr: cannot migrate ~/.ccr while an instance is running — close '${name}' first` };
+    }
+
+    // ---- Harvest, then sweep, then mark. ----
+    for (const { dir } of profileDirs) {
+      let names; try { names = fs.readdirSync(dir); } catch { continue; }
+      for (const n of names) if (BURNLOG_RE.test(n)) harvestBurnlog(path.join(dir, n), root, n);
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* next launch retries */ }
+    }
+    if (rootHasDroppings) for (const n of DROPPINGS) { try { fs.rmSync(path.join(root, n), { force: true }); } catch { /* best effort */ } }
+    try { fs.chmodSync(root, 0o700); } catch { /* best effort */ }
+    fs.writeFileSync(marker, '1\n', { mode: 0o600 });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: `ccr: migration failed: ${e instanceof Error ? e.message : String(e)}` };
+  }
+}
+
+/**
+ * A DOWNGRADE-then-re-upgrade leaves a migrated container plus a 0.3 session's
+ * loose droppings at the root — a dead instance's live state, which the
+ * ephemeral rule says dies. Its burnlogs already live where the pool is, so
+ * the day's history merges for free. Swept only once that session shows no
+ * heartbeat (the safe direction, same as everywhere else).
+ * @param {string} root
+ */
+function sweepLegacyDroppings(root) {
+  try {
+    if (!fs.existsSync(path.join(root, 'last-status.json'))
+      && !fs.existsSync(path.join(root, 'sidecar-alive'))) return;
+    if (legacyLive(root)) return;
+    for (const n of DROPPINGS) { try { fs.rmSync(path.join(root, n), { force: true }); } catch { /* best effort */ } }
+  } catch { /* best effort */ }
+}
+
+module.exports = { ensureLayout, MARKER };