claude-code-kanban 4.31.0 → 5.0.0

package/cli.js

@@ -427,14 +427,25 @@ function unreachable() {
 
 class CliUnreachable extends Error { constructor() { super(unreachable()); this.code = 'unreachable'; } }
 
+// Windows sometimes fails a loopback connect with ETIMEDOUT after ~300 ms when many
+// connects run at once. Nothing reached the server, so even a POST is safe to send again.
+const CONNECT_RETRY_MS = [250, 500, 1000, 2000];
+const isConnectTimeout = (e) => e.cause?.code === 'ETIMEDOUT' && e.cause?.syscall === 'connect';
+
 async function cliFetch(urlPath, init) {
   const base = cliBaseUrl();
   if (!base) throw new CliUnreachable();
-  try {
-    return await fetch(`${base}${urlPath}`, init);
-  } catch (e) {
-    if (e.cause?.code === 'ECONNREFUSED' || /fetch failed/i.test(e.message)) throw new CliUnreachable();
-    throw e;
+  for (let i = 0; ; i++) {
+    try {
+      return await fetch(`${base}${urlPath}`, init);
+    } catch (e) {
+      if (isConnectTimeout(e) && i < CONNECT_RETRY_MS.length) {
+        await new Promise((r) => setTimeout(r, CONNECT_RETRY_MS[i]));
+        continue;
+      }
+      if (e.cause?.code === 'ECONNREFUSED' || /fetch failed/i.test(e.message)) throw new CliUnreachable();
+      throw e;
+    }
   }
 }
 

package/hub-app.json

@@ -0,0 +1,25 @@
+{
+  "manifest": 1,
+  "id": "kanban",
+  "name": "Kanban",
+  "icon": "columns",
+  "run": { "entry": "server.js", "defaultPort": 3541 },
+  "publishes": ["session.changed"],
+  "provides": {
+    "projects": { "path": "/api/projects" },
+    "terminal": { "liveWork": "/api/terminals" }
+  },
+  "loading": {
+    "verbs": [
+      "Shuffling cards…",
+      "Herding tasks…",
+      "Waking sessions…",
+      "Sorting the board…",
+      "Pinning sticky notes…",
+      "Moving cards to done…",
+      "Nudging agents…",
+      "Drawing columns…",
+      "Reading the backlog…"
+    ]
+  }
+}

package/lib/net-guard.js

@@ -36,6 +36,7 @@ const PORT_RE = /^[0-9]{1,5}$/;
 // The port is validated but not compared — the listen(0) fallbacks make the real
 // 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;
 
 function isLoopbackAddress(host) {
   if (!host) return false;
@@ -249,6 +250,10 @@ function createNetGuard(config = {}) {
     const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
     const makeServer = (handler) => {
       const s = http.createServer(serverOpts, handler);
+      // Node's 5 s default closes idle sockets that the hub proxy and the browser would reuse, and a
+      // fresh loopback connect is the one that some Windows network filters drop. The hub's agent
+      // drops its idle sockets before this, so it never reuses one the server is closing.
+      s.keepAliveTimeout = KEEP_ALIVE_MS;
       if (opts.onUpgrade) s.on('upgrade', opts.onUpgrade);
       return s;
     };
@@ -281,4 +286,4 @@ function createNetGuard(config = {}) {
   return { BIND_HOST, ALLOWED_HOSTS, EXPOSED, hostGuard, originGuard, upgradeVerdict, frameGuard, listenLoopback, exposureWarning };
 }
 
-module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress };
+module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress, KEEP_ALIVE_MS };

package/lib/parsers.js

@@ -1622,11 +1622,22 @@ function formatStructuredResult(input) {
   return parts.length ? parts.join('\n\n') : null;
 }
 
-// Workflow-spawned subagents given a schema end their run on a forced
-// StructuredOutput tool call and never emit a text response — so their
-// lastMessage is empty. Tail-read the transcript, take the LAST StructuredOutput
-// tool_use, and format its input as the agent's result. Returns null when absent.
-function extractStructuredResultFromTranscript(jsonlPath) {
+// Some subagents end their run on a tool call and never emit a text response, so
+// their lastMessage is empty: workflow subagents given a schema call StructuredOutput,
+// background subagents report through SubagentHandback. Tail-read the transcript and
+// take the LAST such tool_use as the agent's result. Returns null when absent.
+const RESULT_TOOLS = {
+  StructuredOutput: formatStructuredResult,
+  SubagentHandback: (input) => (typeof input.message === 'string' && input.message) || null,
+};
+const RESULT_TOOL_TEXT = Object.keys(RESULT_TOOLS).map((name) => `"${name}"`);
+
+function resultFromBlock(b) {
+  if (b?.type !== 'tool_use' || !b.input || typeof b.input !== 'object') return null;
+  return RESULT_TOOLS[b.name]?.(b.input) ?? null;
+}
+
+function extractAgentResultFromTranscript(jsonlPath) {
   const { openSync, readSync, closeSync } = fs;
   const stat = statSync(jsonlPath);
   const readSize = Math.min(1048576, stat.size);
@@ -1638,17 +1649,15 @@ function extractStructuredResultFromTranscript(jsonlPath) {
     const text = buf.toString('utf8');
     // Drop the leading partial line unless we read from the very start.
     const clean = start > 0 ? text.slice(text.indexOf('\n') + 1) : text;
-    if (!clean.includes('"StructuredOutput"')) return null;
-    // Scan from the end for the last StructuredOutput tool call.
+    if (!RESULT_TOOL_TEXT.some((t) => clean.includes(t))) return null;
     const lines = clean.split('\n');
     for (let i = lines.length - 1; i >= 0; i--) {
-      if (!lines[i].includes('"StructuredOutput"')) continue;
+      if (!RESULT_TOOL_TEXT.some((t) => lines[i].includes(t))) continue;
       let obj;
       try { obj = JSON.parse(lines[i]); } catch (_) { continue; }
       const content = obj?.message?.content;
-      if (!Array.isArray(content)) continue;
-      const block = content.find(b => b?.type === 'tool_use' && b.name === 'StructuredOutput' && b.input && typeof b.input === 'object');
-      if (block) return formatStructuredResult(block.input);
+      const result = Array.isArray(content) && content.map(resultFromBlock).findLast(Boolean);
+      if (result) return result;
     }
   } catch (_) {
   } finally {
@@ -1821,6 +1830,6 @@ module.exports = {
   findTerminatedTeammates,
   extractPromptFromTranscript,
   extractModelFromTranscript,
-  extractStructuredResultFromTranscript,
+  extractAgentResultFromTranscript,
   extractTranscriptStats
 };

package/lib/terminal.js

@@ -35,6 +35,16 @@ const LOW_WATER = 16 * 1024;
 const HELLO_TIMEOUT_MS = 5000;
 const BOOST_TRIES = 30;
 const MAX_PAYLOAD = 1024 * 1024;
+// Each restored terminal is a full claude process, so they start one at a time.
+const RESTORE_GAP_MS = 2000;
+// The hub stops cck with `taskkill /f /t`, which can deliver the PTY exits to cck a moment
+// before cck itself dies. The delay keeps that teardown out of the saved list.
+const SAVE_DELAY_MS = 1000;
+// A fork runs under its parent's id until claude names the new one, so it has no id to resume.
+const RESTORABLE_MODES = new Set(['resume', 'new']);
+// The size of a PTY no browser has attached to yet; the first attach resizes it.
+const HEADLESS_COLS = 120;
+const HEADLESS_ROWS = 32;
 // 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.
 const STRIP_ENV = [
@@ -64,11 +74,12 @@ function readTerminalConfig({ argv = process.argv, env = process.env, getArgValu
       env.CCK_TERMINAL_SHELL ||
       (typeof cfg.shell === 'string' && cfg.shell) ||
       null,
-    maxSessions: posInt(cfg.maxSessions, 20),
+    maxSessions: posInt(cfg.maxSessions, 30),
     fontFamily: typeof cfg.fontFamily === 'string' && cfg.fontFamily ? cfg.fontFamily : null,
     fontSize: posInt(cfg.fontSize, 13),
     scrollback: posInt(cfg.scrollback, 5000),
     noFlicker: cfg.noFlicker !== false,
+    restore: cfg.restore !== false,
   };
 }
 
@@ -228,6 +239,9 @@ function refuse(socket, status, reason) {
  * @param {(cmd: string) => string|null} o.which
  * @param {string} [o.token]
  * @param {() => void} [o.onChange]  a terminal started, ended or moved to another session id
+ * @param {() => {sessions?: string[]}|null} [o.load]  the saved list, read when config.restore is on
+ * @param {(data: {sessions: string[]}) => void} [o.save]  the session ids to resume on the next start
+ * @param {object} [o.pty]  stands in for @lydell/node-pty in tests
  */
 function createTerminalService(o) {
   const { config, net } = o;
@@ -240,6 +254,14 @@ function createTerminalService(o) {
   let Headless = null;
   let Serialize = null;
   let shell = null;
+  let shuttingDown = false;
+  let saveTimer = null;
+  let lastSaved = null;
+  const saveDelayMs = o.saveDelayMs ?? SAVE_DELAY_MS;
+  const restoreGapMs = o.restoreGapMs ?? RESTORE_GAP_MS;
+  // Read before any terminal starts, so the first save keeps the ids still waiting to restore.
+  const saved = config.restore ? o.load?.()?.sessions : null;
+  const restoreQueue = Array.isArray(saved) ? saved.filter((id) => typeof id === 'string' && UUID_RE.test(id)) : [];
 
   // Lazy and optional: a missing prebuilt or shell must hide the feature, not crash cck.
   function load() {
@@ -251,7 +273,7 @@ function createTerminalService(o) {
       return false;
     }
     try {
-      pty = require('@lydell/node-pty');
+      pty = o.pty || require('@lydell/node-pty');
       ({ Terminal: Headless } = require('@xterm/headless'));
       ({ SerializeAddon: Serialize } = require('@xterm/addon-serialize'));
       const { WebSocketServer } = require('ws');
@@ -270,6 +292,47 @@ function createTerminalService(o) {
     return null;
   }
 
+  function changed() {
+    scheduleSave();
+    o.onChange?.();
+  }
+
+  function scheduleSave() {
+    if (!o.save || shuttingDown || saveTimer) return;
+    saveTimer = setTimeout(saveState, saveDelayMs);
+    saveTimer.unref();
+  }
+
+  function saveState() {
+    saveTimer = null;
+    const ids = new Set(restoreQueue);
+    for (const s of sessions.values()) if (!s.ended && RESTORABLE_MODES.has(s.mode)) ids.add(s.id);
+    const data = { sessions: [...ids] };
+    const json = JSON.stringify(data);
+    if (json === lastSaved) return;
+    lastSaved = json;
+    o.save(data);
+  }
+
+  // Starts `claude --resume` for each terminal open when cck last stopped, headless like
+  // startNew. A session that runs elsewhere or lost its transcript is dropped.
+  function restore() {
+    if (!restoreQueue.length || unavailableReason()) return;
+    console.log(`Restoring ${restoreQueue.length} terminal(s)`);
+    const next = () => {
+      while (restoreQueue.length && !shuttingDown) {
+        const id = restoreQueue.shift();
+        if (sessions.has(id) || o.isLiveElsewhere(id)) continue;
+        const r = start(id, 'resume', {}, HEADLESS_COLS, HEADLESS_ROWS);
+        if (!r.error) break;
+        console.log(`Could not restore terminal ${id}: ${r.error}`);
+      }
+      scheduleSave();
+      if (restoreQueue.length && !shuttingDown) setTimeout(next, restoreGapMs).unref();
+    };
+    next();
+  }
+
   function send(ws, msg) {
     if (ws.readyState === 1) ws.send(JSON.stringify(msg));
   }
@@ -383,7 +446,7 @@ function createTerminalService(o) {
       clearInterval(s.boostTimer);
       if (sessions.get(s.id) === s) sessions.delete(s.id);
       o.onExit?.(s.id);
-      if (!s.ended) o.onChange?.();
+      if (!s.ended) changed();
       for (const ws of s.sockets) {
         send(ws, { t: 'exit', code: exitCode, ended: s.ended });
         ws.close(1000);
@@ -392,7 +455,7 @@ function createTerminalService(o) {
     });
     sessions.set(id, s);
     priority.raiseConsoleHosts();
-    o.onChange?.();
+    changed();
     return s;
   }
 
@@ -428,7 +491,7 @@ function createTerminalService(o) {
       s.id = picked;
       s.mode = 'resume';
       sessions.set(picked, s);
-      o.onChange?.();
+      changed();
       for (const ws of s.sockets) send(ws, { t: 'rekey', id: picked, elsewhere });
     }, PICK_POLL_MS);
   }
@@ -554,7 +617,7 @@ function createTerminalService(o) {
   function kill(s) {
     s.ended = true;
     s.pty.kill();
-    o.onChange?.();
+    changed();
   }
 
   function list() {
@@ -587,18 +650,20 @@ function createTerminalService(o) {
   function startNew(msg, extraEnv) {
     const reason = unavailableReason();
     if (reason) return { status: 403, error: reason };
-    const r = start(crypto.randomUUID(), 'new', msg, 120, 32, extraEnv);
+    const r = start(crypto.randomUUID(), 'new', msg, HEADLESS_COLS, HEADLESS_ROWS, extraEnv);
     return r.error ? r : { id: r.session.id, cwd: r.session.cwd };
   }
 
   function shutdown() {
+    shuttingDown = true;
+    clearTimeout(saveTimer);
     for (const s of sessions.values()) {
       try { s.pty.kill(); } catch { /* already gone */ }
     }
     sessions.clear();
   }
 
-  return { token, handleUpgrade, clientConfig, list, isRunning, end, authorized, startNew, shutdown, unavailableReason };
+  return { token, handleUpgrade, clientConfig, list, isRunning, end, authorized, startNew, restore, shutdown, unavailableReason };
 }
 
 module.exports = { createTerminalService, readTerminalConfig, ptyEnv, shellArgs, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "4.31.0",
+  "version": "5.0.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
   "type": "commonjs",
@@ -52,6 +52,7 @@
   },
   "files": [
     "server.js",
+    "hub-app.json",
     "cli.js",
     "install.js",
     "plugin/**/*",

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

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.15.0",
+  "version": "2.16.1",
   "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

@@ -36,6 +36,18 @@
         ]
       }
     ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "TeammateIdle": [
       {
         "matcher": "",

package/plugin/plugins/claude-code-kanban/scripts/agent-spy.sh

@@ -37,10 +37,17 @@ if [ "$EVENT" = "SessionStart" ]; then
   exit 0
 fi
 
-# PostToolUse / non-waiting PreToolUse: clear waiting state
+# Stop: the session finished its turn. The marker means unread; the board deletes it on open.
+if [ "$EVENT" = "Stop" ]; then
+  DIR="$CCK_ACTIVITY/$SESSION_ID"
+  [ -d "$DIR" ] || mkdir -p "$DIR"
+  : > "$DIR/_stop.json"
+  exit 0
+fi
+
+# PostToolUse / non-waiting PreToolUse: clear waiting state, and unread since the session is working again
 if [ "$EVENT" = "PostToolUse" ] || { [ "$EVENT" = "PreToolUse" ] && [ "$TOOL_NAME" != "AskUserQuestion" ] && [ "$TOOL_NAME" != "ExitPlanMode" ]; }; then
-  WFILE="$CCK_ACTIVITY/$SESSION_ID/_waiting.json"
-  rm -f "$WFILE"
+  rm -f "$CCK_ACTIVITY/$SESSION_ID/_waiting.json" "$CCK_ACTIVITY/$SESSION_ID/_stop.json"
   [ "$EVENT" = "PostToolUse" ] && exit 0
 fi
 

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

@@ -26,6 +26,9 @@ const SERVER_INFO = path.join(CLAUDE_DIR, '.cck', 'server.json');
 // because an enqueue wakes the poll immediately.
 const WAIT_SEC = 120;
 const RETRY_MS = 15000;
+// Windows sometimes fails a loopback connect with ETIMEDOUT while the board is up, so that
+// error gets a few short waits before the normal one.
+const CONNECT_RETRY_MS = [250, 500, 1000, 2000];
 // `--topic dispatch` is the kanban-dispatch inbox: reports from sessions this one started.
 const TOPIC = process.argv.includes('--topic') ? process.argv[process.argv.indexOf('--topic') + 1] : null;
 // A dispatch report is a result, not an instruction, so a late attach still wants it.
@@ -64,13 +67,21 @@ async function poll(base) {
 }
 
 (async () => {
+  let connectRetries = 0;
   for (;;) {
     try {
       for (const line of await poll(serverUrl())) console.log(line);
-    } catch (_) {
+      connectRetries = 0;
+    } catch (e) {
       // No board yet, or it went away. It may come back later in the session, so keep
       // waiting quietly -- a missing server is the normal case, not an error.
-      await sleep(RETRY_MS);
+      const timedOut = e.cause?.code === 'ETIMEDOUT' && e.cause?.syscall === 'connect';
+      if (timedOut && connectRetries < CONNECT_RETRY_MS.length) {
+        await sleep(CONNECT_RETRY_MS[connectRetries++]);
+      } else {
+        connectRetries = 0;
+        await sleep(RETRY_MS);
+      }
     }
   }
 })();