@bakapiano/ccsm 0.6.0 → 0.8.4

package/README.md

@@ -1,58 +1,192 @@
 # ccsm — Claude Code Session Manager
 
-A small web UI + Node server (Windows-only) that:
+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.
 
-- Lists every live Claude Code session on the machine, sorted by last active time, with title / cwd / age / PID and a one-click **focus** button that raises the already-open wt window (via `EnumWindows` + `SetForegroundWindow` with the Alt-key trick) and a **resume new** button that opens a fresh `wt -d <cwd> claude --resume <id>`.
-- Snapshots the full session set every minute (`data/snapshot.json` + rotated history under `data/snapshots/`). One click **restores** the snapshot — one new wt window per session, `cd` + `claude --resume`.
-- **New session** picks an unused workspace under your work directory, clones the repos you selected (streaming live `git clone --progress` to a per-repo progress bar in the UI), then opens a fresh terminal window running `claude` (or whichever command you set).
-- **Ask Claude to find a session** opens a Claude Code session pre-pointed at this repo so you can grep through past conversations.
+[![open](https://img.shields.io/badge/open-bakapiano.github.io%2Fcssm%2Fv1-1a1815?style=flat-square)](https://bakapiano.github.io/cssm/v1/)
 
-## Quick start
+```
+┌── browser ─────────────────────────┐
+│  https://bakapiano.github.io/cssm/v1/   ← static frontend
+└────────────┬───────────────────────┘
+             │  fetch /api/*   (CORS)
+             │  ws://localhost:7777/ws/*
+             ▼
+┌── local backend ───────────────────┐
+│  ccsm (npm bin)                    │
+│   ├── /api/sessions  /api/snapshot │
+│   ├── /api/sessions/new (NDJSON)   │
+│   ├── /ws/terminal/:id (PTY)       │
+│   └── /api/health  /api/heartbeat  │
+└────────────────────────────────────┘
+```
+
+## 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.
+
+## Install
+
+```bash
+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
+
+`npx @bakapiano/ccsm` works too for a one-shot trial — the protocol still
+gets registered.
+
+## Use
 
-```powershell
-# one-liner — no clone needed
-npx github:bakapiano/cssm
-# open http://localhost:7777
+```bash
+ccsm                       # starts the backend, opens the frontend
 ```
 
-Or from a checkout:
+Or just visit **https://bakapiano.github.io/cssm/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.
 
-```powershell
-git clone https://github.com/bakapiano/cssm.git
+### Install as PWA
+
+In Chrome / Edge, click the install icon in the address bar (or use the
+"Install ccsm" button on the **About** tab inside the app). The PWA gets
+its own window, its own icon, and Window Controls Overlay so the title
+bar blends into the page.
+
+After installing, clicking the PWA icon is the new entry point — no
+terminal needed.
+
+## Defaults
+
+| | |
+|---|---|
+| 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 |
+
+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.
+
+## Layout
+
+```
+ccsm/
+├── server.js                 # Express + WebSocket; API only in prod
+├── bin/ccsm.js               # launcher · detaches server, opens browser
+├── scripts/
+│   ├── 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)
+
+~/.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
+```
+
+## How "wake on click" works
+
+The hosted frontend (https://bakapiano.github.io/cssm/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:
+
+```
+HKCU\Software\Classes\ccsm\shell\open\command
+  → wscript.exe "<LOCALAPPDATA>\ccsm\launcher.vbs" "%1"
+```
+
+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.
+
+First click triggers a one-time Windows dialog ("Open ccsm.cmd?"). Tick
+**Always allow** and future clicks are silent.
+
+## Lifecycle (when does the backend die)
+
+| trigger | reaction |
+|---|---|
+| 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 |
+| SIGINT / SIGTERM | gracefulShutdown |
+
+Every gracefulShutdown saves a final snapshot before exit.
+
+## Dev
+
+```bash
+git clone https://github.com/bakapiano/cssm
 cd cssm
 npm install
 node server.js
+# opens http://localhost:7777 with hot-reload (public/ is served locally
+# and SSE pushes a reload event on every file save)
 ```
 
-ccsm stores its config + snapshots under `~/.ccsm/` so it survives across upgrades, npx cache wipes, and multiple checkouts. Override with `CCSM_HOME=<path>` if you want it elsewhere.
+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.
 
-## Layout
+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.
 
 ```
-ccsm\
-├── server.js           # Express app + 60s auto-snapshot loop
-├── lib\
-│   ├── sessions.js     # ~/.claude/sessions/*.json + live PID cross-check via tasklist
-│   ├── snapshot.js     # save / load / rotate / restore
-│   ├── workspace.js    # workspace = subfolder under workDir; clone repos with progress
-│   ├── launcher.js     # dispatch across wt / powershell / pwsh / cmd
-│   ├── focus.js        # PowerShell + Win32 — listWindowsOf, focusByHwnd, focusByPid
-│   └── config.js       # load/save data/config.json
-├── public\             # vanilla HTML/JS frontend, auto-refresh every 5s
-~/.ccsm/                  # (or $CCSM_HOME)
-├── config.json           # source of truth
-├── snapshot.json         # latest auto-snapshot
-└── snapshots/            # rotating history
+https://bakapiano.github.io/cssm/v1/   ← current
+https://bakapiano.github.io/cssm/v2/   ← future, when /api breaking-changes
 ```
 
-## Defaults
+Installed PWAs are pinned to whichever path they were installed from.
+
+## Status
 
-- Port: `7777`
-- Work dir: `~/ccsm-workspaces` (configurable; each workspace holds one or more repo clones)
-- Terminal: `wt` (Windows Terminal). Also: `powershell` | `pwsh` | `cmd`.
-- claude command: `claude` — any string. When terminal is `wt`, the command is wrapped in `pwsh -EncodedCommand …` (configurable as `commandShell`) so PowerShell aliases / functions / profile-defined names like `ccp` resolve correctly.
-- Auto-focus on launch: on (HWND diff across the terminal process — works for modern wt's multi-window-single-process layout).
-- Snapshot interval: 60s; last 30 kept.
-- Default repos: none — add your own through the Config panel (URL is whatever `git clone` accepts).
+- Backend: Windows-first. macOS / Linux backend ports planned (focus
+  management, terminal spawning, and the protocol-handler registration
+  are the only platform-specific pieces).
+- 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.
+See [CLAUDE.md](CLAUDE.md) for design decisions and the non-obvious
+gotchas baked into the launcher / focus / snapshot code.

package/bin/ccsm.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+'use strict';
+
+// ccsm launcher · entry point for `ccsm` / `npx @bakapiano/ccsm`.
+//
+// Two modes by how it's invoked:
+//
+//   plain `ccsm`           → start backend if not running, open a browser
+//                            window pointing at it. Terminal returns to a
+//                            prompt immediately (detached).
+//
+//   `ccsm ccsm://<action>` → fired by Windows when the user clicks a
+//                            ccsm:// link (PWA offline banner). Same
+//                            backend startup as above, but DO NOT spawn
+//                            an extra browser — the PWA window that
+//                            triggered the click is already open and
+//                            will reconnect as soon as the backend
+//                            becomes reachable.
+//
+// In both modes, if a server is already running we just ping it. New
+// browser window opens only in the plain-`ccsm` case.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+const http = require('node:http');
+const { spawn } = require('node:child_process');
+
+const SERVER = path.join(__dirname, '..', 'server.js');
+const HOME = process.env.CCSM_HOME || path.join(os.homedir(), '.ccsm');
+const LOG  = path.join(HOME, 'server.log');
+
+function loadPreferredPort() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(HOME, 'config.json'), 'utf8'));
+    return Number(cfg.port) || 7777;
+  } catch {
+    return 7777;
+  }
+}
+
+function probe(port, timeoutMs = 800) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://localhost:${port}/api/health`, { timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.on('data', (c) => body += c);
+      res.on('end', () => {
+        try {
+          const j = JSON.parse(body);
+          resolve(j && j.name === '@bakapiano/ccsm' ? j : null);
+        } catch { resolve(null); }
+      });
+    });
+    req.on('error',   () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+function post(port, pathname, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    const req = http.request({
+      hostname: 'localhost', port, path: pathname, method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': 2 },
+      timeout: timeoutMs,
+    }, (res) => {
+      res.resume();
+      res.on('end', () => resolve(res.statusCode < 300));
+    });
+    req.on('error',   () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.write('{}');
+    req.end();
+  });
+}
+
+// Detect ccsm:// protocol invocation. Windows runs us as
+// `ccsm.cmd ccsm://start` when the user clicks a protocol link.
+// argv layout: [node, ccsm.js, "ccsm://..."]
+function parseProtocolArg() {
+  const a = process.argv[2];
+  if (!a || !/^ccsm:\/\//i.test(a)) return null;
+  try {
+    // Normalise: ccsm://start or ccsm://start?foo=bar
+    const u = new URL(a);
+    // host is the action (`start`, `restart`, ...); empty host means
+    // the URL was `ccsm:start` or `ccsm:///action`
+    const action = (u.hostname || u.pathname.replace(/^\/+/, '').split('/')[0] || '').toLowerCase();
+    return { action, raw: a };
+  } catch {
+    return { action: '', raw: a };
+  }
+}
+
+// Compare what's running with what's installed. Returns true if they
+// match (or running is unknown). False means we should restart so the
+// new code takes over after an `npm i -g @bakapiano/ccsm@latest`.
+function isSameVersion(running) {
+  try {
+    const installed = require('../package.json').version;
+    return running.version === installed;
+  } catch { return true; }
+}
+
+(async () => {
+  const protocol = parseProtocolArg();
+  const SILENT = !!protocol;  // ccsm:// invocations should not open a new browser
+  const port = loadPreferredPort();
+
+  // Case 1: existing instance on the preferred port
+  let existing = await probe(port);
+
+  // If an old version is running, ask it to shut down so the freshly
+  // installed code can take over. The launcher then falls through to
+  // Case 2 and spawns the new server itself.
+  if (existing && !isSameVersion(existing)) {
+    const installed = require('../package.json').version;
+    console.log(`ccsm upgrading · running v${existing.version} → installed v${installed}`);
+    await post(port, '/api/shutdown');
+    // Wait for the old process to actually exit so its port frees up.
+    for (let i = 0; i < 30; i++) {
+      await new Promise((r) => setTimeout(r, 200));
+      if (!(await probe(port, 200))) { existing = null; break; }
+    }
+  }
+
+  if (existing) {
+    if (!SILENT) {
+      const opened = await post(port, '/api/spawn-browser');
+      console.log(`ccsm already running · v${existing.version} · http://localhost:${port}`);
+      if (!opened) console.log('(could not open a new window — server might be busy)');
+    } else {
+      console.log(`ccsm already running · ${protocol.raw}`);
+    }
+    return;
+  }
+
+  // Case 2: spawn detached server
+  fs.mkdirSync(HOME, { recursive: true });
+  const out = fs.openSync(LOG, 'a');
+  fs.writeSync(out, `\n[${new Date().toISOString()}] ccsm starting (protocol=${protocol?.raw || '-'})...\n`);
+
+  const child = spawn(process.execPath, [SERVER], {
+    detached: true,
+    stdio: ['ignore', out, out],
+    windowsHide: true,
+    env: {
+      ...process.env,
+      CCSM_LAUNCHER: '1',
+      // Suppress the server's own auto-spawn of a browser when this launch
+      // came from a ccsm:// click — the PWA window that fired it is the
+      // browser, and a second window would just be noise.
+      ...(SILENT ? { CCSM_NO_BROWSER: '1' } : {}),
+    },
+  });
+  child.unref();
+
+  // Poll /api/health for up to ~10s. Once it answers we know the server
+  // is fully booted (port is bound, config loaded, snapshot loop running).
+  // The actual port may differ from the preferred one if it was taken,
+  // so on each iteration we re-probe the preferred port first, then fall
+  // back to scanning preferred+1..preferred+9.
+  const portsToTry = [port, ...Array.from({ length: 9 }, (_, i) => port + i + 1)];
+  let actualPort = null;
+  let ready = null;
+  outer:
+  for (let i = 0; i < 50; i++) {
+    await new Promise((r) => setTimeout(r, 200));
+    for (const p of portsToTry) {
+      const r = await probe(p, 300);
+      if (r) { ready = r; actualPort = p; break outer; }
+    }
+  }
+  if (!ready) {
+    console.error(`ccsm server did not come up in 10s. Check ${LOG}`);
+    process.exit(1);
+  }
+  console.log(`ccsm started · v${ready.version}`);
+  console.log(`backend:  http://localhost:${actualPort}${actualPort !== port ? `  (preferred ${port} was taken)` : ''}`);
+  console.log(`frontend: https://bakapiano.github.io/cssm/v1/`);
+  console.log(`logs:     ${LOG}`);
+
+  // First-run hint — printed once, then a marker file makes us quiet.
+  const firstRunMark = path.join(HOME, '.first-run-shown');
+  if (!fs.existsSync(firstRunMark)) {
+    try { fs.writeFileSync(firstRunMark, new Date().toISOString()); } catch {}
+    console.log('');
+    console.log('First run · ccsm is now running in the background.');
+    console.log('Open the frontend URL above, click "Install ccsm" in your browser');
+    console.log('to install it as a PWA so the icon launches directly into the app.');
+  }
+})().catch((err) => {
+  console.error('ccsm launcher failed:', err);
+  process.exit(1);
+});

package/lib/favorites.js

@@ -1,41 +1,23 @@
 'use strict';
 
-// User-pinned ("favorited") sessions. Stored as a JSON object keyed by
-// sessionId at $DATA_DIR/favorites.json. Each entry captures enough
-// metadata (cwd, title, gitBranch) to render the row even after the
-// session's jsonl is gone — the entry is best-effort archival.
+// User-pinned ("favorited") sessions, keyed by sessionId at
+// $DATA_DIR/favorites.json. Each entry captures enough metadata
+// (cwd, title, gitBranch) to render the row even after the session's
+// jsonl is gone — entries are best-effort archival.
 
-const fs = require('node:fs/promises');
-const path = require('node:path');
 const { DATA_DIR } = require('./config');
+const { createKeyedJsonStore } = require('./jsonStore');
 
-const FAVORITES_PATH = path.join(DATA_DIR, 'favorites.json');
-
-async function loadFavorites() {
-  try {
-    const raw = await fs.readFile(FAVORITES_PATH, 'utf8');
-    const obj = JSON.parse(raw);
-    return obj && typeof obj === 'object' && !Array.isArray(obj) ? obj : {};
-  } catch (e) {
-    if (e.code === 'ENOENT') return {};
-    throw e;
-  }
-}
-
-async function saveFavorites(favs) {
-  await fs.writeFile(FAVORITES_PATH, JSON.stringify(favs, null, 2));
-}
-
-async function listFavorites() {
-  const favs = await loadFavorites();
-  return Object.values(favs).sort((a, b) => (b.addedAt || 0) - (a.addedAt || 0));
-}
+const store = createKeyedJsonStore({
+  dataDir: DATA_DIR,
+  filename: 'favorites.json',
+});
 
 async function addFavorite(sessionId, info = {}) {
   if (!sessionId) throw new Error('addFavorite: sessionId required');
-  const favs = await loadFavorites();
-  const existing = favs[sessionId];
-  favs[sessionId] = existing
+  const map = await store.load();
+  const existing = map[sessionId];
+  const next = existing
     ? { ...existing, ...info, sessionId }
     : {
         sessionId,
@@ -45,29 +27,25 @@ async function addFavorite(sessionId, info = {}) {
         label: info.label || null,
         addedAt: Date.now(),
       };
-  await saveFavorites(favs);
-  return favs[sessionId];
+  return store.set(sessionId, next);
 }
 
-async function removeFavorite(sessionId) {
-  const favs = await loadFavorites();
-  if (!(sessionId in favs)) return false;
-  delete favs[sessionId];
-  await saveFavorites(favs);
-  return true;
+async function hasFavorite(sessionId) {
+  const map = await store.load();
+  return sessionId in map;
 }
 
-async function hasFavorite(sessionId) {
-  const favs = await loadFavorites();
-  return sessionId in favs;
+async function listFavorites() {
+  const list = await store.list();
+  return list.sort((a, b) => (b.addedAt || 0) - (a.addedAt || 0));
 }
 
 module.exports = {
-  loadFavorites,
-  saveFavorites,
+  loadFavorites: store.load,
+  saveFavorites: store.save,
   listFavorites,
   addFavorite,
-  removeFavorite,
+  removeFavorite: store.remove,
   hasFavorite,
-  FAVORITES_PATH,
+  FAVORITES_PATH: store.filePath,
 };

package/lib/jsonStore.js

@@ -0,0 +1,60 @@
+'use strict';
+
+// Factory for a keyed-JSON store under $DATA_DIR. Both favorites and labels
+// have the same shape: a JSON object keyed by sessionId, written atomically
+// on each mutation, with ENOENT swallowed to empty.
+//
+//   const store = createKeyedJsonStore({ filename: 'foo.json', transformValue: (v) => ... })
+//   await store.load()        → object
+//   await store.set(key, v)   → returns the stored value (or null if removed)
+//   await store.remove(key)   → returns true if it existed
+//   await store.list()        → array of values
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+function createKeyedJsonStore({ dataDir, filename, transformValue = (v) => v }) {
+  const filePath = path.join(dataDir, filename);
+
+  async function load() {
+    try {
+      const raw = await fs.readFile(filePath, 'utf8');
+      const obj = JSON.parse(raw);
+      return obj && typeof obj === 'object' && !Array.isArray(obj) ? obj : {};
+    } catch (e) {
+      if (e.code === 'ENOENT') return {};
+      throw e;
+    }
+  }
+
+  async function save(map) {
+    await fs.writeFile(filePath, JSON.stringify(map, null, 2));
+  }
+
+  async function set(key, value) {
+    if (!key) throw new Error('set: key required');
+    const next = transformValue(value, key);
+    if (next == null) return remove(key);
+    const map = await load();
+    map[key] = next;
+    await save(map);
+    return next;
+  }
+
+  async function remove(key) {
+    const map = await load();
+    if (!(key in map)) return false;
+    delete map[key];
+    await save(map);
+    return true;
+  }
+
+  async function list() {
+    const map = await load();
+    return Object.values(map);
+  }
+
+  return { load, save, set, remove, list, filePath };
+}
+
+module.exports = { createKeyedJsonStore };

package/lib/labels.js

@@ -1,49 +1,29 @@
 'use strict';
 
-// User-defined display titles for sessions. Stored as a flat JSON object
-// keyed by sessionId at $DATA_DIR/labels.json. Frontend overlays the label
-// on top of the AI-generated title when rendering live / recent / favorites.
+// User-defined display titles for sessions, keyed by sessionId at
+// $DATA_DIR/labels.json. Frontend overlays the label on top of the
+// AI-generated title when rendering live / recent / favorites.
 
-const fs = require('node:fs/promises');
 const path = require('node:path');
 const { DATA_DIR } = require('./config');
+const { createKeyedJsonStore } = require('./jsonStore');
 
-const LABELS_PATH = path.join(DATA_DIR, 'labels.json');
 const MAX_LEN = 200;
 
-async function loadLabels() {
-  try {
-    const raw = await fs.readFile(LABELS_PATH, 'utf8');
-    const obj = JSON.parse(raw);
-    return obj && typeof obj === 'object' && !Array.isArray(obj) ? obj : {};
-  } catch (e) {
-    if (e.code === 'ENOENT') return {};
-    throw e;
-  }
-}
-
-async function saveLabels(labels) {
-  await fs.writeFile(LABELS_PATH, JSON.stringify(labels, null, 2));
-}
-
-async function setLabel(sessionId, label) {
-  if (!sessionId) throw new Error('setLabel: sessionId required');
-  const trimmed = String(label || '').trim().slice(0, MAX_LEN);
-  if (!trimmed) {
-    return removeLabel(sessionId);
-  }
-  const labels = await loadLabels();
-  labels[sessionId] = trimmed;
-  await saveLabels(labels);
-  return trimmed;
-}
-
-async function removeLabel(sessionId) {
-  const labels = await loadLabels();
-  if (!(sessionId in labels)) return false;
-  delete labels[sessionId];
-  await saveLabels(labels);
-  return true;
-}
-
-module.exports = { loadLabels, saveLabels, setLabel, removeLabel, LABELS_PATH };
+const store = createKeyedJsonStore({
+  dataDir: DATA_DIR,
+  filename: 'labels.json',
+  // Empty / null label triggers a remove via the factory contract.
+  transformValue: (v) => {
+    const trimmed = String(v || '').trim().slice(0, MAX_LEN);
+    return trimmed || null;
+  },
+});
+
+module.exports = {
+  loadLabels: store.load,
+  saveLabels: store.save,
+  setLabel: store.set,
+  removeLabel: store.remove,
+  LABELS_PATH: store.filePath,
+};