claude-code-kanban 7.20.0 → 7.22.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, rmSync, mkdirSync, renameSync, openSync, readSync, closeSync, realpathSync } = require('node:fs');
+const { existsSync, readdirSync, readFileSync, writeFileSync, statSync, unlinkSync, mkdirSync, openSync, readSync, closeSync, realpathSync } = require('node:fs');
 const _readline = require('node:readline');
 const chokidar = require('chokidar');
 const os = require('node:os');
@@ -67,6 +67,9 @@ 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');
+const { createAddonStore, sampleUrl } = require('./lib/addons');
+const { writeJsonAtomic } = require('./lib/write-json-atomic');
+const { createAddonRunner } = require('./lib/addon-runner');
 const { probeFraming, parseOrigin } = require('./lib/frame-policy');
 const { pickFolder } = require('./lib/folder-dialog');
 const { loadSessionCache, saveSessionCache } = require('./lib/session-cache');
@@ -74,7 +77,7 @@ const { countTaskDir } = require('./lib/task-counts');
 const { readTaskDir } = require('./lib/task-dir');
 const { foldAgentLines } = require('./lib/agent-log');
 const { projectMatcher, normalizeProjectPath, sessionProjectKey } = require('./public/project-match');
-const { getParentVerdict, setParentVerdict } = require('./lib/parent-cache');
+const { getParentVerdict, setParentVerdict, peekParentVerdict } = require('./lib/parent-cache');
 
 if (process.argv.includes("--install") || process.argv.includes("--uninstall")) {
   const { runInstall, runUninstall } = require("./install");
@@ -123,6 +126,7 @@ 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');
 const PANES_FILE = path.join(CCK_DIR, 'panes.json');
+const ADDONS_FILE = path.join(CCK_DIR, 'addons.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');
@@ -149,18 +153,6 @@ const SCRATCHPAD_ROOT = (() => {
 // #endregion
 
 // #region SERVER_STATE
-function writeJsonAtomic(file, obj, mode) {
-  mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-  try {
-    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;
@@ -1562,10 +1554,11 @@ app.get('/api/sessions', async (req, res) => {
     const compactSuppressed = new Set();
     for (const [sid] of sessionsMap) {
       // Cheap pre-gate: only a session with a boundary anchor can be a continuation,
-      // and lookupParentSession reads JSONLs on a cold cache.
-      if (!metadata[sid]?.logicalParentUuid) continue;
-      const parent = lookupParentSession(sid);
-      if (parent.relation !== 'compact' || !sessionsMap.has(parent.parentSessionId)) continue;
+      // and lookupParentSession reads JSONLs on a cold cache. A fork with no boundary
+      // gets its badge only once a verdict exists (the info modal computes one).
+      const parent = metadata[sid]?.logicalParentUuid ? lookupParentSession(sid) : peekParentVerdict(sid);
+      if (parent?.relation === 'fork') sessionsMap.get(sid).forkedFromSessionId = parent.parentSessionId;
+      if (parent?.relation !== 'compact' || !sessionsMap.has(parent.parentSessionId)) continue;
       compactSuppressed.add(parent.parentSessionId);
       sessionsMap.get(sid).continuedFromSessionId = parent.parentSessionId;
     }
@@ -3381,12 +3374,41 @@ app.post('/api/terminal/pick-folder', async (req, res) => {
   }
 });
 
+// A tab whose terminal is off, or whose token died with an earlier server, ignores
+// `session:launched`, so only a tab that claims the session counts as showing it.
+const LAUNCH_CLAIM_MS = 3000;
+const launchClaims = new Map();
+function awaitLaunchClaim(id) {
+  const claimed = new Promise((resolve) => {
+    launchClaims.set(id, resolve);
+    setTimeout(resolve, LAUNCH_CLAIM_MS, false);
+  });
+  return claimed.finally(() => launchClaims.delete(id));
+}
+
+app.post('/api/terminal/launched/:id', (req, res) => {
+  if (!terminal.authorized(req.get('x-terminal-token'))) return res.status(401).json({ error: 'invalid terminal token' });
+  launchClaims.get(req.params.id)?.(true);
+  res.status(204).end();
+});
+
 // The New session dialog's "Stay here": the PTY starts headless and the board keeps its view.
+// `show` is `claude-code-kanban new` from a shell outside the board: a board tab adds its card
+// and attaches, and with no tab to claim it the PTY is ended, because no one would see it.
 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, effort, worktree, prompt } = req.body || {};
-  const started = await terminal.startNew({ id, cwd, name, model, effort, worktree, prompt });
+  const { id, cwd, name, model, effort, worktree, prompt, claudeArgs, show } = req.body || {};
+  if (show && !clients.size) return res.status(409).json({ error: 'no board tab is open' });
+  const started = await terminal.startNew({ id, cwd, name, model, effort, worktree, prompt, extraArgs: claudeArgs });
   if (started.error) return res.status(started.status).json({ error: started.error });
+  if (show) {
+    const claimed = awaitLaunchClaim(started.id);
+    broadcast({ type: 'session:launched', ...started });
+    if (!(await claimed)) {
+      await terminal.end(started.id, terminal.token);
+      return res.status(409).json({ error: 'no open board tab can show the terminal' });
+    }
+  }
   res.status(201).json({ session: started.id, cwd: started.cwd });
 }));
 
@@ -3499,7 +3521,7 @@ const linkedDocs = createLinkedDocStore(jsonFile(LINKED_DOCS_FILE));
 function withDispatchMarker(sessions) {
   return sessions.map((s) => {
     const marker = dispatched.get(s.id);
-    return marker ? { ...s, dispatched: { parent: marker.parent } } : s;
+    return marker ? { ...s, dispatched: { parent: marker.parent, child: marker.child } } : s;
   });
 }
 
@@ -3507,13 +3529,15 @@ function withDispatchMarker(sessions) {
 // TERMINAL_TOKEN_FILE. The started session never holds it.
 app.post('/api/dispatch', terminalRoute(async (req, res) => {
   if (!terminal.authorized(req.get('x-terminal-token'))) return res.status(401).json({ error: 'invalid terminal token' });
-  const { cwd, spec, name, model, worktree, taskList, parent, group, claudeArgs } = req.body || {};
+  const { cwd, spec, name, model, worktree, taskList, parent, child, 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 && !(typeof group === 'string' && group.trim())) return res.status(400).json({ error: 'group must be a group name, path or id' });
+  if (child && !parent) return res.status(400).json({ error: 'child needs a parent session' });
+  if (child && group) return res.status(400).json({ error: 'pass child or group, not both' });
   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 });
+  dispatched.record(started.id, { parent, child: child === true, cwd: started.cwd, name, group, worktree });
   // 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;
@@ -4368,9 +4392,11 @@ 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);
+    const { title, dock } = req.body || {};
+    if (typeof dock !== 'boolean' && typeof title !== 'string') {
+      throw previewError(400, 'title must be a string, or dock a boolean', 'bad_title');
+    }
+    const layout = typeof dock === 'boolean' ? panes.setDock(sessionId, paneId, dock) : panes.rename(sessionId, paneId, title);
     if (!layout) throw previewError(404, `No pane ${paneId} in session ${sessionId}`, 'no_pane');
     res.json({ layout });
   } catch (error) {
@@ -4386,6 +4412,115 @@ app.delete('/api/panes/:sessionId/:paneId', (req, res) => {
 });
 // #endregion
 
+// #region ADDONS
+// Web pages on the dock rail (lib/addons.js). The board fills each URL for its terminal's
+// session, so the routes carry the templates; every change sends one `addon:changed` and the
+// boards refetch.
+const addonRunner = createAddonRunner({ logDir: path.join(CCK_DIR, 'addons') });
+process.on('exit', addonRunner.shutdown);
+const addons = createAddonStore({
+  ...stampedJsonFile(ADDONS_FILE, writeJsonAtomic),
+  onChange: (global) => {
+    addonRunner.retain(global);
+    broadcast({ type: 'addon:changed' });
+  },
+  isOwnOrigin: (url) => isOwnOrigin(url, { boardPort, boardHosts, hubUrl: process.env.HUB_URL }),
+});
+chokidar.watch(ADDONS_FILE, { ignoreInitial: true }).on('all', (event) => {
+  if (event === 'add' || event === 'change') addons.reload();
+});
+
+app.get('/api/addons', (req, res) => {
+  const sessionId = typeof req.query.session === 'string' ? req.query.session : null;
+  res.json(addons.list(sessionId));
+});
+
+app.post('/api/addons', (req, res) => {
+  try {
+    const { scope, url, title, icon, params, run, cwd, key } = req.body || {};
+    if (typeof scope !== 'string' || !scope) throw previewError(400, "scope must be 'global' or a session id", 'bad_scope');
+    // A run command is a command line the board will start, so it needs what dispatch needs.
+    if (run && !terminal.authorized(req.get('x-terminal-token'))) return res.status(401).json({ error: 'invalid terminal token' });
+    const result = addons.add(scope, { url, title, icon, params, run, cwd, key });
+    res.status(result.added ? 201 : 200).json(result);
+  } catch (error) {
+    paneRouteError(res, error, 'POST /api/addons');
+  }
+});
+
+app.patch('/api/addons/:id', (req, res) => {
+  try {
+    const { session, params } = req.body || {};
+    if (typeof session !== 'string' || !session) throw previewError(400, 'session is required', 'bad_scope');
+    const list = addons.setParams(session, req.params.id, params);
+    if (!list) throw previewError(404, `No add-on ${req.params.id} in session ${session}`, 'no_addon');
+    res.json(list);
+  } catch (error) {
+    paneRouteError(res, error, 'PATCH /api/addons/:id');
+  }
+});
+
+app.delete('/api/addons/:id', (req, res) => {
+  const session = typeof req.query.session === 'string' ? req.query.session : null;
+  const removed = addons.remove(session, req.params.id);
+  if (!removed) return res.status(404).json({ error: `No add-on ${req.params.id} here`, code: 'no_addon' });
+  res.json(removed);
+});
+
+app.post('/api/addons/:id/start', async (req, res) => {
+  const entry = addons.getGlobal(req.params.id);
+  if (!entry) return res.status(404).json({ error: `No global add-on ${req.params.id}`, code: 'no_addon' });
+  try {
+    res.json(await addonRunner.ensure(entry));
+  } catch (error) {
+    res.status(500).json({ state: 'failed', error: error.message });
+  }
+});
+
+// The hub's app launcher rows (`launcher.items` in hub-app.json): the global add-ons,
+// with Restart for the ones whose server the board runs.
+const LAUNCHER_ITEMS = '/api/hub/launcher-items';
+app.get(LAUNCHER_ITEMS, async (_req, res) => {
+  const items = await Promise.all(
+    addons.list(null).global.map(async (a) => {
+      let detail = a.url;
+      try {
+        detail = new URL(sampleUrl(a.url)).host;
+      } catch {}
+      return {
+        id: a.id,
+        name: a.title,
+        kind: 'add-on',
+        detail,
+        state: a.run ? await addonRunner.status(a) : '',
+        path: ADDONS_FILE,
+        ops: a.run ? ['restart', 'remove'] : ['remove'],
+      };
+    }),
+  );
+  res.json({ items });
+});
+
+app.post(`${LAUNCHER_ITEMS}/:id/restart`, async (req, res) => {
+  const entry = addons.getGlobal(req.params.id);
+  if (!entry?.run) return res.status(404).json({ error: `No global add-on ${req.params.id} with a run command`, code: 'no_addon' });
+  try {
+    const result = await addonRunner.restart(entry);
+    if (result.state === 'failed' || result.state === 'external') return res.status(409).json(result);
+    broadcast({ type: 'addon:restarted', id: entry.id });
+    res.json({ state: 'running', message: `Restarted ${entry.title}` });
+  } catch (error) {
+    res.status(500).json({ state: 'failed', error: error.message });
+  }
+});
+
+app.post(`${LAUNCHER_ITEMS}/:id/remove`, (req, res) => {
+  const removed = addons.remove(null, req.params.id);
+  if (!removed) return res.status(404).json({ error: `No global add-on ${req.params.id}`, code: 'no_addon' });
+  res.json({ message: `Removed ${removed.addon.title}` });
+});
+// #endregion
+
 // #region REVIEW
 // API: Send review comments on something the board shows (a file preview today) to a
 // session. The source is described, not interpreted, so a new kind of preview needs a
@@ -4820,7 +4955,7 @@ async function cleanupAgentActivity() {
   } catch { /* agent-activity dir may not exist */ }
 }
 
-// Dispatch markers, pane layouts, reviews, attachments, context status and worktrees: see docs/retention.md.
+// Dispatch markers, pane layouts, add-on sessions, reviews, attachments, context status and worktrees: see docs/retention.md.
 async function runRetention() {
   try {
     const scan = await scanTranscripts(PROJECTS_DIR);
@@ -4828,14 +4963,15 @@ async function runRetention() {
     const markers = dispatched.prune(opts);
     const layouts = panes.prune(opts);
     if (layouts) queuePaneFileWatch();
+    const addonSessions = addons.prune(opts);
     const reviews = await pruneSessionDirs(REVIEW_DIR, opts);
     const attachments = await pruneSessionDirs(ATTACHMENTS_DIR, opts);
     const contexts = await pruneContextStatus(CONTEXT_STATUS_DIR, opts);
     const wts = worktrees.prune(scan?.dirs);
     const taskMaps = await pruneTaskMaps(TASK_MAPS_DIR, opts);
     const grouped = expireGroupMembers(scan?.ids);
-    if (markers || layouts || reviews || attachments || contexts || wts || taskMaps || grouped.members) {
-      console.log(`[retention] removed ${markers} dispatch markers, ${layouts} pane layouts, ${reviews} reviews, ${attachments} attachments, ${contexts} context status files, ${wts} worktrees, ${taskMaps} task-list mappings, ${grouped.members} group members, ${grouped.groups} groups`);
+    if (markers || layouts || addonSessions || reviews || attachments || contexts || wts || taskMaps || grouped.members) {
+      console.log(`[retention] removed ${markers} dispatch markers, ${layouts} pane layouts, ${addonSessions} add-on sessions, ${reviews} reviews, ${attachments} attachments, ${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);

package/skill-guides/dispatch.md

@@ -11,11 +11,14 @@ cck sends nothing back. To hear from the session, the spec tells it to `SendMess
 ## Start
 
 ```bash
-claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name> --group <group> --json -- <claude args>
+claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name> (--child | --group <group>) --json -- <claude args>
 ```
 
 - `--name` is the sidebar name and the session's peer name. Kebab-case and unique: `fix-login-redirect`.
-- `--group` names the effort (`auth-refactor`, or a path like `auth-refactor/api`) and shows the session under that sidebar group. Pass it on every dispatch that belongs to the effort; a dispatch without it goes to its project. A group it makes goes when none of its sessions shows as active; an existing group stays.
+- Every dispatch picks its **place** in the sidebar. Ask one question: will its result come back to you?
+  - Yes: `--child`. It is your part of the work (a fix, a review, research you will use). Its card shows under yours, wherever yours is.
+  - No: `--group <group>`. It is separate work the user follows on the board (a handoff, an unrelated task). `<group>` names the effort (`auth-refactor`, or a path like `auth-refactor/api`); pass the same group to each dispatch in that effort. A group it makes goes when none of its sessions shows as active; an existing group stays.
+  - If you cannot tell, ask the user in one line before you start the session.
 - `--spec-file` keeps a long spec out of shell quoting.
 - Everything after `--` goes to `claude` as it is: any flag in `claude --help`, e.g. `-- --permission-mode auto --add-dir ../shared`. Keep each value one shell word of plain characters (no quotes, `%` or control characters); long text belongs in the spec. cck owns the session id, name, model and worktree, so pass those with its own flags.
 - After a cck restart the terminal comes back with `claude --resume <id>` alone, so the args after `--` apply to the first run only.