@bakapiano/ccsm 0.9.0 → 0.10.1

package/README.md

@@ -1,22 +1,27 @@
 # ccsm — Claude Code Session Manager
 
-A single pane over every live Claude Code session on your machine.
-Hosted web UI + tiny local Node daemon. Windows-first; cross-platform
-in progress.
+A single pane over every Claude / Codex / Copilot CLI session on your
+machine. Each session runs inside the page (xterm.js + a PTY pool in
+the local backend), gets recorded, and re-attaches to the exact
+upstream conversation when you click it again.
 
-[![open](https://img.shields.io/badge/open-bakapiano.github.io%2Fccsm%2Fv1-1a1815?style=flat-square)](https://bakapiano.github.io/ccsm/v1/)
+[![open](https://img.shields.io/badge/open-bakapiano.github.io%2Fccsm-1a1815?style=flat-square)](https://bakapiano.github.io/ccsm/)
 
 ```
 ┌── browser ─────────────────────────┐
-│  https://bakapiano.github.io/ccsm/v1/   ← static frontend
+│  https://bakapiano.github.io/ccsm/  ← version router
+│                  ↓
+│  /ccsm/X.Y.Z/   ← per-version frontend (pinned to your backend)
 └────────────┬───────────────────────┘
              │  fetch /api/*   (CORS)
              │  ws://localhost:7777/ws/*
              ▼
 ┌── local backend ───────────────────┐
 │  ccsm (npm bin)                    │
-│   ├── /api/sessions  /api/snapshot │
-│   ├── /api/sessions/new (NDJSON)   │
+│   ├── /api/sessions  /api/sessions/new   │
+│   ├── /api/sessions/:id/resume     │
+│   ├── /api/sessions/adopt          │
+│   ├── /api/version  /api/upgrade   │
 │   ├── /ws/terminal/:id (PTY)       │
 │   └── /api/health  /api/heartbeat  │
 └────────────────────────────────────┘
@@ -24,12 +29,23 @@ in progress.
 
 ## What it does
 
-- **Lists every live Claude Code session** — title, cwd, age, PID, status. Click **Focus** to raise the wt window that's hosting it (`EnumWindows` + `SetForegroundWindow`, Alt-key trick to defeat the foreground-lock).
-- **Snapshot + Restore** — every 60s the full session set is captured to `~/.ccsm/snapshot.json`. One click restores them: one fresh wt window per session, `cd` + `claude --resume`.
-- **New session** — picks an unused workspace under your work-dir, clones repos with live `git clone --progress` streamed to per-repo progress bars, opens a fresh `claude` in either a wt window or an in-page xterm.js terminal.
-- **Web terminal** — `node-pty` PTY + xterm.js. Runs claude inside the page instead of wt. Optional, install-failure-tolerant.
-- **Favorites / labels / pagination** — pin sessions, rename them, page through history.
-- **Ask Claude to find a session** — opens a claude session pre-pointed at your ccsm data dir so you can grep past conversations.
+- **Runs every CLI session in the page.** `claude`, `codex`, `copilot`
+  or any custom command, in an xterm.js panel. Switch sessions in the
+  sidebar; the PTY keeps running in the backend.
+- **`--resume <uuid>` precision.** ccsm watches the upstream CLI's
+  transcript dir after spawn and captures its session UUID. Click a
+  stopped session later → re-spawns with `--resume <uuid>` (or
+  whatever `resumeIdArgs` template you set per-CLI) so the exact
+  conversation comes back.
+- **Import existing sessions.** Scans `~/.claude` / `~/.codex` /
+  `~/.copilot` and lets you adopt any session ccsm didn't start.
+- **Workspaces + clones.** "New session" picks an unused workspace
+  under your work-dir, clones selected repos with live `git clone
+  --progress` streamed to per-repo progress bars, opens a fresh CLI
+  there. Or pick any existing folder via the file browser.
+- **Folders.** Drag sessions into named folders for organisation.
+- **In-app upgrade.** About page checks npm for newer versions of
+  ccsm and offers a one-click upgrade button. Backend self-restarts.
 
 ## Install
 
@@ -39,11 +55,11 @@ npm i -g @bakapiano/ccsm
 
 This:
 - puts `ccsm` on your PATH
-- registers a `ccsm://` URL protocol so the hosted frontend can wake the
-  backend with one click
+- registers a `ccsm://` URL protocol so the hosted frontend can wake
+  the backend with one click
 
-`npx @bakapiano/ccsm` works too for a one-shot trial — the protocol still
-gets registered.
+`npx @bakapiano/ccsm` works too for a one-shot trial — the protocol
+still gets registered.
 
 ## Use
 
@@ -51,11 +67,13 @@ gets registered.
 ccsm                       # starts the backend, opens the frontend
 ```
 
-Or just visit **https://bakapiano.github.io/ccsm/v1/** in any browser.
-If the backend isn't running, you'll see a "Backend not running" banner
-with a **Start ccsm** button — click it, Windows asks once whether to
-open the `ccsm://` handler (check "Always allow"), and the backend
-spawns silently behind the page. The page auto-reconnects in 1-2s.
+Or just visit **https://bakapiano.github.io/ccsm/** in any browser.
+If the backend isn't running, the router shows a "Backend not running"
+banner with a **Start ccsm** button — click it, Windows asks once
+whether to open the `ccsm://` handler (check "Always allow"), and the
+backend spawns silently behind the page. The router auto-reconnects in
+1-2s and redirects to the frontend matching your installed backend
+version.
 
 ### Install as PWA
 
@@ -73,15 +91,10 @@ terminal needed.
 |---|---|
 | Port | `7777` (auto-bumps if taken) |
 | Work dir | `~/ccsm-workspaces` (each subdirectory holds one or more repo clones) |
-| Terminal | `wt` (Windows Terminal). Also `powershell` / `pwsh` / `cmd` / `web` (in-page xterm.js). |
-| Claude command | `claude` — any alias / function / exe. Wrapped in pwsh when terminal is `wt` so PowerShell aliases like `cc` resolve. |
-| Snapshot interval | 60s; last 30 kept under `~/.ccsm/snapshots/` |
-| Auto-focus | on (HWND-diff across the terminal process — handles modern wt's multi-window single-process layout) |
-| Repos | none by default — add through the **Configure** tab |
+| Built-in CLIs | `claude`, `codex`, `copilot` — add your own via the **Configure** tab |
+| Data dir | `~/.ccsm/` (override with `CCSM_HOME=<path>`) — survives upgrades and npx cache wipes |
 
-All of the above are editable through the **Configure** tab. State lives
-at `~/.ccsm/` (override with `CCSM_HOME=<path>`). Survives upgrades and
-npx cache wipes.
+All of the above are editable through the **Configure** tab.
 
 ## Layout
 
@@ -93,37 +106,30 @@ ccsm/
 │   ├── install.js            # postinstall · registers ccsm:// (Windows)
 │   └── uninstall.js          # preuninstall · cleanup
 ├── lib/
-│   ├── sessions.js           # ~/.claude/sessions/*.json + live PID check via tasklist
-│   ├── snapshot.js           # save / load / rotate / restore
-│   ├── workspace.js          # workspace = subfolder under workDir
-│   ├── launcher.js           # spawn wt / pwsh / cmd
-│   ├── focus.js              # PowerShell + Win32 EnumWindows / SetForegroundWindow
-│   ├── webTerminal.js        # in-process PTY pool · node-pty + WebSocket bridge
-│   ├── config.js / favorites.js / labels.js / jsonStore.js
-└── public/                   # Preact + HTM + signals (no build step) — also pushed to GH Pages
-    ├── js/
-    │   ├── backend.js        # httpBase() / wsBase() — same-origin local, cross-origin GH Pages
-    │   ├── main.js · state.js · api.js · streaming.js · actions.js · dialog.js · toast.js · util.js · icons.js
-    │   ├── components/       # Sidebar, PageHead, Card, SessionsTable, RecentTable, FavoritesTable, TerminalView, NewSessionModal, OfflineBanner …
-    │   └── pages/            # SessionsPage, LaunchPage, TerminalsPage, ConfigurePage, AboutPage
-    └── css/                  # 12 focused stylesheets (tokens, base, layout, sidebar, cards, tables, forms, widgets, feedback, modal, terminals, wco, responsive)
+│   ├── persistedSessions.js  # ~/.ccsm/sessions.json — the source of truth
+│   ├── folders.js            # sidebar tree
+│   ├── localCliSessions.js   # scan ~/.claude · ~/.codex · ~/.copilot
+│   ├── cliSessionWatcher.js  # capture upstream session UUID after spawn
+│   ├── workspace.js          # ws-N allocation + repo clones
+│   ├── webTerminal.js        # node-pty pool · WebSocket bridge
+│   ├── jsonStore.js · config.js
+├── pages-root/               # → GH Pages /  (version router)
+└── public/                   # → GH Pages /<pkg.version>/  (per-version frontend)
 
 ~/.ccsm/                       # or $CCSM_HOME
-├── config.json               # source of truth
-├── snapshot.json             # latest auto-snapshot
-├── snapshots/                # rotating history
-├── favorites.json · labels.json
-├── server.log                # detached-server stdout/stderr
-└── .first-run-shown          # marker so we only print the PWA-install hint once
+├── config.json
+├── sessions.json              # persisted sessions
+├── folders.json
+├── server.log
+└── browser-profile/           # Edge/Chrome --user-data-dir
 ```
 
 ## How "wake on click" works
 
-The hosted frontend (https://bakapiano.github.io/ccsm/v1/) lives entirely
-in the browser sandbox — it cannot spawn processes. So when the backend
-is down, the OfflineBanner's **Start ccsm** is a plain
-`<a href="ccsm://start">`. The OS hands that off to a per-user URL
-protocol handler we registered at install time:
+The hosted frontend lives entirely in the browser sandbox — it cannot
+spawn processes. So when the backend is down, the OfflineBanner's
+**Start ccsm** is a plain `<a href="ccsm://start">`. The OS hands that
+off to a per-user URL protocol handler registered at install time:
 
 ```
 HKCU\Software\Classes\ccsm\shell\open\command
@@ -131,8 +137,8 @@ HKCU\Software\Classes\ccsm\shell\open\command
 ```
 
 The `.vbs` calls `ccsm.cmd "ccsm://start"` with `WindowStyle = 0`. That
-gets to `bin/ccsm.js`, which parses the protocol URL, spawns `server.js`
-detached, and exits. Zero windows ever flash.
+gets to `bin/ccsm.js`, which parses the protocol URL, spawns
+`server.js` detached, and exits. Zero windows ever flash.
 
 First click triggers a one-time Windows dialog ("Open ccsm.cmd?"). Tick
 **Always allow** and future clicks are silent.
@@ -144,17 +150,16 @@ First click triggers a one-time Windows dialog ("Open ccsm.cmd?"). Tick
 | The auto-opened browser window closes | wait 12s · if any other client heartbeats during that window, stay alive; otherwise gracefulShutdown |
 | No heartbeat for 90s | gracefulShutdown |
 | `POST /api/shutdown` | gracefulShutdown |
+| `POST /api/upgrade` after install | self-respawn + gracefulShutdown |
 | SIGINT / SIGTERM | gracefulShutdown |
 
-Every gracefulShutdown saves a final snapshot before exit.
-
 ## Dev
 
 ```bash
 git clone https://github.com/bakapiano/ccsm
-cd cssm
+cd ccsm
 npm install
-node server.js
+CCSM_NO_BROWSER=1 CCSM_KEEP_ALIVE=1 node server.js
 # opens http://localhost:7777 with hot-reload (public/ is served locally
 # and SSE pushes a reload event on every file save)
 ```
@@ -163,30 +168,23 @@ Dev mode is detected via `__dirname.includes('node_modules')` — when
 running from a checkout, the backend also serves `public/`. In an
 npm-installed copy it's API-only, and you use the hosted frontend.
 
-The frontend can also be loaded from GH Pages even in dev — it'll just
-talk to the same `localhost:7777` backend. Useful for testing the
-cross-origin path.
-
 ## Versioning (frontend ↔ backend)
 
-The hosted frontend lives at a versioned path (`/v1/`). Future breaking
-API changes ship a fresh `/v2/` while `/v1/` keeps serving. Each frontend
-build feature-detects via `/api/capabilities`, so a slightly older
-backend still works as long as it advertises the needed feature.
-
-```
-https://bakapiano.github.io/ccsm/v1/   ← current
-https://bakapiano.github.io/ccsm/v2/   ← future, when /api breaking-changes
-```
+The hosted root (`/ccsm/`) is a tiny static **version router**: it
+probes `localhost:7777/api/health`, then redirects you to
+`/ccsm/<backend.version>/`. Each release publishes a fresh
+per-version subdir; old ones stay forever. No semver-compat logic — a
+frontend is always 1:1 with the backend it was built against.
 
-Installed PWAs are pinned to whichever path they were installed from.
+If your backend gets upgraded under a still-loaded page, the
+per-version frontend detects the mismatch on its next probe and
+bounces you back through the router automatically.
 
 ## Status
 
-- Backend: Windows-first. macOS / Linux backend ports planned (focus
-  management, terminal spawning, and the protocol-handler registration
-  are the only platform-specific pieces).
+- Backend: Windows-first. macOS / Linux backend ports planned (URL
+  protocol registration is the only platform-specific install piece).
 - Frontend: cross-platform (pure web).
 
 See [CLAUDE.md](CLAUDE.md) for design decisions and the non-obvious
-gotchas baked into the launcher / focus / snapshot code.
+gotchas baked into the launcher / session-watcher / lifecycle code.

package/lib/cliSessionWatcher.js

@@ -0,0 +1,249 @@
+'use strict';
+
+// Captures the upstream CLI's session id (claude / codex / copilot) so
+// ccsm can later spawn `<cli> --resume <uuid>` and reattach to the same
+// conversation precisely.
+//
+// Approach (poll-based, deliberately):
+// - fs.watch is unreliable on Windows for in-place content writes.
+// - CLIs reuse existing transcripts in the same cwd when they can —
+//   there's no "new file appears" signal to wait on.
+// - Instead we poll the per-CLI transcript dir every POLL_MS, find
+//   candidates whose mtime > spawnAt, read each one's cwd field, and
+//   if exactly one matches our spawn cwd that's the session id.
+// - Window expires after WINDOW_MS — CLIs only persist after the first
+//   user message, so this needs to be generous.
+//
+// Per-CLI profile shape:
+//   dirFor(cwd)          → directory to poll
+//   entryType            → 'file' (claude/codex) or 'dir' (copilot —
+//                          each child dir = one session)
+//   recursive            → for 'file' mode only; walk subdirs too
+//   filePattern          → regex an entry's basename must match
+//   parseId(basename)    → extract the upstream session id from name
+//                          (returns null to skip)
+//   readCwd(entryPath)   → async; returns the cwd recorded inside the
+//                          session, or null if not yet readable.
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const readline = require('node:readline');
+
+const POLL_MS = 1_500;
+const WINDOW_MS = 5 * 60_000;
+
+const profiles = {
+  claude: {
+    dirFor: (cwd) => path.join(os.homedir(), '.claude', 'projects', claudeSlug(cwd)),
+    entryType: 'file',
+    filePattern: /\.jsonl$/i,
+    parseId: (filename) => filename.replace(/\.jsonl$/i, ''),
+    readCwd: (filepath) => firstJsonField(filepath, 'cwd', 12),
+  },
+  codex: {
+    dirFor: () => path.join(os.homedir(), '.codex', 'sessions'),
+    entryType: 'file',
+    recursive: true,
+    filePattern: /\.jsonl$/i,
+    parseId: (filename) => {
+      const m = filename.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i);
+      return m ? m[1] : null;
+    },
+    readCwd: (filepath) => firstJsonField(filepath, 'cwd', 12),
+  },
+  copilot: {
+    // ~/.copilot/session-state/<uuid>/  with workspace.yaml + events.jsonl
+    // Each session is a directory, not a single file.
+    dirFor: () => path.join(os.homedir(), '.copilot', 'session-state'),
+    entryType: 'dir',
+    // Subdir name is the uuid; tolerate any non-empty name (copilot uses
+    // standard uuid4 but we'd rather not be strict).
+    parseId: (dirname) => /^[0-9a-f-]+$/i.test(dirname) ? dirname : null,
+    readCwd: async (dirpath) => {
+      // workspace.yaml has plain `cwd: <path>` on its own line — quick
+      // regex parse, no YAML dep.
+      const yaml = path.join(dirpath, 'workspace.yaml');
+      try {
+        const txt = await fsp.readFile(yaml, 'utf8');
+        const m = txt.match(/^\s*cwd\s*:\s*(.+?)\s*$/m);
+        return m ? m[1].trim() : null;
+      } catch {
+        return null;
+      }
+    },
+  },
+};
+
+function captureSessionId({ cliType, cwd, onCapture, onTimeout, windowMs = WINDOW_MS }) {
+  const profile = profiles[cliType];
+  if (!profile) return () => {};
+  const dir = profile.dirFor(cwd);
+  const spawnAt = Date.now();
+  console.log(`[cliSessionWatcher] start ${cliType} dir=${dir} cwd=${cwd}`);
+
+  let stopped = false;
+  let captured = false;
+  let pollTimer = null;
+  let expireTimer = null;
+  // Track entries we've already proven aren't ours so we don't re-read them.
+  // Only used for "wrong cwd recorded inside the file" — that's stable.
+  // We do NOT cache mtime-based rejections: a stale file can be re-touched
+  // by the CLI later (claude appends to existing transcripts) and we want
+  // to re-evaluate it then.
+  const rejected = new Set();
+
+  const cleanup = () => {
+    if (stopped) return;
+    stopped = true;
+    if (pollTimer) clearTimeout(pollTimer);
+    if (expireTimer) clearTimeout(expireTimer);
+  };
+
+  const finish = (sessionId) => {
+    if (stopped) return;
+    captured = true;
+    cleanup();
+    console.log(`[cliSessionWatcher] captured ${cliType} ${sessionId}`);
+    try { onCapture?.(sessionId); } catch (e) { console.error('[cliSessionWatcher] onCapture:', e); }
+  };
+
+  const onExpire = () => {
+    if (stopped || captured) return;
+    cleanup();
+    console.warn(`[cliSessionWatcher] timeout ${cliType} (no transcript in ${Math.round(windowMs / 1000)}s) cwd=${cwd}`);
+    try { onTimeout?.(); } catch (e) { console.error('[cliSessionWatcher] onTimeout:', e); }
+  };
+
+  const poll = async () => {
+    if (stopped) return;
+    try {
+      const entries = await listEntries(dir, profile);
+      console.log(`[cliSessionWatcher] poll: ${entries.length} entries, rejected=${rejected.size}`);
+      const candidates = [];
+      for (const entryPath of entries) {
+        const base = path.basename(entryPath);
+        if (rejected.has(entryPath)) continue;
+        if (profile.filePattern && !profile.filePattern.test(base)) continue;
+        const id = profile.parseId(base);
+        if (!id) continue;
+        let st;
+        try { st = await fsp.stat(entryPath); } catch { continue; }
+        // Mtime gate is re-evaluated every poll: don't memoise it. If the
+        // CLI later re-touches an old transcript (claude appends to the
+        // existing one for the cwd), this poll will pick it up.
+        if (st.mtimeMs < spawnAt - 2000) continue;
+        candidates.push({ entryPath, id, mtime: st.mtimeMs });
+      }
+      const matched = [];
+      for (const c of candidates) {
+        const cwdFromEntry = await profile.readCwd(c.entryPath);
+        if (cwdFromEntry == null) continue; // not enough data yet
+        if (!samePath(cwdFromEntry, cwd)) { rejected.add(c.entryPath); continue; }
+        matched.push(c);
+      }
+      if (matched.length === 1) {
+        finish(matched[0].id);
+        return;
+      }
+      if (matched.length > 1) {
+        console.warn(`[cliSessionWatcher] ambiguous: ${matched.length} candidates for ${cwd} — skipping capture`);
+        cleanup();
+        return;
+      }
+    } catch (e) {
+      console.error('[cliSessionWatcher] poll:', e.message);
+    }
+    if (!stopped) pollTimer = setTimeout(poll, POLL_MS);
+  };
+
+  (async () => {
+    try { await fsp.mkdir(dir, { recursive: true }); } catch {}
+    if (stopped) return;
+    expireTimer = setTimeout(onExpire, windowMs);
+    poll();
+  })();
+
+  return cleanup;
+}
+
+module.exports = { captureSessionId };
+
+// ── helpers ─────────────────────────────────────────────────────────
+
+async function listEntries(root, profile) {
+  if (profile.entryType === 'dir') {
+    let names;
+    try { names = await fsp.readdir(root, { withFileTypes: true }); }
+    catch { return []; }
+    return names.filter((e) => e.isDirectory()).map((e) => path.join(root, e.name));
+  }
+  // file mode
+  if (profile.recursive) return listAllFiles(root);
+  try {
+    const names = await fsp.readdir(root);
+    return names.map((n) => path.join(root, n));
+  } catch {
+    return [];
+  }
+}
+
+function claudeSlug(cwd) {
+  return cwd.replace(/[:\\\/]/g, '-');
+}
+
+function samePath(a, b) {
+  if (!a || !b) return false;
+  const norm = (p) => path.resolve(p).replace(/[\\\/]+$/, '').toLowerCase();
+  return norm(a) === norm(b);
+}
+
+async function firstJsonField(filepath, field, maxLines) {
+  return new Promise((resolve) => {
+    let stream;
+    try { stream = fs.createReadStream(filepath, { encoding: 'utf8' }); }
+    catch { resolve(null); return; }
+    const rl = readline.createInterface({ input: stream });
+    let count = 0;
+    // rl.close() synchronously emits 'close' on some platforms, which would
+    // re-enter done(null) and clobber the value resolve. Guard against that.
+    let settled = false;
+    const done = (v) => {
+      if (settled) return;
+      settled = true;
+      try { rl.close(); } catch {}
+      try { stream.destroy(); } catch {}
+      resolve(v);
+    };
+    rl.on('line', (line) => {
+      count++;
+      try {
+        const obj = JSON.parse(line);
+        if (obj && Object.prototype.hasOwnProperty.call(obj, field)) {
+          done(obj[field]);
+          return;
+        }
+      } catch {}
+      if (count >= maxLines) done(null);
+    });
+    rl.on('close', () => done(null));
+    rl.on('error', () => done(null));
+  });
+}
+
+async function listAllFiles(root) {
+  const out = [];
+  const walk = async (dir) => {
+    let entries;
+    try { entries = await fsp.readdir(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) await walk(p);
+      else out.push(p);
+    }
+  };
+  await walk(root);
+  return out;
+}

package/lib/config.js

@@ -13,32 +13,59 @@ const CONFIG_PATH = path.join(DATA_DIR, 'config.json');
 
 const LEGACY_DATA_DIR = path.join(__dirname, '..', 'data');
 
+// v1.0 — wt / system-terminal launch path removed. Sessions are always
+// in-page web terminals managed by ccsm. CLI is pluggable: configure one
+// or more entries under `clis` (claude, codex, custom wrappers), pick a
+// default. Old config keys (`terminal`, `commandShell`, `claudeCommand`,
+// `defaultTerminalMode`, `autoFocusOnLaunch`, `focusMovesToCenter`,
+// `snapshot*`) are silently dropped on load.
+const DEFAULT_CLIS = [
+  {
+    id: 'claude',
+    name: 'Claude Code',
+    command: 'claude',
+    args: [],
+    resumeArgs: ['--continue'],
+    resumeIdArgs: ['--resume', '<id>'],
+    shell: 'direct',
+    type: 'claude',
+    builtin: true,
+  },
+  {
+    id: 'codex',
+    name: 'OpenAI Codex',
+    command: 'codex',
+    args: [],
+    resumeArgs: ['resume', '--last'],
+    resumeIdArgs: ['resume', '<id>'],
+    shell: 'direct',
+    type: 'codex',
+    builtin: true,
+  },
+  {
+    id: 'copilot',
+    name: 'GitHub Copilot',
+    command: 'copilot',
+    args: [],
+    resumeArgs: ['--continue'],
+    resumeIdArgs: ['--resume', '<id>'],
+    shell: 'direct',
+    type: 'copilot',
+    builtin: true,
+  },
+];
+
 const DEFAULTS = {
   port: 7777,
   workDir: path.join(os.homedir(), 'ccsm-workspaces'),
-  snapshotIntervalMs: 60 * 1000,
-  snapshotHistoryKeep: 30,
-  claudeCommand: 'claude',
-  terminal: 'wt',
-  commandShell: 'pwsh',
-  // 'wt'  — open a new Windows Terminal window (or whatever `terminal` is set to)
-  // 'web' — spawn in-process PTY, attach via xterm.js in the Terminals tab
-  // Used as the default for new sessions, resume, continue, finder.
-  // Per-launch radio in the UI can still override.
-  defaultTerminalMode: 'wt',
-  autoFocusOnLaunch: true,
-  focusMovesToCenter: false,
-  // 'app'  — Edge/Chrome --app=<url> chromeless window (looks like a desktop app)
-  // 'tab'  — open in default browser as a normal tab
-  // 'none' — don't open anything
-  browserMode: 'app',
-  // Add the repos you most often need on hand. The "new session" button
-  // clones any selected entries into the workspace before launching claude.
-  // Example shape:
+  // Repos available for cloning into a fresh workspace at launch time.
   //   { name: 'foo', url: 'https://github.com/me/foo.git', defaultSelected: true }
   repos: [],
-  finderPrompt:
-    `Help me find an old Claude Code session on this machine. ccsm's data dir is ${DATA_DIR} (latest snapshot at snapshot.json, history under snapshots/). Live sessions are at ~/.claude/sessions/*.json and conversation transcripts under ~/.claude/projects/<cwd-slug>/<sessionId>.jsonl. Ask me what I'm looking for and grep accordingly.`,
+  // Pluggable CLIs. Add wrappers like `ccp` (gc2cc) or self-hosted
+  // proxies by appending an entry. defaultCliId picks one for the
+  // Launch button when the user doesn't override.
+  clis: DEFAULT_CLIS,
+  defaultCliId: 'claude',
 };
 
 function ensureDataDir() {
@@ -59,7 +86,6 @@ function migrateLegacyDataIfNeeded() {
   try {
     fsSync.cpSync(LEGACY_DATA_DIR, DATA_DIR, { recursive: true });
     console.log(`[ccsm] migrated legacy data: ${LEGACY_DATA_DIR} → ${DATA_DIR}`);
-    console.log(`[ccsm] safe to remove the legacy dir when you're sure: rmdir /s "${LEGACY_DATA_DIR}"`);
   } catch (e) {
     console.error('[ccsm] legacy migration failed:', e.message);
   }
@@ -67,10 +93,60 @@ function migrateLegacyDataIfNeeded() {
 
 migrateLegacyDataIfNeeded();
 
+// Strip dropped v0.x keys + clamp shape of survivors. Returns a fresh
+// object so callers don't mutate DEFAULTS.
 function mergeWithDefaults(partial) {
   const out = { ...DEFAULTS, ...partial };
-  if (!Array.isArray(out.repos)) {
-    out.repos = DEFAULTS.repos;
+  // Drop v0.x keys that the new architecture doesn't use.
+  delete out.terminal;
+  delete out.commandShell;
+  delete out.claudeCommand;
+  delete out.defaultTerminalMode;
+  delete out.autoFocusOnLaunch;
+  delete out.focusMovesToCenter;
+  delete out.snapshotIntervalMs;
+  delete out.snapshotHistoryKeep;
+  delete out.autoOpenBrowser;
+  delete out.browserMode;
+  delete out.finderPrompt;
+
+  if (!Array.isArray(out.repos)) out.repos = DEFAULTS.repos;
+  if (!Array.isArray(out.clis)) out.clis = [];
+  // Always inject builtin CLIs (claude, codex) if they're missing or were
+  // deleted from a saved config — they're managed by ccsm, the user can
+  // tweak args/shell but can't remove them. Preserves any user
+  // customisation on existing builtin entries.
+  for (const def of DEFAULT_CLIS) {
+    const existing = out.clis.find((c) => c.id === def.id);
+    if (existing) {
+      existing.builtin = true;
+      // Backfill defaults from the built-in template for any field the
+      // user's saved copy is missing — keeps old configs aligned with new
+      // schema additions (resumeArgs, type, etc.) without clobbering the
+      // user's customisations.
+      if (existing.resumeArgs == null) existing.resumeArgs = def.resumeArgs;
+      if (existing.resumeIdArgs == null) existing.resumeIdArgs = def.resumeIdArgs;
+      if (!existing.type) existing.type = def.type;
+    } else {
+      out.clis.unshift({ ...def });
+    }
+  }
+  // Normalize per-CLI fields.
+  out.clis = out.clis.map((c) => {
+    const { installed, installPath, ...rest } = c;  // strip computed probe fields
+    return {
+      ...rest,
+      args: Array.isArray(rest.args) ? rest.args : [],
+      resumeArgs: Array.isArray(rest.resumeArgs) ? rest.resumeArgs : [],
+      resumeIdArgs: Array.isArray(rest.resumeIdArgs) ? rest.resumeIdArgs : [],
+      shell: ['direct', 'pwsh', 'cmd'].includes(rest.shell) ? rest.shell : 'direct',
+      type: ['claude', 'codex', 'copilot', 'other'].includes(rest.type) ? rest.type : 'other',
+      builtin: !!rest.builtin,
+    };
+  });
+  // Make sure defaultCliId points at an actual CLI; fall back to first.
+  if (!out.clis.find((c) => c.id === out.defaultCliId)) {
+    out.defaultCliId = out.clis[0].id;
   }
   return out;
 }
@@ -105,4 +181,5 @@ module.exports = {
   CONFIG_PATH,
   LEGACY_DATA_DIR,
   DEFAULTS,
+  DEFAULT_CLIS,
 };