claude-code-kanban 5.2.0 → 5.3.0

package/lib/claude-dir.js

@@ -50,4 +50,10 @@ function displayPath(p) {
   return rel.split(path.sep).join('/');
 }
 
-module.exports = { getArgValue, getClaudeDir, claudeCliEnv, isDefaultClaudeDir, displayPath, storageNamespace };
+// The harness spells a project path into a temp/log dir name by replacing every
+// non-alphanumeric character with a dash, drive colon and separators included.
+function encodeProjectDirName(p) {
+  return p.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+module.exports = { getArgValue, getClaudeDir, claudeCliEnv, isDefaultClaudeDir, displayPath, storageNamespace, encodeProjectDirName };

package/lib/net-guard.js

@@ -37,11 +37,14 @@ const PORT_RE = /^[0-9]{1,5}$/;
 // port dynamic, so only the host is allowlisted.
 const validPort = (p) => PORT_RE.test(p) && Number(p) >= 1 && Number(p) <= 65535;
 const KEEP_ALIVE_MS = 65000;
+// A whole IPv4 literal: a prefix test would let a rebinding name like 127.evil.com through.
+const LOOPBACK_V4_RE = /^127(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}$/;
 
 function isLoopbackAddress(host) {
   if (!host) return false;
-  const h = String(host).toLowerCase();
-  return LOOPBACK_HOSTS.has(h) || h.startsWith('127.');
+  // An Origin or URL host carries an IPv6 literal in brackets.
+  const h = String(host).toLowerCase().replace(/^\[(.*)\]$/, '$1');
+  return LOOPBACK_HOSTS.has(h) || LOOPBACK_V4_RE.test(h);
 }
 
 // Hand-parsed rather than via new URL(), which is far more permissive than we
@@ -102,7 +105,7 @@ function getFlag(name) {
 }
 
 /**
- * @param {{appName?: string}} [config]
+ * @param {{appName?: string, selfFramedPaths?: string[]}} [config]
  */
 function createNetGuard(config = {}) {
   const appName = config.appName || 'This app';
@@ -216,9 +219,18 @@ function createNetGuard(config = {}) {
     CSP = "frame-ancestors 'none'";
   }
 
-  function frameGuard(_req, res, next) {
+  // Alone, these pages may be framed by this app's own port under its loopback names, for a page
+  // that frames itself from its other name to get its own renderer process.
+  const selfFramed = new Set(config.selfFramedPaths || []);
+
+  function frameGuard(req, res, next) {
     res.setHeader('X-Content-Type-Options', 'nosniff');
     res.setHeader('Referrer-Policy', 'no-referrer');
+    if (!hubOrigin && selfFramed.has(req.path)) {
+      const port = req.socket.localPort;
+      res.setHeader('Content-Security-Policy', `frame-ancestors 'self' http://localhost:${port} http://127.0.0.1:${port}`);
+      return next();
+    }
     res.setHeader('Content-Security-Policy', CSP);
     if (!hubOrigin) res.setHeader('X-Frame-Options', 'DENY');
     next();
@@ -232,7 +244,10 @@ function createNetGuard(config = {}) {
    * the OS resolver orders A/AAAA records - binding only 127.0.0.1 breaks hosts
    * where `localhost` resolves to ::1, and vice versa. Doing it on the *resolved*
    * port means every existing URL, startup banner and postMessage origin is
-   * unchanged. Failures are swallowed: it is an optimization, not a requirement.
+   * unchanged. A family the host does not have is skipped. A port that another
+   * process holds on the other family is treated as busy: the primary closes and
+   * emits EADDRINUSE (port 0 picks another random port instead), because that process would answer `localhost:<port>` (and a
+   * cross-site frame on it) in our name. onReady waits for the second bind.
    *
    * Returns the primary server, so callers keep attaching their own 'error'
    * handler for the EADDRINUSE fallback.
@@ -259,18 +274,30 @@ function createNetGuard(config = {}) {
     };
     const server = makeServer(app);
     let secondary = null;
+    let randomTries = 0;
 
     server.on('listening', () => {
-      actualPort = server.address().port;
-      if (!EXPOSED) {
-        const otherFamily = BIND_HOST.includes(':') ? '127.0.0.1' : '::1';
-        try {
-          secondary = makeServer(app);
-          secondary.on('error', () => {}); // that family may not exist on this host
-          secondary.listen({ host: otherFamily, port: actualPort, ipv6Only: otherFamily === '::1' });
-        } catch { /* best effort */ }
+      const boundPort = server.address().port;
+      actualPort = boundPort;
+      // Not actualPort: the hub listens several servers through one guard, and another one can bind
+      // while this one waits for its second family.
+      const ready = () => { if (onReady) onReady(boundPort); };
+      if (EXPOSED) return ready();
+      const otherFamily = BIND_HOST.includes(':') ? '127.0.0.1' : '::1';
+      try {
+        secondary = makeServer(app);
+        secondary.once('listening', ready);
+        secondary.on('error', (err) => {
+          if (err.code !== 'EADDRINUSE') return ready();
+          // A caller asking for port 0 has no fallback of its own, so it gets another random port here.
+          if (port === 0 && ++randomTries < 5) return server.close(() => server.listen(0, BIND_HOST));
+          server.close();
+          server.emit('error', err);
+        });
+        secondary.listen({ host: otherFamily, port: boundPort, ipv6Only: otherFamily === '::1' });
+      } catch {
+        ready();
       }
-      if (onReady) onReady(actualPort);
     });
     server.on('close', () => { try { if (secondary) secondary.close(); } catch { /* already gone */ } });
 

package/lib/proc-stats.js

@@ -0,0 +1,82 @@
+'use strict';
+
+// Memory and CPU of a few processes in one OS call. Only the processes named: a process-tree walk
+// costs more than the number is worth. CPU is the change in cumulative CPU time since the last
+// call, so the first call for a pid has none.
+const { execFile } = require('node:child_process');
+
+const QUERY_TIMEOUT_MS = 10000;
+// An older sample would turn the CPU number into an average over minutes.
+const MAX_BASELINE_MS = 30000;
+
+function parseCpuTime(text) {
+  const [days, clock] = text.includes('-') ? text.split('-') : ['0', text];
+  const seconds = clock.split(':').reduce((acc, part) => acc * 60 + Number.parseFloat(part), 0);
+  return (Number(days) * 86400 + seconds) * 1000;
+}
+
+// Lines of "pid workingSetBytes cpuMs".
+function parseWindows(stdout) {
+  const out = new Map();
+  for (const line of stdout.split(/\r?\n/)) {
+    const [pid, rss, cpuMs] = line.trim().split(/\s+/).map(Number);
+    if (pid && Number.isFinite(rss) && Number.isFinite(cpuMs)) out.set(pid, { rss, cpuMs });
+  }
+  return out;
+}
+
+// Lines of `ps -o pid=,rss=,time=`: rss in KiB, time as [dd-]hh:mm:ss on Linux or mm:ss.ss on macOS.
+function parsePs(stdout) {
+  const out = new Map();
+  for (const line of stdout.split(/\r?\n/)) {
+    const [pid, rss, time] = line.trim().split(/\s+/);
+    if (!time) continue;
+    const cpuMs = parseCpuTime(time);
+    if (Number(pid) && Number.isFinite(cpuMs)) out.set(Number(pid), { rss: Number(rss) * 1024, cpuMs });
+  }
+  return out;
+}
+
+function query(pids, platform = process.platform) {
+  return new Promise((resolve) => {
+    const ids = pids.join(',');
+    const [file, args, parse] = platform === 'win32'
+      ? ['powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+        `Get-Process -Id ${ids} -ErrorAction SilentlyContinue | ForEach-Object { "$($_.Id) $($_.WorkingSet64) $([long]$_.TotalProcessorTime.TotalMilliseconds)" }`], parseWindows]
+      : ['ps', ['-o', 'pid=,rss=,time=', '-p', ids], parsePs];
+    // ps exits 1 when a pid is gone, and still prints the others.
+    execFile(file, args, { windowsHide: true, timeout: QUERY_TIMEOUT_MS }, (_err, stdout) => resolve(parse(stdout || '')));
+  });
+}
+
+function createProcStats({ run = query, now = Date.now } = {}) {
+  let last = new Map();
+  let inFlight = null;
+
+  async function sample(pids) {
+    const at = now();
+    const found = await run(pids);
+    const next = new Map();
+    const result = {};
+    for (const pid of pids) {
+      const cur = found.get(pid);
+      if (!cur) continue;
+      const prev = last.get(pid);
+      const fresh = prev && at - prev.at <= MAX_BASELINE_MS && cur.cpuMs >= prev.cpuMs;
+      result[pid] = { rss: cur.rss, cpu: fresh ? Math.round(((cur.cpuMs - prev.cpuMs) / (at - prev.at)) * 100) : null };
+      next.set(pid, { at, cpuMs: cur.cpuMs });
+    }
+    last = next;
+    return result;
+  }
+
+  // Asks that overlap share one OS call.
+  return function stats(pids) {
+    const valid = [...new Set(pids)].filter((p) => Number.isInteger(p) && p > 0);
+    if (!valid.length) return Promise.resolve({});
+    inFlight ??= sample(valid).finally(() => { inFlight = null; });
+    return inFlight;
+  };
+}
+
+module.exports = { createProcStats, parseWindows, parsePs, parseCpuTime };

package/lib/retention.js

@@ -82,25 +82,28 @@ function createDispatchedStore({ load, save, now = Date.now }) {
 }
 
 // Names only, no stat or parse: the sweep needs which transcripts exist, not what they hold.
-// Null when none is found, so a missing or unreadable projects dir never reads as every
-// transcript gone.
-async function listTranscriptIds(projectsDir) {
+// `ids` are session ids and `dirs` the project dir names holding at least one transcript. Null
+// when none is found, so a missing or unreadable projects dir never reads as every transcript gone.
+async function scanTranscripts(projectsDir) {
   const ids = new Set();
-  let dirs;
+  const dirs = new Set();
+  let entries;
   try {
-    dirs = await fs.readdir(projectsDir, { withFileTypes: true });
+    entries = await fs.readdir(projectsDir, { withFileTypes: true });
   } catch {
     return null;
   }
-  for (const d of dirs) {
+  for (const d of entries) {
     if (!d.isDirectory()) continue;
     try {
       for (const f of await fs.readdir(path.join(projectsDir, d.name))) {
-        if (f.endsWith('.jsonl')) ids.add(f.slice(0, -'.jsonl'.length));
+        if (!f.endsWith('.jsonl')) continue;
+        ids.add(f.slice(0, -'.jsonl'.length));
+        dirs.add(d.name);
       }
     } catch {}
   }
-  return ids.size ? ids : null;
+  return ids.size ? { ids, dirs } : null;
 }
 
 // `<dir>/<session id>/<ts>.md`, one folder per session.
@@ -134,4 +137,4 @@ async function pruneSessionDirs(dir, { known, maxAgeMs, now = Date.now() }) {
   return removed;
 }
 
-module.exports = { createDispatchedStore, listTranscriptIds, pruneSessionDirs, retentionMs, GRACE_MS, MAX_DISPATCHED, DAY_MS };
+module.exports = { createDispatchedStore, scanTranscripts, pruneSessionDirs, retentionMs, GRACE_MS, MAX_DISPATCHED, DAY_MS };

package/lib/terminal.js

@@ -387,9 +387,13 @@ function createTerminalService(o) {
     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;
+    if (own || s.mode !== 'fork') {
+      s.claudePid = own?.pid;
+      return s.claudePid;
+    }
     const claimed = new Set([...sessions.values()].map((x) => x.claudePid).filter(Boolean));
-    return findPickProcess(live, s, claimed);
+    s.claudePid = findPickProcess(live, s, claimed);
+    return s.claudePid;
   }
 
   // claude writes its registry entry a moment after it starts, so the pid is polled for.
@@ -404,7 +408,6 @@ function createTerminalService(o) {
         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 };
       };
@@ -635,6 +638,16 @@ function createTerminalService(o) {
     }));
   }
 
+  function claudePids() {
+    const out = {};
+    for (const s of sessions.values()) {
+      if (s.ended || s.exited || s.mode === 'shell') continue;
+      const pid = inputPid(s);
+      if (pid) out[s.id] = pid;
+    }
+    return out;
+  }
+
   function isRunning(id) {
     const s = sessions.get(id);
     return !!s && !s.ended;
@@ -683,7 +696,7 @@ function createTerminalService(o) {
     sessions.clear();
   }
 
-  return { token, handleUpgrade, clientConfig, list, isRunning, end, authorized, startNew, paste, restore, shutdown, unavailableReason };
+  return { token, handleUpgrade, clientConfig, list, claudePids, isRunning, end, authorized, startNew, paste, restore, shutdown, unavailableReason };
 }
 
 module.exports = { createTerminalService, readTerminalConfig, ptyEnv, shellArgs, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };

package/lib/worktrees.js

@@ -0,0 +1,105 @@
+// Which project paths are linked worktrees, and of which repo. The rule and the sweep:
+// docs/retention.md.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { GRACE_MS } = require('./retention');
+const { encodeProjectDirName } = require('./claude-dir');
+
+// A linked worktree's `.git` is a file holding `gitdir: <main>/.git/worktrees/<name>`, so the
+// main checkout is readable without spawning git. Path shape alone would not do: only some
+// worktrees live under `<repo>/.claude/worktrees/`, the rest sit beside the repo.
+const GITDIR_WORKTREE_RE = /^gitdir:\s*(.*)[/\\]\.git[/\\]worktrees[/\\]([^/\\]+)[/\\]?$/;
+// Where `claude -w` puts a worktree. Used only once the `.git` file is gone, because Claude
+// Code removes worktrees while their transcripts stay.
+const CLAUDE_WORKTREE_RE = /^(.*)[/\\]\.claude[/\\]worktrees[/\\]([^/\\]+)[/\\]?$/;
+const MISS_CACHE_MAX = 500;
+
+function readGitFile(dir) {
+  return fs.readFileSync(path.join(dir, '.git'), 'utf8');
+}
+
+function fromGitFile(dir, text) {
+  const m = GITDIR_WORKTREE_RE.exec(text.trim());
+  // Git writes the pointer with forward slashes on Windows; the project path uses the OS spelling.
+  return m ? { repo: path.resolve(dir, m[1]), name: m[2] } : null;
+}
+
+function fromPathShape(dir) {
+  const m = CLAUDE_WORKTREE_RE.exec(dir);
+  return m ? { repo: m[1], name: m[2] } : null;
+}
+
+/**
+ * Hits are saved, so a worktree keeps its repo after Claude Code deletes the checkout. Misses
+ * stay in memory: an ordinary checkout cannot become a linked worktree without being recreated.
+ * @param {object} o
+ * @param {() => object|null} o.load returns `{version: 1, worktrees: {[dir]: {repo, name, at}}}` or null
+ * @param {(data: object) => void} o.save
+ * @param {(fn: () => void) => void} [o.defer] when to save; one session list can resolve many new worktrees
+ */
+function createWorktreeStore({ load, save, read = readGitFile, now = Date.now, defer = setImmediate }) {
+  const hits = new Map();
+  const misses = new Set();
+  const saved = load()?.worktrees;
+  if (saved && typeof saved === 'object') {
+    for (const [dir, e] of Object.entries(saved)) {
+      if (e && typeof e.repo === 'string' && typeof e.name === 'string' && Number.isFinite(e.at)) hits.set(dir, e);
+    }
+  }
+
+  let pending = false;
+  function persist() {
+    if (pending) return;
+    pending = true;
+    defer(() => {
+      pending = false;
+      save({ version: 1, worktrees: Object.fromEntries(hits) });
+    });
+  }
+
+  function resolve(dir) {
+    if (!dir) return null;
+    const hit = hits.get(dir);
+    if (hit) return { repo: hit.repo, name: hit.name };
+    if (misses.has(dir)) return null;
+
+    let worktree = null;
+    try {
+      worktree = fromGitFile(dir, read(dir));
+    } catch (e) {
+      // An ordinary checkout's `.git` is a directory, so the read throws EISDIR. That is the
+      // answer, and it costs one syscall instead of a stat followed by a read.
+      if (e.code === 'ENOENT') worktree = fromPathShape(dir);
+    }
+
+    if (!worktree) {
+      misses.add(dir);
+      if (misses.size > MISS_CACHE_MAX) misses.delete(misses.values().next().value);
+      return null;
+    }
+    hits.set(dir, { ...worktree, at: now() });
+    persist();
+    return worktree;
+  }
+
+  // `knownDirs` holds the project dir names that still have a transcript, or null when the scan
+  // found none, so a failed scan never drops every entry. Returns how many entries went.
+  function prune(knownDirs) {
+    if (!knownDirs) return 0;
+    const t = now();
+    let removed = 0;
+    for (const [dir, e] of hits) {
+      if (t - e.at >= GRACE_MS && !knownDirs.has(encodeProjectDirName(dir))) {
+        hits.delete(dir);
+        removed++;
+      }
+    }
+    if (removed) persist();
+    return removed;
+  }
+
+  return { resolve, prune };
+}
+
+module.exports = { createWorktreeStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
   "type": "commonjs",

package/plugin/plugins/claude-code-kanban/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.17.0",
+  "version": "2.17.2",
   "description": "claude-code-kanban dashboard integration: agent activity tracking, context statusline, skills to drive the board from a session and to follow it",
   "experimental": {
     "monitors": "./monitors.json"

package/plugin/plugins/claude-code-kanban/hooks/hooks.json

@@ -34,7 +34,7 @@
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
             "shell": "bash",
-            "timeout": 5
+            "timeout": 30
           }
         ]
       }

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

@@ -1,7 +1,7 @@
 ---
 name: dispatch
 description: Dispatch a task to another Claude Code session through the kanban board (cck), fire-and-forget or with a report back. Use when the user asks to dispatch, delegate, or start a session for a task, or to collect or check on a dispatched session's result.
-argument-hint: '<task> [--report] [--group <name>] [--model haiku|sonnet|opus|fable] [--worktree [name]]'
+argument-hint: '<task> [--no-report] [--group <name>] [--model haiku|sonnet|opus|fable] [--worktree [name]]'
 ---
 
 # Kanban dispatch

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

@@ -2,7 +2,6 @@
 name: kanban
 description: Drive the kanban board — open, pin, preview, link, inspect.
 argument-hint: '[open|pin|unpin|preview|link] [target]'
-disable-model-invocation: true
 ---
 
 # Kanban Skill