@bakapiano/ccsm 0.6.0 → 0.8.4

package/CLAUDE.md

@@ -1,110 +1,284 @@
 # ccsm — Claude Code Session Manager
 
-A small Node/Express + vanilla-JS web tool that gives a single pane over all live Claude Code sessions on this machine, snapshots them, restores them through Windows Terminal, and launches new sessions inside isolated workspaces.
+A small Node/Express + Preact web tool that gives a single pane over all
+live Claude Code sessions on this machine, snapshots them, restores them
+through Windows Terminal, and launches new sessions inside isolated
+workspaces.
 
 ## Why this exists
 
-When you're running 8–10 concurrent `claude` sessions across ad-hoc clones (`D:\proj`, `D:\proj2`, `…`, plus GUID worktree dirs), it's easy to lose track of which terminal is which session. ccsm gives an at-a-glance list and a snapshot/restore safety net.
+When you're running 8–10 concurrent `claude` sessions across ad-hoc
+clones (`D:\proj`, `D:\proj2`, `…`, plus GUID worktree dirs), it's easy
+to lose track of which terminal is which session. ccsm gives an
+at-a-glance list and a snapshot/restore safety net.
+
+## Architecture: hosted frontend + local backend
+
+The single most important fact about ccsm v0.8+ is that **the frontend
+is no longer bundled into the npm package** in production. It lives at
+`https://bakapiano.github.io/cssm/v1/`, served by GitHub Pages, deployed
+via the workflow at `.github/workflows/deploy-pages.yml`.
+
+```
+┌── browser ────────────────────────────┐
+│  https://bakapiano.github.io/cssm/v1/    ← static frontend
+└────────────┬──────────────────────────┘
+             │  fetch /api/*   (CORS, allow-list)
+             │  ws://localhost:7777/ws/*
+             ▼
+┌── local backend ──────────────────────┐
+│  npm i -g @bakapiano/ccsm             │
+│  ccsm                                  │
+│   ├── /api/sessions  /api/snapshot    │
+│   ├── /api/sessions/new (NDJSON)      │
+│   ├── /ws/terminal/:id (PTY)          │
+│   ├── /api/heartbeat /api/spawn-browser│
+│   └── /api/health /api/shutdown       │
+└───────────────────────────────────────┘
+```
+
+Why this split:
+- Frontend can be updated independently — push to `main`, CI rebuilds GH Pages, every user hot-refreshes.
+- No service worker complexity needed for "PWA loads even when backend is dead". The page itself is on GH Pages; the backend going down only loses `/api/*`, and the page handles that gracefully with an OfflineBanner.
+- Cross-platform path forward — backend can be ported per-OS, but the frontend never has to be.
+- Versioned at `/v1/` so future breaking changes ship a fresh `/v2/` while `/v1/` keeps serving the older clients.
+
+In **dev mode** (running from a checkout — `__dirname` not under
+`node_modules`), the backend ALSO serves `public/` so contributors can
+iterate at `localhost:7777/` without pushing.
 
 ## Run
 
 ```powershell
-# from a checkout
-node server.js
+# install once
+npm install -g @bakapiano/ccsm
 
-# zero-install
-npx github:bakapiano/cssm
+# then anywhere
+ccsm
 ```
-Then open http://localhost:7777.
 
-Default port `7777`, default workDir `~/ccsm-workspaces`. Config + snapshots live at `~/.ccsm/` (override with `CCSM_HOME=<path>`). All settings editable through the Config panel (`~/.ccsm/config.json` on disk). Notable knobs:
+`ccsm` opens the hosted frontend in a chromeless Edge `--app=` window.
+Terminal returns immediately (the server is spawned detached). Close
+the window → server saves a final snapshot and exits within ~12s.
 
-- `port` (default `7777`) — preferred listen port. If taken, ccsm tries `+1..+9` then asks the OS for any free port. The startup log prints the actual URL so you always see where it ended up.
-- `browserMode` (default `app`) — how to open the UI on server start. `app` finds Edge or Chrome and spawns it with `--app=<url> --user-data-dir=<DATA_DIR>/browser-profile` for a chromeless webview-style window (no tabs, no address bar). `tab` opens the default browser as a regular tab. `none` skips opening. Legacy `autoOpenBrowser: false` still maps to `none` for back-compat.
-- `claudeCommand` (default `"claude"`) — what gets `--resume`'d or freshly invoked inside the new terminal. Can be an exe (`claude`, `claude.exe`), a PowerShell alias or function (`ccp`), or any wrapper script — see `commandShell` below.
-- `terminal` — `wt` | `powershell` | `pwsh` | `cmd`. wt opens a fresh window per launch (`wt -w new` is set to defeat the "fold into existing window" setting some users have). The other three each spawn via `cmd /c start ... <shell>`.
-- `commandShell` (default `pwsh`) — only consulted when `terminal=wt`. Values `pwsh` / `powershell` wrap `claudeCommand` inside `<shell> -NoExit -NoLogo -Command "Set-Location ...; & '<cmd>' '<args>'..."` so PowerShell aliases / functions / profile-defined names (like `ccp` from `$PROFILE`) resolve. `none` runs the command directly via wt (raw `CreateProcess`) — fine if `claudeCommand` is an actual exe on PATH, broken for aliases. `pwsh` / `powershell` kinds already wrap natively so this knob doesn't affect them; `cmd` kind has no shell concept for aliases.
-- `autoFocusOnLaunch` (default true) — after every launch (new session, finder, resume, restore) the server takes an HWND snapshot of terminal windows, polls for a new HWND, and `SetForegroundWindow`s it. See gotcha below — wt is multi-window single-process, so we diff HWNDs not PIDs.
+If you don't want the auto-opened window (e.g. you live in the PWA),
+just visit `https://bakapiano.github.io/cssm/v1/` — when backend is
+down you see an OfflineBanner with a **Start ccsm** button.
 
-## Layout
+Default port `7777`, default workDir `~/ccsm-workspaces`. Config +
+snapshots live at `~/.ccsm/` (override with `CCSM_HOME=<path>`). All
+settings editable through the Configure panel
+(`~/.ccsm/config.json` on disk). Notable knobs:
+
+- `port` (default `7777`) — preferred listen port. If taken, ccsm tries `+1..+9` then asks the OS for any free port. The startup log prints the actual URL.
+- `browserMode` (default `app`) — `app` finds Edge or Chrome and spawns it with `--app=<url> --user-data-dir=<DATA_DIR>/browser-profile`. `tab` opens the default browser. `none` skips opening.
+- `claudeCommand` (default `"claude"`) — what gets `--resume`'d or freshly invoked. Can be an exe, alias, function, or wrapper script.
+- `terminal` — `wt` | `powershell` | `pwsh` | `cmd`. wt opens a fresh window per launch (`wt -w new`).
+- `commandShell` (default `pwsh`) — only consulted when `terminal=wt`. Wraps `claudeCommand` in `pwsh -NoExit -NoLogo -Command ...` so PowerShell aliases resolve.
+- `autoFocusOnLaunch` (default true) — after every launch (new session, finder, resume, restore) the server takes an HWND snapshot of terminal windows, polls for a new HWND, and `SetForegroundWindow`s it.
+- `finderPrompt` — initial message passed to the "Ask Claude to find a session" finder session.
+
+## ccsm:// protocol · "wake on click"
+
+The hosted frontend can't spawn processes (sandboxed). For "click to
+wake backend" we register a per-user URL protocol handler on Windows:
 
 ```
-D:\ccsm\
-├── server.js                # Express app + 60s auto-snapshot loop
-├── lib\
-│   ├── sessions.js          # reads ~/.claude/sessions/*.json + cross-checks live PIDs (tasklist)
-│   │                        # + pulls last ai-title from ~/.claude/projects/<cwd-slug>/<sessionId>.jsonl
-│   │                        # + listRecentSessions(limit, offset) returns paged {recent, total}
-│   ├── snapshot.js          # save/load/rotate/restore — restore = launch one wt window per session
-│   ├── workspace.js         # workspace = subfolder under workDir holding repo clones;
-│   │                        # "in use" = any live session's cwd is at/under the workspace path
-│   ├── launcher.js          # dispatches across terminal kinds (wt/powershell/pwsh/cmd);
-│   │                        # path.resolve()s cwd; throws if cwd doesn't exist
-│   ├── focus.js             # PowerShell + Win32 — listWindowsOf, focusByHwnd, focusByPid,
-│   │                        # focusNewlyOpenedHwnd (HWND-diff for auto-focus on launch)
-│   ├── favorites.js         # user-pinned sessions, ~/.ccsm/favorites.json keyed by sessionId
-│   └── config.js            # loadConfig/saveConfig with defaults
-├── public\
-│   ├── index.html, app.js, styles.css   # vanilla, auto-refresh every 5s
-└── package.json             # bin entry → `ccsm` (for npx github:bakapiano/cssm)
-
-~/.ccsm/                     # or $CCSM_HOME
-├── config.json              # source of truth
-├── snapshot.json            # latest snapshot, rewritten every 60s
-├── snapshots/               # rotating history (default keep=30)
-├── favorites.json           # { [sessionId]: { sessionId, cwd, title, gitBranch, addedAt } }
-└── browser-profile/         # Edge/Chrome --user-data-dir when browserMode=app
+HKCU\Software\Classes\ccsm\shell\open\command
+  → wscript.exe "<LOCALAPPDATA>\ccsm\launcher.vbs" "%1"
 ```
 
-On first run, if a legacy `<repo>/data/` directory exists and `~/.ccsm/` is empty, `lib/config.js` copies the old data over (one-time, idempotent). The legacy dir is left in place — clean up manually after verifying.
+`launcher.vbs` uses `Shell.Run(..., 0, False)` — windowstyle 0 means the
+spawned `ccsm.cmd` runs **completely hidden**. No console flash. The
+`.cmd` goes through `bin/ccsm.js`, which detects `ccsm://start` in argv,
+spawns `server.js` detached with `CCSM_NO_BROWSER=1`, and exits.
 
-## Locked-in design decisions
+OfflineBanner's "Start ccsm" button is just an `<a href="ccsm://start">`.
+First click triggers a one-time Windows confirmation dialog ("Open
+ccsm.cmd?"); ticking "Always allow" makes it silent thereafter.
+
+postinstall (`scripts/install.js`) registers the protocol unconditionally
+on Windows — including npx-cache installs. The path stored in the
+registry points at whatever `ccsm.cmd` location npm gave us
+(`<prefix>/ccsm.cmd` from `npm config get prefix`).
+
+## Lifecycle
+
+Single `gracefulShutdown(reason)` function in `server.js` is the only
+exit path. It races `saveSnapshot()` against a 2s timeout, kills any
+PTY children, then `process.exit(0)`. Every trigger funnels here:
+
+| trigger | path |
+|---|---|
+| auto-spawned browser window closes | `child.on('exit')` — see smart-kill below |
+| `POST /api/shutdown` | from npm uninstall, from launcher's auto-upgrade |
+| SIGINT / SIGTERM | OS signals |
+| heartbeat watchdog timeout | 90s with no heartbeat, only when launched via `bin/ccsm.js` |
+
+**Smart browser-exit**: when the spawned browser child dies, we don't
+kill immediately. Two filters:
+
+1. **Fast-exit (<5s)** — Edge `--app=` often hands the URL off to an
+   existing Edge profile process group and the spawned child dies
+   milliseconds after creation. We ignore any exit inside the first 5s.
+
+2. **Deferred multi-client check (12s)** — after a real close, wait 12s
+   and check if any heartbeat arrived AFTER the close timestamp. If
+   yes, a hosted-frontend tab (or another window) is keeping us busy,
+   stay alive. If no, gracefulShutdown.
 
-**Workspace = folder holding multiple repo clones.** Each `ws-N` under `workDir` contains a subdirectory per cloned repo. Claude launches at the workspace root so all selected repos are sibling folders.
+Frontend heartbeat cadence is 10s (in `main.js`), so one full cycle
+fits inside the 12s decision window.
+
+Environment overrides:
+- `CCSM_KEEP_ALIVE=1` → disable both browser-exit hook and heartbeat watchdog. For automation hosts.
+- `CCSM_LAUNCHER=1` → set by `bin/ccsm.js` when it spawns the server; enables the heartbeat watchdog.
+- `CCSM_NO_BROWSER=1` → set by the launcher when handling a `ccsm://` click; suppresses the server's auto-open browser.
+- `CCSM_NO_DEV=1` → suppress dev-mode features (static serving, hot-reload SSE) even when running from a checkout.
+
+## Layout
 
 ```
-D:\ccsm-workspaces\
-├── ws-1\
-│   ├── repo-a\
-│   └── repo-b\
-├── ws-2\
-│   └── repo-a\
+ccsm/
+├── server.js                     # Express + WebSocket; API-only in prod
+├── bin/ccsm.js                   # launcher · detach, wake-on-protocol,
+│                                 # auto-upgrade-restart, first-run hint
+├── scripts/
+│   ├── install.js                # postinstall · ccsm:// + launcher.vbs
+│   └── uninstall.js              # preuninstall · cleanup + /api/shutdown
+├── lib/
+│   ├── sessions.js               # ~/.claude/sessions/*.json + tasklist PID check
+│   ├── snapshot.js               # save / load / rotate / restore
+│   ├── workspace.js              # workspace = folder under workDir
+│   ├── launcher.js               # spawn wt / pwsh / cmd
+│   ├── focus.js                  # PowerShell + Win32 EnumWindows / SetForegroundWindow
+│   ├── webTerminal.js            # in-process PTY pool · node-pty + WebSocket bridge
+│   ├── favorites.js · labels.js  # pinned sessions / rename overrides
+│   ├── jsonStore.js              # shared keyed-JSON store factory
+│   └── config.js                 # loadConfig / saveConfig
+└── public/                       # Preact + HTM + signals (no build step) — also pushed to GH Pages /v1/
+    ├── index.html                # relative paths so it works at any host path
+    ├── manifest.webmanifest      # PWA · relative start_url, WCO display override
+    ├── favicon.svg
+    ├── js/
+    │   ├── backend.js            # httpBase() / wsBase() — same-origin local, cross-origin hosted
+    │   ├── main.js               # boot · clock tick · heartbeat · is-app body class
+    │   ├── state.js              # signals
+    │   ├── api.js                # fetch wrapper + loaders
+    │   ├── streaming.js          # NDJSON clone-progress stream
+    │   ├── actions.js            # focus / resume / favorite / rename
+    │   ├── dialog.js · toast.js  # ccsmConfirm / ccsmPrompt / setToast
+    │   ├── html.js · icons.js · util.js
+    │   ├── components/
+    │   │   ├── App.js · Sidebar.js · PageHead.js · Footer.js
+    │   │   ├── ServerStatus.js · Toast.js · Fab.js · OfflineBanner.js
+    │   │   ├── Card.js · Pagination.js · TitleCell.js
+    │   │   ├── SessionsTable.js · RecentTable.js · FavoritesTable.js
+    │   │   ├── RepoPicker.js · ReposEditor.js · WorkspacePicker.js
+    │   │   ├── WorkspacesGrid.js · SnapshotPanel.js · ProgressList.js
+    │   │   ├── TerminalView.js · NewSessionModal.js
+    │   │   └── DialogHost.js
+    │   └── pages/
+    │       ├── SessionsPage.js · LaunchPage.js
+    │       ├── TerminalsPage.js
+    │       ├── ConfigurePage.js · AboutPage.js
+    └── css/                      # 13 focused stylesheets
+        ├── tokens.css · base.css · layout.css
+        ├── sidebar.css · cards.css · tables.css · forms.css
+        ├── widgets.css · feedback.css · modal.css
+        ├── terminals.css · wco.css · responsive.css
+
+~/.ccsm/                          # or $CCSM_HOME
+├── config.json                   # source of truth
+├── snapshot.json                 # latest auto-snapshot
+├── snapshots/                    # rotating history (default keep=30)
+├── favorites.json · labels.json  # pinned / renamed sessions
+├── server.log                    # detached-server stdout/stderr
+├── .first-run-shown              # marker so launcher only prints PWA hint once
+└── browser-profile/              # Edge/Chrome --user-data-dir when browserMode=app
+
+%LOCALAPPDATA%/ccsm/
+└── launcher.vbs                  # silent ccsm:// dispatcher (written by postinstall)
+
+HKCU\Software\Classes\ccsm        # URL protocol registration
 ```
 
-The alternative ("one repo per workspace") was explicitly rejected — don't refactor toward it without re-confirming.
+On first run, if a legacy `<repo>/data/` directory exists and `~/.ccsm/`
+is empty, `lib/config.js` copies the old data over (one-time,
+idempotent).
+
+## Locked-in design decisions
+
+**Workspace = folder holding multiple repo clones.** Each `ws-N` under
+`workDir` contains a subdirectory per cloned repo. Claude launches at
+the workspace root so all selected repos are sibling folders. "One repo
+per workspace" was explicitly rejected.
+
+**wt: one window per session, not stacked tabs.** Both
+`/api/snapshot/restore` and `/api/sessions/new` open a fresh `wt`
+window. "Stacked tabs via `-w 0 nt`" was explicitly rejected.
+
+**"In use" detection.** A workspace is in use iff any live Claude
+session's cwd is at-or-inside the workspace path (case-insensitive
+Windows compare via `path.resolve().toLowerCase()`).
 
-**wt: one window per session, not stacked tabs.** Both `/api/snapshot/restore` and `/api/sessions/new` open a fresh `wt` window. The alternative ("`-w 0 nt` stacking in one window") was explicitly rejected — tabs become hard to track when restoring 8+ sessions.
+**Workspace naming.** Auto-allocated names are `ws-1`, `ws-2`, …
+(lowest free integer). Hand-named folders under `workDir` are still
+picked up.
 
-**"In use" detection.** A workspace is in use iff any live Claude session's cwd is at-or-inside the workspace path (case-insensitive Windows compare via `path.resolve().toLowerCase()`). New-session always tries to pick a free workspace before creating `ws-N+1`.
+**Frontend trusts the backend's capability advertisement.**
+`/api/capabilities` returns `{ webTerminal: true|false, ... }`. The
+frontend uses ONLY features the backend says it has. Future breaking
+changes ship a fresh `/v2/` frontend path; old `/v1/` still works
+against backends that advertise the v1 contract.
 
-**Workspace naming.** Auto-allocated names are `ws-1`, `ws-2`, … (lowest free integer). Hand-named folders the user drops under `workDir` are still picked up — workspace name = literal folder name.
+**One source of truth for cross-origin.** `public/js/backend.js`
+exports `httpBase()` and `wsBase()`. Localhost → same-origin (empty
+base). Anything else → `http://localhost:7777`. CORS on the backend
+allows `https://bakapiano.github.io` only — never `*`.
 
 ## API surface
 
 | Method | Path | Purpose |
 |---|---|---|
 | GET | `/api/sessions` | live sessions sorted by `updatedAt` desc |
-| GET / PUT | `/api/config` | read / replace config (merged against defaults) |
+| GET | `/api/sessions/recent` | recently-used sessions from jsonl mtimes · `?limit=&offset=` |
+| POST | `/api/sessions/new` | body `{repos, workspace?, terminal: 'wt'\|'web'}` — NDJSON stream |
+| POST | `/api/sessions/finder` | opens a wt with `claude` in `~/.ccsm` and `finderPrompt` |
+| POST | `/api/sessions/:id/resume` | body `{cwd}` — `wt -d <cwd> claude --resume <id>` |
+| POST | `/api/sessions/:id/focus` | match a wt window by title, fall back to PID-parent walk |
+| GET | `/api/sessions/web` | list active web-terminal PTY sessions |
+| DELETE | `/api/sessions/web/:id` | kill a web-terminal PTY |
+| GET / PUT | `/api/config` | read / replace config |
 | GET / POST | `/api/snapshot` | latest snapshot / force-save now |
 | GET | `/api/snapshot/history` | rotated history filenames |
-| POST | `/api/snapshot/restore` | launch one wt window per session in latest snapshot (body `{file}` for historic) |
+| POST | `/api/snapshot/restore` | launch one wt window per session in snapshot |
 | GET | `/api/workspaces` | workspaces under workDir with repo clone status + in-use flag |
-| POST | `/api/sessions/new` | body `{repos, workspace?, launch?}` — picks/creates ws, clones missing repos, launches wt |
-| POST | `/api/sessions/finder` | opens a wt with `claude` in `D:\ccsm` and the `finderPrompt` as opening message |
-| POST | `/api/sessions/:id/resume` | body `{cwd}` — launches `wt -d <cwd> claude --resume <id>` |
-| GET | `/api/sessions/recent` | recently-used sessions from `~/.claude/projects/*/*.jsonl` mtimes, excluding live ids · query `?limit=15&offset=0` for pagination · returns `{recent, total, limit, offset}` |
-| POST | `/api/sessions/:id/focus` | matches a wt window by title (cleaned of leading status glyphs) against the session's ai-title; falls back to PID-parent walk if no unique match |
-| GET | `/api/favorites` | array of pinned sessions sorted by `addedAt` desc |
-| POST | `/api/favorites/:id` | star a session; body `{cwd, title, gitBranch?, label?}` (snapshot of current row data so the favorite stays meaningful after the jsonl is gone) |
-| DELETE | `/api/favorites/:id` | unstar |
-| GET | `/api/terminals` | enumerate built-in terminal kinds + their process names |
-| GET | `/api/health` | sanity ping |
-
-`/api/sessions/new` streams **NDJSON** (one JSON object per line, `Content-Type: application/x-ndjson`). Event types: `workspace`, `clone-start`, `clone-progress` (phase/percent/current/total/detail), `clone-line` (raw git stderr line when not a progress line), `clone-end`, `launched`, `done`. The frontend reads it with `fetch().body.getReader()` + `TextDecoder` and updates per-repo progress bars live.
+| GET | `/api/favorites` · POST/DELETE `/api/favorites/:id` | star / unstar |
+| GET | `/api/labels` · PUT/DELETE `/api/labels/:id` | rename / clear override |
+| GET | `/api/terminals` | enumerate built-in terminal kinds |
+| GET | `/api/capabilities` | `{ webTerminal: bool, ... }` for frontend feature gating |
+| GET | `/api/health` | sanity ping + version |
+| POST | `/api/heartbeat` | called every 10s by the frontend; feeds lifecycle decisions |
+| POST | `/api/spawn-browser` | open another Edge window into the running server |
+| POST | `/api/shutdown` | gracefulShutdown — used by uninstall + auto-upgrade |
+| WS | `/ws/terminal/:id` | xterm.js bridge to a PTY in the webTerminal pool |
+| GET (dev) | `/api/dev/ping` · `/api/dev/reload` | hot-reload SSE (only when running from a checkout) |
+
+`/api/sessions/new` streams **NDJSON** (one JSON object per line). Event
+types: `workspace`, `clone-start`, `clone-progress` (phase/percent/
+current/total/detail), `clone-line` (raw git stderr line when not a
+progress line), `clone-end`, `launched`, `done`. The frontend reads it
+with `fetch().body.getReader()` + `TextDecoder` and updates per-repo
+progress bars live.
+
+**WebSocket Origin check**: same allow-list as CORS. The upgrade handler
+rejects any Origin not in `ALLOWED_ORIGINS` (plus localhost/127.0.0.1).
+Browsers always send Origin on WS upgrades.
 
 ## Non-obvious gotchas
 
-**wt.exe `-d` flag, verified variants** (marker-file probes confirming `%CD%` inside the new tab):
+**wt.exe `-d` flag** (marker-file probes confirming `%CD%` inside the new tab):
 
 | variant | result |
 |---|---|
@@ -116,79 +290,159 @@ The alternative ("one repo per workspace") was explicitly rejected — don't ref
 | `wt -d "D:\ccsm" <cmd>` (literal quotes) | ✗ wt doesn't open |
 | `wt new-tab -d D:\ccsm <cmd>` | ✗ wt doesn't open |
 
-ccsm uses variant 1 and always `path.resolve()`s the cwd first — defends against a malformed `D:ccsm` (no separator) being interpreted as "current dir on drive D + ccsm", which would resolve to e.g. `D:\ccsm\ccsm`.
+ccsm uses variant 1 and always `path.resolve()`s the cwd first — defends
+against a malformed `D:ccsm` being interpreted as "current dir on drive
+D + ccsm".
 
 **Don't test wt launching via `node -e "..."` inside `bash -c`.** Backslashes get eaten by shell quoting and the JS string ends up malformed. Write a `.js` file and `node file.js` instead.
 
-**focusBySession — title-based wt window matching.** Walking up the claude.exe PID parent chain and taking `MainWindowHandle` of the wt process *always* returns the same canonical window in modern multi-window single-process wt — clicking different sessions all focused the same window. `focusBySession` instead lists all visible wt windows (`EnumWindows` filtered by process name), strips the leading wt status glyph (`✳ `, `⠐ `, `⠠ ` …) and compares to the session's ai-title. Falls back to title-substring, then cwd-basename, then the old PID-parent walk when no unique match — at least the user sees *some* wt window even if it's the wrong tab. Caveat: for sessions sitting in an inactive tab of a multi-tab wt window, the window title shows the *active* tab's title — so we can't find them by title alone and the fallback is wrong-tab.
-
-**Focus helper (`lib/focus.js`).** One `powershell.exe -EncodedCommand <base64>` invocation per call, dispatched by `CCSM_FOCUS_MODE` env var into modes `list` (enumerate visible top-level windows owned by a process name), `focus-hwnd` (activate a specific HWND), `focus-pid` (walk parent chain to MainWindowHandle then activate). Encoded as UTF-16-LE-base64 — passing the C# block via stdin to `-Command -` silently produces no output, so we don't. Three gotchas baked in:
-1. C# `out _` discard breaks PowerShell 5.1's bundled C# compiler — use a named `uint dummy`.
-2. Windows blocks background processes from `SetForegroundWindow` — synthesize an Alt-key down/up via `keybd_event 0x12` first ("Alt-key trick") to qualify our process. Without it, `activated` returns false even though the window is found.
-3. `ConvertTo-Json -AsArray` is PS 7+; on PS 5.1 build the JSON array manually as `'[' + ($items -join ',') + ']'` to avoid the single-element flattening.
-
-**HWND-diff for auto-focus, not PID-diff.** Modern Windows Terminal is multi-window single-process: one `WindowsTerminal.exe` PID owns 8+ top-level HWNDs. So `tasklist`-style PID-set-diff after launch returns empty even though a new window actually opened. We list visible top-level windows (filtered by owning-process name) via `EnumWindows`, snapshot the HWND set before launch, poll after, focus the new HWND. Works uniformly for wt and the per-process terminals (`powershell.exe` etc) where each launch is also a new process.
-
-**wt `-w new`.** wt's `windowingBehavior` setting in some user profiles folds new `wt …` invocations into the existing window as a tab, breaking "one window per session". Force-prepending `-w new` makes wt always create a new window (which is one of those many HWNDs above). Without `-w new`, both the auto-focus path and the design-decision-of-one-window-per-session silently break.
-
-**Auto-snapshot loop.** `setInterval` in `server.js` calls `saveSnapshot` every `snapshotIntervalMs`. The history dir grows until `snapshotHistoryKeep` is exceeded, then oldest are pruned.
-
-**Session listing.** `~/.claude/sessions/<pid>.json` is the source of truth. We cross-check the `pid` field against `tasklist /FI "IMAGENAME eq claude.exe"` so stale entries from crashed/exited claudes don't appear. `ai-title` is read by tailing the last 1 MB of the matching `.jsonl` and finding the last `"type":"ai-title"` line.
-
-**`projectSlugForCwd`.** The path-to-slug mapping is `cwd.replace(/[:\\]/g, '-')`, e.g. `D:\ccsm` → `D--ccsm`, `C:\Users\foo` → `C--Users-foo`, `D:\` → `D--`.
+**focusBySession — title-based wt window matching.** Walking up the
+claude.exe PID parent chain and taking `MainWindowHandle` of the wt
+process *always* returns the same canonical window in modern multi-
+window single-process wt — clicking different sessions all focused the
+same window. `focusBySession` lists all visible wt windows
+(`EnumWindows` filtered by process name), strips the leading wt status
+glyph (`✳ `, `⠐ `, `⠠ ` …) and compares to the session's ai-title.
+Falls back to title-substring, then cwd-basename, then the old PID-
+parent walk when no unique match.
+
+**Focus helper (`lib/focus.js`).** One `powershell.exe -EncodedCommand <base64>` invocation per call, dispatched by `CCSM_FOCUS_MODE` env var. Encoded as UTF-16-LE-base64. Three baked-in gotchas:
+1. C# `out _` discard breaks PowerShell 5.1's C# compiler — use a named `uint dummy`.
+2. Windows blocks background processes from `SetForegroundWindow` — synthesize an Alt-key down/up via `keybd_event 0x12` first ("Alt-key trick").
+3. `ConvertTo-Json -AsArray` is PS 7+; on PS 5.1 build the JSON array manually.
+
+**HWND-diff for auto-focus, not PID-diff.** Modern Windows Terminal is multi-window single-process: one `WindowsTerminal.exe` PID owns 8+ top-level HWNDs.
+
+**wt `-w new`.** wt's `windowingBehavior` setting in some profiles folds new `wt …` invocations into the existing window as a tab. Force-prepending `-w new` makes wt always create a new window.
+
+**Auto-snapshot loop.** `setInterval` in `server.js` calls
+`saveSnapshot` every `snapshotIntervalMs`. The history dir grows until
+`snapshotHistoryKeep` is exceeded, then oldest are pruned. AND
+`gracefulShutdown` always saves one last snapshot before exit so a
+restart can restore current state.
+
+**Session listing.** `~/.claude/sessions/<pid>.json` is the source of
+truth. We cross-check the `pid` field against
+`tasklist /FI "IMAGENAME eq claude.exe"` so stale entries from crashed
+claudes don't appear. `ai-title` is read by tailing the last 1 MB of
+the matching `.jsonl` and finding the last `"type":"ai-title"` line.
+
+**`projectSlugForCwd`.** `cwd.replace(/[:\\]/g, '-')`, e.g. `D:\ccsm` → `D--ccsm`.
+
+**ccsm:// silent dispatch.** Direct registration of `ccsm.cmd` as the
+protocol handler causes a brief console window flash (cmd hosts the
+.cmd file). The wscript.exe + .vbs wrapper avoids it entirely — wscript
+is a Windows-subsystem host (no console) and `Shell.Run(..., 0, False)`
+launches the target hidden. The `.vbs` is generated at install time
+with the correct ccsm.cmd path baked in.
+
+**Edge --app handoff race.** When the user has an existing Edge profile
+process running, `--app=URL --user-data-dir=DIR` against the same DIR
+may cause the new msedge.exe to immediately exit after handing the URL
+off to the existing process. Our child handle dies milliseconds after
+spawn. The lifecycle hook ignores any browser-child exit inside the
+first 5s for exactly this reason.
 
 ## Frontend design language
 
-The UI deliberately copies **claude.ai's** calm light aesthetic — warm cream surfaces, generous spacing, soft borders, single Claude-orange accent. Don't dark-mode-ify or chrome-ify.
+The UI deliberately copies **claude.ai's** calm light aesthetic — warm
+cream surfaces, generous spacing, soft borders, **no orange highlights**.
+The brand orange `#b3614a` survives only in the brand mark / wordmark
+dot. Every other "highlight" use (selection, focus rings, dirty
+indicators, progress bars, page-actions banner) is ink/gray.
 
-**Palette** (CSS vars in `public/styles.css`):
+**Palette** (CSS vars in `public/css/tokens.css`):
 - `--bg`            `#faf9f5`  warm cream page background
 - `--bg-elev`       `#ffffff`  card surfaces
-- `--sidebar-bg`    `#f3f0e8`  slightly darker cream for the rail
-- `--border`        `#e8e3d5`  hairlines
-- `--ink`           `#1a1815`  body text (warm near-black)
-- `--ink-mid`       `#534e44`  secondary
-- `--ink-muted`     `#8a8475`  meta
-- `--accent`        `#c45f3f`  Claude warm orange — for primary actions, focus rings, active states ONLY
-- Status: green `#4a8a4a` idle · yellow `#c4892b` busy (pulsing) · red `#b73f3f` danger
+- `--sidebar-bg`    `#faf9f5`  (same as `--bg`, single continuous surface)
+- `--border`        `#e8e3d5`
+- `--ink`           `#1a1815`  body text (warm near-black, also used for terminal background)
+- `--ink-mid` / `--ink-muted` / `--ink-faint`
+- `--accent`        `#b3614a`  desaturated terracotta — brand only
+- Status: green `#4a8a4a` idle · blue `#4a73a5` busy (pulsing) · red `#b73f3f` danger
+- Favorite star: `#e3b341` (gold, the only intentional non-grayscale accent in the data area)
 
 **Type**:
-- Body / headings: **Geist** (Google Fonts, 300–700). No Fraunces / no italic display.
-- Mono: **JetBrains Mono** for paths, PIDs, sessionIds, branch tags, timestamps in meta.
+- Body / headings: **Geist** (Google Fonts, 300–700).
+- Mono: **JetBrains Mono** for paths, PIDs, sessionIds, branch tags.
 - Always `font-variant-numeric: tabular-nums` on numeric cells.
 
+**Buttons**:
+- `.action` (default) — white bg, ink-mid border, ink text.
+- `.action.primary` — black ink bg, white text. The "do this" CTA.
+- `.action.subtle` — transparent bg, light border.
+- `.action.danger` — filled red bg + white text (e.g. Remove repo).
+
 **Layout**:
-- **Sidebar** (collapsible, ~232px ↔ ~60px, state in `localStorage["ccsm.sidebar-collapsed"]`):
-  - top: brand mark (orange rounded square) + `ccsm.` wordmark
-  - mid: 3 nav items (Sessions / Launch / Configure) with stroke icons + label + optional badge
-  - divider + utility items (Refresh, Ask Claude)
-  - footer: collapse toggle (chevron flips on collapse via CSS rotate)
-- **Main column**: page header (title + subtitle + meta row of port/terminal/clock) → content cards → footer status line
-- Cards: `.card` (white, 10px radius, very soft `--shadow`), `.card-head` with title+meta, `.card-body` with optional `.card-body-flush` for tables.
-- Tables: wrapped in `.table-scroll` (`overflow-x: auto`, min-width 760px) so narrow viewports scroll horizontally instead of cramping.
+- Sidebar (collapsible, ~232px ↔ ~60px, state in `localStorage["ccsm.sidebar-collapsed"]`)
+  - brand mark + `CCSM.` wordmark
+  - 5 nav items: Sessions / Launch / Terminals / Configure / About (Terminals only shown when `capabilities.webTerminal === true`)
+  - footer: Collapse toggle (chevron flips on collapse)
+- Page-head: title + subtitle on the left, server-status pill + Refresh button on the right
+- Top-right control group uses fixed `min-height: 28px` and `border-radius: 999px` so server-status + Refresh align as a coherent control row
 
 **Animation**:
-- **Don't re-animate on refresh.** Rows have a one-shot staggered fade-in animation. `app.js` `markRendered(tableId)` adds `.no-anim` to the tbody after the first render via double `requestAnimationFrame`, so subsequent 5-second auto-refreshes don't restage every row (would strobe).
+- Row staggered fade-in on first render. Preact's component identity prevents re-stage on auto-refresh (no `markRendered` machinery needed in v0.7+).
 - Panel switch: 0.35s `panel-in` fade-up.
-- Tab indicator: orange left bar on active sidebar item (`::before`).
-- Busy status mark: green-pulse via `box-shadow` keyframes.
-
-**Star (favorites) UI**:
-- Star button sits **inside the title cell**, right next to the title text (not in its own column). Outline-style by default at 55% opacity; row-hover bumps to 100%; favorited state fills with the accent color.
-- Click is delegated at the table level (`button[data-star]`). Toggle is **optimistic**: `state.favorites` updates and re-renders all 3 tables before the network call returns; failure shows a toast.
-- Backend snapshots `cwd / title / gitBranch` into `favorites.json` so the favorite is still meaningful after the source jsonl is gone.
-
-**No emoji in the UI** unless the user typed it (e.g. wt status glyphs in session titles). Use inline SVG icons everywhere (line stroke, 1.5–2px) so they take `currentColor` and live with the type weight.
-
-## Lifecycle: server tied to browser window
-
-When the user launches via `npx @bakapiano/ccsm` from an interactive terminal (`process.stdout.isTTY === true`) AND `browserMode === 'app'`, the server keeps the spawned Edge/Chrome child handle and listens for its `exit` event. When the user closes the chromeless window, msedge.exe (running with its own `--user-data-dir=<DATA_DIR>/browser-profile` process group) exits, our hook fires `process.exit(0)`, and the terminal returns to a prompt. Headless / `nohup` launches don't get this hook (no TTY) and stay running.
+- Busy status mark: blue pulse via `box-shadow` keyframes.
+
+**No emoji in the UI** unless the user typed it (e.g. wt status glyphs
+in session titles). Use inline SVG icons everywhere (line stroke, 1.5–
+2px) so they take `currentColor`.
+
+**PWA + WCO**:
+- `display_override: ["window-controls-overlay", "standalone"]` in
+  manifest. When installed and launched as PWA, the title bar's
+  middle is reclaimed; only OS controls float top-right.
+- `public/css/wco.css` provides drag regions (`-webkit-app-region:
+  drag` on `.sidebar-brand`, `.page-head`, etc., unconditional — Chromium
+  ignores in plain tabs, honors in PWA / `--app=`). Interactive
+  elements opt out via the no-drag block.
+- Padding gets shuffled (`body.is-app .main / .sidebar` lose top
+  padding, children compensate) so the very top of the window is
+  draggable instead of being `.main`'s dead padding zone.
+
+## Versioning
+
+The hosted frontend lives at `/v1/`. Backend follows semver but treats
+its API surface as additive:
+- Patch: bug fixes, no API change.
+- Minor: new endpoints, new fields on existing responses. Old frontend tolerates unknown extras.
+- Major: breaking changes. New frontend at `/v2/`; old frontend at `/v1/` keeps working against backends that advertise the v1 contract via `/api/capabilities`.
+
+`bin/ccsm.js` does auto-upgrade-restart: when the user runs `ccsm` and
+the installed package version differs from a running backend, it POSTs
+`/api/shutdown` to the old, waits for the port to free, then spawns a
+fresh server. So `npm i -g @bakapiano/ccsm@latest && ccsm` is one
+seamless step.
+
+## Cross-platform
+
+Today: Windows-first.
+
+Cross-platform-clean already:
+- Frontend (pure web)
+- `bin/ccsm.js` (pure node)
+- `lib/webTerminal.js` (node-pty handles platform)
+- `lib/snapshot.js`, `lib/config.js`, `lib/jsonStore.js` (fs only)
+- `server.js` Express + ws
+
+Windows-specific (need ports for Mac/Linux):
+- `scripts/install.js` — uses `reg.exe` and `wscript.exe`. Mac: write `Info.plist` with `CFBundleURLTypes`. Linux: write `~/.local/share/applications/ccsm.desktop` with `MimeType=x-scheme-handler/ccsm`.
+- `lib/focus.js` — PowerShell + Win32. Mac: `osascript`. Linux: `wmctrl`.
+- `lib/launcher.js` — wt/pwsh/cmd. Mac: Terminal.app via osascript. Linux: gnome-terminal etc.
+- `lib/sessions.js` — `tasklist`. Mac/Linux: `ps -eo pid,comm`.
+
+Pattern for adding a platform: `switch (process.platform)` at each
+entry point in those files. Each platform branch is roughly 50-100
+lines.
 
 ## Extending
 
 When adding features, the natural extension points:
-- New REST routes: `server.js` (keep them under `/api/*`, use `asyncH` wrapper).
-- Frontend section: add a `<section class="card">` in `public/index.html` and a render function in `public/app.js`. Use `markRendered(tableId)` after the first render to suppress refresh strobing.
-- Persistent user data: drop a JSON file under `~/.ccsm/` (like `favorites.json`) and wrap with a small lib module — config.js / favorites.js pattern.
-- Workspace lifecycle (delete, rename): `lib/workspace.js`.
-- Different launch modes (e.g., stacked tabs): `lib/launcher.js` — but check first whether the "one window per session" decision still holds.
+- **New REST routes**: `server.js` (keep under `/api/*`, use the `asyncH` wrapper, decide if it needs CORS by being in the allow-list).
+- **Frontend page**: `public/js/pages/<Name>Page.js`, route in `App.js`, sidebar nav item in `Sidebar.js`, heading in `state.js`'s `TAB_HEADINGS`.
+- **Persistent user data**: drop a JSON file under `~/.ccsm/` and use `lib/jsonStore.js`'s factory.
+- **Workspace lifecycle** (delete, rename): `lib/workspace.js`.
+- **Different launch modes**: `lib/launcher.js` — but check first whether the "one window per session" decision still holds.
+- **A capability**: advertise via `/api/capabilities`. Frontend gates UI on `caps.<feature>`.