claude-code-kanban 7.4.0 → 7.6.0

package/server.js

@@ -4,7 +4,7 @@
 const express = require('express');
 const path = require('node:path');
 const fs = require('node:fs').promises;
-const { existsSync, readdirSync, readFileSync, writeFileSync, statSync, unlinkSync, mkdirSync, renameSync, openSync, readSync, closeSync, realpathSync } = require('node:fs');
+const { existsSync, readdirSync, readFileSync, writeFileSync, statSync, unlinkSync, rmSync, mkdirSync, renameSync, openSync, readSync, closeSync, realpathSync } = require('node:fs');
 const _readline = require('node:readline');
 const chokidar = require('chokidar');
 const os = require('node:os');
@@ -12,7 +12,7 @@ const crypto = require('node:crypto');
 const { spawn } = require('node:child_process');
 const { assertOpenTarget, openInEditor, whichSync, exeBehindShim } = require('./lib/open-editor');
 const { createNetGuard } = require('./lib/net-guard');
-const { isContained } = require('./lib/contain');
+const { isContained, realpathDeepest } = require('./lib/contain');
 const { resolveScratchSubdir, listScratchDir } = require('./lib/scratch-files');
 const { fileUrlToPath } = require('./lib/file-url');
 const { httpError: previewError } = require('./lib/http-error');
@@ -28,6 +28,7 @@ const {
   modelDisplayName,
   buildSessionDigest,
   readCompactSummaries,
+  fillCompactSummaries,
   readArtifactLinks,
   readScratchpadCreations,
   extractPromptFromTranscript,
@@ -48,14 +49,15 @@ const { buildDecision, decisionFileName, isDecisionFile, approvalsFrom, boardRef
 const { getClaudeDir, getArgValue, storageNamespace, isDefaultClaudeDir } = require('./lib/claude-dir');
 const { readTerminalConfig } = require('./lib/terminal');
 const { createTerminalClient } = require('./lib/terminal-client');
+const { createShowStore, mountShowRoutes, showBodyParser, SHOW_PATH } = require('./lib/show');
 const { readLiveSessions, isPidAlive, isSessionLive } = require('./lib/live-sessions');
 const { createProcStats } = require('./lib/proc-stats');
-const { createDispatchRegistry } = require('./lib/dispatch');
 const { createGroupStore, isGroupName, suggestGroupName } = require('./lib/dispatch-groups');
-const { createDispatchedStore, scanTranscripts, pruneSessionDirs, pruneContextStatus, retentionMs } = require('./lib/retention');
+const { createDispatchedStore, scanTranscripts, pruneSessionDirs, pruneContextStatus, pruneTaskMaps, retentionMs } = require('./lib/retention');
 const { freshRateLimits } = require('./lib/rate-limits');
 const { createWorktreeStore } = require('./lib/worktrees');
-const { createScratchpadDirResolver } = require('./lib/scratchpad-dir');
+const { createScratchpadDirResolver, scratchpadRoot } = require('./lib/scratchpad-dir');
+const { readSettings } = require('./lib/claude-settings');
 const { readGitBranch, sessionGitBranch } = require('./lib/git-branch');
 const { createLinkedDocStore, linkUrl } = require('./lib/linked-docs');
 const { createPaneStore, isOwnOrigin } = require('./lib/panes');
@@ -63,6 +65,7 @@ const { probeFraming, parseOrigin } = require('./lib/frame-policy');
 const { pickFolder } = require('./lib/folder-dialog');
 const { loadSessionCache, saveSessionCache } = require('./lib/session-cache');
 const { countTaskDir } = require('./lib/task-counts');
+const { readTaskDir } = require('./lib/task-dir');
 const { projectMatcher, normalizeProjectPath } = require('./public/project-match');
 const { getParentVerdict, setParentVerdict } = require('./lib/parent-cache');
 
@@ -115,13 +118,25 @@ const PANES_FILE = path.join(CCK_DIR, 'panes.json');
 const SERVER_INFO_FILE = path.join(CCK_DIR, 'server.json');
 const TERMINAL_TOKENS_DIR = path.join(CCK_DIR, 'terminal-tokens');
 const SESSION_CACHE_FILE = path.join(CCK_DIR, 'session-cache.json');
-const TERMINALS_FILE = path.join(CCK_DIR, 'terminals.json');
+// Every board on a config dir rewrites the whole file, so a test board points this elsewhere.
+const TERMINALS_FILE = process.env.CCK_TERMINALS_FILE ? path.resolve(process.env.CCK_TERMINALS_FILE) : path.join(CCK_DIR, 'terminals.json');
 // 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(); }
 })();
 // Harness-owned scratchpad root; the per-session dir under it is created lazily.
-const SCRATCHPAD_ROOT = path.join(TEMP_ROOT, 'claude');
+// Used only for a transcript that does not record its scratchpad dir. Settings come first:
+// cck often runs under the hub or a tray, not in the shell where `claude` ran.
+const SCRATCHPAD_ROOT = (() => {
+  const root = scratchpadRoot({
+    platform: process.platform,
+    overrides: [readSettings(path.join(CLAUDE_DIR, 'settings.json'))?.env?.CLAUDE_CODE_TMPDIR, process.env.CLAUDE_CODE_TMPDIR],
+    tmpdir: os.tmpdir(),
+    uid: process.getuid?.(),
+  });
+  // Claude Code resolves the root with realpath too: /private/tmp/claude-<uid> on macOS.
+  return realpathDeepest(root);
+})();
 
 // #endregion
 
@@ -136,25 +151,66 @@ function readPins() {
 }
 
 function writeJsonAtomic(file, obj, mode) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
   try {
-    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);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+// Claude Code reads task files while the board writes them, so it must never see half a file.
+// On Windows a rename over a file another handle has open fails with EPERM or EBUSY until it closes.
+let taskWriteSeq = 0;
+async function writeTaskFile(file, task) {
+  const tmp = `${file}.${process.pid}.${++taskWriteSeq}.tmp`;
+  try {
+    await fs.writeFile(tmp, JSON.stringify(task, null, 2));
+    for (let attempt = 1; ; attempt++) {
+      try {
+        await fs.rename(tmp, file);
+        break;
+      } catch (e) {
+        if (attempt >= 10 || (e.code !== 'EPERM' && e.code !== 'EBUSY')) throw e;
+        await new Promise((r) => setTimeout(r, attempt * 10));
+      }
+    }
+  } catch (e) {
+    await fs.rm(tmp, { force: true });
+    throw e;
+  }
+}
+
+// For state that is also held in memory: a failed save is logged and the server goes on.
+function writeJsonAtomicOrLog(file, obj, mode) {
+  try {
+    writeJsonAtomic(file, obj, mode);
   } catch (e) {
     console.error(`Failed to write ${path.basename(file)}:`, e.message);
   }
 }
 
+function readJsonOrNull(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+const jsonFile = (file) => ({
+  load: () => readJsonOrNull(file),
+  save: (data) => writeJsonAtomicOrLog(file, data),
+});
+
 function writePins(pins) {
   writeJsonAtomic(PINS_FILE, pins);
 }
 
-// Port discovery for out-of-process helpers (the postman monitor, the CLI).
+// Port discovery for out-of-process helpers (the plugin's doorbell mod, the CLI).
 // The pid rides along so a reader can tell a live server from a file left behind by
 // a crashed one.
 function writeServerInfo(port) {
-  writeJsonAtomic(SERVER_INFO_FILE, { port, pid: process.pid });
+  writeJsonAtomicOrLog(SERVER_INFO_FILE, { port, pid: process.pid });
 }
 
 // For `dispatch start`: a local process as the same user can already run claude itself,
@@ -172,14 +228,14 @@ function writeTerminalToken(port) {
     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);
+  writeJsonAtomicOrLog(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 sends the postman monitor and the CLI to a closed
+// A beacon that outlives its server sends the doorbell mod and the CLI to a closed
 // port. 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
@@ -255,9 +311,14 @@ function persistAgent(dir, agent) {
 const CCK_CONFIG_FILE = path.join(CCK_DIR, 'config.json');
 const LEGACY_APPROVALS_FILE = path.join(CCK_DIR, 'approvals.json');
 const cckConfigCache = new Map();
+const readCckConfig = () => JSON.parse(readFileSync(CCK_CONFIG_FILE, 'utf8'));
 function approvalsConfig() {
   return cachedByMtime(cckConfigCache, 'approvals', CCK_CONFIG_FILE,
-    () => approvalsFrom(JSON.parse(readFileSync(CCK_CONFIG_FILE, 'utf8'))), approvalsFrom(null));
+    () => approvalsFrom(readCckConfig()), approvalsFrom(null));
+}
+function boardEventsEnabled() {
+  return cachedByMtime(cckConfigCache, 'boardEvents', CCK_CONFIG_FILE,
+    () => boardEventsOn(readCckConfig()), boardEventsOn(null));
 }
 
 // approvals.json predates config.json (and was opt-in). Fold it into
@@ -268,7 +329,7 @@ function migrateLegacyApprovalsConfig() {
     const legacy = JSON.parse(readFileSync(LEGACY_APPROVALS_FILE, 'utf8'));
     let cfg = {};
     try { cfg = JSON.parse(readFileSync(CCK_CONFIG_FILE, 'utf8')) || {}; } catch { /* absent */ }
-    if (!cfg.approvals) writeJsonAtomic(CCK_CONFIG_FILE, { ...cfg, approvals: legacy });
+    if (!cfg.approvals) writeJsonAtomicOrLog(CCK_CONFIG_FILE, { ...cfg, approvals: legacy });
     unlinkSync(LEGACY_APPROVALS_FILE);
     cckConfigCache.clear();
   } catch (e) {
@@ -352,12 +413,7 @@ function getGitBranch(cwd) {
   return branch;
 }
 
-const worktrees = createWorktreeStore({
-  load: () => {
-    try { return JSON.parse(readFileSync(WORKTREES_FILE, 'utf8')); } catch { return null; }
-  },
-  save: (data) => writeJsonAtomic(WORKTREES_FILE, data),
-});
+const worktrees = createWorktreeStore(jsonFile(WORKTREES_FILE));
 
 function getSessionLogStat(meta) {
   if (!meta.jsonlPath) return { mtime: null, hasMessages: false };
@@ -457,6 +513,11 @@ function resolveSessionId(sessionId) {
   return (teamConfig?.leadSessionId) ? teamConfig.leadSessionId : sessionId;
 }
 
+function sessionMetaFor(sessionId) {
+  const metadata = loadSessionMetadata();
+  return metadata[sessionId] || metadata[resolveSessionId(sessionId)];
+}
+
 // Recent Claude Code releases auto-create a single-member "self-team" for every
 // session: a teams/session-<id>/config.json whose only member is the "team-lead"
 // (the session itself). These are not real multi-agent teams — surfacing them
@@ -600,8 +661,9 @@ app.param('name', (_req, res, next, val) => {
   next();
 });
 
-// Parse JSON bodies
-app.use(express.json());
+app.use(SHOW_PATH, showBodyParser());
+// Parse JSON bodies. A review of 50 comments at the field caps is about 450 kB.
+app.use(express.json({ limit: '1mb' }));
 // #endregion
 
 // #region STATIC
@@ -840,6 +902,7 @@ function refreshSessionMetadataPath(jsonlPath) {
   if (info.compactBoundaryUuid) existing.compactBoundaryUuid = info.compactBoundaryUuid;
   existing.permissionMode = info.permissionMode;
   existing.cacheTtl = info.cacheTtl;
+  if (info.scratchpadDir) existing.scratchpadDir = info.scratchpadDir;
   existing.lastReply = info.lastReply;
   return true;
 }
@@ -932,7 +995,8 @@ function loadSessionMetadata() {
           compactBoundaryUuid: sessionInfo.compactBoundaryUuid || null,
           permissionMode: sessionInfo.permissionMode,
           cacheTtl: sessionInfo.cacheTtl || null,
-          lastReply: sessionInfo.lastReply || null
+          lastReply: sessionInfo.lastReply || null,
+          scratchpadDir: sessionInfo.scratchpadDir || null
         };
         sessionIds.push(sessionId);
       }
@@ -1136,6 +1200,8 @@ function getSessionDisplayName(_sessionId, meta) {
 const getScratchpadDir = createScratchpadDirResolver({
   root: SCRATCHPAD_ROOT,
   resolveWorktree: worktrees.resolve,
+  // Transcripts record the 8.3 short form on Windows; path checks and the watcher need the long one.
+  toLong: realpathDeepest,
 });
 
 function buildSessionObject(id, meta, overrides = {}) {
@@ -1707,25 +1773,9 @@ function addOwnerSessions(tasks, listIdOf) {
 
 app.get('/api/sessions/:sessionId', async (req, res) => {
   try {
-    const sessionPath = taskDirFor(req.params.sessionId);
-
     // A session that never used the board has no task dir. That is the common case and
     // an answer, not a failure; a 404 only reached the browser console.
-    if (!existsSync(sessionPath)) {
-      return res.json([]);
-    }
-
-    const taskFiles = readdirSync(sessionPath).filter(f => f.endsWith('.json'));
-    const tasks = [];
-
-    for (const file of taskFiles) {
-      try {
-        const task = JSON.parse(readFileSync(path.join(sessionPath, file), 'utf8'));
-        tasks.push(task);
-      } catch (e) {
-        console.error(`Error parsing ${file}:`, e);
-      }
-    }
+    const tasks = (await readTaskDir(taskDirFor(req.params.sessionId))).map(({ task }) => task);
 
     // Sort by ID (numeric)
     tasks.sort((a, b) => parseInt(a.id, 10) - parseInt(b.id, 10));
@@ -1739,41 +1789,24 @@ app.get('/api/sessions/:sessionId', async (req, res) => {
 });
 
 // API: Get combined tasks for a project (all sessions + shared task lists)
-app.get('/api/projects/:encodedPath/tasks', (req, res) => {
+app.get('/api/projects/:encodedPath/tasks', async (req, res) => {
   try {
     const projectPath = Buffer.from(req.params.encodedPath, 'base64').toString('utf8');
     const metadata = loadSessionMetadata();
-    const { sessionToList } = loadAllTaskMaps();
-
-    const projectSessionIds = Object.entries(metadata)
-      .filter(([, m]) => m.project === projectPath)
-      .map(([id]) => id);
-
-    const taskDirs = new Set();
-    for (const sid of projectSessionIds) {
-      const listName = sessionToList[sid];
-      if (listName) {
-        const dir = path.join(TASKS_DIR, listName);
-        if (existsSync(dir)) taskDirs.add(dir);
-      } else {
-        const dir = path.join(TASKS_DIR, sid);
-        if (existsSync(dir)) taskDirs.add(dir);
-      }
-    }
+    const taskDirs = new Set(
+      Object.entries(metadata)
+        .filter(([, m]) => m.project === projectPath)
+        .map(([id]) => taskDirFor(id)),
+    );
 
     const tasks = [];
-    const seenKeys = new Set();
     for (const dir of taskDirs) {
-      for (const file of readdirSync(dir).filter(f => f.endsWith('.json'))) {
-        try {
-          const task = JSON.parse(readFileSync(path.join(dir, file), 'utf8'));
-          const key = `${dir}:${task.id}`;
-          if (!seenKeys.has(key)) {
-            seenKeys.add(key);
-            task._taskDir = path.basename(dir);
-            tasks.push(task);
-          }
-        } catch (_) {}
+      const seenIds = new Set();
+      for (const { task } of await readTaskDir(dir)) {
+        if (seenIds.has(task.id)) continue;
+        seenIds.add(task.id);
+        task._taskDir = path.basename(dir);
+        tasks.push(task);
       }
     }
     tasks.sort((a, b) => parseInt(a.id, 10) - parseInt(b.id, 10));
@@ -1788,8 +1821,7 @@ app.get('/api/projects/:encodedPath/tasks', (req, res) => {
 // API: Get session plan
 app.get('/api/sessions/:sessionId/plan', async (req, res) => {
   try {
-    const metadata = loadSessionMetadata();
-    const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+    const meta = sessionMetaFor(req.params.sessionId);
     // Most sessions have no saved plan, and the info modal asks for one every time it
     // opens, so "no plan" is a normal answer rather than a 404 in the console.
     const slug = meta?.slug;
@@ -1808,8 +1840,7 @@ app.get('/api/sessions/:sessionId/plan', async (req, res) => {
 
 app.get('/api/sessions/:sessionId/loop', (req, res) => {
   try {
-    const metadata = loadSessionMetadata();
-    const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+    const meta = sessionMetaFor(req.params.sessionId);
     if (!meta?.jsonlPath) return res.json({ wakeups: [], crons: [] });
     const state = refreshLoopInfoState(meta.jsonlPath);
     const filtered = filterActiveLoopInfo(buildLoopInfoFromState(state));
@@ -1851,8 +1882,7 @@ function getArtifactLinks(jsonlPath) {
 
 app.get('/api/sessions/:sessionId/artifacts', async (req, res) => {
   try {
-    const metadata = loadSessionMetadata();
-    const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+    const meta = sessionMetaFor(req.params.sessionId);
     if (!meta?.jsonlPath) return res.json({ artifacts: [] });
     res.json({ artifacts: await getArtifactLinks(meta.jsonlPath) });
   } catch (error) {
@@ -1956,8 +1986,7 @@ function getCreatedPads(meta) {
 
 app.get('/api/sessions/:sessionId/pads', async (req, res) => {
   try {
-    const metadata = loadSessionMetadata();
-    const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+    const meta = sessionMetaFor(req.params.sessionId);
     if (!meta?.jsonlPath) return res.json({ pads: [] });
     res.json({ pads: await getCreatedPads(meta) });
   } catch (error) {
@@ -2290,8 +2319,7 @@ app.post('/api/sessions/:sessionId/workflows/:wfId/open', (req, res) => {
 // API: Open session plan in VS Code
 app.post('/api/sessions/:sessionId/plan/open', (req, res) => {
   try {
-    const metadata = loadSessionMetadata();
-    const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+    const meta = sessionMetaFor(req.params.sessionId);
     const slug = meta?.slug;
     if (!slug) return res.status(404).json({ error: 'No plan found' });
 
@@ -3006,8 +3034,7 @@ app.get('/api/sessions/:sessionId/agents/:agentId/messages/stream', (req, res) =
 async function sendSessionMessages(req, res) {
   const limit = Math.min(parseInt(req.query.limit, 10) || 10, 50);
   const before = req.query.before || null;
-  const metadata = loadSessionMetadata();
-  const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+  const meta = sessionMetaFor(req.params.sessionId);
   const jsonlPath = meta?.jsonlPath;
   if (!jsonlPath) return res.json({ messages: [], hasMore: false, sessionId: req.params.sessionId });
   let messages, hasMore;
@@ -3020,7 +3047,10 @@ async function sendSessionMessages(req, res) {
     hasMore = messages.length > limit;
     if (hasMore) messages = messages.slice(-limit);
   }
-  const compactPromise = cachedByMtime(compactSummaryCache, jsonlPath, jsonlPath, () => readCompactSummaries(jsonlPath), []);
+  const compactedMsgs = messages.filter(m => m.systemLabel === 'Compacted');
+  const compactPromise = compactedMsgs.some(m => !m.compactSummary)
+    ? cachedByMtime(compactSummaryCache, jsonlPath, jsonlPath, () => readCompactSummaries(jsonlPath), [])
+    : null;
   const agentMessages = messages.filter(m => m.tool === 'Agent' && m.toolUseId);
   if (agentMessages.length) {
     const progressMap = await getProgressMap(jsonlPath);
@@ -3074,16 +3104,7 @@ async function sendSessionMessages(req, res) {
       }
     }
   }
-  const compactSummaries = await compactPromise;
-  // Match compaction messages to summaries by chronological order
-  const compactedMsgs = messages
-    .filter(m => m.systemLabel === 'Compacted')
-    .sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
-  for (let i = 0; i < compactedMsgs.length; i++) {
-    if (i < compactSummaries.length) {
-      compactedMsgs[i].compactSummary = compactSummaries[i].summary;
-    }
-  }
+  if (compactPromise) fillCompactSummaries(compactedMsgs, await compactPromise);
   // The client keeps needing toolUseId when it builds a follow-up URL from it:
   // lazy-fetching a truncated tool result, or fetching each tool-result image.
   const clientNeedsToolUseId = (msg) => msg.toolResultTruncated || msg.toolResultImageCount;
@@ -3097,8 +3118,7 @@ async function sendSessionMessages(req, res) {
 app.get('/api/sessions/:sessionId/messages', asyncRoute(sendSessionMessages));
 
 app.get('/api/sessions/:sessionId/tool-result/:toolUseId', asyncRoute(async (req, res) => {
-  const metadata = loadSessionMetadata();
-  const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+  const meta = sessionMetaFor(req.params.sessionId);
   const jsonlPath = meta?.jsonlPath;
   if (!jsonlPath) return res.status(404).json({ error: 'session not found' });
   const content = await readFullToolResult(jsonlPath, req.params.toolUseId);
@@ -3203,8 +3223,7 @@ async function buildToolStats(jsonlPath) {
 }
 
 app.get('/api/sessions/:sessionId/tool-stats', async (req, res) => {
-  const metadata = loadSessionMetadata();
-  const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+  const meta = sessionMetaFor(req.params.sessionId);
   const jsonlPath = meta?.jsonlPath;
   if (!jsonlPath) return res.status(404).json({ error: 'session not found' });
   try {
@@ -3217,8 +3236,7 @@ app.get('/api/sessions/:sessionId/tool-stats', async (req, res) => {
 });
 
 async function sendTranscriptImage(req, res, read) {
-  const metadata = loadSessionMetadata();
-  const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+  const meta = sessionMetaFor(req.params.sessionId);
   const jsonlPath = meta?.jsonlPath;
   if (!jsonlPath) return res.status(404).end();
   const img = await read(jsonlPath);
@@ -3299,6 +3317,16 @@ function resolveSessionFolder(id) {
   return meta ? meta.project || meta.cwd || null : null;
 }
 
+// The host saves its terminals; cck adds the show map (terminal id → session id) beside them.
+const terminalsFile = jsonFile(TERMINALS_FILE);
+let savedTerminals = terminalsFile.load() || {};
+
+function saveTerminals() {
+  const kept = new Set(Object.values(savedTerminals.terminalIds || {}));
+  const showSessions = show.prune((id) => kept.has(id) || terminal.hasTerminal(id));
+  terminalsFile.save({ ...savedTerminals, showSessions });
+}
+
 const terminal = createTerminalClient({
   config: readTerminalConfig({ getArgValue }),
   net,
@@ -3306,17 +3334,18 @@ const terminal = createTerminalClient({
   isDefaultDir: isDefaultClaudeDir(CLAUDE_DIR),
   sessionsDir: SESSIONS_DIR,
   token: process.env.CCK_TERMINAL_TOKEN,
-  load: () => {
-    try { return JSON.parse(readFileSync(TERMINALS_FILE, 'utf8')); } catch { return null; }
+  load: terminalsFile.load,
+  save: (data) => {
+    savedTerminals = data;
+    saveTerminals();
   },
-  save: (data) => writeJsonAtomic(TERMINALS_FILE, data),
   // The project, not the last cwd: `claude --resume` finds a session under the
   // project dir it started in, and cwd drifts into subdirectories.
   resolveCwd: resolveSessionFolder,
   isAllowedFolder,
   onChange: () => broadcast({ type: 'terminals-update', ids: terminal.ids() }),
   onExit: (id) => {
-    if (dispatches.remove(id)) broadcast({ type: 'dispatch-update' });
+    if (dispatched.get(id)) broadcast({ type: 'dispatch-update' });
   },
 });
 
@@ -3377,6 +3406,25 @@ app.delete('/api/terminals/:id', terminalRoute(async (req, res) => {
   res.status(204).end();
 }));
 
+const show = createShowStore({
+  load: () => savedTerminals.showSessions,
+  onChange: saveTerminals,
+  onPosted: (e) => broadcast({ type: 'show:posted', ...e }),
+  startedSession: terminal.sessionOfTerminal,
+  resolveDir: (id) => {
+    const meta = sessionMetaFor(id);
+    return meta ? getScratchpadDir(id, meta) : null;
+  },
+});
+mountShowRoutes(app, {
+  store: show,
+  authorized: (token) => terminal.authorized(token),
+  hasTerminal: (id) => terminal.hasTerminal(id),
+  readPreviewFile,
+  broadcast,
+  onRemoved: (sessionId, paths) => panes.removeShow(sessionId, paths),
+});
+
 // Served from node_modules, never a CDN: any script on this page can use the token.
 const XTERM_FILES = {
   'xterm.js': '@xterm/xterm/lib/xterm.js',
@@ -3396,30 +3444,15 @@ app.get('/vendor/xterm/:file', (req, res) => {
 // #endregion
 
 // #region DISPATCH
-const dispatched = createDispatchedStore({
-  load: () => {
-    try { return JSON.parse(readFileSync(DISPATCHED_FILE, 'utf8')); } catch { return null; }
-  },
-  save: (data) => writeJsonAtomic(DISPATCHED_FILE, data),
-});
-
-const dispatches = createDispatchRegistry();
+const dispatched = createDispatchedStore(jsonFile(DISPATCHED_FILE));
 
 const dispatchGroups = createGroupStore({
-  load: () => {
-    try { return JSON.parse(readFileSync(DISPATCH_GROUPS_FILE, 'utf8')); } catch { return null; }
-  },
-  save: (data) => writeJsonAtomic(DISPATCH_GROUPS_FILE, data),
+  ...jsonFile(DISPATCH_GROUPS_FILE),
   isAlive: (id) => terminal.isRunning(id) || isSessionLive(loadLiveSessions(), id),
   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),
-});
+const linkedDocs = createLinkedDocStore(jsonFile(LINKED_DOCS_FILE));
 
 // The board places a session from these alone, so it never has to move it later.
 function withDispatchPlacement(sessions) {
@@ -3448,8 +3481,7 @@ app.post('/api/dispatch', terminalRoute(async (req, res) => {
   }
   const started = await terminal.startNew({ cwd, name, model, worktree, taskList, prompt: spec.trim(), extraArgs: claudeArgs });
   if (started.error) return res.status(started.status).json({ error: started.error });
-  dispatches.add({ session: started.id, parent, cwd: started.cwd, name, group: group || null, worktree });
-  dispatched.record(started.id, parent);
+  dispatched.record(started.id, { parent, cwd: started.cwd, name, group, worktree });
   // The starter stays where it is: moving it would jump it under the user.
   if (group) dispatchGroups.join(group, [started.id]);
   broadcast({ type: 'dispatch-update' });
@@ -3459,7 +3491,7 @@ app.post('/api/dispatch', terminalRoute(async (req, res) => {
 app.get('/api/dispatch', (req, res) => {
   res.setHeader('Cache-Control', 'no-store');
   const parent = typeof req.query.parent === 'string' && req.query.parent ? req.query.parent : null;
-  res.json({ running: dispatches.list({ parent }) });
+  res.json({ running: dispatched.running(terminal.isRunning, { parent }) });
 });
 // #endregion
 
@@ -3473,14 +3505,13 @@ app.get('/api/tasks/all', async (_req, res) => {
 
     const metadata = loadSessionMetadata();
     const { listToSessions } = loadAllTaskMaps();
-    const sessionDirs = readdirSync(TASKS_DIR, { withFileTypes: true })
+    const sessionDirs = (await fs.readdir(TASKS_DIR, { withFileTypes: true }))
       .filter(d => d.isDirectory());
+    const dirTasks = await Promise.all(sessionDirs.map((d) => readTaskDir(path.join(TASKS_DIR, d.name))));
 
     const allTasks = [];
 
-    for (const sessionDir of sessionDirs) {
-      const sessionPath = path.join(TASKS_DIR, sessionDir.name);
-      const taskFiles = readdirSync(sessionPath).filter(f => f.endsWith('.json'));
+    sessionDirs.forEach((sessionDir, i) => {
       const meta = metadata[sessionDir.name] || {};
 
       // For custom task list directories (non-UUID dirs), resolve project from the
@@ -3496,20 +3527,15 @@ app.get('/api/tasks/all', async (_req, res) => {
         }
       }
 
-      for (const file of taskFiles) {
-        try {
-          const task = JSON.parse(readFileSync(path.join(sessionPath, file), 'utf8'));
-          allTasks.push({
-            ...task,
-            sessionId: sessionDir.name,
-            sessionName: getSessionDisplayName(sessionDir.name, meta),
-            project
-          });
-        } catch {
-          // Skip invalid files
-        }
+      for (const { task } of dirTasks[i]) {
+        allTasks.push({
+          ...task,
+          sessionId: sessionDir.name,
+          sessionName: getSessionDisplayName(sessionDir.name, meta),
+          project
+        });
       }
-    }
+    });
 
     res.json(allTasks);
   } catch (error) {
@@ -3519,11 +3545,13 @@ app.get('/api/tasks/all', async (_req, res) => {
 });
 
 const {
+  boardEventsOn,
   enqueueSessionEvent,
   formatReviewSubmitted,
   formatTaskMoved,
   handleSessionEvents,
-  hasSessionListener,
+  hasDoorbell,
+  configureSessionEvents,
 } = require('./lib/session-events');
 app.get('/api/sessions/:sessionId/events', handleSessionEvents);
 
@@ -3557,7 +3585,7 @@ app.post('/api/tasks/:sessionId', async (req, res) => {
 
     // No doorbell here, unlike a move: the user typed this task, so telling their session
     // about it would only repeat what they just said. Dragging it to In Progress rings.
-    await fs.writeFile(path.join(sessionDir, `${id}.json`), JSON.stringify(task, null, 2));
+    await writeTaskFile(path.join(sessionDir, `${id}.json`), task);
     res.json({ success: true, task });
   } catch (error) {
     console.error('Error creating task:', error);
@@ -3585,14 +3613,14 @@ app.put('/api/tasks/:sessionId/:taskId', async (req, res) => {
     if (description !== undefined) task.description = description;
     if (req.body.status !== undefined) task.status = req.body.status;
 
-    await fs.writeFile(taskPath, JSON.stringify(task, null, 2));
+    await writeTaskFile(taskPath, task);
 
     // Ring the session only for a move. The direction has to ride in the line because
     // the write above destroyed the old status -- nothing downstream can recover it, and
     // which way a task moved is what decides whether to start work or stop it.
-    if (task.status !== prevStatus) {
+    if (task.status !== prevStatus && boardEventsEnabled()) {
       // The route param is a task *directory*, which for a shared list or team board is
-      // not a session id -- and the postman polls with its own session id, so an unresolved
+      // not a session id -- and the doorbell polls with its own session id, so an unresolved
       // name would queue the line where nobody drains it.
       const line = formatTaskMoved(taskId, prevStatus, task);
       for (const sid of resolveSessionsForTaskDir(sessionId)) enqueueSessionEvent(sid, line);
@@ -3608,21 +3636,7 @@ app.put('/api/tasks/:sessionId/:taskId', async (req, res) => {
 // A deleted task can't block anything, so drop the dangling reference instead of
 // refusing the delete -- a stale blockedBy id would pin the other task as BLOCKED forever.
 async function deleteTasks(dir, shouldDelete) {
-  let files;
-  try {
-    files = (await fs.readdir(dir)).filter((f) => f.endsWith('.json'));
-  } catch (e) {
-    if (e.code === 'ENOENT') return [];
-    throw e;
-  }
-  const tasks = [];
-  for (const file of files) {
-    try {
-      tasks.push({ file, task: JSON.parse(await fs.readFile(path.join(dir, file), 'utf8')) });
-    } catch (e) {
-      console.error(`Error parsing ${file}:`, e);
-    }
-  }
+  const tasks = await readTaskDir(dir);
   const doomed = tasks.filter((t) => shouldDelete(t));
   const doomedIds = new Set(doomed.map(({ task }) => task.id));
   const strip = (ids) => ids?.filter((id) => !doomedIds.has(id));
@@ -3635,7 +3649,7 @@ async function deleteTasks(dir, shouldDelete) {
         task.blockedBy = strip(task.blockedBy);
         task.blocks = strip(task.blocks);
         if (JSON.stringify(task) === before) return null;
-        return fs.writeFile(path.join(dir, file), JSON.stringify(task, null, 2));
+        return writeTaskFile(path.join(dir, file), task);
       }),
   );
   // Delete the task file
@@ -3831,6 +3845,7 @@ function resolvePreviewPath(rawPath, base) {
 app.post('/api/preview', async (req, res) => {
   try {
     const { path: filePath, sessionId, base } = req.body || {};
+    if (sessionId && !isSafeId(sessionId)) return res.status(400).json({ error: 'Invalid session ID' });
     const abs = resolvePreviewPath(filePath, base);
     if (!abs) return res.status(400).json({ error: 'path is required' });
     // Validate here so the CLI still gets 400/404, but broadcast the path only —
@@ -3852,7 +3867,8 @@ app.post('/api/preview', async (req, res) => {
 app.post('/api/document/link', async (req, res) => {
   try {
     const { path: filePath, sessionId, unlink, open } = req.body || {};
-    if (typeof sessionId !== 'string' || !sessionId) return res.status(400).json({ error: 'sessionId is required' });
+    if (!sessionId) return res.status(400).json({ error: 'sessionId is required' });
+    if (!isSafeId(sessionId)) return res.status(400).json({ error: 'Invalid session ID' });
     const url = linkUrl(filePath);
     const abs = url || resolvePreviewPath(filePath);
     if (!abs) return res.status(400).json({ error: 'path is required' });
@@ -4026,10 +4042,10 @@ const panes = createPaneStore({
     const stamp = panesFileStamp();
     if (stamp === panesStamp) return undefined;
     panesStamp = stamp;
-    try { return JSON.parse(readFileSync(PANES_FILE, 'utf8')); } catch { return null; }
+    return readJsonOrNull(PANES_FILE);
   },
   save: (data) => {
-    writeJsonAtomic(PANES_FILE, data);
+    writeJsonAtomicOrLog(PANES_FILE, data);
     panesStamp = panesFileStamp();
   },
   onChange: (sessionId, layout) => {
@@ -4103,9 +4119,11 @@ app.get('/api/panes/:sessionId', (req, res) => {
 
 app.post('/api/panes/:sessionId', async (req, res) => {
   try {
-    const { target, base, title } = req.body || {};
+    const { target, base, title, kind, show } = req.body || {};
     if (typeof target !== 'string' || !target) throw previewError(400, 'target is required', 'bad_target');
-    res.json(panes.add(req.params.sessionId, { ...(await resolvePaneTarget(target, base)), title }));
+    // A message target is a session log message id, which the board resolves when it shows the pane.
+    const resolved = kind === 'message' ? { kind, target } : await resolvePaneTarget(target, base);
+    res.json(panes.add(req.params.sessionId, { ...resolved, title, show: show === true }));
   } catch (error) {
     paneRouteError(res, error, 'POST /api/panes');
   }
@@ -4140,6 +4158,19 @@ app.get('/api/panes/:sessionId/:paneId/framing', async (req, res) => {
   }
 });
 
+app.patch('/api/panes/:sessionId/:paneId', (req, res) => {
+  try {
+    const { sessionId, paneId } = req.params;
+    const title = req.body?.title;
+    if (typeof title !== 'string') throw previewError(400, 'title must be a string', 'bad_title');
+    const layout = panes.rename(sessionId, paneId, title);
+    if (!layout) throw previewError(404, `No pane ${paneId} in session ${sessionId}`, 'no_pane');
+    res.json({ layout });
+  } catch (error) {
+    paneRouteError(res, error, 'PATCH /api/panes/:paneId');
+  }
+});
+
 app.delete('/api/panes/:sessionId/:paneId', (req, res) => {
   const { sessionId, paneId } = req.params;
   const layout = panes.remove(sessionId, paneId);
@@ -4155,6 +4186,23 @@ app.delete('/api/panes/:sessionId/:paneId', (req, res) => {
 // carries one line, and the file is what each route points at.
 const REVIEW_DIR = path.join(CCK_DIR, 'reviews');
 const REVIEW_KIND_RE = /^[a-z]{1,20}$/;
+
+// `<ts>.pending` holds the doorbell line of a review the mod has not acked yet.
+configureSessionEvents({
+  onDelivered: (entry) => fs.unlink(entry.marker).catch(() => {}),
+  restore: async (sessionId) => {
+    if (!isUUID(sessionId)) return [];
+    const dir = path.join(REVIEW_DIR, sessionId);
+    const names = (await fs.readdir(dir).catch(() => [])).filter((n) => n.endsWith('.pending')).sort();
+    const lines = [];
+    for (const name of names) {
+      const marker = path.join(dir, name);
+      const text = await fs.readFile(marker, 'utf8').catch(() => '');
+      if (text) lines.push({ text, marker });
+    }
+    return lines;
+  },
+});
 const REVIEW_MAX_COMMENTS = 50;
 const REVIEW_MAX_CHARS = 4000;
 
@@ -4223,8 +4271,11 @@ app.post('/api/sessions/:sessionId/review', async (req, res) => {
     await fs.writeFile(file, markdown);
 
     let delivered = null;
-    if (hasSessionListener(sessionId)) {
-      enqueueSessionEvent(sessionId, formatReviewSubmitted(src.items.length, src.label, file));
+    if (boardEventsEnabled() && hasDoorbell(sessionId)) {
+      const line = formatReviewSubmitted(src.items.length, src.label, file);
+      const marker = file.replace(/\.md$/, '.pending');
+      await fs.writeFile(marker, line);
+      enqueueSessionEvent(sessionId, line, { marker });
       delivered = 'doorbell';
     } else if (
       terminal.authorized(req.get('x-terminal-token')) &&
@@ -4284,6 +4335,13 @@ app.use('/api', (_req, res) => {
   res.status(404).json({ error: 'Not found' });
 });
 
+app.use((err, req, res, next) => {
+  if (res.headersSent || !req.path.startsWith('/api/')) return next(err);
+  const status = err.status || 500;
+  if (status >= 500) console.error(`Error in ${req.method} ${req.path}:`, err);
+  res.status(status).json({ error: status >= 500 ? 'Internal error' : err.message });
+});
+
 // Watch for file changes (chokidar handles non-existent paths)
 const watcher = chokidar.watch(TASKS_DIR, {
   persistent: true,
@@ -4498,8 +4556,10 @@ async function cleanupAgentActivity() {
     const now = Date.now();
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
+      const dirPath = path.join(AGENT_ACTIVITY_DIR, entry.name);
+      // Map files are rewritten in place, so the dir mtime does not track their use.
+      if (dirPath === TASK_MAPS_DIR) continue;
       try {
-        const dirPath = path.join(AGENT_ACTIVITY_DIR, entry.name);
         const contents = await fs.readdir(dirPath);
         const stat = await fs.stat(dirPath);
         const age = now - stat.mtimeMs;
@@ -4533,8 +4593,9 @@ async function runRetention() {
     const reviews = await pruneSessionDirs(REVIEW_DIR, opts);
     const contexts = await pruneContextStatus(CONTEXT_STATUS_DIR, opts);
     const wts = worktrees.prune(scan?.dirs);
-    if (markers || layouts || reviews || contexts || wts) {
-      console.log(`[retention] removed ${markers} dispatch markers, ${layouts} pane layouts, ${reviews} reviews, ${contexts} context status files, ${wts} worktrees`);
+    const taskMaps = await pruneTaskMaps(TASK_MAPS_DIR, opts);
+    if (markers || layouts || reviews || contexts || wts || taskMaps) {
+      console.log(`[retention] removed ${markers} dispatch markers, ${layouts} pane layouts, ${reviews} reviews, ${contexts} context status files, ${wts} worktrees, ${taskMaps} task-list mappings`);
     }
   } catch (e) {
     console.warn('[retention] failed:', e.message);
@@ -4561,7 +4622,7 @@ const PREWARM_SLICE_MS = 10;
 // 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));
+const persistSessionCache = () => saveSessionCache((data) => writeJsonAtomicOrLog(SESSION_CACHE_FILE, data));
 let prewarmStarted = false;
 function startPrewarm() {
   if (prewarmStarted) return;
@@ -4595,8 +4656,8 @@ async function prewarmCaches() {
   const onReady = (actualPort) => {
     boardPort = Number(actualPort);
     terminal.setServerUrl(`http://127.0.0.1:${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.
+    // The port is configurable and falls back to a random one when taken, so the doorbell
+    // mod 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}`);
@@ -4637,7 +4698,5 @@ async function prewarmCaches() {
       throw err;
     }
   });
-
-
-// #endregion
 }
+// #endregion