@bakapiano/ccsm 0.1.0

package/CLAUDE.md

@@ -0,0 +1,134 @@
+# 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.
+
+## 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.
+
+## Run
+
+```powershell
+# from a checkout
+node server.js
+
+# zero-install
+npx github:bakapiano/cssm
+```
+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:
+
+- `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.
+
+## Layout
+
+```
+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
+│   ├── 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)
+│   └── 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)
+```
+
+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.
+
+## 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.
+
+```
+D:\ccsm-workspaces\
+├── ws-1\
+│   ├── repo-a\
+│   └── repo-b\
+├── ws-2\
+│   └── repo-a\
+```
+
+The alternative ("one repo per workspace") was explicitly rejected — don't refactor toward it without re-confirming.
+
+**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.
+
+**"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`.
+
+**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.
+
+## 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 / 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) |
+| 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>` |
+| POST | `/api/sessions/:id/focus` | walks up the claude PID parent chain to find the wt window, raises it via SetForegroundWindow |
+| 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.
+
+## Non-obvious gotchas
+
+**wt.exe `-d` flag, verified variants** (marker-file probes confirming `%CD%` inside the new tab):
+
+| variant | result |
+|---|---|
+| `wt -d D:\ccsm <cmd>` | ✓ |
+| `wt -d D:/ccsm <cmd>` | ✓ (forward slashes fine) |
+| `wt --startingDirectory D:\ccsm <cmd>` | ✓ |
+| `wt -d D:\ccsm\ <cmd>` (trailing sep) | ✓ |
+| spawn `{ cwd: ... }` with no `-d` | ✗ wt ignores parent cwd |
+| `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`.
+
+**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.
+
+**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--`.
+
+## 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="panel">` in `public/index.html` and a render function in `public/app.js`.
+- 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.

package/README.md

@@ -0,0 +1,58 @@
+# ccsm — Claude Code Session Manager
+
+A small web UI + Node server (Windows-only) that:
+
+- 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.
+
+## Quick start
+
+```powershell
+# one-liner — no clone needed
+npx github:bakapiano/cssm
+# open http://localhost:7777
+```
+
+Or from a checkout:
+
+```powershell
+git clone https://github.com/bakapiano/cssm.git
+cd cssm
+npm install
+node server.js
+```
+
+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.
+
+## Layout
+
+```
+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
+```
+
+## Defaults
+
+- 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).
+
+See [CLAUDE.md](CLAUDE.md) for design decisions and the non-obvious gotchas baked into the launcher / focus / snapshot code.

package/lib/config.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const fsSync = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// Data dir lives under ~/.ccsm by default so config survives across upgrades
+// (incl. running from a new npx checkout). Override with CCSM_HOME if you
+// want a different location.
+const DATA_DIR = process.env.CCSM_HOME || path.join(os.homedir(), '.ccsm');
+const CONFIG_PATH = path.join(DATA_DIR, 'config.json');
+
+const LEGACY_DATA_DIR = path.join(__dirname, '..', 'data');
+
+const DEFAULTS = {
+  port: 7777,
+  workDir: path.join(os.homedir(), 'ccsm-workspaces'),
+  snapshotIntervalMs: 60 * 1000,
+  snapshotHistoryKeep: 30,
+  claudeCommand: 'claude',
+  terminal: 'wt',
+  commandShell: 'pwsh',
+  autoFocusOnLaunch: true,
+  // 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:
+  //   { 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.`,
+};
+
+function ensureDataDir() {
+  if (!fsSync.existsSync(DATA_DIR)) {
+    fsSync.mkdirSync(DATA_DIR, { recursive: true });
+  }
+}
+
+// If we find a legacy <repo>/data dir from before the home-dir move AND
+// no ~/.ccsm yet, copy across. Idempotent — only fires when DATA_DIR is
+// empty so existing users with both dirs aren't clobbered.
+function migrateLegacyDataIfNeeded() {
+  if (!fsSync.existsSync(LEGACY_DATA_DIR)) return;
+  if (LEGACY_DATA_DIR === DATA_DIR) return;
+  ensureDataDir();
+  const dataEmpty = fsSync.readdirSync(DATA_DIR).length === 0;
+  if (!dataEmpty) return;
+  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);
+  }
+}
+
+migrateLegacyDataIfNeeded();
+
+function mergeWithDefaults(partial) {
+  const out = { ...DEFAULTS, ...partial };
+  if (!Array.isArray(out.repos)) {
+    out.repos = DEFAULTS.repos;
+  }
+  return out;
+}
+
+async function loadConfig() {
+  ensureDataDir();
+  try {
+    const raw = await fs.readFile(CONFIG_PATH, 'utf8');
+    return mergeWithDefaults(JSON.parse(raw));
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      const cfg = { ...DEFAULTS };
+      await fs.writeFile(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+      return cfg;
+    }
+    throw e;
+  }
+}
+
+async function saveConfig(partial) {
+  ensureDataDir();
+  const current = await loadConfig();
+  const next = mergeWithDefaults({ ...current, ...partial });
+  await fs.writeFile(CONFIG_PATH, JSON.stringify(next, null, 2));
+  return next;
+}
+
+module.exports = {
+  loadConfig,
+  saveConfig,
+  DATA_DIR,
+  CONFIG_PATH,
+  LEGACY_DATA_DIR,
+  DEFAULTS,
+};

package/lib/focus.js

@@ -0,0 +1,235 @@
+'use strict';
+
+// Focus helpers — find or raise a wt (or other terminal) window via Win32
+// APIs called through PowerShell + Add-Type.
+//
+// Two distinct use cases:
+//   1. focusByPid(pid)             — for the "focus" button in the UI: given
+//                                     a live claude.exe PID, walk parents to
+//                                     find the wt window hosting it.
+//   2. snapshotWindowsOf(name) +
+//      focusNewlyOpenedHwnd(...)  — for auto-focus after launch: snapshot the
+//                                     set of visible top-level windows owned by
+//                                     processes named e.g. "WindowsTerminal.exe"
+//                                     BEFORE launch, then poll for new HWNDs
+//                                     and focus the diff. HWND-based because
+//                                     modern wt is multi-window single-process —
+//                                     PID-based diff would always return empty.
+
+const { spawn } = require('node:child_process');
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// One PowerShell helper handles both: list-windows-of and focus-hwnd modes.
+// Mode is passed via env var so we don't fight quoting.
+const FOCUS_HELPER_PS = String.raw`
+$ErrorActionPreference = 'Stop'
+
+Add-Type @'
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Text;
+public class CcsmWin {
+    [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
+    [DllImport("user32.dll")] public static extern void SwitchToThisWindow(IntPtr h, bool t);
+    [DllImport("user32.dll")] public static extern bool ShowWindowAsync(IntPtr h, int n);
+    [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
+    [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
+    [DllImport("user32.dll")] public static extern bool AttachThreadInput(uint a, uint b, bool x);
+    [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+    [DllImport("kernel32.dll")] public static extern uint GetCurrentThreadId();
+    [DllImport("user32.dll")] public static extern void keybd_event(byte vk, byte scan, uint flags, UIntPtr extra);
+    [DllImport("user32.dll")] public static extern bool BringWindowToTop(IntPtr h);
+    [DllImport("user32.dll")] public static extern bool EnumWindows(EnumWindowsProc cb, IntPtr p);
+    [DllImport("user32.dll", CharSet=CharSet.Auto)] public static extern int GetWindowText(IntPtr h, StringBuilder s, int max);
+    [DllImport("user32.dll")] public static extern int GetWindowTextLength(IntPtr h);
+    public delegate bool EnumWindowsProc(IntPtr h, IntPtr p);
+
+    public static List<object> EnumVisibleTopLevel() {
+        var results = new List<object>();
+        EnumWindows((h, l) => {
+            if (!IsWindowVisible(h)) return true;
+            int len = GetWindowTextLength(h);
+            if (len == 0) return true;
+            uint pid = 0;
+            GetWindowThreadProcessId(h, out pid);
+            var sb = new StringBuilder(len + 1);
+            GetWindowText(h, sb, sb.Capacity);
+            results.Add(new { hwnd = h.ToInt64(), pid = pid, title = sb.ToString() });
+            return true;
+        }, IntPtr.Zero);
+        return results;
+    }
+
+    public static bool Activate(IntPtr h) {
+        if (IsIconic(h)) ShowWindowAsync(h, 9);
+        keybd_event(0x12, 0, 0, UIntPtr.Zero);
+        keybd_event(0x12, 0, 0x0002, UIntPtr.Zero);
+        uint ownerPid = 0;
+        uint t = GetWindowThreadProcessId(h, out ownerPid);
+        uint c = GetCurrentThreadId();
+        bool attached = false;
+        if (t != c) attached = AttachThreadInput(c, t, true);
+        BringWindowToTop(h);
+        bool ok = SetForegroundWindow(h);
+        SwitchToThisWindow(h, true);
+        if (attached) AttachThreadInput(c, t, false);
+        return ok;
+    }
+}
+'@ | Out-Null
+
+$mode = $env:CCSM_FOCUS_MODE
+$arg  = $env:CCSM_FOCUS_ARG
+
+if ($mode -eq 'list') {
+    $procName = $arg -replace '\.exe$',''
+    $pidSet = @{}
+    foreach ($p in (Get-Process -Name $procName -ErrorAction SilentlyContinue)) {
+        $pidSet[[uint32]$p.Id] = $true
+    }
+    $all = [CcsmWin]::EnumVisibleTopLevel()
+    $items = @()
+    foreach ($w in $all) {
+        if ($pidSet.ContainsKey([uint32]$w.pid)) {
+            $items += (ConvertTo-Json @{
+                hwnd = [int64]$w.hwnd
+                pid = [int64]$w.pid
+                title = [string]$w.title
+            } -Compress)
+        }
+    }
+    Write-Output ('[' + ($items -join ',') + ']')
+    exit 0
+}
+
+if ($mode -eq 'focus-hwnd') {
+    $hwndInt = [int64]$arg
+    $hwnd = [IntPtr]::new($hwndInt)
+    $ok = [CcsmWin]::Activate($hwnd)
+    Write-Output (ConvertTo-Json @{ ok = $true; activated = $ok; hwnd = $hwndInt } -Compress)
+    exit 0
+}
+
+if ($mode -eq 'focus-pid') {
+    $current = [int]$arg
+    $hwnd = [IntPtr]::Zero
+    $found = $null
+    $chain = @()
+    for ($i = 0; $i -lt 12; $i++) {
+        $p = $null
+        try { $p = Get-Process -Id $current -ErrorAction Stop } catch { break }
+        $chain += @{ pid = $p.Id; name = $p.ProcessName; hwnd = $p.MainWindowHandle.ToInt64() }
+        if ($p.MainWindowHandle -ne [IntPtr]::Zero) { $hwnd = $p.MainWindowHandle; $found = $p; break }
+        $parent = Get-CimInstance Win32_Process -Filter "ProcessId=$current" -ErrorAction SilentlyContinue | Select-Object -First 1
+        if (-not $parent -or -not $parent.ParentProcessId) { break }
+        $current = [int]$parent.ParentProcessId
+    }
+    if ($hwnd -eq [IntPtr]::Zero) {
+        Write-Output (ConvertTo-Json @{ ok = $false; error = "no window handle found for pid $arg"; chain = $chain } -Compress -Depth 5)
+        exit 1
+    }
+    $activated = [CcsmWin]::Activate($hwnd)
+    Write-Output (ConvertTo-Json @{
+        ok = $true; activated = $activated
+        hwnd = $hwnd.ToInt64()
+        windowPid = $found.Id
+        windowProcess = $found.ProcessName
+        windowTitle = $found.MainWindowTitle
+        chain = $chain
+    } -Compress -Depth 5)
+    exit 0
+}
+
+Write-Output (ConvertTo-Json @{ ok = $false; error = "unknown CCSM_FOCUS_MODE: $mode" } -Compress)
+exit 1
+`;
+
+function runPsHelper(mode, arg) {
+  return new Promise((resolve, reject) => {
+    const encoded = Buffer.from(FOCUS_HELPER_PS, 'utf16le').toString('base64');
+    const child = spawn(
+      'powershell.exe',
+      ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded],
+      {
+        windowsHide: true,
+        env: { ...process.env, CCSM_FOCUS_MODE: mode, CCSM_FOCUS_ARG: String(arg) },
+      }
+    );
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => (out += d.toString()));
+    child.stderr.on('data', (d) => (err += d.toString()));
+    child.on('error', reject);
+    child.on('close', (code) => {
+      const last = out.trim().split(/\r?\n/).pop();
+      try {
+        const parsed = JSON.parse(last);
+        if (Array.isArray(parsed)) {
+          resolve({ exitCode: code, value: parsed, stderr: err.trim() || undefined });
+        } else {
+          resolve({ exitCode: code, ...parsed, stderr: err.trim() || undefined });
+        }
+      } catch (e) {
+        reject(
+          new Error(
+            `focus helper (mode=${mode}) exit ${code}: ${err || out || '(no output)'}`
+          )
+        );
+      }
+    });
+  });
+}
+
+// ---- public API ----
+
+async function focusByPid(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) throw new Error(`focusByPid: invalid pid ${pid}`);
+  return await runPsHelper('focus-pid', n);
+}
+
+async function focusByHwnd(hwnd) {
+  return await runPsHelper('focus-hwnd', hwnd);
+}
+
+async function listWindowsOf(processName) {
+  const r = await runPsHelper('list', processName);
+  return Array.isArray(r.value) ? r.value : [];
+}
+
+async function snapshotWindowsOf(processName) {
+  const list = await listWindowsOf(processName);
+  return new Set(list.map((w) => Number(w.hwnd)));
+}
+
+async function focusNewlyOpenedHwnd(beforeHwnds, processName, opts = {}) {
+  const { timeoutMs = 8000, intervalMs = 300 } = opts;
+  const deadline = Date.now() + timeoutMs;
+  await sleep(intervalMs);
+  while (Date.now() < deadline) {
+    const after = await listWindowsOf(processName);
+    const fresh = after.filter((w) => !beforeHwnds.has(Number(w.hwnd)));
+    if (fresh.length > 0) {
+      const target = fresh[fresh.length - 1];
+      const r = await focusByHwnd(target.hwnd);
+      return { ...r, hwnd: target.hwnd, title: target.title, candidates: fresh };
+    }
+    await sleep(intervalMs);
+  }
+  return {
+    ok: false,
+    error: `no new ${processName} window appeared within ${timeoutMs}ms`,
+  };
+}
+
+module.exports = {
+  focusByPid,
+  focusByHwnd,
+  listWindowsOf,
+  snapshotWindowsOf,
+  focusNewlyOpenedHwnd,
+};