claude-code-kanban 7.6.1 → 7.8.0

package/server.js

@@ -16,7 +16,6 @@ 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');
-const { oneLine } = require('./lib/one-line');
 const { pluginStatus } = require('./lib/plugin-status');
 const { getAutoCompact } = require('./lib/auto-compact');
 
@@ -49,10 +48,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 { kanbotOn, kanbotModel, createKanbot } = require('./lib/kanbot');
 const { createShowStore, mountShowRoutes, showBodyParser, SHOW_PATH } = require('./lib/show');
-const { readLiveSessions, isPidAlive, isSessionLive } = require('./lib/live-sessions');
+const { readLiveSessions, isPidAlive } = require('./lib/live-sessions');
 const { createProcStats } = require('./lib/proc-stats');
-const { createGroupStore, isGroupName, suggestGroupName } = require('./lib/dispatch-groups');
+const { createUserGroupStore } = require('./lib/user-groups');
+const { createSessionPinStore } = require('./lib/session-pins');
+const { stampedJsonFile } = require('./lib/stamped-json-file');
+const { ownerLinks, moveRecipients } = require('./lib/owner-routing');
+const { parseReviewSource, parseActionBody, formatActionMarkdown } = require('./lib/preview-action');
 const { createDispatchedStore, scanTranscripts, pruneSessionDirs, pruneContextStatus, pruneTaskMaps, retentionMs } = require('./lib/retention');
 const { freshRateLimits } = require('./lib/rate-limits');
 const { createWorktreeStore } = require('./lib/worktrees');
@@ -66,7 +70,7 @@ 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 { projectMatcher, normalizeProjectPath, sessionProjectKey } = require('./public/project-match');
 const { getParentVerdict, setParentVerdict } = require('./lib/parent-cache');
 
 if (process.argv.includes("--install") || process.argv.includes("--uninstall")) {
@@ -110,7 +114,7 @@ const CCK_DIR = path.join(CLAUDE_DIR, '.cck');
 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 USER_GROUPS_FILE = path.join(CCK_DIR, 'groups.json');
 const DISPATCHED_FILE = path.join(CCK_DIR, 'dispatched.json');
 const WORKTREES_FILE = path.join(CCK_DIR, 'worktrees.json');
 const LINKED_DOCS_FILE = path.join(CCK_DIR, 'linked-docs.json');
@@ -141,15 +145,6 @@ const SCRATCHPAD_ROOT = (() => {
 // #endregion
 
 // #region SERVER_STATE
-// Server-side pin mirror (UI authoritative, server stores latest pushed state for CLI queries).
-function readPins() {
-  try {
-    const obj = JSON.parse(readFileSync(PINS_FILE, 'utf8'));
-    if (obj && typeof obj === 'object' && !Array.isArray(obj)) return obj;
-  } catch (_) {}
-  return {};
-}
-
 function writeJsonAtomic(file, obj, mode) {
   mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
@@ -202,9 +197,7 @@ const jsonFile = (file) => ({
   save: (data) => writeJsonAtomicOrLog(file, data),
 });
 
-function writePins(pins) {
-  writeJsonAtomic(PINS_FILE, pins);
-}
+const sessionPins = createSessionPinStore(stampedJsonFile(PINS_FILE, writeJsonAtomic));
 
 // 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
@@ -320,6 +313,16 @@ function boardEventsEnabled() {
   return cachedByMtime(cckConfigCache, 'boardEvents', CCK_CONFIG_FILE,
     () => boardEventsOn(readCckConfig()), boardEventsOn(null));
 }
+function kanbotEnabled() {
+  return cachedByMtime(cckConfigCache, 'kanbot', CCK_CONFIG_FILE,
+    () => kanbotOn(readCckConfig()), kanbotOn(null));
+}
+function kanbotModelSetting() {
+  return cachedByMtime(cckConfigCache, 'kanbotModel', CCK_CONFIG_FILE,
+    () => kanbotModel(readCckConfig()), kanbotModel(null));
+}
+// Kanbot's transcripts all land in one project folder, which the board never lists (docs/kanbot.md).
+const kanbot = createKanbot({ cckDir: CCK_DIR, projectsDir: PROJECTS_DIR });
 
 // approvals.json predates config.json (and was opt-in). Fold it into
 // config.json once so an existing opt-in keeps its tuning, then drop it.
@@ -934,7 +937,7 @@ function loadSessionMetadata() {
     }
 
     const projectDirs = readdirSync(PROJECTS_DIR, { withFileTypes: true })
-      .filter(d => d.isDirectory());
+      .filter(d => d.isDirectory() && !kanbot.isOwnProjectDirName(d.name));
 
     for (const projectDir of projectDirs) {
       const projectPath = path.join(PROJECTS_DIR, projectDir.name);
@@ -1263,12 +1266,13 @@ app.get('/api/sessions', async (req, res) => {
     const limitParam = req.query.limit || '20';
     const limit = limitParam === 'all' ? null : parseInt(limitParam, 10);
 
-    const pinnedParam = req.query.pinned;
+    // `pinned=` from a board page loaded before the server kept pins is ignored.
     const includeIds = req.query.include ? new Set(req.query.include.split(',').filter(Boolean)) : new Set();
-    const pinnedIds = pinnedParam ? new Set(pinnedParam.split(',').filter(Boolean)) : new Set();
+    const pins = req.query.pins === 'off' ? {} : sessionPins.state().pins;
+    const pinnedIds = new Set(Object.keys(pins));
     for (const id of includeIds) pinnedIds.add(id);
     const activeFilter = req.query.filter === 'active';
-    const terminalIds = activeFilter ? new Set(terminal.ids()) : new Set();
+    const terminalIds = new Set(terminal.ids());
 
     const metadata = loadSessionMetadata();
     const sessionsMap = new Map();
@@ -1524,6 +1528,9 @@ app.get('/api/sessions', async (req, res) => {
       } catch (_) {}
     }
 
+    // Task dirs and agent-activity name Kanbot's sessions too.
+    for (const sid of sessionsMap.keys()) if (kanbot.isOwnSession(sid)) sessionsMap.delete(sid);
+
     // Correlate plan sessions with their implementation sessions (same slug)
     const slugGroups = new Map();
     for (const [_sid, session] of sessionsMap) {
@@ -1589,20 +1596,16 @@ app.get('/api/sessions', async (req, res) => {
       }));
     }
 
-    // Server-side activity filter (mirrors the client predicate in public/app.js).
-    // Pinned IDs bypass — they should always be in the response.
-    if (activeFilter) {
-      const isActive = (s) =>
-        s.hasMessages && (
-          (!s.sharedTaskList && (s.pending > 0 || s.inProgress > 0))
-          || s.hasActiveAgents
-          || s.hasWaitingForUser
-          || s.hasRecentActivity
-        );
-      for (const [id, s] of sessionsMap) {
-        if (pinnedIds.has(id) || terminalIds.has(id)) continue;
-        if (!isActive(s)) sessionsMap.delete(id);
-      }
+    // The sidebar's Active rule (getFilteredSessions in public/app.js); the CLI reads `active`
+    // instead of keeping its own copy. Pinned IDs bypass the filter.
+    for (const [id, s] of sessionsMap) {
+      s.active = terminalIds.has(id) || !!(s.hasMessages && (
+        (!s.sharedTaskList && (s.pending > 0 || s.inProgress > 0))
+        || s.hasActiveAgents
+        || s.hasWaitingForUser
+        || s.hasRecentActivity
+      ));
+      if (activeFilter && !s.active && !pinnedIds.has(id)) sessionsMap.delete(id);
     }
 
     // Convert map to array and sort by most recently modified
@@ -1611,7 +1614,7 @@ app.get('/api/sessions', async (req, res) => {
 
     // Apply project filter before limit so the limit is per-project
     const projectFilter = req.query.project;
-    // `include` is narrower than `pinned`: pinned rows survive the limit but still obey
+    // `include` is narrower than a pin: pinned rows survive the limit but still obey
     // the project filter, because pinning is a preference and the filter is an intent.
     // 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.
@@ -1631,6 +1634,7 @@ app.get('/api/sessions', async (req, res) => {
     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));
+    res.setHeader('X-Total-Count', String(sessions.length));
     // Apply limit if specified, but always include pinned sessions
     if (paged) {
       const top = sessions.slice(0, limit);
@@ -1639,17 +1643,21 @@ app.get('/api/sessions', async (req, res) => {
       sessions = [...top, ...missingPinned];
     }
 
-    // Loop info can mean a full read of the transcript, so only the rows sent pay for it.
+    // Loop info can mean a full read of the transcript, so only the rows sent pay for it, and
+    // `lite=1` (the CLI's group list, which only counts and names sessions) skips it.
     // Same for autoCompact: up to 3 settings stats per call.
+    const lite = req.query.lite === '1';
     const autoCompactByProject = new Map();
     for (const s of sessions) {
+      s.pin = pins[s.id] || null;
+      if (lite) continue;
       s.loopInfo = getLoopInfoSummary(s);
       if (!s.contextStatus) continue;
       if (!autoCompactByProject.has(s.project)) autoCompactByProject.set(s.project, getAutoCompact(CLAUDE_DIR, s.project));
       s.autoCompact = autoCompactByProject.get(s.project);
     }
 
-    res.json(withDispatchPlacement(sessions));
+    res.json(withDispatchMarker(sessions));
     startPrewarm();
   } catch (error) {
     console.error('Error listing sessions:', error);
@@ -1687,7 +1695,7 @@ app.get('/api/sessions/known', (_req, res) => {
       known.set(id, { id, project: meta.project || null, name: getSessionDisplayName(id, meta) });
     }
     const add = (id, project = null) => {
-      if (!known.has(id)) known.set(id, { id, project, name: null });
+      if (!known.has(id) && !kanbot.isOwnSession(id)) known.set(id, { id, project, name: null });
     };
     for (const dir of [TASKS_DIR, AGENT_ACTIVITY_DIR]) {
       if (!existsSync(dir)) continue;
@@ -1749,24 +1757,19 @@ app.get('/api/projects', (_req, res) => {
   res.json(projects);
 });
 
+const ownerRoutingInputs = () => ({
+  dispatched,
+  listToSessions: loadAllTaskMaps().listToSessions,
+  metadata: loadSessionMetadata,
+});
+
 // API: Get tasks for a session
-// A card's owner links to the session of that name that the list's session dispatched.
-// A name two of its dispatched sessions share gets no link.
 function addOwnerSessions(tasks, listIdOf) {
   const lists = new Set(tasks.filter((t) => t.owner).map(listIdOf));
   if (!lists.size) return;
-  const childIds = [...dispatched.entries()].filter(([, e]) => lists.has(e.parent));
-  if (!childIds.length) return;
-  const metadata = loadSessionMetadata();
-  const children = new Map();
-  for (const [id, { parent }] of childIds) {
-    const name = metadata[id]?.agentName;
-    if (!name) continue;
-    const key = `${parent}\n${name}`;
-    children.set(key, children.has(key) ? null : id);
-  }
+  const linkOf = ownerLinks(lists, ownerRoutingInputs());
   for (const t of tasks) {
-    const id = t.owner && children.get(`${listIdOf(t)}\n${t.owner}`);
+    const id = t.owner && linkOf(listIdOf(t), t.owner);
     if (id) t.ownerSessionId = id;
   }
 }
@@ -3276,19 +3279,17 @@ app.get('/api/config', (_req, res) => {
     memoryUrl: MEMORY_URL,
     scratchAvailable: !!whichSync('scratch'),
     terminal: terminal.clientConfig(),
+    kanbot: kanbotEnabled(),
   });
 });
 
 // #endregion
 
 // #region TERMINAL
-// A new session may start only in a folder the user has already worked in, or one they
-// chose in the native dialog during this run. Anything else would let a page script pick
-// the directory claude runs in.
-const pickedFolders = new Set();
+// Any existing folder is allowed: the terminal token already opens a shell PTY, so a folder
+// list would block valid use without protecting anything.
 function isAllowedFolder(dir) {
-  const known = pickedFolders.has(dir) || Object.values(loadSessionMetadata()).some((m) => m.project === dir);
-  try { return known && statSync(dir).isDirectory(); } catch { return false; }
+  try { return statSync(dir).isDirectory(); } catch { return false; }
 }
 
 // Restore runs before the first full metadata scan, so until that scan has run a session's
@@ -3300,7 +3301,7 @@ function resolveSessionFolder(id) {
   }
   try {
     for (const dir of readdirSync(PROJECTS_DIR, { withFileTypes: true })) {
-      if (!dir.isDirectory()) continue;
+      if (!dir.isDirectory() || kanbot.isOwnProjectDirName(dir.name)) continue;
       const jsonlPath = path.join(PROJECTS_DIR, dir.name, `${id}.jsonl`);
       if (!existsSync(jsonlPath)) continue;
       let indexProject = null;
@@ -3343,7 +3344,7 @@ const terminal = createTerminalClient({
   // project dir it started in, and cwd drifts into subdirectories.
   resolveCwd: resolveSessionFolder,
   isAllowedFolder,
-  onChange: () => broadcast({ type: 'terminals-update', ids: terminal.ids() }),
+  onChange: () => broadcast({ type: 'terminals-update', ids: terminal.ids(), awaitingTrust: terminal.awaitingTrust() }),
   onExit: (id) => {
     if (dispatched.get(id)) broadcast({ type: 'dispatch-update' });
   },
@@ -3365,7 +3366,6 @@ app.post('/api/terminal/pick-folder', async (req, res) => {
   folderDialogOpen = true;
   try {
     const dir = await pickFolder(whichSync, { start: req.body?.start });
-    if (dir) pickedFolders.add(dir);
     res.json({ path: dir });
   } catch (e) {
     res.status(501).json({ error: e.message });
@@ -3377,8 +3377,8 @@ app.post('/api/terminal/pick-folder', async (req, res) => {
 // The New session dialog's "Stay here": the PTY starts headless and the board keeps its view.
 app.post('/api/terminal/start', terminalRoute(async (req, res) => {
   if (!terminal.authorized(req.get('x-terminal-token'))) return res.status(401).json({ error: 'invalid terminal token' });
-  const { id, cwd, name, model, worktree, prompt } = req.body || {};
-  const started = await terminal.startNew({ id, cwd, name, model, worktree, prompt });
+  const { id, cwd, name, model, effort, worktree, prompt } = req.body || {};
+  const started = await terminal.startNew({ id, cwd, name, model, effort, worktree, prompt });
   if (started.error) return res.status(started.status).json({ error: started.error });
   res.status(201).json({ session: started.id, cwd: started.cwd });
 }));
@@ -3386,7 +3386,14 @@ app.post('/api/terminal/start', terminalRoute(async (req, res) => {
 // The hub's eviction check reads this to keep a pool with live PTYs alive.
 app.get('/api/terminals', terminalRoute(async (_req, res) => {
   res.setHeader('Cache-Control', 'no-store');
-  res.json({ sessions: await terminal.sessions() });
+  const sessions = await terminal.sessions();
+  res.json({
+    sessions: sessions.map((t) => {
+      if (t.id === kanbot.ptyId) return { ...t, kanbot: true };
+      const marker = dispatched.get(t.id);
+      return marker ? { ...t, dispatched: { parent: marker.parent || null } } : t;
+    }),
+  });
 }));
 
 const terminalProcStats = createProcStats();
@@ -3404,6 +3411,7 @@ app.delete('/api/terminals/:id', terminalRoute(async (req, res) => {
   if (err === 'auth') return res.status(401).json({ error: 'invalid terminal token' });
   if (err === 'not-found') return res.status(404).json({ error: 'no such terminal' });
   res.status(204).end();
+  broadcast({ type: 'terminal:ended', id: req.params.id });
 }));
 
 const show = createShowStore({
@@ -3446,26 +3454,12 @@ app.get('/vendor/xterm/:file', (req, res) => {
 // #region DISPATCH
 const dispatched = createDispatchedStore(jsonFile(DISPATCHED_FILE));
 
-const dispatchGroups = createGroupStore({
-  ...jsonFile(DISPATCH_GROUPS_FILE),
-  isAlive: (id) => terminal.isRunning(id) || isSessionLive(loadLiveSessions(), id),
-  pinnedIds: () => new Set(Object.keys(readPins())),
-});
-
 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) {
-  const groups = dispatchGroups.snapshot();
+function withDispatchMarker(sessions) {
   return sessions.map((s) => {
-    const dispatchGroup = groups.get(s.id);
     const marker = dispatched.get(s.id);
-    if (!dispatchGroup && !marker) return s;
-    return {
-      ...s,
-      dispatchGroup,
-      dispatched: marker ? { parent: marker.parent } : undefined,
-    };
+    return marker ? { ...s, dispatched: { parent: marker.parent } } : s;
   });
 }
 
@@ -3476,16 +3470,31 @@ app.post('/api/dispatch', terminalRoute(async (req, res) => {
   const { cwd, spec, name, model, worktree, taskList, parent, group, claudeArgs } = req.body || {};
   if (typeof spec !== 'string' || !spec.trim()) return res.status(400).json({ error: 'spec is required' });
   if (parent != null && !(typeof parent === 'string' && isUUID(parent))) return res.status(400).json({ error: 'invalid parent' });
-  if (group != null && !isGroupName(group)) {
-    return res.status(400).json({ error: `group must be kebab-case, e.g. ${suggestGroupName(group) || 'my-group'}` });
-  }
+  if (group != null && !(typeof group === 'string' && group.trim())) return res.status(400).json({ error: 'group must be a group name, path or id' });
   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 });
   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]);
+  // Joined before dispatch-update, so the board places the session from its first frame. The
+  // starter stays where it is: moving it would jump it under the user.
+  let joined = null;
+  let groupError;
+  if (group) {
+    try {
+      userGroups.reload();
+      joined = userGroups.joinDispatch(group, started.id);
+      broadcast({ type: 'group:changed', rev: joined.rev });
+    } catch (e) {
+      groupError = e.message;
+    }
+  }
   broadcast({ type: 'dispatch-update' });
-  res.status(201).json({ session: started.id, cwd: started.cwd, group: group || null });
+  res.status(201).json({
+    session: started.id,
+    cwd: started.cwd,
+    group: joined?.path ?? null,
+    ...(joined ? { groupId: joined.group, transient: joined.transient } : {}),
+    ...(groupError ? { groupError } : {}),
+  });
 }));
 
 app.get('/api/dispatch', (req, res) => {
@@ -3495,6 +3504,45 @@ app.get('/api/dispatch', (req, res) => {
 });
 // #endregion
 
+// #region KANBOT
+function kanbotRoute(fn) {
+  return terminalRoute(async (req, res) => {
+    if (!kanbotEnabled()) return res.status(404).json({ error: 'kanbot is turned off in .cck/config.json' });
+    return fn(req, res);
+  });
+}
+
+const kanbotState = () => ({ ptyId: kanbot.ptyId, sessionId: kanbot.sessionId });
+
+// After /exit the PTY lives on as a plain shell, so it is ended and the chat resumed in a new one.
+async function ensureKanbot() {
+  if (kanbot.ptyId && terminal.isRunning(kanbot.ptyId)) {
+    const row = (await terminal.sessions()).find((t) => t.id === kanbot.ptyId);
+    if (row && !row.claudeExited) return null;
+    if (row) await terminal.end(kanbot.ptyId, terminal.token);
+  }
+  const started = await terminal.startNew(kanbot.startSpec({
+    model: kanbotModelSetting(),
+    boardUrl: `http://127.0.0.1:${boardPort}`,
+  }));
+  if (started.error) return started;
+  kanbot.ptyId = started.id;
+  kanbot.own(started.id);
+  return null;
+}
+
+// Two opens at once would start two claude processes on the same transcript.
+let kanbotStarting = null;
+
+app.post('/api/kanbot/start', kanbotRoute(async (req, res) => {
+  if (!terminal.authorized(req.get('x-terminal-token'))) return res.status(401).json({ error: 'invalid terminal token' });
+  kanbotStarting ||= ensureKanbot().finally(() => { kanbotStarting = null; });
+  const failed = await kanbotStarting;
+  if (failed) return res.status(failed.status).json({ error: failed.error });
+  res.json(kanbotState());
+}));
+// #endregion
+
 // #region TASK_ROUTES
 // API: Get all tasks across all sessions
 app.get('/api/tasks/all', async (_req, res) => {
@@ -3548,6 +3596,7 @@ const {
   boardEventsOn,
   enqueueSessionEvent,
   formatReviewSubmitted,
+  formatActionSubmitted,
   formatTaskMoved,
   handleSessionEvents,
   hasDoorbell,
@@ -3577,7 +3626,6 @@ app.post('/api/tasks/:sessionId', async (req, res) => {
       id,
       subject,
       description: (req.body.description || '').trim(),
-      activeForm: subject,
       status: 'pending',
       blocks: [],
       blockedBy: [],
@@ -3623,7 +3671,9 @@ app.put('/api/tasks/:sessionId/:taskId', async (req, res) => {
       // 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);
+      const recipients =
+        moveRecipients(sessionId, task.owner, ownerRoutingInputs()) ?? resolveSessionsForTaskDir(sessionId);
+      for (const sid of recipients) enqueueSessionEvent(sid, line);
     }
 
     res.json({ success: true, task });
@@ -3907,6 +3957,9 @@ app.get('/api/session/resolve', (req, res) => {
       const m = metadata[idArg];
       return res.json({ id: idArg, customTitle: m?.customTitle || null });
     }
+    // A session cck just dispatched has no transcript yet, and its starter groups it at once.
+    const started = dispatched.get(idArg);
+    if (started) return res.json({ id: idArg, customTitle: started.name || null });
     const matches = ids.filter(id => id.startsWith(idArg));
     if (matches.length === 0) return res.status(404).json({ matches: [] });
     if (matches.length > 1) {
@@ -3934,36 +3987,136 @@ app.post('/api/session/open', async (req, res) => {
   }
 });
 
-app.post('/api/session/pin', async (req, res) => {
-  try {
-    const { id, state } = req.body || {};
-    if (!id || typeof id !== 'string') return res.status(400).json({ error: 'id is required' });
-    if (!['none', 'pinned', 'sticky'].includes(state)) {
-      return res.status(400).json({ error: 'state must be none|pinned|sticky' });
-    }
-    const pins = readPins();
-    if (state === 'none') delete pins[id];
-    else pins[id] = state;
-    writePins(pins);
-    broadcast({ type: 'session:pin', id, state });
-    res.json({ success: true, id, state });
-  } catch (error) {
-    console.error('Error in /api/session/pin:', error);
-    res.status(500).json({ error: error.message || 'Failed' });
+// #region SESSION_PINS
+function broadcastPins(changed) {
+  for (const { id, state } of changed) broadcast({ type: 'session:pin', id, state });
+}
+
+// Another board on this config dir wrote the file. The reload in each route covers a write that
+// lands before the watcher fires.
+chokidar.watch(PINS_FILE, { ignoreInitial: true }).on('all', (event) => {
+  if (event === 'add' || event === 'change') broadcastPins(sessionPins.reload());
+});
+
+function pinsReply() {
+  const { pins } = sessionPins.state();
+  return { pins, items:Object.entries(pins).map(([id, state]) => ({ id, state })) };
+}
+
+function pinRoute(fn) {
+  return (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    broadcastPins(sessionPins.reload());
+    res.json(fn(req.body || {}));
+  };
+}
+
+app.post('/api/session/pin', pinRoute(({ ids, state }) => {
+  broadcastPins(sessionPins.set(ids, state));
+  return { success: true, ids, state };
+}));
+
+app.post('/api/session/pins/import', pinRoute((b) => {
+  broadcastPins(sessionPins.importLocal(b));
+  return pinsReply();
+}));
+
+app.get('/api/session/pins', pinRoute(() => pinsReply()));
+// #endregion
+
+// #region USER_GROUPS
+const userGroups = createUserGroupStore(stampedJsonFile(USER_GROUPS_FILE, writeJsonAtomic));
+// The watcher tells this board's pages about another board's write; the reload in each route
+// covers a write that lands before the watcher fires.
+chokidar.watch(USER_GROUPS_FILE, { ignoreInitial: true }).on('all', (event) => {
+  if ((event === 'add' || event === 'change') && userGroups.reload()) {
+    broadcast({ type: 'group:changed', rev: userGroups.state().rev });
   }
 });
 
-app.get('/api/session/pins', (_req, res) => {
+// A 409 is a stale rev and carries the current state, so the board needs no second read.
+function groupRoute(fn) {
+  return (req, res, next) => {
+    userGroups.reload();
+    const before = userGroups.state().rev;
+    let out;
+    try {
+      out = fn(req.body || {}, req.params);
+    } catch (e) {
+      if (e.status === 409) return res.status(409).json({ error: e.message, ...userGroups.state() });
+      return next(e);
+    }
+    res.json(out);
+    if (out.rev !== before) broadcast({ type: 'group:changed', rev: out.rev });
+  };
+}
+
+app.get('/api/groups', (_req, res) => {
   res.setHeader('Cache-Control', 'no-store');
-  try {
-    const pins = readPins();
-    const items = Object.entries(pins).map(([id, state]) => ({ id, state }));
-    res.json({ pins, items });
-  } catch (error) {
-    console.error('Error in GET /api/session/pins:', error);
-    res.status(500).json({ error: error.message || 'Failed' });
-  }
+  userGroups.reload();
+  res.json(userGroups.state());
 });
+app.post('/api/groups', groupRoute((b) => userGroups.create(b)));
+app.put('/api/groups', groupRoute((b) => userGroups.replace(b)));
+app.post('/api/groups/import', groupRoute((b) => userGroups.importLocal(b)));
+app.post('/api/groups/ungroup', groupRoute((b) => userGroups.ungroup(b)));
+app.patch('/api/groups/:id', groupRoute((b, p) => userGroups.update(p.id, b)));
+app.delete('/api/groups/:id', groupRoute((_b, p) => userGroups.remove(p.id)));
+app.put('/api/groups/:id/members', groupRoute((b, p) => userGroups.place(p.id, b)));
+app.post('/api/groups/path', groupRoute((b) => userGroups.createPath(b.path, b.transient === true)));
+app.post('/api/groups/rename', groupRoute((b) => userGroups.rename(b.group, b.name)));
+app.post('/api/groups/remove', groupRoute((b) => userGroups.removeByKey(b.group)));
+app.post('/api/groups/prune', groupRoute((b) => {
+  const known = loadSessionMetadata();
+  return userGroups.prune({ dryRun: b.dryRun === true, isLive: liveGroupMember((id) => !!known[id]) });
+}));
+// `keep` is the ids of `/api/sessions?filter=active&limit=all`: the Active rule lives in that route.
+// `hide` is the ids dismissed on the board: hidden there even while their terminal runs, unless pinned.
+app.post('/api/groups/clean', groupRoute((b) => {
+  if (!Array.isArray(b.keep)) throw previewError(400, 'keep must be an array of session ids');
+  const keep = new Set(b.keep);
+  const hide = new Set(Array.isArray(b.hide) ? b.hide : []);
+  const pins = sessionPins.state().pins;
+  const live = liveGroupMember((id) => keep.has(id));
+  const isVisible = (m) => (Object.hasOwn(pins, m.ref) || !hide.has(m.ref)) && live(m);
+  return userGroups.clean({ group: b.group ?? null, dryRun: b.dryRun === true, isVisible });
+}));
+
+// A session that runs in the terminal or is still starting has no transcript yet.
+function liveGroupMember(isKnown) {
+  const live = new Set([...terminal.ids(), ...Object.keys(sessionPins.state().pins)]);
+  return (m) => m.type !== 'session' || isKnown(m.ref) || live.has(m.ref);
+}
+
+// Members dead in the previous sweep too, which is the grace period: a member has no timestamp.
+let groupMembersDead = new Set();
+function expireGroupMembers(known) {
+  if (!known) return { members: 0, groups: 0 };
+  const isLive = liveGroupMember((id) => known.has(id));
+  const dead = new Set();
+  userGroups.reload();
+  const out = userGroups.expire((m) => {
+    if (isLive(m)) return false;
+    dead.add(m.ref);
+    return groupMembersDead.has(m.ref);
+  });
+  groupMembersDead = dead;
+  if (out.members) broadcast({ type: 'group:changed', rev: out.rev });
+  return out;
+}
+// `with` names another session; its project is keyed as the board keys it, by the worktree's repo.
+function groupPeer(id) {
+  const meta = loadSessionMetadata()[id];
+  if (!meta) throw previewError(404, `no session ${id}`);
+  return {
+    ref: id,
+    project: sessionProjectKey({ project: meta.project, worktree: worktrees.resolve(meta.project) }),
+    name: getSessionDisplayName(id, meta) || `Session ${id.slice(0, 8)}`,
+  };
+}
+app.post('/api/sessions/:id/group', groupRoute((b, p) =>
+  userGroups.groupSession(p.id, { ...b, peer: typeof b.with === 'string' ? groupPeer(b.with) : undefined })));
+// #endregion
 
 app.get('/api/preview', async (req, res) => {
   const abs = resolvePreviewPath(req.query.path, req.query.base);
@@ -4185,7 +4338,6 @@ app.delete('/api/panes/:sessionId/:paneId', (req, res) => {
 // client change only. The batch is always written to a file: the doorbell is lossy and
 // 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({
@@ -4208,10 +4360,7 @@ const REVIEW_MAX_CHARS = 4000;
 
 function parseReviewBody(body) {
   const { source, comments } = body || {};
-  if (!source || !REVIEW_KIND_RE.test(source.kind)) throw previewError(400, 'source.kind is required');
-  // The label is pasted into the terminal; an ESC could end bracketed paste and submit text.
-  const label = oneLine(source.label, 200);
-  if (!label) throw previewError(400, 'source.label is required');
+  const src = parseReviewSource(source);
   if (!Array.isArray(comments) || !comments.length || comments.length > REVIEW_MAX_COMMENTS) {
     throw previewError(400, `comments must hold 1 to ${REVIEW_MAX_COMMENTS} items`);
   }
@@ -4227,8 +4376,14 @@ function parseReviewBody(body) {
     selector: code(c?.selector, 500),
   }));
   if (items.some((c) => !c.comment)) throw previewError(400, 'every comment needs text');
-  const locate = oneLine(source.locate, 600) || null;
-  return { kind: source.kind, label, path: source.kind === 'file' ? source.path : null, locate, items };
+  return { ...src, items };
+}
+
+async function resolveReviewSource(src) {
+  if (src.kind !== 'file') return;
+  src.path = resolvePreviewPath(src.path);
+  if (!src.path) throw previewError(400, 'source.path is required for a file');
+  await statFileTarget(src.path);
 }
 
 function formatReviewMarkdown(src, items) {
@@ -4258,32 +4413,13 @@ app.post('/api/sessions/:sessionId/review', async (req, res) => {
     const sessionId = req.params.sessionId;
     if (!isUUID(sessionId)) return res.status(400).json({ error: 'invalid session id' });
     const src = parseReviewBody(req.body);
-    if (src.kind === 'file') {
-      src.path = resolvePreviewPath(src.path);
-      if (!src.path) return res.status(400).json({ error: 'source.path is required for a file' });
-      await statFileTarget(src.path);
-    }
-
+    await resolveReviewSource(src);
     const markdown = formatReviewMarkdown(src, src.items);
-    const dir = path.join(REVIEW_DIR, sessionId);
-    await fs.mkdir(dir, { recursive: true });
-    const file = path.join(dir, `${Date.now()}.md`);
-    await fs.writeFile(file, markdown);
-
-    let delivered = null;
-    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')) &&
-      terminal.isRunning(sessionId) &&
-      !isWaitingOnUser(sessionId)
-    ) {
-      if (await terminal.paste(sessionId, `Address my review comments on ${src.label}: ${file}`)) delivered = 'terminal';
-    }
+    const file = await writeReviewFile(sessionId, markdown);
+    const delivered = await deliverReviewFile(req, sessionId, file, {
+      line: formatReviewSubmitted(src.items.length, src.label, file),
+      paste: `Address my review comments on ${src.label}: ${file}`,
+    });
     res.json({ delivered, file, markdown });
   } catch (error) {
     if (!error.status) console.error('Error in POST /api/sessions/:id/review:', error);
@@ -4291,6 +4427,53 @@ app.post('/api/sessions/:sessionId/review', async (req, res) => {
   }
 });
 
+// A button or form in an HTML preview, sent by the board after the user's click. The file goes in
+// REVIEW_DIR, so a review's restore and retention cover it.
+app.post('/api/sessions/:sessionId/action', async (req, res) => {
+  try {
+    const sessionId = req.params.sessionId;
+    if (!isUUID(sessionId)) return res.status(400).json({ error: 'invalid session id' });
+    const act = parseActionBody(req.body);
+    await resolveReviewSource(act.src);
+    const markdown = formatActionMarkdown(act);
+    const file = await writeReviewFile(sessionId, markdown);
+    const delivered = await deliverReviewFile(req, sessionId, file, {
+      line: formatActionSubmitted(act.action, act.src.label, file),
+      paste: `Act on my answer "${act.action}" on ${act.src.label}: ${file}`,
+    });
+    res.json({ delivered, file, markdown });
+  } catch (error) {
+    if (!error.status) console.error('Error in POST /api/sessions/:id/action:', error);
+    res.status(error.status || 500).json({ error: error.message || 'Action failed' });
+  }
+});
+
+async function writeReviewFile(sessionId, markdown) {
+  const dir = path.join(REVIEW_DIR, sessionId);
+  await fs.mkdir(dir, { recursive: true });
+  const file = path.join(dir, `${Date.now()}.md`);
+  await fs.writeFile(file, markdown);
+  return file;
+}
+
+async function deliverReviewFile(req, sessionId, file, { line, paste }) {
+  if (boardEventsEnabled() && hasDoorbell(sessionId)) {
+    const marker = file.replace(/\.md$/, '.pending');
+    await fs.writeFile(marker, line);
+    enqueueSessionEvent(sessionId, line, { marker });
+    return 'doorbell';
+  }
+  if (
+    terminal.authorized(req.get('x-terminal-token')) &&
+    terminal.isRunning(sessionId) &&
+    !isWaitingOnUser(sessionId) &&
+    (await terminal.paste(sessionId, paste))
+  ) {
+    return 'terminal';
+  }
+  return null;
+}
+
 // #endregion
 
 // #region SSE
@@ -4339,7 +4522,7 @@ 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 });
+  res.status(status).json({ error: status >= 500 && !err.expose ? 'Internal error' : err.message });
 });
 
 // Watch for file changes (chokidar handles non-existent paths)
@@ -4428,6 +4611,7 @@ const projectsWatcher = chokidar.watch(PROJECTS_DIR, {
 
 projectsWatcher.on('all', (event, filePath) => {
   if (event !== 'add' && event !== 'change' && event !== 'unlink') return;
+  if (kanbot.isOwnPath(filePath)) return kanbot.onTranscript(filePath, event);
   if (filePath.endsWith('.jsonl')) {
     if (event === 'unlink') {
       loopInfoStateByPath.delete(filePath);
@@ -4594,8 +4778,9 @@ async function runRetention() {
     const contexts = await pruneContextStatus(CONTEXT_STATUS_DIR, opts);
     const wts = worktrees.prune(scan?.dirs);
     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`);
+    const grouped = expireGroupMembers(scan?.ids);
+    if (markers || layouts || reviews || contexts || wts || taskMaps || grouped.members) {
+      console.log(`[retention] removed ${markers} dispatch markers, ${layouts} pane layouts, ${reviews} reviews, ${contexts} context status files, ${wts} worktrees, ${taskMaps} task-list mappings, ${grouped.members} group members, ${grouped.groups} groups`);
     }
   } catch (e) {
     console.warn('[retention] failed:', e.message);