claude-code-kanban 5.2.0 → 5.3.0

package/public/terminal-frame.js

@@ -0,0 +1,341 @@
+// The terminal half of the board's TERMINAL region. The board frames this page from the other
+// loopback name (see terminalFrameOrigin in app.js), a different site, so Chrome runs it in its own
+// renderer process: keys, output and acks never wait behind board work. The board keeps every decision
+// (when to open, retries, prompts, focus); this page keeps xterm and the socket.
+((root) => {
+  'use strict';
+
+  const ACK_BATCH_BYTES = 32 * 1024;
+  const MSG = 'cck-term:';
+
+  const modsOf = (e) =>
+    [e.ctrlKey && 'ctrl', e.altKey && 'alt', e.shiftKey && 'shift', e.metaKey && 'meta'].filter(Boolean).join('+');
+
+  // A claim names a key by its physical code, or by its character when the layout moves it.
+  function keySigs(e) {
+    const mods = modsOf(e);
+    return [e.code && `${mods}|c:${e.code}`, typeof e.key === 'string' && `${mods}|k:${e.key.toLowerCase()}`].filter(
+      Boolean,
+    );
+  }
+
+  const claimSig = (c) => keySigs(c)[0];
+
+  const isClaimed = (claims, e) => keySigs(e).some((s) => claims.has(s));
+
+  // Hub keys are matched the way the SDK matches them, so a layout that moves a key agrees on both sides.
+  const handsBack = (claims, forward, comboOf, e) => (!!comboOf && forward.has(comboOf(e))) || isClaimed(claims, e);
+
+  function parentOriginOf(hash) {
+    const m = /[#&]p=([^&]*)/.exec(hash || '');
+    if (!m) return null;
+    try {
+      return new URL(decodeURIComponent(m[1])).origin;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  function tailOf(buf, count) {
+    if (!buf) return '';
+    const lines = [];
+    for (let i = buf.length - 1; i >= 0 && lines.length < count; i--) {
+      const text = buf.getLine(i)?.translateToString(true) ?? '';
+      if (text.trim() || lines.length) lines.unshift(text);
+    }
+    return lines.join('\n');
+  }
+
+  function oscColor(hex) {
+    const m = /^#([0-9a-f]{6})$/i.exec(hex || '');
+    if (!m) return null;
+    return `rgb:${[0, 2, 4].map((i) => m[1].slice(i, i + 2).repeat(2)).join('/')}`;
+  }
+
+  function createTerminalFrame(win) {
+    const doc = win.document;
+    const parentOrigin = parentOriginOf(win.location.hash);
+    const host = doc.getElementById('host');
+    const state = {
+      term: null,
+      fit: null,
+      webgl: null,
+      ws: null,
+      attached: false,
+      ackPending: 0,
+      ackTimer: null,
+      claims: new Set(),
+      forward: new Set(),
+    };
+    const comboOf = win.ClaudeHub?.comboOf;
+
+    function up(t, data) {
+      if (parentOrigin) win.parent.postMessage({ ...data, type: MSG + t }, parentOrigin);
+    }
+
+    function send(msg) {
+      if (state.ws?.readyState === win.WebSocket.OPEN) state.ws.send(JSON.stringify(msg));
+    }
+
+    // The WebGL renderer keeps its last frame and glyph atlas while the frame is 0×0, and comes back
+    // showing stale cells or backgrounds with no text. xterm does not repaint on its own.
+    function repaint() {
+      const term = state.term;
+      if (!term) return;
+      try {
+        state.webgl?.clearTextureAtlas();
+      } catch (_) {}
+      term.refresh(0, term.rows - 1);
+    }
+
+    // The fit addon measures 0×0 while the board's pane (or the hub's iframe) is display:none.
+    function fit() {
+      if (!state.fit || !host.offsetWidth || !host.offsetHeight) return;
+      try {
+        state.fit.fit();
+      } catch (_) {}
+    }
+
+    function setBg(options) {
+      doc.documentElement.style.setProperty('--bg', options?.theme?.background || '');
+    }
+
+    function applyTheme(options) {
+      Object.assign(state.term.options, options);
+      setBg(options);
+      repaint();
+    }
+
+    function applyFont(size) {
+      const term = state.term;
+      term.options.fontSize = size;
+      fit();
+      doc.fonts
+        ?.load(`${size}px ${term.options.fontFamily}`)
+        .then(repaint)
+        .catch(() => {});
+    }
+
+    function forwardClaimed(e) {
+      if (!handsBack(state.claims, state.forward, comboOf, e)) return false;
+      e.preventDefault();
+      up('key', { key: e.key, code: e.code, ctrl: e.ctrlKey, alt: e.altKey, shift: e.shiftKey, meta: e.metaKey });
+      return true;
+    }
+
+    function keyFilter(e) {
+      if (e.type !== 'keydown') return true;
+      if (forwardClaimed(e)) return false;
+      const ctrlOnly = e.ctrlKey && !e.altKey && !e.metaKey;
+      if (ctrlOnly && e.code === 'KeyC' && (e.shiftKey || state.term.hasSelection())) {
+        e.preventDefault();
+        win.navigator.clipboard?.writeText(state.term.getSelection()).catch(() => {});
+        state.term.clearSelection();
+        return false;
+      }
+      // The browser's own paste event reaches xterm's textarea.
+      return !(ctrlOnly && e.code === 'KeyV');
+    }
+
+    function init(o) {
+      if (state.term) return;
+      const term = new win.Terminal({
+        fontFamily: o.fontFamily,
+        fontSize: o.fontSize,
+        scrollback: o.scrollback,
+        cursorBlink: true,
+        allowProposedApi: true,
+        ...o.themeOptions,
+      });
+      state.term = term;
+      state.fit = new win.FitAddon.FitAddon();
+      term.loadAddon(state.fit);
+      term.loadAddon(new win.Unicode11Addon.Unicode11Addon());
+      term.unicode.activeVersion = '11';
+      term.open(host);
+      try {
+        const gl = new win.WebglAddon.WebglAddon();
+        gl.onContextLoss(() => {
+          gl.dispose();
+          state.webgl = null;
+          repaint();
+        });
+        term.loadAddon(gl);
+        state.webgl = gl;
+      } catch (_) {
+        // No WebGL: xterm falls back to its DOM renderer.
+      }
+      setBg(o.themeOptions);
+      applyFont(o.fontSize);
+      term.attachCustomKeyEventHandler(keyFilter);
+      // After a click on the scrollbar, or before the board's focus message lands, the frame has focus
+      // but xterm's textarea does not, and the board's keys must still get out.
+      doc.addEventListener('keydown', (e) => {
+        if (e.target !== term.textarea) forwardClaimed(e);
+      });
+      term.textarea.addEventListener('focus', () => up('focused'));
+      // xterm leaves OSC 10/11 color queries unanswered, so apps that pick a palette from the
+      // background (Claude Code's Auto theme) assume dark even on a light theme.
+      for (const [code, key] of [
+        [10, 'foreground'],
+        [11, 'background'],
+      ]) {
+        term.parser.registerOscHandler(code, (data) => {
+          if (data !== '?') return false;
+          const rgb = oscColor(term.options.theme[key]);
+          if (rgb) send({ t: 'in', d: `\x1b]${code};${rgb}\x1b\\` });
+          return true;
+        });
+      }
+      term.onData((d) => send({ t: 'in', d }));
+      term.onResize(({ cols, rows }) => send({ t: 'resize', cols, rows }));
+      // One fit per frame while a drag resizes the pane. The atlas is rebuilt only when the frame comes
+      // back from 0×0, which is also how a hidden hub iframe or pane shows again.
+      let frame = 0;
+      let visible = false;
+      new win.ResizeObserver(() => {
+        if (frame) return;
+        frame = win.requestAnimationFrame(() => {
+          frame = 0;
+          const nowVisible = host.offsetWidth > 0;
+          fit();
+          if (nowVisible && !visible) repaint();
+          visible = nowVisible;
+        });
+      }).observe(host);
+      // Vimium eats Escape inside a text field and only blurs it, so the key never reaches Claude.
+      // A blur no click caused, while this frame keeps focus, is that Escape. When the board takes
+      // focus back, this document loses it, so that blur is not one.
+      let pointerDown = false;
+      doc.addEventListener('mousedown', () => (pointerDown = true), true);
+      doc.addEventListener('mouseup', () => (pointerDown = false), true);
+      term.textarea.addEventListener('blur', () => {
+        if (pointerDown) return;
+        win.requestAnimationFrame(() => {
+          if (!state.attached || !host.offsetWidth) return;
+          if (!doc.hasFocus() || doc.activeElement !== doc.body) return;
+          send({ t: 'in', d: '\x1b' });
+          term.focus();
+        });
+      });
+      up('term');
+    }
+
+    function ack(ws, n) {
+      if (state.ws !== ws) return;
+      state.ackPending += n;
+      const flush = () => {
+        win.clearTimeout(state.ackTimer);
+        state.ackTimer = null;
+        if (state.ws === ws && state.ackPending) send({ t: 'ack', n: state.ackPending });
+        state.ackPending = 0;
+      };
+      if (state.ackPending >= ACK_BATCH_BYTES) flush();
+      else if (!state.ackTimer) state.ackTimer = win.setTimeout(flush, 50);
+    }
+
+    // RIS through the write queue, not term.reset(): reset() runs at once, and output the previous
+    // session had already queued would still be drawn after it.
+    function clearScreen() {
+      state.term.write('\x1bc', repaint);
+    }
+
+    function detach() {
+      const ws = state.ws;
+      state.ws = null;
+      state.attached = false;
+      win.clearTimeout(state.ackTimer);
+      state.ackTimer = null;
+      state.ackPending = 0;
+      if (ws) {
+        ws.onclose = null;
+        ws.close();
+      }
+    }
+
+    function open({ socketId, hello, reset }) {
+      detach();
+      up('opening', { socketId });
+      const term = state.term;
+      let outputSent = false;
+      if (reset) clearScreen();
+      fit();
+      const proto = win.location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const ws = new win.WebSocket(`${proto}//${win.location.host}/api/terminal/ws`);
+      ws.binaryType = 'arraybuffer';
+      state.ws = ws;
+      ws.onopen = () => ws.send(JSON.stringify({ ...hello, t: 'hello', cols: term.cols, rows: term.rows }));
+      ws.onmessage = (ev) => {
+        if (state.ws !== ws) return;
+        if (typeof ev.data !== 'string') {
+          const bytes = new Uint8Array(ev.data);
+          term.write(bytes, () => {
+            ack(ws, bytes.length);
+            if (!outputSent && state.ws === ws && tailOf(term.buffer.active, 1)) {
+              outputSent = true;
+              up('output', { socketId });
+            }
+          });
+          return;
+        }
+        let msg;
+        try {
+          msg = JSON.parse(ev.data);
+        } catch (_) {
+          return;
+        }
+        if (msg.t === 'ready') {
+          state.attached = true;
+          // A retry keeps the last screen until the replay arrives.
+          if (!reset) clearScreen();
+          send({ t: 'resize', cols: term.cols, rows: term.rows });
+        } else if (msg.t === 'exit') state.attached = false;
+        up('ws', { socketId, msg, ...(msg.t === 'exit' && { tail: tailOf(term.buffer.active, 6) }) });
+      };
+      ws.onclose = (ev) => {
+        if (state.ws !== ws) return;
+        state.ws = null;
+        state.attached = false;
+        up('close', { socketId, code: ev.code });
+      };
+    }
+
+    function onMessage(e) {
+      if (e.source !== win.parent || e.origin !== parentOrigin) return;
+      const m = e.data;
+      if (typeof m?.type !== 'string' || !m.type.startsWith(MSG)) return;
+      if (m.type === `${MSG}init`) return init(m);
+      if (!state.term) return;
+      switch (m.type.slice(MSG.length)) {
+        case 'open':
+          return open(m);
+        case 'detach':
+          return detach();
+        case 'send':
+          return send(m.msg);
+        case 'theme':
+          return applyTheme(m.options);
+        case 'font':
+          return applyFont(m.size);
+        case 'claims':
+          state.claims = new Set((m.keys || []).map(claimSig));
+          state.forward = new Set(m.forward || []);
+          return;
+        case 'focus':
+          return state.term.focus();
+        case 'refresh':
+          fit();
+          return repaint();
+      }
+    }
+
+    win.addEventListener('message', onMessage);
+    up('loaded');
+  }
+
+  if (typeof module === 'object' && module.exports) {
+    module.exports = { createTerminalFrame, claimSig, isClaimed, handsBack, parentOriginOf, tailOf };
+  } else {
+    createTerminalFrame(root);
+  }
+})(typeof window === 'undefined' ? globalThis : window);

package/public/terminal.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Terminal</title>
+  <link rel="stylesheet" href="/fonts/fonts.css">
+  <link rel="stylesheet" href="/vendor/xterm/xterm.css">
+  <style>
+    html, body { margin: 0; height: 100%; overflow: hidden; background: var(--bg, transparent); }
+    #host { height: 100%; }
+    #host .xterm { height: 100%; }
+    /* xterm.css paints the viewport #000; it shows below the last row when the height is not a whole number of rows. */
+    /* xterm draws its own scrollbar; the viewport's native one would show at the bottom-right corner. */
+    #host .xterm .xterm-viewport { background-color: var(--bg, transparent); scrollbar-width: none; }
+  </style>
+  <!-- For ClaudeHub.comboOf only. In <head>, where there is no body yet for the SDK to paint theme vars on. -->
+  <script src="/vendor/claude-hub-sdk.js"></script>
+</head>
+<body>
+  <div id="host"></div>
+  <script src="/vendor/xterm/xterm.js"></script>
+  <script src="/vendor/xterm/addon-fit.js"></script>
+  <script src="/vendor/xterm/addon-webgl.js"></script>
+  <script src="/vendor/xterm/addon-unicode11.js"></script>
+  <script src="/terminal-frame.js"></script>
+</body>
+</html>

package/public/vendor/claude-hub-sdk.js

@@ -1,9 +1,18 @@
-// claude-hub-sdk 1.1.0 (sha256 0fed14faa670). Copied by npm run sdk:sync in claude-code-hub. Do not edit.
+// claude-hub-sdk 1.2.0 (sha256 62c7d9f477b2). Copied by npm run sdk:sync in claude-code-hub. Do not edit.
 // Claude Code Hub SDK stub: what an app serves when no hub runs it. Under a hub, the hub hands the
 // app its real SDK (client.js) in place of this file. The API must match client.js; a test checks it.
 ((root) => {
   'use strict';
 
+  // A copy of client.js comboOf(); a test checks they match.
+  function comboOf(e) {
+    const lower = typeof e.key === 'string' ? e.key.toLowerCase() : '';
+    const m = /^(?:Key|Digit)([A-Z1-9])$/.exec(e.code || '');
+    const key = /^[a-z1-9]$/.test(lower) ? lower : m ? m[1].toLowerCase() : e.key;
+    const mods = [e.ctrlKey && 'ctrl', e.altKey && 'alt', e.shiftKey && 'shift', e.metaKey && 'meta'];
+    return [...mods, key].filter(Boolean).join('+');
+  }
+
   function createClaudeHub(win) {
     let hub = null;
     const off = () => {};
@@ -33,6 +42,7 @@
         },
         can: (action) => !!standaloneFn(action),
         forwards: () => false,
+        forwardCombos: () => [],
         closeGuard() {},
         openExternal(url) {
           win.open(url, '_blank', 'noopener');
@@ -42,9 +52,9 @@
       return hub;
     }
 
-    return { connect };
+    return { connect, comboOf };
   }
 
-  if (typeof module === 'object' && module.exports) module.exports = { createClaudeHub };
+  if (typeof module === 'object' && module.exports) module.exports = { createClaudeHub, comboOf };
   else root.ClaudeHub = createClaudeHub(root);
 })(typeof window !== 'undefined' ? window : globalThis);

package/server.js

@@ -39,16 +39,18 @@ const {
 } = require('./lib/parsers');
 const { inlineHtmlAssets, MIME_BY_EXT } = require('./lib/inline-assets');
 const { buildDecision, decisionFileName, isDecisionFile, approvalsFrom, boardRefusal } = require('./lib/approvals');
-const { getClaudeDir, getArgValue, storageNamespace, isDefaultClaudeDir } = require('./lib/claude-dir');
+const { getClaudeDir, getArgValue, storageNamespace, isDefaultClaudeDir, encodeProjectDirName } = require('./lib/claude-dir');
 const { createTerminalService, readTerminalConfig } = require('./lib/terminal');
+const { createProcStats } = require('./lib/proc-stats');
 const { createDispatchRegistry, formatPreamble, formatDispatchLine, isPeerName, DISPATCH_OUTCOME } = require('./lib/dispatch');
 const { createGroupStore, isGroupName, suggestGroupName } = require('./lib/dispatch-groups');
-const { createDispatchedStore, listTranscriptIds, pruneSessionDirs, retentionMs } = require('./lib/retention');
+const { createDispatchedStore, scanTranscripts, pruneSessionDirs, retentionMs } = require('./lib/retention');
+const { createWorktreeStore } = require('./lib/worktrees');
 const { createLinkedDocStore, linkUrl } = require('./lib/linked-docs');
 const { pickFolder } = require('./lib/folder-dialog');
 const { loadSessionCache, saveSessionCache } = require('./lib/session-cache');
 const { countTaskDir } = require('./lib/task-counts');
-const { projectMatcher } = require('./public/project-match');
+const { projectMatcher, normalizeProjectPath } = require('./public/project-match');
 const { getParentVerdict, setParentVerdict } = require('./lib/parent-cache');
 
 if (process.argv.includes("--install") || process.argv.includes("--uninstall")) {
@@ -69,7 +71,8 @@ const PORT = parseInt(getArgValue('port') || process.env.PORT || '3541', 10);
 
 // Mounted before express.json() so a rejected request never buffers a body, and
 // before the /api catch-all so no route escapes the check.
-const net = createNetGuard({ appName: 'Claude Task Kanban' });
+// The board frames the terminal from its other loopback name, so Chrome runs it in its own process.
+const net = createNetGuard({ appName: 'Claude Task Kanban', selfFramedPaths: ['/terminal.html'] });
 app.use(net.hostGuard);
 app.use(net.frameGuard);
 app.use(net.originGuard);
@@ -93,6 +96,7 @@ 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 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 SERVER_INFO_FILE = path.join(CCK_DIR, 'server.json');
 const TERMINAL_TOKENS_DIR = path.join(CCK_DIR, 'terminal-tokens');
@@ -338,33 +342,12 @@ function getGitBranch(cwd) {
   return branch;
 }
 
-// A linked worktree's `.git` is a file holding `gitdir: <main>/.git/worktrees/<name>`, so the
-// main checkout is readable without spawning git. Path shape alone would not do: only some
-// worktrees live under `<repo>/.claude/worktrees/`, the rest sit beside the repo.
-// Cached without a TTL, misses included: a directory cannot turn from an ordinary checkout into
-// a linked worktree without being recreated, and a recreated path is a new cache key.
-const worktreeCache = new Map();
-const WORKTREE_CACHE_MAX = 500;
-const GITDIR_WORKTREE_RE = /^gitdir:\s*(.*)[/\\]\.git[/\\]worktrees[/\\]([^/\\]+)[/\\]?$/;
-
-function resolveWorktree(dir) {
-  if (!dir) return null;
-  if (worktreeCache.has(dir)) return worktreeCache.get(dir);
-
-  let worktree = null;
-  try {
-    // An ordinary checkout's `.git` is a directory, so the read throws EISDIR — that is the
-    // answer, and it costs one syscall instead of a stat followed by a read.
-    const m = GITDIR_WORKTREE_RE.exec(readFileSync(path.join(dir, '.git'), 'utf8').trim());
-    if (m) worktree = { repo: m[1], name: m[2] };
-  } catch (_) {}
-
-  worktreeCache.set(dir, worktree);
-  if (worktreeCache.size > WORKTREE_CACHE_MAX) {
-    worktreeCache.delete(worktreeCache.keys().next().value);
-  }
-  return worktree;
-}
+const worktrees = createWorktreeStore({
+  load: () => {
+    try { return JSON.parse(readFileSync(WORKTREES_FILE, 'utf8')); } catch { return null; }
+  },
+  save: (data) => writeJsonAtomic(WORKTREES_FILE, data),
+});
 
 // Only spawn git when cwd has diverged from the launch project — that's the
 // only case the JSONL value is wrong. Saves N spawns on a typical list build.
@@ -1140,12 +1123,6 @@ function getSessionDisplayName(_sessionId, meta) {
   return null;
 }
 
-// The harness spells a project path into a temp/log dir name by replacing every
-// non-alphanumeric character with a dash, drive colon and separators included.
-function encodeProjectDirName(p) {
-  return p.replace(/[^a-zA-Z0-9]/g, '-');
-}
-
 // Derived by convention, not looked up: the harness creates the dir lazily, so a
 // stat here would report "missing" for every session that has not written a temp
 // file yet — and it would put IO on the session-list hot path. Pure string join.
@@ -1160,7 +1137,7 @@ function getScratchpadDir(id, meta) {
   // harness actually created. Probed only for worktree sessions, and only until one
   // of them exists — before that there is nothing to disambiguate and `byProject`,
   // right for a session started inside the worktree, stands.
-  const wt = resolveWorktree(meta.project);
+  const wt = worktrees.resolve(meta.project);
   if (!wt || existsSync(byProject)) return byProject;
   const byRepo = path.join(SCRATCHPAD_ROOT, encodeProjectDirName(wt.repo), id, 'scratchpad');
   return existsSync(byRepo) ? byRepo : byProject;
@@ -1179,7 +1156,7 @@ function buildSessionObject(id, meta, overrides = {}) {
     cwd: meta.cwd || null,
     description: meta.description || null,
     gitBranch: resolveSessionGitBranch(meta),
-    worktree: resolveWorktree(meta.project),
+    worktree: worktrees.resolve(meta.project),
     customTitle: meta.customTitle || null,
     taskCount: 0,
     completed: 0,
@@ -1578,7 +1555,7 @@ app.get('/api/sessions', async (req, res) => {
     // if the row is missing — that one is not a preference.
     if (projectFilter) {
       const matches = projectMatcher(String(projectFilter));
-      sessions = sessions.filter(s => matches(s.project) || includeIds.has(s.id));
+      sessions = sessions.filter(s => matches(s.project, s.worktree?.repo) || includeIds.has(s.id));
     }
     // The sidebar's 24h filter: projects with any transcript written in the window, so an older
     // session of such a project stays in.
@@ -1650,14 +1627,30 @@ function projectActivity() {
   return activity;
 }
 
-// API: Get distinct project paths with last-modified timestamps
+// API: Get distinct project paths with last-modified timestamps. A linked worktree is folded
+// into its repo, which lists it under `worktrees`; the repo row exists even when only its
+// worktrees have transcripts.
 app.get('/api/projects', (_req, res) => {
   res.setHeader('Cache-Control', 'no-store');
-  const projects = [...projectActivity()]
-    .map(([path, mtime]) => ({
-      path,
-      modifiedAt: mtime ? new Date(mtime).toISOString() : null,
-      ...(isTempPath(path) && { temp: true }),
+  const byRepo = new Map();
+  for (const [project, mtime] of projectActivity()) {
+    const repo = worktrees.resolve(project)?.repo || project;
+    const key = normalizeProjectPath(repo);
+    let row = byRepo.get(key);
+    if (!row) {
+      row = { path: repo, mtime: 0, worktrees: [] };
+      byRepo.set(key, row);
+    }
+    if (repo === project) row.path = project;
+    else row.worktrees.push(project);
+    row.mtime = Math.max(row.mtime, mtime || 0);
+  }
+  const projects = [...byRepo.values()]
+    .map((r) => ({
+      path: r.path,
+      modifiedAt: r.mtime ? new Date(r.mtime).toISOString() : null,
+      ...(isTempPath(r.path) && { temp: true }),
+      ...(r.worktrees.length && { worktrees: r.worktrees.sort() }),
     }))
     .sort((a, b) => a.path.localeCompare(b.path));
   res.json(projects);
@@ -3298,6 +3291,16 @@ app.get('/api/terminals', (_req, res) => {
   res.json({ sessions: terminal.list() });
 });
 
+const terminalProcStats = createProcStats();
+app.get('/api/terminals/stats', async (_req, res) => {
+  res.setHeader('Cache-Control', 'no-store');
+  const pids = terminal.claudePids();
+  const byPid = await terminalProcStats([process.pid, ...Object.values(pids)]);
+  const terminals = {};
+  for (const [id, pid] of Object.entries(pids)) if (byPid[pid]) terminals[id] = byPid[pid];
+  res.json({ cck: byPid[process.pid] || null, terminals });
+});
+
 app.delete('/api/terminals/:id', (req, res) => {
   const err = terminal.end(req.params.id, req.get('x-terminal-token'));
   if (err === 'auth') return res.status(401).json({ error: 'invalid terminal token' });
@@ -3978,7 +3981,7 @@ function formatReviewMarkdown(src, items) {
   const parts = [
     `# Review of ${src.path || src.label}`,
     '',
-    "Each comment is the user's instruction about the quoted text. A quote missing from the source means the source changed after the review: say so.",
+    `Each comment is the user's instruction about the quoted text.${src.path ? ' A quote missing from the source means the source changed after the review: say so.' : ''}`,
   ];
   items.forEach((c, i) => {
     const where = [c.line && `line ${c.line}`, c.heading && `under "${c.heading}"`].filter(Boolean).join(', ');
@@ -4321,13 +4324,17 @@ async function cleanupAgentActivity() {
   } catch { /* agent-activity dir may not exist */ }
 }
 
-// Dispatch markers and reviews: see docs/retention.md.
+// Dispatch markers, reviews and worktrees: see docs/retention.md.
 async function runRetention() {
   try {
-    const opts = { known: await listTranscriptIds(PROJECTS_DIR), maxAgeMs: retentionMs(CLAUDE_DIR) };
+    const scan = await scanTranscripts(PROJECTS_DIR);
+    const opts = { known: scan?.ids, maxAgeMs: retentionMs(CLAUDE_DIR) };
     const markers = dispatched.prune(opts);
     const reviews = await pruneSessionDirs(REVIEW_DIR, opts);
-    if (markers || reviews) console.log(`[retention] removed ${markers} dispatch markers, ${reviews} reviews`);
+    const wts = worktrees.prune(scan?.dirs);
+    if (markers || reviews || wts) {
+      console.log(`[retention] removed ${markers} dispatch markers, ${reviews} reviews, ${wts} worktrees`);
+    }
   } catch (e) {
     console.warn('[retention] failed:', e.message);
   }

package/skill-guides/dispatch.md

@@ -2,7 +2,7 @@
 
 A dispatch is one Claude Code session that cck starts for a task, in its embedded terminal. It is an ordinary session, not a child: it shows in the sidebar like any other, and the user can open its terminal at any time.
 
-A dispatch is **fire-and-forget** by default: you hand the task off, and the user watches it in the sidebar. Add `--report` only when you need the outcome back: the user asked you to collect it, or your next step depends on it.
+A dispatch **reports back** by default: start it with `--report` and `--peer`, then collect and verify the outcome (With `--report`, below). When the user's request says `--no-report`, it is **fire-and-forget**: start it with neither flag (Fire-and-forget, below). `--no-report` lives only in the user's request; `dispatch start` has no such flag.
 
 ## Write the spec
 
@@ -19,12 +19,12 @@ Dispatch when the task can run on its own. Do the work yourself when it is small
 ## Start
 
 ```bash
-claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name> --group <group> --peer <your-peer> [--report] --json
+claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name> --group <group> --peer <your-peer> --report --json
 ```
 
 `claude-code-kanban help dispatch start` lists every flag (model, worktree, and the rest). `project list` shows the folders `--cwd` accepts. How to choose the values:
 
-- `--peer` is your own peer name: the first line of `ListAgents` ("This session is `<name>`"). Pass it whenever you have the `ListAgents` tool. cck then tells the started session to ask you with `SendMessage` instead of failing on a question. See [Peer](#peer).
+- `--peer` is your own peer name: the first line of `ListAgents` ("This session is `<name>`"). Pass it when you have the `ListAgents` tool. cck then tells the started session to ask you with `SendMessage` instead of failing on a question. See [Peer](#peer).
 - `--spec-file` over `--spec` for anything longer than a line: no shell quoting.
 - `--name` is what the user sees in the sidebar. Kebab-case, saying what the session does: `fix-login-redirect`, not `task-1`.
 - `--group` names the effort, in kebab-case (`auth-refactor`), and shows the new session under that sidebar group. This session stays where it is. Pass it on your first dispatch; later dispatches join the same group without it. A group goes away when its sessions end, unless the user pins a member or keeps the group.
@@ -32,7 +32,7 @@ claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name
 
 ## Fire-and-forget
 
-Tell the user the session name, its group, and the dispatch id, then carry on with your own work or end your turn. The user follows the dispatch in the sidebar. With `--peer`, its questions still reach you as new turns.
+The started session gets the task alone and does not know your session exists. Tell the user the session name, its group, and the dispatch id. Your part ends with that message: the user follows the dispatch in the sidebar, and asks you when they want it checked.
 
 ## With `--report`