claude-code-kanban 7.21.0 → 7.22.0

package/public/index.html

@@ -379,6 +379,8 @@
           </div>
           <div id="terminal-host" class="terminal-host">
             <section id="show-card" class="show-card" aria-label="Show overlay"></section>
+            <section id="dock-addon" class="dock-addon" aria-label="Add-on" hidden></section>
+            <nav id="dock-rail" class="dock-rail" aria-label="Dock" hidden></nav>
             <div id="ask-modal" class="ask-modal" hidden>
               <section class="ask-box" role="dialog" aria-modal="true" aria-labelledby="ask-title">
                 <header class="ask-head">
@@ -501,6 +503,9 @@
           <button id="preview-link-btn" class="icon-btn" aria-label="Link to the session" title="Link to the session" onclick="togglePreviewSessionLink()">
             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="16" height="16"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>
           </button>
+          <button class="icon-btn" aria-label="Copy path" title="Copy path" onclick="copyWithFeedback(currentPreviewPath, this)">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="16" height="16"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+          </button>
           <button class="icon-btn" aria-label="Open in editor" title="Open in editor" onclick="openPreviewInEditor()">
             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="16" height="16"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
           </button>
@@ -517,7 +522,7 @@
           <div id="preview-modal-body" class="rendered-md modal-zoomable"></div>
           <aside id="preview-review-panel" class="review-panel" hidden></aside>
         </div>
-        <div id="preview-modal-meta"></div>
+        <div id="preview-modal-meta" title="Click to copy path" onclick="copyPreviewPath(this)"></div>
       </div>
     </div>
   </div>

package/public/style.css

@@ -62,6 +62,7 @@
   --font-serif: var(--serif);
   /* reading-surface scale for the message-detail and preview modals (Ctrl +/-/0) */
   --modal-zoom: 1;
+  --show-zoom: 1;
   --review-panel-w: 320px;
 }
 
@@ -4002,6 +4003,161 @@ code.ct .ct-has[aria-expanded='false'] .ct-name::after {
   position: relative;
 }
 
+.terminal-pane {
+  --dock-rail-w: 0px;
+  --dock-panel-w: 0px;
+}
+
+.terminal-pane.dock-rail-on {
+  --dock-rail-w: 30px;
+}
+
+.terminal-pane.show-docked {
+  --dock-panel-w: var(--show-dock-w);
+}
+
+.terminal-pane.dock-rail-on,
+.terminal-pane.show-docked {
+  padding-top: 0;
+  padding-right: 0;
+  padding-bottom: 0;
+}
+
+.terminal-pane.dock-rail-on .terminal-frame,
+.terminal-pane.show-docked .terminal-frame {
+  width: calc(100% - var(--dock-panel-w) - var(--dock-rail-w));
+}
+
+.terminal-pane.dock-rail-on .terminal-bar,
+.terminal-pane.show-docked .terminal-bar {
+  top: 8px;
+  right: calc(8px + var(--dock-panel-w) + var(--dock-rail-w));
+}
+
+.dock-rail {
+  position: absolute;
+  z-index: 2;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  box-sizing: border-box;
+  width: var(--dock-rail-w);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+  padding-top: 6px;
+  border-left: 1px solid var(--border);
+  background: var(--bg-surface);
+}
+
+.dock-rail[hidden],
+.dock-addon[hidden],
+.dock-addon-frame[hidden] {
+  display: none;
+}
+
+.dock-rail-btn {
+  position: relative;
+  display: grid;
+  place-items: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--text-tertiary);
+  font: 600 11px var(--font-mono);
+  cursor: pointer;
+}
+
+.dock-rail-btn:hover {
+  color: var(--text-primary);
+  background: var(--bg-hover);
+}
+
+.dock-rail-btn.on {
+  color: var(--accent);
+  background: var(--bg-deep);
+  box-shadow: inset 0 0 0 1px var(--border);
+}
+
+.dock-rail-btn svg {
+  width: 13px;
+  height: 13px;
+}
+
+.dock-rail-btn.dot::after {
+  content: '';
+  position: absolute;
+  top: 1px;
+  right: 1px;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--accent);
+}
+
+.dock-addon {
+  position: absolute;
+  z-index: 2;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  border-left: 1px solid var(--border);
+  border-bottom: 1px solid var(--border);
+  background: var(--bg-surface);
+  color: var(--text-secondary);
+  font-family: var(--font-mono);
+}
+
+.dock-addon:focus-within,
+.dock-addon.focused {
+  border-color: var(--accent);
+  box-shadow:
+    0 0 0 1px var(--accent),
+    0 0 10px var(--accent-glow);
+}
+
+.dock-addon-head:focus {
+  outline: none;
+}
+
+/* Stops above the prompt rows, as the expanded show card does. */
+.dock-addon.expanded {
+  left: 0;
+  bottom: calc(7.2 * var(--show-term-font, 13px));
+  width: auto;
+  border-bottom: 1px solid var(--border);
+}
+
+.dock-addon.expanded .show-dock-edge {
+  display: none;
+}
+
+.dock-addon-body {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+}
+
+.dock-addon-frame {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border: 0;
+  background: var(--bg-surface);
+}
+
+.dock-addon-view {
+  height: 100%;
+}
+
+.show-card.open.under-addon {
+  display: none;
+}
+
 .show-card {
   --show-inset: 8px;
   /* Six terminal rows (prompt, its rules, status line) at xterm's cell height of about 1.2 × font size. */
@@ -4009,7 +4165,7 @@ code.ct .ct-has[aria-expanded='false'] .ct-name::after {
   position: absolute;
   z-index: 2;
   top: var(--show-inset);
-  right: var(--show-inset);
+  right: calc(var(--show-inset) + var(--dock-rail-w));
   display: none;
   flex-direction: column;
   box-sizing: border-box;
@@ -4058,6 +4214,27 @@ body.light .show-card {
   max-height: none;
 }
 
+/* Off the bottom edge: the Windows 11 window frame covers the last pixel row, which hides the
+   bottom border there. */
+.dock-addon,
+.show-card.docked {
+  top: 0;
+  right: var(--dock-rail-w);
+  bottom: 2px;
+  width: var(--show-dock-drag, var(--show-dock-w));
+}
+
+.show-card.docked {
+  left: auto;
+  height: auto;
+  min-width: 0;
+  max-width: none;
+  max-height: none;
+  border-width: 0 0 1px 1px;
+  border-radius: 0;
+  box-shadow: none;
+}
+
 .show-card.collapsed {
   left: auto;
   bottom: auto;
@@ -4069,7 +4246,9 @@ body.light .show-card {
 .show-card.collapsed .show-body,
 .show-card.collapsed .show-review,
 .show-card.collapsed .show-grip,
-.show-card.expanded .show-grip {
+.show-card.expanded .show-grip,
+.show-card.docked .show-grip,
+.show-card:not(.docked) .show-dock-edge {
   display: none;
 }
 
@@ -4159,6 +4338,12 @@ body.light .show-card.focused {
     0 0 10px var(--accent-glow);
 }
 
+.dock-addon:focus-within,
+.dock-addon.focused,
+.show-card.docked.focused {
+  border-bottom-color: var(--border);
+}
+
 .show-actions {
   flex: none;
   display: flex;
@@ -4197,6 +4382,10 @@ body.light .show-card.focused {
   height: 14px;
 }
 
+.show-btn.active {
+  color: var(--accent);
+}
+
 .show-btn.remove:hover:not(:disabled) {
   color: var(--text-primary);
   background: var(--bg-elevated);
@@ -4271,6 +4460,7 @@ body.light .show-card.focused {
   padding: 0.8em 1.1em 1em;
   /* The same scale as an HTML card's frame (the zoom in showBridge). */
   font-size: clamp(12.5px, calc(9.7px + 0.58cqi), 17.5px);
+  zoom: var(--show-zoom, 1);
   line-height: 1.6;
   color: var(--text-secondary);
   overflow-wrap: anywhere;
@@ -4459,6 +4649,22 @@ body.light .show-card.focused {
   height: 9px;
 }
 
+.show-dock-edge {
+  position: absolute;
+  top: 0;
+  left: 0;
+  bottom: 0;
+  width: 5px;
+  cursor: col-resize;
+  touch-action: none;
+  transition: background 0.15s;
+}
+
+.show-dock-edge:hover,
+body.show-resizing .show-dock-edge {
+  background: var(--accent-dim);
+}
+
 body.show-resizing {
   user-select: none;
 }
@@ -5915,7 +6121,7 @@ body.show-resizing iframe {
   padding: 8px 14px;
   font-size: 11px;
   color: var(--text-secondary);
-  z-index: 10000;
+  z-index: 10020;
   opacity: 0;
   transform: translateY(10px);
   transition:
@@ -8130,6 +8336,12 @@ body.light .msg-assistant .msg-text {
   font-size: 11px;
   color: var(--text-muted);
   flex-shrink: 0;
+  cursor: copy;
+  align-self: flex-start;
+}
+
+#preview-modal-meta:hover {
+  color: var(--text-primary);
 }
 
 /* Rendered HTML pages need far more room than a markdown doc. */

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');
@@ -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;
@@ -3382,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 });
 }));
 
@@ -3500,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;
   });
 }
 
@@ -3508,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;
@@ -4369,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) {
@@ -4387,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
@@ -4821,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);
@@ -4829,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.