claude-code-kanban 5.4.0 → 6.1.0

package/lib/parsers.js

@@ -373,13 +373,20 @@ const modeOf = (data) => {
   return (data.type === 'user' || data.type === 'permission-mode') && data.permissionMode || null;
 };
 
+// The TTL of the last prompt-cache write, from the API's 5m/1h split of cache_creation.
+const cacheTtlOf = (data) => {
+  const cc = data.type === 'assistant' && !data.isSidechain && data.message?.usage?.cache_creation;
+  if (!cc) return null;
+  return cc.ephemeral_1h_input_tokens > 0 ? '1h' : cc.ephemeral_5m_input_tokens > 0 ? '5m' : null;
+};
+
 // gitBranch in the JSONL is pinned to the launch-time repo by Claude Code
 // and goes stale once cwd shifts (Bash `cd`, submodule). Callers needing the
 // live branch must resolve it from cwd separately. Cache is reset on inode
 // change or truncation (size < scannedUpTo).
 
 function readSessionInfoFromJsonl(jsonlPath) {
-  const result = { slug: null, projectPath: null, cwd: null, gitBranch: null, customTitle: null, logicalParentUuid: null, compactBoundaryUuid: null, permissionMode: null };
+  const result = { slug: null, projectPath: null, cwd: null, gitBranch: null, customTitle: null, logicalParentUuid: null, compactBoundaryUuid: null, permissionMode: null, cacheTtl: null };
   let stat;
   let fd;
   try {
@@ -400,6 +407,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
       logicalParentUuid: cached.logicalParentUuid || null,
       compactBoundaryUuid: cached.compactBoundaryUuid || null,
       permissionMode: cached.permissionMode || null,
+      cacheTtl: cached.cacheTtl || null,
       customTitle: readCustomTitle(jsonlPath, stat)
     };
   }
@@ -412,6 +420,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
     result.logicalParentUuid = cached.logicalParentUuid || null;
     result.compactBoundaryUuid = cached.compactBoundaryUuid || null;
     result.permissionMode = cached.permissionMode || null;
+    result.cacheTtl = cached.cacheTtl || null;
   }
 
   let lastCwdSeen = result.cwd;
@@ -426,6 +435,8 @@ function readSessionInfoFromJsonl(jsonlPath) {
       if (data.gitBranch) result.gitBranch = data.gitBranch;
       const mode = modeOf(data);
       if (mode) result.permissionMode = mode;
+      const ttl = cacheTtlOf(data);
+      if (ttl) result.cacheTtl = ttl;
       if (data.subtype === 'compact_boundary' && data.logicalParentUuid && !result.logicalParentUuid) {
         result.logicalParentUuid = data.logicalParentUuid;
         // The boundary record's own uuid: a fork copies it verbatim from the
@@ -498,19 +509,22 @@ function readSessionInfoFromJsonl(jsonlPath) {
         const lines = tailBuf.toString('utf8', 0, tn).split('\n');
         let latestTailCwd = null;
         let latestTailMode = null;
+        let latestTailTtl = null;
         for (let i = lines.length - 1; i >= 0; i--) {
           try {
             const data = JSON.parse(lines[i]);
+            if (!latestTailTtl) latestTailTtl = cacheTtlOf(data);
             if (!result.slug && data.slug) result.slug = data.slug;
             if (!result.projectPath && data.cwd) result.projectPath = data.cwd;
             if (!result.gitBranch && data.gitBranch) result.gitBranch = data.gitBranch;
             if (!latestTailCwd && data.cwd) latestTailCwd = data.cwd;
             if (!latestTailMode) latestTailMode = modeOf(data);
-            if (latestTailCwd && latestTailMode && result.slug && result.projectPath && result.gitBranch) break;
+            if (latestTailCwd && latestTailMode && latestTailTtl && result.slug && result.projectPath && result.gitBranch) break;
           } catch {}
         }
         if (latestTailCwd) lastCwdSeen = latestTailCwd;
         if (latestTailMode) result.permissionMode = latestTailMode;
+        if (latestTailTtl) result.cacheTtl = latestTailTtl;
       }
       scannedUpTo = stat.size;
     }
@@ -533,7 +547,8 @@ function readSessionInfoFromJsonl(jsonlPath) {
       cwd: result.cwd,
       logicalParentUuid: result.logicalParentUuid,
       compactBoundaryUuid: result.compactBoundaryUuid,
-      permissionMode: result.permissionMode
+      permissionMode: result.permissionMode,
+      cacheTtl: result.cacheTtl
     });
     if (sessionInfoCache.size > SESSION_INFO_CACHE_MAX) {
       const firstKey = sessionInfoCache.keys().next().value;

package/lib/retention.js

@@ -3,7 +3,6 @@
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const { readSettings } = require('./claude-settings');
-const { DISPATCH_OUTCOME } = require('./dispatch');
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_CLEANUP_DAYS = 30;
@@ -11,7 +10,6 @@ const DEFAULT_CLEANUP_DAYS = 30;
 // read that gap as a deleted transcript.
 const GRACE_MS = 60 * 60 * 1000;
 const MAX_DISPATCHED = 500;
-const OUTCOMES = new Set(Object.keys(DISPATCH_OUTCOME));
 
 // Only the config dir's settings: retention is per config dir, not per project.
 function retentionMs(claudeDir) {
@@ -28,10 +26,10 @@ function isExpired(id, at, { known, maxAgeMs, now }) {
 }
 
 /**
- * Sessions started through `dispatch start`, kept after the dispatch settles so the card
+ * Sessions started through `dispatch start`, kept after their terminal ends so the card
  * keeps its marker.
  * @param {object} o
- * @param {() => object|null} o.load returns `{version: 1, sessions: {[id]: {parent, status, at}}}` or null
+ * @param {() => object|null} o.load returns `{version: 1, sessions: {[id]: {parent, at}}}` or null
  * @param {(data: object) => void} o.save
  */
 function createDispatchedStore({ load, save, now = Date.now }) {
@@ -41,10 +39,7 @@ function createDispatchedStore({ load, save, now = Date.now }) {
   if (saved && typeof saved === 'object') {
     for (const [id, e] of Object.entries(saved)) {
       if (!e || !Number.isFinite(e.at)) continue;
-      // The dispatch registry is in memory: a dispatch that was running when the server
-      // stopped can never settle, so it reads as ended.
-      const status = OUTCOMES.has(e.status) ? e.status : 'exited';
-      entries.set(id, { parent: typeof e.parent === 'string' ? e.parent : null, status, at: e.at });
+      entries.set(id, { parent: typeof e.parent === 'string' ? e.parent : null, at: e.at });
     }
   }
 
@@ -52,18 +47,11 @@ function createDispatchedStore({ load, save, now = Date.now }) {
 
   function record(id, parent) {
     entries.delete(id);
-    entries.set(id, { parent: parent || null, status: 'running', at: now() });
+    entries.set(id, { parent: parent || null, at: now() });
     if (entries.size > MAX_DISPATCHED) entries.delete(entries.keys().next().value);
     persist();
   }
 
-  function settle(id, status) {
-    const e = entries.get(id);
-    if (!e || e.status !== 'running' || !OUTCOMES.has(status)) return;
-    e.status = status;
-    persist();
-  }
-
   // Returns how many entries went; writes only when one did.
   function prune({ known, maxAgeMs }) {
     const t = now();
@@ -78,7 +66,7 @@ function createDispatchedStore({ load, save, now = Date.now }) {
     return removed;
   }
 
-  return { record, settle, prune, get: (id) => entries.get(id) || null };
+  return { record, prune, get: (id) => entries.get(id) || null };
 }
 
 // Names only, no stat or parse: the sweep needs which transcripts exist, not what they hold.

package/lib/session-cache.js

@@ -4,7 +4,7 @@ const { exportParentVerdicts, importParentVerdicts, parentVerdictsDirty } = requ
 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 = 3;
+const VERSION = 4;
 // A cache this large is not one cck wrote for a normal set of transcripts. Rebuild it cold.
 const MAX_BYTES = 8 * 1024 * 1024;
 

package/lib/session-events.js

@@ -79,8 +79,9 @@ function clampWait(sec) {
   return Math.min(Math.max(Number(sec) || 0, 0), MAX_WAIT_SEC);
 }
 
-// Each topic rides its own bucket, so the dispatch postman never prints task moves
-// the user did not grant with the follow skill. No topic is the task-move bucket.
+// Each topic rides its own bucket, so a postman on a topic never prints task moves the
+// user did not grant with the follow skill. No topic is the task-move bucket. Plugins
+// before 2.22.0 run a `--topic dispatch` postman, which must keep getting nothing.
 function topicKey(topic, sessionId) {
   return topic ? `${topic}:${sessionId}` : sessionId;
 }

package/lib/terminal-client.js

@@ -0,0 +1,221 @@
+'use strict';
+
+// cck's side of the terminal host (lib/terminal-host.js). cck keeps the gates it can check
+// alone (enabled, exposure, Host and Origin, the token) and the ids the host last reported,
+// so the board's sync callers stay sync; everything else is a call over IPC.
+
+const crypto = require('node:crypto');
+const { fork } = require('node:child_process');
+const path = require('node:path');
+const { tokenMatches, localUnavailableReason, refuseUpgrade, clientConfigFor } = require('./terminal');
+
+const HOST = path.join(__dirname, 'terminal-host.js');
+const CALL_TIMEOUT_MS = 15000;
+const MAX_RESTARTS = 3;
+const RESTART_WINDOW_MS = 60000;
+const RESTART_DELAY_MS = 1000;
+
+function hostError(message) {
+  return Object.assign(new Error(message), { status: 503 });
+}
+
+/**
+ * @param {object} o
+ * @param {ReturnType<typeof import('./terminal').readTerminalConfig>} o.config
+ * @param {{EXPOSED: boolean, upgradeVerdict: (req: any) => string|null}} o.net
+ * @param {string} o.claudeDir
+ * @param {boolean} o.isDefaultDir
+ * @param {string} o.sessionsDir  claude's live-session registry
+ * @param {(id: string) => string|null|Promise<string|null>} o.resolveCwd
+ * @param {(dir: string) => boolean|Promise<boolean>} o.isAllowedFolder
+ * @param {string} [o.token]
+ * @param {() => {sessions?: string[]}|null} [o.load]
+ * @param {(data: {sessions: string[]}) => void} [o.save]
+ * @param {() => void} [o.onChange]
+ * @param {(id: string) => void} [o.onExit]
+ */
+function createTerminalClient(o) {
+  const { config, net } = o;
+  const token = o.token || crypto.randomBytes(32).toString('hex');
+  const localReason = localUnavailableReason(config, net);
+  let child = null;
+  let hostReason = null;
+  let ids = [];
+  let serverUrl = null;
+  let restoreAsked = false;
+  let stopped = false;
+  let shuttingDown = false;
+  const restarts = [];
+  let nextCall = 0;
+  const calls = new Map();
+  let settle;
+  const started = new Promise((resolve) => { settle = resolve; });
+
+  function unavailableReason() {
+    if (localReason) return localReason;
+    if (stopped) return 'the terminal host stopped';
+    if (!child) return 'the terminal host is restarting';
+    return hostReason;
+  }
+
+  function spawn() {
+    hostReason = null;
+    const c = fork(HOST, [], { execArgv: [], windowsHide: true });
+    child = c;
+    c.on('message', (msg) => { if (c === child) onMessage(c, msg); });
+    c.on('exit', (code, signal) => { if (c === child) onHostExit(code, signal); });
+    c.on('error', () => {});
+    c.send({
+      t: 'init', config, claudeDir: o.claudeDir, isDefaultDir: o.isDefaultDir, sessionsDir: o.sessionsDir, token, serverUrl,
+      saved: config.restore ? o.load?.() ?? null : null,
+    });
+    if (restoreAsked) call('restore').catch(() => {});
+  }
+
+  function onMessage(c, msg) {
+    if (msg.t === 'state') {
+      hostReason = msg.reason;
+      ids = msg.ids;
+      settle(hostReason);
+      o.onChange?.();
+    } else if (msg.t === 'exit') o.onExit?.(msg.id);
+    else if (msg.t === 'save') o.save?.(msg.data);
+    else if (msg.t === 'reply') {
+      const pending = calls.get(msg.id);
+      if (!pending) return;
+      calls.delete(msg.id);
+      clearTimeout(pending.timer);
+      if (msg.error) pending.reject(new Error(msg.error));
+      else pending.resolve(msg.value);
+    } else if (msg.t === 'ask') answer(c, msg);
+  }
+
+  const ASKS = {
+    resolveCwd: [o.resolveCwd, null],
+    isAllowedFolder: [o.isAllowedFolder, false],
+  };
+
+  async function answer(c, msg) {
+    const [fn, fallback] = ASKS[msg.op];
+    let value;
+    try {
+      value = await fn(msg.arg);
+    } catch {
+      value = fallback;
+    }
+    if (c.connected) c.send({ t: 'answer', id: msg.id, value });
+  }
+
+  // The PTYs die with the host, as they do with cck; a new host resumes terminals.json.
+  function onHostExit(code, signal) {
+    child = null;
+    for (const pending of calls.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(hostError('the terminal host stopped'));
+    }
+    calls.clear();
+    if (shuttingDown) return;
+    console.log(`Terminal host exited (${signal || code})`);
+    const lost = ids;
+    ids = [];
+    for (const id of lost) o.onExit?.(id);
+    o.onChange?.();
+    const now = Date.now();
+    while (restarts.length && now - restarts[0] > RESTART_WINDOW_MS) restarts.shift();
+    if (restarts.length >= MAX_RESTARTS) {
+      stopped = true;
+      console.log(`Terminal unavailable: the host stopped ${MAX_RESTARTS} times in ${RESTART_WINDOW_MS / 1000} s`);
+      settle(unavailableReason());
+      return;
+    }
+    restarts.push(now);
+    setTimeout(() => { if (!shuttingDown) spawn(); }, RESTART_DELAY_MS * restarts.length).unref();
+  }
+
+  function call(op, ...args) {
+    const c = child;
+    if (!c?.connected) return Promise.reject(hostError(unavailableReason() || 'the terminal host is not running'));
+    return new Promise((resolve, reject) => {
+      const id = ++nextCall;
+      const timer = setTimeout(() => {
+        calls.delete(id);
+        reject(hostError('the terminal host did not answer'));
+      }, CALL_TIMEOUT_MS);
+      calls.set(id, { resolve, reject, timer });
+      c.send({ t: 'call', id, op, args });
+    });
+  }
+
+  function handleUpgrade(req, socket, head) {
+    if (refuseUpgrade(req, socket, () => unavailableReason() || net.upgradeVerdict(req))) return;
+    // The client sends nothing before the 101, so no byte is lost between the two processes.
+    child.send({ t: 'upgrade', method: req.method, url: req.url, headers: req.headers, head: head.toString('base64') }, socket, (err) => {
+      if (err) socket.destroy();
+    });
+  }
+
+  function authorized(providedToken) {
+    return tokenMatches(token, providedToken);
+  }
+
+  function isRunning(id) {
+    return ids.includes(id);
+  }
+
+  async function startNew(msg, extraEnv) {
+    if (localReason) return { status: 403, error: localReason };
+    return call('startNew', msg, extraEnv);
+  }
+
+  async function end(id, providedToken) {
+    if (!authorized(providedToken)) return 'auth';
+    if (localReason) return 'not-found';
+    return call('end', id, providedToken);
+  }
+
+  async function paste(id, text) {
+    if (!isRunning(id)) return false;
+    return call('paste', id, text).catch(() => false);
+  }
+
+  function restore() {
+    restoreAsked = true;
+    if (child) call('restore').catch(() => {});
+  }
+
+  function setServerUrl(url) {
+    serverUrl = url;
+    if (child?.connected) child.send({ t: 'port', url });
+  }
+
+  // With no host there are no terminals, which the hub's eviction check must still read.
+  async function sessions() {
+    return child?.connected ? call('sessions') : [];
+  }
+
+  async function stats() {
+    const c = child;
+    return { hostPid: c?.pid ?? null, claudePids: c?.connected ? await call('claudePids') : {} };
+  }
+
+  function clientConfig() {
+    return clientConfigFor(config, !unavailableReason());
+  }
+
+  // Closing the channel is what ends the host, so it ends its PTYs itself.
+  function shutdown() {
+    shuttingDown = true;
+    try { child?.disconnect(); } catch { /* already closed */ }
+  }
+
+  if (localReason) settle(localReason);
+  else spawn();
+
+  return {
+    token, handleUpgrade, clientConfig, unavailableReason, authorized, isRunning, startNew, end, paste, restore,
+    setServerUrl, sessions, stats, shutdown, started,
+    ids: () => [...ids],
+  };
+}
+
+module.exports = { createTerminalClient };

package/lib/terminal-host.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// The terminal's own process, forked by lib/terminal-client.js. It runs the terminal
+// service unchanged; cck reaches it only over the IPC channel and ends it by closing that.
+
+const { createTerminalService } = require('./terminal');
+const { readLiveSessions, isSessionLive } = require('./live-sessions');
+const { whichSync } = require('./open-editor');
+
+let service = null;
+let serverUrl = null;
+let lastState = null;
+let nextAsk = 0;
+const asks = new Map();
+
+function send(msg) {
+  if (process.connected) process.send(msg);
+}
+
+function ask(op, arg) {
+  return new Promise((resolve) => {
+    const id = ++nextAsk;
+    asks.set(id, resolve);
+    send({ t: 'ask', id, op, arg });
+  });
+}
+
+// The service reports every attach and detach too; cck needs only a change of ids or reason.
+function pushState() {
+  const state = { t: 'state', reason: service.unavailableReason(), ids: service.list().map((s) => s.id) };
+  const key = JSON.stringify(state);
+  if (key === lastState) return;
+  lastState = key;
+  send(state);
+}
+
+function init(msg) {
+  serverUrl = msg.serverUrl;
+  const liveSessions = () => readLiveSessions(msg.sessionsDir);
+  service = createTerminalService({
+    config: msg.config,
+    // cck checked Host, Origin and exposure before it handed the socket over.
+    net: { EXPOSED: false, upgradeVerdict: () => null },
+    claudeDir: msg.claudeDir,
+    isDefaultDir: msg.isDefaultDir,
+    token: msg.token,
+    serverUrl: () => serverUrl,
+    which: whichSync,
+    liveSessions,
+    isLiveElsewhere: (id, exceptPid) => isSessionLive(liveSessions(), id, exceptPid),
+    resolveCwd: (id) => ask('resolveCwd', id),
+    isAllowedFolder: (dir) => ask('isAllowedFolder', dir),
+    load: () => msg.saved,
+    save: (data) => send({ t: 'save', data }),
+    onChange: pushState,
+    onExit: (id) => send({ t: 'exit', id }),
+  });
+  pushState();
+}
+
+const CALLS = {
+  startNew: (msg, extraEnv) => service.startNew(msg, extraEnv),
+  end: (id, token) => service.end(id, token),
+  paste: (id, text) => service.paste(id, text),
+  restore: () => service.restore(),
+  sessions: () => service.list(),
+  claudePids: () => service.claudePids(),
+};
+
+async function call(msg) {
+  try {
+    send({ t: 'reply', id: msg.id, value: await CALLS[msg.op](...msg.args) });
+  } catch (e) {
+    send({ t: 'reply', id: msg.id, error: e.message });
+  }
+}
+
+process.on('message', (msg, socket) => {
+  if (msg.t === 'init') init(msg);
+  else if (msg.t === 'port') serverUrl = msg.url;
+  else if (msg.t === 'upgrade') {
+    if (!socket) return;
+    service.handleUpgrade({ method: msg.method, url: msg.url, headers: msg.headers }, socket, Buffer.from(msg.head, 'base64'));
+  } else if (msg.t === 'call') call(msg);
+  else if (msg.t === 'answer') {
+    asks.get(msg.id)?.(msg.value);
+    asks.delete(msg.id);
+  }
+});
+
+// cck is gone, so no claude may outlive the board that started it.
+process.on('disconnect', () => {
+  service?.shutdown();
+  process.exit(0);
+});