claude-code-kanban 4.28.0 → 4.30.0

package/lib/priority.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// Windows boosts the threads of the foreground window, and a process behind a hidden ConPTY never
+// gets that, so the one the user types into competes on equal terms with every busy agent.
+// Elsewhere a raise needs root, and a raised nice value would pass on to every child, so this is
+// Windows only. There a child of an above-normal process starts at normal, so the tools it runs
+// stay unboosted.
+const { execFile } = require('node:child_process');
+const os = require('node:os');
+
+const { PRIORITY_ABOVE_NORMAL } = os.constants.priority;
+
+function enabled(platform, env) {
+  return platform === 'win32' && env.CCK_PRIORITY_BOOST !== '0';
+}
+
+function raise(pid = 0, platform = process.platform, env = process.env) {
+  if (!enabled(platform, env)) return null;
+  try {
+    const before = os.getPriority(pid);
+    if (before <= PRIORITY_ABOVE_NORMAL) return null;
+    os.setPriority(pid, PRIORITY_ABOVE_NORMAL);
+    return before;
+  } catch {
+    return null;
+  }
+}
+
+function restore(pid, before) {
+  try { os.setPriority(pid, before); } catch { /* the process is gone */ }
+}
+
+// ConPTY's console host relays every byte between cck and the shell, and node-pty does not expose
+// its pid. Under load a normal-priority host starves for seconds, until Windows' anti-starvation
+// boost picks it up.
+function raiseConsoleHosts(done) {
+  if (!enabled(process.platform, process.env)) return done?.();
+  const query = `(Get-CimInstance Win32_Process -Filter "ParentProcessId=${process.pid} AND (Name='conhost.exe' OR Name='OpenConsole.exe')").ProcessId`;
+  execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', query], { windowsHide: true, timeout: 30000 }, (err, stdout) => {
+    if (!err) for (const pid of stdout.split(/\s+/).filter(Boolean)) raise(Number(pid));
+    done?.();
+  });
+}
+
+module.exports = { raise, restore, raiseConsoleHosts };

package/lib/session-cache.js

@@ -0,0 +1,34 @@
+const fs = require('node:fs');
+const { exportSessionCaches, importSessionCaches, sessionCachesDirty } = require('./parsers');
+const { exportParentVerdicts, importParentVerdicts, parentVerdictsDirty } = require('./parent-cache');
+const { exportTaskCounts, importTaskCounts, taskCountsDirty } = require('./task-counts');
+
+// Bump when an entry's shape or meaning changes: a file with another version is ignored.
+const VERSION = 2;
+// A cache this large is not one cck wrote for a normal set of transcripts. Rebuild it cold.
+const MAX_BYTES = 8 * 1024 * 1024;
+
+function loadSessionCache(file) {
+  try {
+    if (fs.statSync(file).size > MAX_BYTES) {
+      fs.rmSync(file, { force: true });
+      return false;
+    }
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (data?.version !== VERSION) return false;
+    importSessionCaches(data);
+    importParentVerdicts(data.parents);
+    importTaskCounts(data.taskCounts);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// write(data) must replace the file atomically; server.js passes writeJsonAtomic.
+function saveSessionCache(write) {
+  if (!sessionCachesDirty() && !parentVerdictsDirty() && !taskCountsDirty()) return;
+  write({ version: VERSION, ...exportSessionCaches(), parents: exportParentVerdicts(), taskCounts: exportTaskCounts() });
+}
+
+module.exports = { loadSessionCache, saveSessionCache };

package/lib/session-events.js

@@ -25,6 +25,7 @@ const sessionEventBuckets = new Map();
 // One cap for the whole line rather than one per field, because the description comes
 // last: truncation eats its tail first and leaves the machine-readable head intact.
 function sanitizeEventLine(line) {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: strips control characters on purpose
   return line.replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 1500);
 }
 
@@ -81,7 +82,7 @@ function handleSessionEvents(req, res) {
   // bucket is still evicted from the map.
   if (bucket && req.query.first === '1') drain(sessionId, bucket);
 
-  if (bucket && bucket.queue.length) return res.json({ events: drain(sessionId, bucket) });
+  if (bucket?.queue.length) return res.json({ events: drain(sessionId, bucket) });
   if (!wait) return res.json({ events: [] });
 
   const pending = bucket || { queue: [], waiters: new Set() };

package/lib/task-counts.js

@@ -0,0 +1,90 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+// A task file's status is reused while its size, mtime and inode are unchanged. An mtime can be
+// as coarse as 2 s (FAT), so a file read within that window of its last write could be written
+// again with the same stamp and size. Such a file is not stored and is read again next time.
+const RACY_MS = 3000;
+const SKIP = 'skip';
+const STATUSES = new Set(['completed', 'in_progress', 'pending', SKIP]);
+
+const dirs = new Map();
+let dirty = false;
+
+function readStatus(taskPath) {
+  const text = fs.readFileSync(taskPath, 'utf8');
+  let task;
+  try {
+    task = JSON.parse(text);
+  } catch (_) {
+    return SKIP;
+  }
+  if (task == null || task.metadata?._internal) return SKIP;
+  if (task.status === 'completed' || task.status === 'in_progress') return task.status;
+  return 'pending';
+}
+
+function countTaskDir(dir) {
+  const prev = dirs.get(dir);
+  const next = new Map();
+  const now = Date.now();
+  const tally = { completed: 0, in_progress: 0, pending: 0 };
+  let newestTaskMtime = null;
+
+  for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+    const taskPath = path.join(dir, file);
+    let st;
+    try {
+      st = fs.statSync(taskPath);
+    } catch (_) {
+      continue;
+    }
+    const e = prev?.get(file);
+    let status;
+    if (e && e.size === st.size && e.mtimeMs === st.mtimeMs && e.ino === st.ino) {
+      status = e.status;
+      next.set(file, e);
+    } else {
+      try {
+        status = readStatus(taskPath);
+      } catch (_) {
+        continue;
+      }
+      if (now - st.mtimeMs >= RACY_MS) {
+        next.set(file, { size: st.size, mtimeMs: st.mtimeMs, ino: st.ino, status });
+        dirty = true;
+      }
+    }
+    if (status === SKIP) continue;
+    tally[status]++;
+    if (!newestTaskMtime || st.mtime > newestTaskMtime) newestTaskMtime = st.mtime;
+  }
+
+  if (prev && prev.size !== next.size) dirty = true;
+  dirs.set(dir, next);
+  return { completed: tally.completed, inProgress: tally.in_progress, pending: tally.pending, newestTaskMtime };
+}
+
+const taskCountsDirty = () => dirty;
+
+function exportTaskCounts() {
+  dirty = false;
+  return [...dirs].filter(([dir]) => fs.existsSync(dir)).map(([dir, files]) => [dir, [...files]]);
+}
+
+function importTaskCounts(entries) {
+  if (!Array.isArray(entries)) return;
+  const num = (x) => typeof x === 'number';
+  for (const pair of entries) {
+    if (typeof pair?.[0] !== 'string' || !Array.isArray(pair[1])) continue;
+    const files = new Map();
+    for (const item of pair[1]) {
+      const [file, e] = Array.isArray(item) ? item : [];
+      if (typeof file !== 'string' || !e || !num(e.size) || !num(e.mtimeMs) || !num(e.ino) || !STATUSES.has(e.status)) continue;
+      files.set(file, e);
+    }
+    dirs.set(pair[0], files);
+  }
+}
+
+module.exports = { countTaskDir, taskCountsDirty, exportTaskCounts, importTaskCounts };

package/lib/terminal.js

@@ -13,6 +13,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { isContained } = require('./contain');
+const priority = require('./priority');
 
 const WS_PATH = '/api/terminal/ws';
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -32,6 +33,7 @@ const PROMPT_QUIET_MS = 400;
 const HIGH_WATER = 128 * 1024;
 const LOW_WATER = 16 * 1024;
 const HELLO_TIMEOUT_MS = 5000;
+const BOOST_TRIES = 30;
 const MAX_PAYLOAD = 1024 * 1024;
 // The hub hands its children PORT=0 and friends; a dev server started in the terminal
 // would otherwise bind a random port, and a nested `claude` would think it runs inside one.
@@ -58,7 +60,7 @@ function readTerminalConfig({ argv = process.argv, env = process.env, getArgValu
   return {
     enabled: argv.includes('--enable-terminal') || cfg.enabled === true,
     shell:
-      (getArgValue && getArgValue('terminal-shell')) ||
+      getArgValue?.('terminal-shell') ||
       env.CCK_TERMINAL_SHELL ||
       (typeof cfg.shell === 'string' && cfg.shell) ||
       null,
@@ -149,6 +151,7 @@ function parseNewSpec(msg) {
   if (typeof worktree !== 'boolean' && !(typeof worktree === 'string' && WORKTREE_RE.test(worktree))) return 'worktree name';
   const model = msg.model || null;
   if (model && !MODELS.has(model)) return 'model';
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: strips ESC so a prompt cannot carry terminal sequences
   const prompt = typeof msg.prompt === 'string' ? msg.prompt.replace(/\x1b/g, '').trim() : '';
   if (prompt.length > MAX_PROMPT) return 'prompt';
   return { cwd: msg.cwd, name: name || null, worktree, model, prompt: prompt || null };
@@ -177,11 +180,15 @@ function screenText(term) {
 
 // Claude Code keeps .claude.json beside ~/.claude when CLAUDE_CONFIG_DIR is unset but
 // inside the dir when set, so the default dir must stay unset, not be spelled out.
-function ptyEnv({ claudeDir, isDefaultDir, noFlicker }) {
+// CCK_URL pins the CLI and the postman to this board: two boards on one config dir share
+// one server.json, and the last one started owns it.
+function ptyEnv({ claudeDir, isDefaultDir, noFlicker, cckUrl }) {
   const env = { ...process.env };
   for (const k of STRIP_ENV) delete env[k];
   if (isDefaultDir) delete env.CLAUDE_CONFIG_DIR;
   else env.CLAUDE_CONFIG_DIR = claudeDir;
+  if (cckUrl) env.CCK_URL = cckUrl;
+  else delete env.CCK_URL;
   // xterm.js #5801: a clear inside a synchronized-output block jumps the viewport.
   if (noFlicker) env.CLAUDE_CODE_NO_FLICKER = '1';
   env.TERM = 'xterm-256color';
@@ -224,6 +231,7 @@ function refuse(socket, status, reason) {
  */
 function createTerminalService(o) {
   const { config, net } = o;
+  if (config.enabled) priority.raise();
   const token = o.token || crypto.randomBytes(32).toString('hex');
   const sessions = new Map();
   let pty = null;
@@ -302,9 +310,46 @@ function createTerminalService(o) {
     };
   }
 
+  // The process a viewer types into: claude, found through its registry entry, or the shell.
+  function inputPid(s) {
+    if (s.mode === 'shell') return s.pty.pid;
+    if (s.claudePid || s.mode === 'pick') return s.claudePid;
+    const live = o.liveSessions();
+    const own = live.find((l) => l.pid && l.sessionId === s.id && l.startedAt >= s.startedAt - PICK_START_SLACK_MS);
+    if (own || s.mode !== 'fork') return own?.pid;
+    const claimed = new Set([...sessions.values()].map((x) => x.claudePid).filter(Boolean));
+    return findPickProcess(live, s, claimed);
+  }
+
+  // claude writes its registry entry a moment after it starts, so the pid is polled for.
+  function syncBoost(s) {
+    const want = s.sockets.size > 0 && !s.exited;
+    if (want && !s.boost) {
+      if (s.boostTimer) return;
+      let tries = 0;
+      const tryBoost = () => {
+        const pid = inputPid(s);
+        if (!pid && ++tries < BOOST_TRIES) return;
+        clearInterval(s.boostTimer);
+        s.boostTimer = null;
+        if (!pid) return;
+        if (s.mode !== 'shell') s.claudePid = pid;
+        const before = priority.raise(pid);
+        s.boost = { pid, before };
+      };
+      s.boostTimer = setInterval(tryBoost, PICK_POLL_MS);
+      tryBoost();
+    } else if (!want) {
+      clearInterval(s.boostTimer);
+      s.boostTimer = null;
+      if (s.boost && s.boost.before !== null && !s.exited) priority.restore(s.boost.pid, s.boost.before);
+      s.boost = null;
+    }
+  }
+
   function spawnSession(id, mode, cwdCandidate, cols, rows, spec, extraEnv) {
     const cwd = cwdCandidate && fs.existsSync(cwdCandidate) ? cwdCandidate : os.homedir();
-    const env = { ...ptyEnv({ claudeDir: o.claudeDir, isDefaultDir: o.isDefaultDir, noFlicker: config.noFlicker }), ...extraEnv };
+    const env = { ...ptyEnv({ claudeDir: o.claudeDir, isDefaultDir: o.isDefaultDir, noFlicker: config.noFlicker, cckUrl: o.serverUrl?.() }), ...extraEnv };
     // Git Bash's login profile cds to $HOME unless this is set.
     if (shellFamily(shell) === 'gitbash') env.CHERE_INVOKING = '1';
     const proc = pty.spawn(shell, shellArgs(shell, claudeArgsFor(mode, id, spec)), {
@@ -335,6 +380,7 @@ function createTerminalService(o) {
     proc.onExit(({ exitCode }) => {
       s.exited = true;
       clearInterval(s.pickTimer);
+      clearInterval(s.boostTimer);
       if (sessions.get(s.id) === s) sessions.delete(s.id);
       o.onExit?.(s.id);
       if (!s.ended) o.onChange?.();
@@ -345,6 +391,7 @@ function createTerminalService(o) {
       term.dispose();
     });
     sessions.set(id, s);
+    priority.raiseConsoleHosts();
     o.onChange?.();
     return s;
   }
@@ -389,6 +436,7 @@ function createTerminalService(o) {
   function attach(ws, s, attached) {
     ws.unacked = 0;
     s.sockets.add(ws);
+    syncBoost(s);
     send(ws, { t: 'ready', attached });
     const snapshot = s.serializer.serialize();
     if (snapshot) sendOutput(ws, Buffer.from(snapshot, 'utf8'));
@@ -411,6 +459,7 @@ function createTerminalService(o) {
     });
     ws.on('close', () => {
       s.sockets.delete(ws);
+      syncBoost(s);
       if (!s.exited) updateFlow(s);
     });
   }
@@ -552,4 +601,4 @@ function createTerminalService(o) {
   return { token, handleUpgrade, clientConfig, list, isRunning, end, authorized, startNew, shutdown, unavailableReason };
 }
 
-module.exports = { createTerminalService, readTerminalConfig, shellArgs, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };
+module.exports = { createTerminalService, readTerminalConfig, ptyEnv, shellArgs, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "claude-code-kanban",
-  "version": "4.28.0",
+  "version": "4.30.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
+  "type": "commonjs",
   "bin": {
     "claude-code-kanban": "server.js"
   },

package/plugin/plugins/claude-code-kanban/scripts/postman.js

@@ -38,7 +38,10 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Re-read every cycle rather than caching: it is how we follow the board across a
 // restart onto a different port. A file left behind by a crashed server names a port
 // something else may now hold, so trust it only while its pid is alive.
+// CCK_URL comes from the board whose terminal started this session. That board owns the
+// session's queue, and server.json may name another board on the same config dir.
 function serverUrl() {
+  if (process.env.CCK_URL) return process.env.CCK_URL.replace(/\/+$/, '');
   const { port, pid } = JSON.parse(fs.readFileSync(SERVER_INFO, 'utf8'));
   if (pid) process.kill(pid, 0);
   return `http://127.0.0.1:${port}`;

package/plugin/plugins/claude-code-kanban/skills/kanban/SKILL.md

@@ -9,58 +9,28 @@ disable-model-invocation: true
 
 This session id is `${CLAUDE_SESSION_ID}`, substituted when the skill loads.
 
-An argument names the section below that handles it; with no argument, open the current session. Prefer the bare `claude-code-kanban` binary, falling back to `npx claude-code-kanban` when it is off PATH or the user asks for npx.
+An argument names the command that handles it; with no argument, open the current session. Prefer the bare `claude-code-kanban` binary, falling back to `npx claude-code-kanban` when it is off PATH or the user asks for npx.
 
-To be driven *by* the board instead — card moves arriving as instructions — the user types `/claude-code-kanban:kanban-follow`.
-
-## `open` — the current session
-
-Pins the session and switches the board to the Active tab.
-
-```bash
-claude-code-kanban session open ${CLAUDE_SESSION_ID}
-```
-
-## `pin` — keep the session visible
-
-```bash
-claude-code-kanban session pin ${CLAUDE_SESSION_ID}            # pin
-claude-code-kanban session pin ${CLAUDE_SESSION_ID} --sticky   # always at the top
-claude-code-kanban session pin ${CLAUDE_SESSION_ID} --unpin    # clear
-claude-code-kanban session pins                                # list pinned; --sticky narrows
-```
-
-## `preview` — open a file in the modal
-
-Markdown or standalone HTML. HTML renders in a sandboxed iframe, so sibling assets like `./style.css` do not load. Relative paths are fine — the server resolves them.
-
-```bash
-claude-code-kanban preview-doc <file.md|.html> --session ${CLAUDE_SESSION_ID}
-```
-
-## `link` — attach a doc without the modal
-
-Adds the file to the session's linked docs in the sidebar. Any extension, and nothing pops up, so it is the safe choice while the user is working.
+The CLI help is the reference, and it always matches the installed binary. Read it before you run a command, instead of guessing flags:
 
 ```bash
-claude-code-kanban link-doc <path> --session ${CLAUDE_SESSION_ID}            # link
-claude-code-kanban link-doc <path> --session ${CLAUDE_SESSION_ID} --unlink   # remove
+claude-code-kanban help                        # every command
+claude-code-kanban help <command>              # its subcommands
+claude-code-kanban help <command> <subcommand> # flags and examples
 ```
 
-## `list` / `view` / `peek` — read-only
+| Argument | Command |
+|---|---|
+| `open` (or none) | `session open ${CLAUDE_SESSION_ID}` |
+| `pin` / `unpin` | `session pin ${CLAUDE_SESSION_ID}` (`--sticky`, `--unpin`) |
+| `preview` | `preview-doc <file> --session ${CLAUDE_SESSION_ID}` — opens a modal on the user's screen |
+| `link` | `link-doc <file> --session ${CLAUDE_SESSION_ID}` — no modal, so it is the safe choice while the user is working |
+| `list` / `search` | `session list`, `session search <text>` |
+| `view` / `peek` | `session view <id>`, `session peek <id>` |
+| tasks, projects | `task list`, `project list` |
 
-```bash
-claude-code-kanban session list --active                            # recent active sessions
-claude-code-kanban session list --project <name>                    # filter by project
-claude-code-kanban session list --days 0.5 --limit all              # touched in last 12h, uncapped
-claude-code-kanban session view ${CLAUDE_SESSION_ID}                # full stats for current session
-claude-code-kanban session peek ${CLAUDE_SESSION_ID} --limit 20     # last 20 messages (server caps at 50)
-```
-
-`session list` shows 10 rows and always includes pinned sessions, sticky first (`--no-pins` disables both). `--json` works on any list-style verb.
+To be driven *by* the board instead — card moves arriving as instructions — the user types `/claude-code-kanban:kanban-follow`.
 
 ## Troubleshooting
 
-`claude-code-kanban help <command>` prints the authoritative flags — read it instead of guessing.
-
-- **"Cannot reach cck server…"** → the error names the port it tried. Ask the user to start the server with `claude-code-kanban`. If they run it elsewhere, set `PORT=<n>` when invoking the CLI.
+- **"Cannot reach cck server…"** → the error names the config dir and the port it tried. Ask the user to start the server with `claude-code-kanban`. If they run it elsewhere, set `PORT=<n>` or `CCK_URL=<url>` when invoking the CLI.