claude-code-kanban 4.29.0 → 4.30.0

package/server.js

@@ -41,7 +41,12 @@ const { getClaudeDir, getArgValue, storageNamespace, isDefaultClaudeDir } = requ
 const { createTerminalService, readTerminalConfig } = require('./lib/terminal');
 const { createDispatchRegistry, formatPreamble, formatDispatchLine, isPeerName } = require('./lib/dispatch');
 const { createGroupStore, isGroupName, suggestGroupName } = require('./lib/dispatch-groups');
+const { createLinkedDocStore } = require('./lib/linked-docs');
 const { pickFolder } = require('./lib/folder-dialog');
+const { loadSessionCache, saveSessionCache } = require('./lib/session-cache');
+const { countTaskDir } = require('./lib/task-counts');
+const { projectMatcher } = require('./public/project-match');
+const { getParentVerdict, setParentVerdict } = require('./lib/parent-cache');
 
 if (process.argv.includes("--install") || process.argv.includes("--uninstall")) {
   const { runInstall, runUninstall } = require("./install");
@@ -49,10 +54,12 @@ if (process.argv.includes("--install") || process.argv.includes("--uninstall"))
   (process.argv.includes("--install") ? runInstall({ pluginOnly }) : runUninstall())
     .then(() => process.exit(0))
     .catch(e => { console.error(e.message); process.exit(1); });
-  return;
+} else if (!require("./cli").runCli(process.argv)) {
+  startServer();
 }
-if (require("./cli").runCli(process.argv)) return;
 
+// Not indented: the formatter is off for this file, and a reindent would rewrite every line.
+function startServer() {
 
 const app = express();
 const PORT = process.env.PORT || 3541;
@@ -82,8 +89,10 @@ const AGENT_ACTIVITY_DIR = path.join(CCK_DIR, 'agent-activity');
 const CONTEXT_STATUS_DIR = path.join(CCK_DIR, 'context-status');
 const PINS_FILE = path.join(CCK_DIR, 'pins.json');
 const DISPATCH_GROUPS_FILE = path.join(CCK_DIR, 'dispatch-groups.json');
+const LINKED_DOCS_FILE = path.join(CCK_DIR, 'linked-docs.json');
 const SERVER_INFO_FILE = path.join(CCK_DIR, 'server.json');
-const TERMINAL_TOKEN_FILE = path.join(CCK_DIR, 'terminal-token.json');
+const TERMINAL_TOKENS_DIR = path.join(CCK_DIR, 'terminal-tokens');
+const SESSION_CACHE_FILE = path.join(CCK_DIR, 'session-cache.json');
 // Harness-owned scratchpad root; the per-session dir under it is created lazily.
 const SCRATCHPAD_ROOT = path.join(os.tmpdir(), 'claude');
 
@@ -101,7 +110,7 @@ function readPins() {
 
 function writeJsonAtomic(file, obj, mode) {
   try {
-    mkdirSync(CCK_DIR, { recursive: true });
+    mkdirSync(path.dirname(file), { recursive: true });
     const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
     writeFileSync(tmp, JSON.stringify(obj, null, 2), { encoding: 'utf8', mode });
     renameSync(tmp, file);
@@ -119,37 +128,46 @@ function writePins(pins) {
 // a crashed one.
 function writeServerInfo(port) {
   writeJsonAtomic(SERVER_INFO_FILE, { port, pid: process.pid });
-  writeTerminalToken();
 }
 
 // For `dispatch start`: a local process as the same user can already run claude itself,
 // so handing it the token adds little. A browser still cannot read the file.
-function writeTerminalToken() {
+// One file per port: two boards on one config dir each keep a token, so the CLI can
+// reach the board CCK_URL names even when the other one owns server.json.
+// The sweep also drops terminal-token.json, the single file that older versions wrote.
+let terminalTokenFile = null;
+function writeTerminalToken(port) {
   if (terminal.unavailableReason()) return;
-  writeJsonAtomic(TERMINAL_TOKEN_FILE, { pid: process.pid, token: terminal.token }, 0o600);
+  let stale = [path.join(CCK_DIR, 'terminal-token.json')];
+  try { stale = stale.concat(readdirSync(TERMINAL_TOKENS_DIR).map(name => path.join(TERMINAL_TOKENS_DIR, name))); } catch (_) { /* no dir yet */ }
+  for (const file of stale) {
+    const pid = ownerPid(file);
+    if (pid !== null && !isPidAlive(pid)) try { unlinkSync(file); } catch (_) { /* already gone */ }
+  }
+  terminalTokenFile = path.join(TERMINAL_TOKENS_DIR, `${port}.json`);
+  writeJsonAtomic(terminalTokenFile, { pid: process.pid, token: terminal.token }, 0o600);
+}
+
+function ownerPid(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')).pid ?? null; } catch (_) { return null; }
 }
 
 // A beacon that outlives its server disarms UI approvals silently: approval-gate.sh
 // probes the port, finds it closed and never waits. The hub spawns every sub-app on
 // an ephemeral port, so a stale beacon never comes back on its own — drop ours on
 // the way out. Only when the file is still ours: a newer server on the same config
-// dir has already claimed it.
+// dir has already claimed it. The terminal token file goes the same way.
 function removeServerInfo() {
-  for (const file of [SERVER_INFO_FILE, TERMINAL_TOKEN_FILE]) {
-    try {
-      const info = JSON.parse(readFileSync(file, 'utf8'));
-      if (info.pid === process.pid) unlinkSync(file);
-    } catch (_) { /* gone, unreadable, or not ours */ }
+  for (const file of [SERVER_INFO_FILE, terminalTokenFile]) {
+    if (file && ownerPid(file) === process.pid) try { unlinkSync(file); } catch (_) { /* already gone */ }
   }
 }
 
 // A second server on the same config dir (a test hub, say) takes the beacon and removes it on
 // exit, which leaves this live server undiscoverable. A newer live owner keeps it.
 function reclaimServerInfo(port) {
-  try {
-    const { pid } = JSON.parse(readFileSync(SERVER_INFO_FILE, 'utf8'));
-    if (pid === process.pid || isPidAlive(pid)) return;
-  } catch (_) { /* missing or unreadable beacon */ }
+  const pid = ownerPid(SERVER_INFO_FILE);
+  if (pid !== null && isPidAlive(pid)) return;
   writeServerInfo(port);
 }
 
@@ -718,29 +736,13 @@ function getTaskCounts(sessionPath) {
   const cached = taskCountsCache.get(sessionPath);
   if (cached) return cached;
 
-  const taskFiles = readdirSync(sessionPath).filter(f => f.endsWith('.json'));
-  let completed = 0, inProgress = 0, pending = 0, newestTaskMtime = null;
+  const { completed, inProgress, pending, newestTaskMtime } = countTaskDir(sessionPath);
   // Directory mtime bumps when task files are added/removed, so it stays fresh even for an
   // emptied dir (task list closed) that has no files left to date. Task-file mtime alone would
   // report 0 for such a dir and lose "latest wins" to a stale prior-boot dir.
   let dirMtime = 0;
   try { dirMtime = statSync(sessionPath).mtimeMs; } catch (_) {}
 
-  for (const file of taskFiles) {
-    try {
-      const taskPath = path.join(sessionPath, file);
-      const task = JSON.parse(readFileSync(taskPath, 'utf8'));
-      if (task.metadata?._internal) continue;
-      if (task.status === 'completed') completed++;
-      else if (task.status === 'in_progress') inProgress++;
-      else pending++;
-      const taskStat = statSync(taskPath);
-      if (!newestTaskMtime || taskStat.mtime > newestTaskMtime) {
-        newestTaskMtime = taskStat.mtime;
-      }
-    } catch { /* skip invalid */ }
-  }
-
   const taskCount = completed + inProgress + pending;
   const result = { taskCount, completed, inProgress, pending, newestTaskMtime, dirMtime };
   taskCountsCache.set(sessionPath, result);
@@ -823,8 +825,6 @@ function refreshSessionMetadataPath(jsonlPath) {
   if (info.cwd) existing.cwd = info.cwd;
   if (info.gitBranch) existing.gitBranch = info.gitBranch;
   if (info.customTitle) existing.customTitle = info.customTitle;
-  // Direct assign (not guarded) so a /goal clear propagates as null.
-  existing.goal = info.goal || null;
   if (info.logicalParentUuid) existing.logicalParentUuid = info.logicalParentUuid;
   if (info.compactBoundaryUuid) existing.compactBoundaryUuid = info.compactBoundaryUuid;
   return true;
@@ -911,7 +911,6 @@ function loadSessionMetadata() {
           cwd: sessionInfo.cwd || null,
           gitBranch: sessionInfo.gitBranch || null,
           customTitle: sessionInfo.customTitle || null,
-          goal: sessionInfo.goal || null,
           jsonlPath: jsonlPath,
           logicalParentUuid: sessionInfo.logicalParentUuid || null,
           compactBoundaryUuid: sessionInfo.compactBoundaryUuid || null
@@ -1155,7 +1154,6 @@ function buildSessionObject(id, meta, overrides = {}) {
     gitBranch: resolveSessionGitBranch(meta),
     worktree: resolveWorktree(meta.project),
     customTitle: meta.customTitle || null,
-    goal: meta.goal || null,
     taskCount: 0,
     completed: 0,
     inProgress: 0,
@@ -1177,7 +1175,6 @@ function buildSessionObject(id, meta, overrides = {}) {
     contextStatus: getContextStatus(id, meta),
     ...getPlanInfo(meta.slug),
     ...getWorkflowInfoSummary(id),
-    loopInfo: getLoopInfoSummary(meta),
     ...overrides,
     // Remove internal-only field
     _logStat: undefined,
@@ -1551,24 +1548,62 @@ app.get('/api/sessions', async (req, res) => {
     // The client sends the session it currently has open, which it cannot render at all
     // if the row is missing — that one is not a preference.
     if (projectFilter) {
-      sessions = sessions.filter(s => s.project === projectFilter || includeIds.has(s.id));
+      const matches = projectMatcher(String(projectFilter));
+      sessions = sessions.filter(s => matches(s.project) || includeIds.has(s.id));
+    }
+    // The sidebar's 24h filter: projects with any transcript written in the window, so an older
+    // session of such a project stays in.
+    const recentHours = Number(req.query.recentHours);
+    if (recentHours > 0) {
+      const cutoff = Date.now() - recentHours * 3600 * 1000;
+      const activity = projectActivity();
+      sessions = sessions.filter(s => (activity.get(s.project) || 0) > cutoff || includeIds.has(s.id));
     }
 
+    const paged = limit !== null && limit > 0;
+    // The sidebar loads the next page on scroll while this is true. A header, so the body stays a plain array.
+    res.setHeader('X-Has-More', String(paged && sessions.length > limit));
     // Apply limit if specified, but always include pinned sessions
-    if (limit !== null && limit > 0) {
+    if (paged) {
       const top = sessions.slice(0, limit);
       const topIds = new Set(top.map(s => s.id));
       const missingPinned = sessions.filter(s => pinnedIds.has(s.id) && !topIds.has(s.id));
       sessions = [...top, ...missingPinned];
     }
 
+    // Loop info can mean a full read of the transcript, so only the rows sent pay for it.
+    for (const s of sessions) s.loopInfo = getLoopInfoSummary(s);
+
     res.json(withDispatchPlacement(sessions));
+    startPrewarm();
   } catch (error) {
     console.error('Error listing sessions:', error);
     res.status(500).json({ error: 'Failed to list sessions' });
   }
 });
 
+// Ids of sessions whose id or name contains q, from any transcript, newest first. The client
+// gets the rows through `/api/sessions?include=`. A linear scan is enough: ~4 ms for 10k ids,
+// plus one stat per hit for the sort.
+const SESSION_SEARCH_MIN = 3;
+const SESSION_SEARCH_MAX = 20;
+app.get('/api/sessions/search', (req, res) => {
+  res.setHeader('Cache-Control', 'no-store');
+  const text = String(req.query.q || '').trim().toLowerCase();
+  if (text.length < SESSION_SEARCH_MIN) return res.json([]);
+  const idQ = text.replace(/-/g, '');
+  const searchIds = idQ.length >= SESSION_SEARCH_MIN && /^[0-9a-f]+$/.test(idQ);
+  const hits = [];
+  for (const [id, meta] of Object.entries(loadSessionMetadata())) {
+    const name = getSessionDisplayName(id, meta);
+    if ((searchIds && id.replace(/-/g, '').includes(idQ)) || name?.toLowerCase().includes(text)) {
+      hits.push({ id, mtime: getSessionLogStat(meta).mtime || 0 });
+    }
+  }
+  hits.sort((a, b) => b.mtime - a.mtime);
+  res.json(hits.slice(0, SESSION_SEARCH_MAX).map((h) => h.id));
+});
+
 // os.tmpdir() can be an 8.3 short path on Windows; transcripts record the long form.
 const TEMP_ROOT = (() => {
   try { return realpathSync.native(os.tmpdir()); } catch { return os.tmpdir(); }
@@ -1578,19 +1613,22 @@ function isTempPath(p) {
   return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
 }
 
-// API: Get distinct project paths with last-modified timestamps
-app.get('/api/projects', (_req, res) => {
-  res.setHeader('Cache-Control', 'no-store');
-  const metadata = loadSessionMetadata();
-  const projectMap = {};
-  for (const meta of Object.values(metadata)) {
+// Project path → newest transcript mtime among its sessions (undefined when none has one).
+function projectActivity() {
+  const activity = new Map();
+  for (const meta of Object.values(loadSessionMetadata())) {
     if (!meta.project) continue;
     const mtime = getSessionLogStat(meta).mtime;
-    if (!projectMap[meta.project] || (mtime && mtime > projectMap[meta.project])) {
-      projectMap[meta.project] = mtime;
-    }
+    const prev = activity.get(meta.project);
+    if (!prev || (mtime && mtime > prev)) activity.set(meta.project, mtime);
   }
-  const projects = Object.entries(projectMap)
+  return activity;
+}
+
+// API: Get distinct project paths with last-modified timestamps
+app.get('/api/projects', (_req, res) => {
+  res.setHeader('Cache-Control', 'no-store');
+  const projects = [...projectActivity()]
     .map(([path, mtime]) => ({
       path,
       modifiedAt: mtime ? new Date(mtime).toISOString() : null,
@@ -2398,7 +2436,8 @@ app.get('/api/sessions/:sessionId/agents', (req, res) => {
       try {
         const progressMap = getProgressMap(meta.jsonlPath);
         for (const entry of Object.values(progressMap)) {
-          const e = (byAgentId[entry.agentId] ||= {});
+          byAgentId[entry.agentId] ||= {};
+          const e = byAgentId[entry.agentId];
           for (const f of ['prompt', 'name', 'description', 'usage']) {
             if (entry[f] && !e[f]) e[f] = entry[f];
           }
@@ -2674,7 +2713,6 @@ function resolveSubagentJsonl(meta, sessionId, agentId) {
 //   Fork: copies the parent's early messages verbatim (same UUIDs). Anchor = first UUID.
 //   Compact: writes a compact_boundary record with logicalParentUuid in the preamble.
 // Birthtime (not mtime) identifies the parent — mtime changes on resume, birthtime is immutable.
-const parentSessionCache = new Map();
 const FORK_ANCHOR_SCAN_LINES = 10;
 function findForkAnchorUuid(jsonlPath) {
   let text;
@@ -2688,8 +2726,8 @@ function findForkAnchorUuid(jsonlPath) {
   return firstUuid;
 }
 // Fallback when the metadata cache lacks the boundary pair (older entries, cold cache).
-// Reached only from lookupParentSession, whose result is memoized for the process life —
-// at most one read per session, never per request.
+// Reached only from lookupParentSession, whose result is cached (lib/parent-cache.js) —
+// one read per session until its verdict goes stale, never per request.
 // Bounded read (~1 MB) mirrors readSessionInfoFromJsonl's HEAD_MAX — compact_boundary
 // always sits in the preamble before the first user/assistant record.
 const COMPACT_ANCHOR_READ_MAX = 1048576;
@@ -2729,8 +2767,9 @@ function findSessionContainingUuid(projectDir, targetUuid, excludeJsonlPath, max
     if (!f.endsWith('.jsonl')) continue;
     const fp = path.join(projectDir, f);
     if (fp === excludeJsonlPath) continue;
-    let birthtime = 0;
-    try { birthtime = statSync(fp).birthtimeMs; } catch { continue; }
+    let st;
+    try { st = statSync(fp); } catch { continue; }
+    const birthtime = st.birthtimeMs;
     if (maxBirthtimeMs != null && birthtime >= maxBirthtimeMs) continue;
     if (birthtime >= bestBirthtime) continue;
     let text;
@@ -2741,7 +2780,7 @@ function findSessionContainingUuid(projectDir, targetUuid, excludeJsonlPath, max
       try {
         const d = JSON.parse(l);
         if (d.uuid === targetUuid && d.sessionId) {
-          best = { parentSessionId: d.sessionId, parentJsonlPath: fp, isFork: false };
+          best = { parentSessionId: d.sessionId, parentJsonlPath: fp, parentIno: st.ino, isFork: false };
           bestBirthtime = birthtime;
           bestText = text;
           break;
@@ -2754,8 +2793,10 @@ function findSessionContainingUuid(projectDir, targetUuid, excludeJsonlPath, max
   return best;
 }
 function lookupParentSession(sessionId) {
-  if (parentSessionCache.has(sessionId)) return parentSessionCache.get(sessionId);
   const meta = loadSessionMetadata()[sessionId];
+  const known = getParentVerdict(sessionId, meta);
+  if (known) return known;
+  let self = null, parentIno = null;
   // relation is the single verdict: 'none' (no parent found), 'compact' (this session
   // continues a lineage the parent could not hold) or 'fork' (an intentional branch off
   // a parent that keeps its own life). isCompact/isFork are derived views of it.
@@ -2770,23 +2811,24 @@ function lookupParentSession(sessionId) {
     // A fork copies the parent's early records verbatim, so its first uuid is the anchor.
     const anchorUuid = compactAnchor ?? findForkAnchorUuid(meta.jsonlPath);
     if (anchorUuid) {
-      let selfBirthtime;
-      try { selfBirthtime = statSync(meta.jsonlPath).birthtimeMs; } catch { /* ignore */ }
-      if (selfBirthtime != null) {
-        const hit = findSessionContainingUuid(path.dirname(meta.jsonlPath), anchorUuid, meta.jsonlPath, selfBirthtime, boundary?.boundaryUuid);
+      try { self = statSync(meta.jsonlPath); } catch { /* ignore */ }
+      if (self) {
+        const hit = findSessionContainingUuid(path.dirname(meta.jsonlPath), anchorUuid, meta.jsonlPath, self.birthtimeMs, boundary?.boundaryUuid);
         if (hit) {
           // No compact boundary at all → fork by construction; with one, the copied
           // boundary uuid (hit.isFork) is what separates a fork from a continuation.
           result.parentSessionId = hit.parentSessionId;
           result.parentJsonlPath = hit.parentJsonlPath;
           result.relation = (!compactAnchor || hit.isFork) ? 'fork' : 'compact';
+          parentIno = hit.parentIno;
         }
       }
     }
   }
   result.isCompact = result.relation === 'compact';
   result.isFork = result.relation === 'fork';
-  parentSessionCache.set(sessionId, result);
+  // No anchor yet means the head is not written; that "no parent" is not a verdict.
+  if (self) setParentVerdict(sessionId, meta, self, parentIno, result);
   return result;
 }
 // #endregion
@@ -3143,8 +3185,10 @@ function isAllowedFolder(dir) {
   try { return known && statSync(dir).isDirectory(); } catch { return false; }
 }
 
+let listenPort = null;
 const terminal = createTerminalService({
   config: readTerminalConfig({ getArgValue }),
+  serverUrl: () => (listenPort ? `http://127.0.0.1:${listenPort}` : null),
   net,
   claudeDir: CLAUDE_DIR,
   isDefaultDir: isDefaultClaudeDir(CLAUDE_DIR),
@@ -3229,6 +3273,13 @@ const dispatchGroups = createGroupStore({
   pinnedIds: () => new Set(Object.keys(readPins())),
 });
 
+const linkedDocs = createLinkedDocStore({
+  load: () => {
+    try { return JSON.parse(readFileSync(LINKED_DOCS_FILE, 'utf8')); } catch { return null; }
+  },
+  save: (data) => writeJsonAtomic(LINKED_DOCS_FILE, data),
+});
+
 // The board places a session from these alone, so it never has to move it later.
 // `startedBy` lets it follow a starter the user put in a named group, which only the
 // browser knows; it goes once the dispatch settles.
@@ -3256,8 +3307,7 @@ app.post('/api/dispatch', (req, res) => {
   if (group != null && !isGroupName(group)) {
     return res.status(400).json({ error: `group must be kebab-case, e.g. ${suggestGroupName(group) || 'my-group'}` });
   }
-  const starterGroup = parent ? dispatchGroups.groupOf(parent) : null;
-  const target = group || starterGroup;
+  const target = group || (parent && dispatchGroups.groupOf(parent)) || null;
   const r = dispatches.create({ parent, name, spec: spec.trim(), report: report === true, peer, group: target, worktree });
   const env = { CCK_DISPATCH_ID: r.id, ...(parent && { PARENT_SESSION_ID: parent }) };
   const started = terminal.startNew({ cwd, name, model, worktree, prompt: formatPreamble(r) }, env);
@@ -3266,8 +3316,8 @@ app.post('/api/dispatch', (req, res) => {
     return res.status(started.status).json({ error: started.error });
   }
   dispatches.attach(r.id, { session: started.id, cwd: started.cwd });
-  // A starter already in a group stays where it is: moving it would jump it under the user.
-  if (target) dispatchGroups.join(target, [starterGroup ? null : parent, started.id]);
+  // The starter stays where it is: moving it would jump it under the user.
+  if (target) dispatchGroups.join(target, [started.id], parent);
   broadcast({ type: 'dispatch-update' });
   res.status(201).json({ dispatch: r.id, session: started.id, cwd: started.cwd, group: target });
 });
@@ -3653,14 +3703,29 @@ app.post('/api/document/link', async (req, res) => {
     const abs = resolvePreviewPath(filePath);
     if (!abs) return res.status(400).json({ error: 'path is required' });
     if (!unlink) await statFileTarget(abs);
+    if (unlink) linkedDocs.unlink(sessionId, abs);
+    else linkedDocs.link(sessionId, abs);
     broadcast({ type: 'document:link', path: abs, sessionId, unlink: !!unlink });
-    res.json({ success: true });
+    res.json({ success: true, path: abs, tabs: clients.size });
   } catch (error) {
     console.error('Error in /api/document/link:', error);
     res.status(error.status || 500).json({ error: error.message || 'Link failed' });
   }
 });
 
+app.get('/api/document/links', (req, res) => {
+  res.setHeader('Cache-Control', 'no-store');
+  const sessionId = req.query.session ? String(req.query.session) : null;
+  res.json(sessionId ? { [sessionId]: linkedDocs.get(sessionId) } : linkedDocs.all());
+});
+
+// The browser's own unlink: it already updated its list, so this only drops the server
+// copy that would bring the doc back on the next merge. No path clears the session.
+app.delete('/api/document/links/:sessionId', (req, res) => {
+  const filePath = req.query.path ? resolvePreviewPath(String(req.query.path)) : null;
+  res.json({ removed: linkedDocs.unlink(req.params.sessionId, filePath) });
+});
+
 app.get('/api/session/resolve', (req, res) => {
   try {
     const idArg = (req.query.id || '').toString();
@@ -4080,30 +4145,51 @@ setInterval(cleanupContextStatus, 30 * 60 * 1000);
 // enrichment for inactive sessions, so we no longer drive a full self-request
 // here — that was 690× wasted work for an active-filter first hit.
 // Yields to the event loop periodically so any inbound request isn't starved.
+// A yield every N sessions does not bound the wait: one large transcript is a long sync read.
+const PREWARM_SLICE_MS = 10;
+// Started on the ready line, the full read of every transcript competes for disk and CPU with
+// the hub's other apps while they render, and slows their first render. It starts after the
+// first list is sent, or after the fallback when no client asks.
+const PREWARM_FALLBACK_MS = 5000;
+const SESSION_CACHE_SAVE_MS = 30000;
+const persistSessionCache = () => saveSessionCache((data) => writeJsonAtomic(SESSION_CACHE_FILE, data));
+let prewarmStarted = false;
+function startPrewarm() {
+  if (prewarmStarted) return;
+  prewarmStarted = true;
+  setImmediate(prewarmCaches);
+}
+
 async function prewarmCaches() {
   const t0 = Date.now();
   try {
     const metadata = loadSessionMetadata();
 
-    let i = 0;
+    let sliceStart = Date.now();
     for (const meta of Object.values(metadata)) {
       if (meta?.jsonlPath) {
         try { refreshLoopInfoState(meta.jsonlPath); } catch {}
       }
-      if (++i % 50 === 0) await new Promise(r => setImmediate(r));
+      if (Date.now() - sliceStart >= PREWARM_SLICE_MS) {
+        await new Promise(r => setImmediate(r));
+        sliceStart = Date.now();
+      }
     }
 
     console.log(`[prewarm] done in ${Date.now() - t0}ms (${Object.keys(metadata).length} sessions)`);
+    persistSessionCache();
   } catch (e) {
     console.warn('[prewarm] failed:', e.message);
   }
 }
 
   const onReady = (actualPort) => {
-    console.log(`Claude Task Kanban running at http://localhost:${actualPort}`);
+    listenPort = actualPort;
     // The port is configurable and falls back to a random one when taken, so the postman
     // monitor cannot assume it -- publish the live one where it can read it.
     writeServerInfo(actualPort);
+    writeTerminalToken(actualPort);
+    console.log(`Claude Task Kanban running at http://localhost:${actualPort}`);
     setInterval(() => reclaimServerInfo(actualPort), 30000).unref();
     migrateLegacyApprovalsConfig();
     const warning = net.exposureWarning();
@@ -4118,9 +4204,15 @@ async function prewarmCaches() {
     if (process.argv.includes('--open')) {
       import('open').then(open => open.default(`http://localhost:${actualPort}`));
     }
-    setImmediate(prewarmCaches);
+    setTimeout(startPrewarm, PREWARM_FALLBACK_MS).unref();
   };
 
+  loadSessionCache(SESSION_CACHE_FILE);
+  // Under the hub a child can end by TerminateProcess on Windows, where no exit handler runs,
+  // so the cache is also saved on a timer.
+  setInterval(persistSessionCache, SESSION_CACHE_SAVE_MS).unref();
+  process.on('exit', persistSessionCache);
+
   const listenOpts = { onUpgrade: terminal.handleUpgrade };
   const server = net.listenLoopback(app, PORT, onReady, listenOpts);
   process.on('exit', terminal.shutdown);
@@ -4135,4 +4227,5 @@ async function prewarmCaches() {
   });
 
 
-// #endregion
+// #endregion
+}

package/skill-guides/dispatch.md

@@ -19,14 +19,15 @@ Dispatch when the task can run on its own. Do the work yourself when it is small
 ## Start
 
 ```bash
-claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name> --group <group> --peer <your-peer> [--report] [--model haiku|sonnet|opus|fable] [--worktree [name]] --json
+claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name> --group <group> --peer <your-peer> [--report] --json
 ```
 
+`claude-code-kanban help dispatch start` lists every flag (model, worktree, and the rest). `project list` shows the folders `--cwd` accepts. How to choose the values:
+
 - `--peer` is your own peer name: the first line of `ListAgents` ("This session is `<name>`"). Pass it whenever you have the `ListAgents` tool. cck then tells the started session to ask you with `SendMessage` instead of failing on a question. See [Peer](#peer).
-- `--cwd` must be a project cck already knows (default: the current dir).
 - `--spec-file` over `--spec` for anything longer than a line: no shell quoting.
 - `--name` is what the user sees in the sidebar. Kebab-case, saying what the session does: `fix-login-redirect`, not `task-1`.
-- `--group` names the effort, in kebab-case (`auth-refactor`), and shows the new session and this session together under one sidebar group. Pass it on your first dispatch; later dispatches join the same group without it. A group goes away when its sessions end, unless the user pins a member or keeps the group.
+- `--group` names the effort, in kebab-case (`auth-refactor`), and shows the new session under that sidebar group. This session stays where it is. Pass it on your first dispatch; later dispatches join the same group without it. A group goes away when its sessions end, unless the user pins a member or keeps the group.
 - The result holds the `dispatch` id and the `session` id.
 
 ## Fire-and-forget
@@ -44,7 +45,7 @@ The started session settles with one report, `succeeded` or `failed`, or as `exi
 claude-code-kanban dispatch wait [<id>...] --timeout 15m --json
 ```
 
-It returns `settled`, `running`, and `timeout`, as soon as any watched dispatch settles; call it again with the ids still running. A timeout is a checkpoint: the session may still be working. Look before you act:
+Call it again with the ids still running (`help dispatch wait` has the output fields). A timeout is a checkpoint: the session may still be working. Look before you act:
 
 ```bash
 claude-code-kanban dispatch list --json