claude-code-kanban 7.4.0 → 7.6.0

package/README.md

@@ -82,7 +82,7 @@ Run `claude` in any project. You do not configure anything per project. Claude C
 - **Embedded terminal.** Run a real Claude Code process for any session next to its board (<kbd>Ctrl</kbd>+<kbd>&#96;</kbd>). <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>R</kbd> resumes a past session and <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>S</kbd> swaps to the previous one. The terminal is off by default when the board runs alone. Start it with `--enable-terminal` and open the `#t=<token>` link the server prints. [Embedded terminal](https://nikiforovall.blog/claude-code-kanban/guides/embedded-terminal/)
 - **New session.** <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>N</kbd> opens a dialog to pick a folder, a name, a model, an optional git worktree and a first prompt. Needs the terminal.
 - **Dispatch.** Hand a written task to a new session with `claude-code-kanban dispatch start`, or ask Claude to do it with the `dispatch` skill. Args after `--` go to `claude` as they are, and the started session reports back with `SendMessage`. Needs the terminal. [Dispatch tasks to other sessions](https://nikiforovall.blog/claude-code-kanban/guides/dispatch/)
-- **Steer with card moves.** Run `/claude-code-kanban:follow` in a session, then drag its cards. Claude starts, parks or stops the task. [Claude Code plugin skills](https://nikiforovall.blog/claude-code-kanban/guides/plugin-skills/)
+- **Steer with card moves.** Drag a session's cards. Claude starts, parks or stops the task. Turn it off with `boardEvents.enabled: false` in `.cck/config.json`. [Claude Code plugin skills](https://nikiforovall.blog/claude-code-kanban/guides/plugin-skills/)
 - **Review comments.** Select text in a previewed file or the plan, add comments and send them to the session in one step. [Review comments](https://nikiforovall.blog/claude-code-kanban/guides/review-comments/)
 
 <picture>
@@ -98,7 +98,7 @@ Run `claude` in any project. You do not configure anything per project. Claude C
 ### Organize
 
 - **Session groups.** Drag sessions and projects from different folders into one named group in the sidebar. [Session groups](https://nikiforovall.blog/claude-code-kanban/guides/session-groups/)
-- **Filters, search and pins.** Filter by project and activity, search across sessions and tasks, pin a session or make it sticky. <kbd>Shift</kbd>+<kbd>P</kbd> opens the session picker.
+- **Filters, search and pins.** Filter by project and activity, search across sessions and tasks, pin a session or make it sticky. <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> opens the session picker, and <kbd>Shift</kbd>+<kbd>P</kbd> the project picker.
 - **Scratchpad and linked documents.** Keep a note per session, project or group (<kbd>N</kbd>), and link files or web URLs to a session to open them in one click.
 - **Themes.** 17 color themes, each in light and dark. <kbd>T</kbd> switches the mode.
 - **Keyboard first.** Arrow keys move through tasks, and <kbd>Tab</kbd> moves between the sidebar and the board. Press <kbd>?</kbd> for the full list. [Keyboard shortcuts](https://nikiforovall.blog/claude-code-kanban/reference/keyboard-shortcuts/)
@@ -111,7 +111,8 @@ With no subcommand, `claude-code-kanban` starts the server. Subcommands talk to
 - `task list` and `project list` to read tasks and projects.
 - `doc link|unlink|list|preview` to link a file or URL to a session, or show it in the preview.
 - `pane add|rm|list` to add live panes to a session's view.
-- `dispatch start|list` to start sessions with a task in the board's terminal.
+- `dispatch start|list|end` to start sessions with a task in the board's terminal, and end them.
+- `skills get <name>` to print the guide for a skill bundled with this version.
 
 Run `claude-code-kanban --help` or see the [CLI reference](https://nikiforovall.blog/claude-code-kanban/reference/cli/).
 
@@ -126,6 +127,7 @@ EDITOR="code -w" claude-code-kanban        # Command for Open in editor (default
 
 - The server listens on `127.0.0.1` only and has no authentication. To reach it from another machine, use `--host` and `--allowed-hosts`, and do it only on a network you trust.
 - UI approvals are on by default. Turn them off or tune them in `<config-dir>/.cck/config.json`.
+- Board events (card moves and reviews sent to the session as prompts) are on by default. Turn them off with `"boardEvents": {"enabled": false}` in the same file.
 - Terminal settings, such as the shell, font size and scrollback, go in the `CCK_TERMINAL` JSON variable.
 
 See [Configuration](https://nikiforovall.blog/claude-code-kanban/reference/configuration/) for every setting, and [Troubleshooting](https://nikiforovall.blog/claude-code-kanban/troubleshooting/) for common problems.

package/cli.js

@@ -224,7 +224,7 @@ const COMMANDS = {
     },
   },
   dispatch: {
-    summary: 'Start a Claude Code session for a task in cck\'s terminal',
+    summary: 'Start, list and end Claude Code sessions for tasks in cck\'s terminal',
     verbs: {
       start: {
         summary: 'Start claude in cck\'s terminal with a task; prints the session id',
@@ -257,6 +257,18 @@ const COMMANDS = {
         },
         run: runDispatchListCli,
       },
+      end: {
+        summary: 'End the terminal of a session this session started',
+        usage: 'claude-code-kanban dispatch end (<session id or prefix> | --name <n>) [--json]',
+        flags: {
+          '<session id or prefix>': 'A session from `dispatch list`',
+          '--name <n>': 'The session\'s --name from dispatch start',
+          '--json': 'Output JSON',
+        },
+        notes: 'Needs the terminal token, like dispatch start. The worktree stays.',
+        examples: ['claude-code-kanban dispatch end --name api-worker'],
+        run: runDispatchEndCli,
+      },
     },
   },
   skills: {
@@ -333,6 +345,20 @@ function resolveCliCommand(argv) {
   return { kind: 'leaf', name: `${noun} ${verb}`, entry: entry.verbs[verb], args: argv.slice(4) };
 }
 
+// The website's reference/cli.md has the same table; change both.
+const SERVER_FLAGS = [
+  ['--port <n>', 'PORT', 'Port (default 3541)'],
+  ['--open', '', 'Open the board in the browser'],
+  ['--dir <path>', 'CLAUDE_CONFIG_DIR', 'Config dir (default ~/.claude); also for --install'],
+  ['--enable-terminal', '', 'Turn on the embedded terminal'],
+  ['--terminal-shell <shell>', 'CCK_TERMINAL_SHELL', 'gitbash, a program on PATH, or a path'],
+  ['--host <addr>', 'HOST', 'Listen address (default 127.0.0.1)'],
+  ['--allowed-hosts <list>', 'ALLOWED_HOSTS', 'Extra Host header values, comma-separated'],
+  ['--<app>-url <url>', '<APP>_URL', 'Link to app: marketplace, cost, memory'],
+  ['--install, --uninstall', '', 'Install or remove the plugin'],
+  ['--yes', '', 'With --install: no prompt'],
+];
+
 function printTopHelp() {
   console.log('Usage: claude-code-kanban <command> [args] [--flags]\n');
   console.log('Commands:');
@@ -344,13 +370,11 @@ function printTopHelp() {
   console.log('\nFlags:');
   console.log('  --help, -h            Show help (top-level, noun-level, or leaf-level)');
   console.log('  --version, -v         Print version and exit');
-  console.log('\nServer mode (no subcommand):');
-  console.log('  --port <n>            Port to listen on (default 3541)');
-  console.log('  --dir <path>          Override Claude config dir (default ~/.claude); also targets --install/--uninstall');
-  console.log('  --open                Open browser on start');
-  console.log('  --install, --uninstall    Install or remove the plugin');
-  console.log('  --yes                 With --install: install without a prompt');
-  console.log('\nEnvironment:');
+  console.log('\nServer (no command; a flag wins over its env var):');
+  const flagPad = Math.max(...SERVER_FLAGS.map(([flag]) => flag.length)) + 2;
+  const envPad = Math.max(...SERVER_FLAGS.map(([, env]) => env.length)) + 2;
+  for (const [flag, env, desc] of SERVER_FLAGS) console.log(`  ${flag.padEnd(flagPad)}${env.padEnd(envPad)}${desc}`);
+  console.log('\nCommand env:');
   console.log('  CCK_URL               Server base URL, e.g. http://127.0.0.1:4795 (wins over PORT)');
   console.log('  PORT                  Server port (default: the one this config dir\'s server reports, else 3541)');
   console.log('  CLAUDE_CONFIG_DIR     Claude config dir whose board to use');
@@ -492,7 +516,7 @@ function reportCliError(e) {
 }
 
 async function runPreviewCli(args) {
-  const filePathArg = args.find(a => !a.startsWith('--'));
+  const [filePathArg] = positionals(args, ['--session']);
   if (!filePathArg) {
     printLeafHelp(COMMANDS.doc.verbs.preview);
     return 1;
@@ -620,9 +644,8 @@ async function runPaneListCli(args, entry) {
 
 async function printLinkedDocs(sessionId, asJson) {
   try {
-    const res = await cliFetch(`/api/document/links?session=${encodeURIComponent(sessionId)}`);
-    if (!res.ok) throw new Error(`Failed to fetch linked docs (${res.status})`);
-    const paths = (await res.json())[sessionId] || [];
+    const links = await cliGetJson(`/api/document/links?session=${encodeURIComponent(sessionId)}`, 'Linked docs');
+    const paths = links[sessionId] || [];
     if (asJson) console.log(JSON.stringify(paths, null, 2));
     else if (!paths.length) console.log(`No linked docs for session ${sessionId.slice(0, 8)}.`);
     else for (const p of paths) console.log(p);
@@ -655,9 +678,11 @@ async function fetchSessionsList(limit, pinnedIds = [], project = null) {
   const q = limit === null ? 'all' : String(limit);
   const pinnedQ = pinnedIds.length ? `&pinned=${pinnedIds.join(',')}` : '';
   const projectQ = project ? `&project=${encodeURIComponent(project)}` : '';
-  const res = await cliFetch(`/api/sessions?limit=${q}${pinnedQ}${projectQ}`);
-  if (!res.ok) throw new Error(`Failed to fetch sessions (${res.status})`);
-  return res.json();
+  return cliGetJson(`/api/sessions?limit=${q}${pinnedQ}${projectQ}`, 'Session list');
+}
+
+function fetchSessionsByIds(ids, label) {
+  return cliGetJson(`/api/sessions?limit=1&include=${ids.map(encodeURIComponent).join(',')}`, label);
 }
 
 async function fetchPinsMap() {
@@ -823,7 +848,7 @@ async function runSessionViewCli(args) {
   if (!resolved) return 1;
   let list;
   try {
-    list = await fetchSessionsList(null);
+    list = await fetchSessionsByIds([resolved.id], 'Session view');
   } catch (e) { reportCliError(e); return 1; }
   const s = list.find(x => x.id === resolved.id);
   if (!s) {
@@ -900,7 +925,7 @@ async function runSessionSearchCli(args) {
   if (!parsed.ok) return usageError(entry, parsed.error);
   try {
     const ids = (await cliGetJson(`/api/sessions/search?q=${encodeURIComponent(text)}`, 'Search')).slice(0, parsed.limit);
-    const list = ids.length ? await cliGetJson(`/api/sessions?limit=1&include=${ids.join(',')}`, 'Search') : [];
+    const list = ids.length ? await fetchSessionsByIds(ids, 'Search') : [];
     const byId = new Map(list.map(s => [s.id, s]));
     const rows = ids.map(id => byId.get(id) || { id });
     if (args.includes('--json')) {
@@ -1054,20 +1079,26 @@ function textArg(args, name) {
   return file ? fs.readFileSync(cliPath(file), 'utf8') : getArgValue(args, name);
 }
 
-async function runDispatchStartCli(argv) {
-  const sep = argv.indexOf('--');
-  const args = sep === -1 ? argv : argv.slice(0, sep);
-  const claudeArgs = sep === -1 ? [] : argv.slice(sep + 1);
+function readTerminalToken() {
   const port = cliTargetPort();
   if (port === null) {
     console.error(unreachable());
-    return 1;
+    return null;
   }
   const token = port && readCckJson(`terminal-tokens/${port}.json`)?.token;
   if (!token) {
     console.error(`No terminal token for ${displayPath(getClaudeDir())} at ${cliBaseUrl()}. The cck server must be running with the terminal enabled.`);
-    return 1;
+    return null;
   }
+  return token;
+}
+
+async function runDispatchStartCli(argv) {
+  const sep = argv.indexOf('--');
+  const args = sep === -1 ? argv : argv.slice(0, sep);
+  const claudeArgs = sep === -1 ? [] : argv.slice(sep + 1);
+  const token = readTerminalToken();
+  if (!token) return 1;
   let spec;
   try { spec = textArg(args, 'spec'); } catch (e) { console.error(e.message); return 1; }
   if (!spec) {
@@ -1107,15 +1138,50 @@ async function runDispatchStartCli(argv) {
   } catch (e) { reportCliError(e); return 1; }
 }
 
-async function runDispatchListCli(args) {
+async function fetchDispatches(all) {
   const q = new URLSearchParams();
-  if (!args.includes('--all') && process.env.CLAUDE_CODE_SESSION_ID) q.set('parent', process.env.CLAUDE_CODE_SESSION_ID);
+  if (!all && process.env.CLAUDE_CODE_SESSION_ID) q.set('parent', process.env.CLAUDE_CODE_SESSION_ID);
+  return (await cliGetJson(`/api/dispatch?${q}`, 'Dispatch list')).running.sort((a, b) => b.startedAt - a.startedAt);
+}
+
+const dispatchLine = (r) => `${r.session}${r.name ? `  ${r.name}` : ''}${r.group ? `  [${r.group}]` : ''}`;
+
+async function runDispatchListCli(args) {
   try {
-    const res = await cliFetch(`/api/dispatch?${q}`);
-    const rows = (await res.json()).running.sort((a, b) => b.startedAt - a.startedAt);
+    const rows = await fetchDispatches(args.includes('--all'));
     if (args.includes('--json')) console.log(JSON.stringify(rows, null, 2));
     else if (!rows.length) console.log('No dispatches.');
-    else for (const r of rows) console.log(`${r.session}${r.name ? `  ${r.name}` : ''}${r.group ? `  [${r.group}]` : ''}`);
+    else for (const r of rows) console.log(dispatchLine(r));
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runDispatchEndCli(args) {
+  const entry = COMMANDS.dispatch.verbs.end;
+  const name = getArgValue(args, 'name');
+  const id = positionals(args, ['--name'])[0];
+  if (!id && !name) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  if (id && name) return usageError(entry, 'Give one of <session id or prefix> or --name.');
+  const token = readTerminalToken();
+  if (!token) return 1;
+  try {
+    const matches = (await fetchDispatches(false)).filter(r => name ? r.name === name : r.session.startsWith(id));
+    if (!matches.length) {
+      console.error(`No running dispatch matches "${name || id}". Run "claude-code-kanban dispatch list".`);
+      return 1;
+    }
+    if (matches.length > 1) {
+      console.error(`"${name || id}" matches ${matches.length} dispatches:`);
+      for (const r of matches) console.error(`  ${dispatchLine(r)}`);
+      return 1;
+    }
+    const { session } = matches[0];
+    if (!await cliSendJson('DELETE', `/api/terminals/${session}`, undefined, 'Dispatch end', { 'x-terminal-token': token })) return 1;
+    if (args.includes('--json')) console.log(JSON.stringify({ session }, null, 2));
+    else console.log(`Ended session ${session}`);
     return 0;
   } catch (e) { reportCliError(e); return 1; }
 }
@@ -1131,4 +1197,4 @@ async function runSkillsGetCli(args) {
   return 0;
 }
 
-module.exports = { runCli, COMMANDS };
+module.exports = { runCli, COMMANDS, SERVER_FLAGS };

package/hub-app.json

@@ -6,6 +6,11 @@
   "run": { "entry": "server.js", "defaultPort": 3541 },
   "publishes": ["session.changed"],
   "keys": { "keeps": ["ctrl+alt+n", "ctrl+alt+r", "ctrl+alt+s"] },
+  "plugin": {
+    "id": "claude-code-kanban@claude-code-kanban",
+    "path": "plugin/plugins/claude-code-kanban",
+    "install": "claude-code-kanban --install --yes"
+  },
   "provides": {
     "projects": { "path": "/api/projects" },
     "terminal": { "liveWork": "/api/terminals" }

package/lib/panes.js

@@ -11,7 +11,10 @@ const { pruneMap } = require('./retention');
 
 const MAX_PANES = 50;
 const MAX_TITLE = 100;
-const KINDS = new Set(['url', 'html', 'markdown', 'text', 'image']);
+const FILE_KINDS = new Set(['html', 'markdown', 'text', 'image']);
+const KINDS = new Set([...FILE_KINDS, 'url', 'message']);
+const MAX_MESSAGE_TARGET = 300;
+const isFileKind = (kind) => FILE_KINDS.has(kind);
 
 const portOf = (u) => Number(u.port || (u.protocol === 'https:' ? 443 : 80));
 
@@ -39,9 +42,10 @@ function isOwnOrigin(url, { boardPort, boardHosts = [], hubUrl }) {
 
 const emptyLayout = () => ({ rev: 0, nextId: 1, panes: [], updatedAt: null });
 
-const targetKey = (kind, target) => (kind === 'url' ? `url:${target}` : `file:${canonicalPath(target)}`);
+const targetKey = (kind, target) => (isFileKind(kind) ? `file:${canonicalPath(target)}` : `${kind}:${target}`);
 
 function defaultTitle(kind, target) {
+  if (kind === 'message') return 'Message';
   if (kind !== 'url') return path.basename(target);
   try {
     return new URL(target).host;
@@ -50,6 +54,8 @@ function defaultTitle(kind, target) {
   }
 }
 
+const paneTitle = (kind, target, title) => oneLine(title, MAX_TITLE) || oneLine(defaultTitle(kind, target), MAX_TITLE);
+
 const idNumber = (id) => Number(id.slice(1)) || 0;
 
 function cleanLayout(raw) {
@@ -118,8 +124,12 @@ function createPaneStore({ load, save, onChange = () => {}, now = Date.now }) {
   }
 
   // The same target added again returns its pane where it is, so a repeated `pane add` is harmless.
-  function add(sessionId, { kind, target, title }) {
+  // `show` marks a show card's file, which the board renders with the card's theme.
+  function add(sessionId, { kind, target, title, show }) {
     if (!KINDS.has(kind)) throw httpError(400, `Unknown pane kind: ${kind}`, 'bad_kind');
+    if (kind === 'message' && target.length > MAX_MESSAGE_TARGET) {
+      throw httpError(400, `A message target holds at most ${MAX_MESSAGE_TARGET} characters`, 'bad_target');
+    }
     reload();
     const layout = bySession.get(sessionId) || emptyLayout();
     const key = targetKey(kind, target);
@@ -130,7 +140,8 @@ function createPaneStore({ load, save, onChange = () => {}, now = Date.now }) {
       id: `p${layout.nextId++}`,
       kind,
       target,
-      title: oneLine(title, MAX_TITLE) || oneLine(defaultTitle(kind, target), MAX_TITLE),
+      title: paneTitle(kind, target, title),
+      ...(show && { show: true }),
       addedAt: now(),
     };
     layout.panes.push(pane);
@@ -148,6 +159,30 @@ function createPaneStore({ load, save, onChange = () => {}, now = Date.now }) {
     return write(sessionId, layout);
   }
 
+  // Drops the show panes of these files; returns the new layout, or null when none matched.
+  function removeShow(sessionId, files) {
+    reload();
+    const layout = bySession.get(sessionId);
+    if (!layout) return null;
+    const keys = new Set(files.map((f) => targetKey('html', f)));
+    const kept = layout.panes.filter((p) => !(p.show && keys.has(targetKey(p.kind, p.target))));
+    if (kept.length === layout.panes.length) return null;
+    layout.panes = kept;
+    return write(sessionId, layout);
+  }
+
+  // An empty title gives the pane its default title back. Returns null when the session has no such pane.
+  function rename(sessionId, paneId, title) {
+    reload();
+    const layout = bySession.get(sessionId);
+    const pane = layout?.panes.find((p) => p.id === paneId);
+    if (!pane) return null;
+    const next = paneTitle(pane.kind, pane.target, title);
+    if (next === pane.title) return get(sessionId);
+    pane.title = next;
+    return write(sessionId, layout);
+  }
+
   // `order` is every pane id of the session, in the new tab order.
   function reorder(sessionId, order) {
     reload();
@@ -171,12 +206,12 @@ function createPaneStore({ load, save, onChange = () => {}, now = Date.now }) {
   function fileTargets() {
     const out = new Set();
     for (const layout of bySession.values()) {
-      for (const p of layout.panes) if (p.kind !== 'url') out.add(p.target);
+      for (const p of layout.panes) if (isFileKind(p.kind)) out.add(p.target);
     }
     return out;
   }
 
-  return { get, add, remove, reorder, prune, reload, fileTargets };
+  return { get, add, remove, removeShow, rename, reorder, prune, reload, fileTargets };
 }
 
 module.exports = { createPaneStore, isOwnOrigin, portOf, MAX_PANES, MAX_TITLE };

package/lib/parsers.js

@@ -383,6 +383,11 @@ const modeOf = (data) => {
   return (data.type === 'user' || data.type === 'permission-mode') && data.permissionMode || null;
 };
 
+// Claude Code writes its environment, scratchpad dir included, at each process start, so a resume
+// in a worktree adds a second one: the last wins.
+const scratchpadOf = (data) =>
+  (data.type === 'attachment' && data.attachment?.type === 'environment' && data.attachment.snapshot?.scratchpadDirectory) || null;
+
 const isMainReply = (data) =>
   data.type === 'assistant' && !data.isSidechain && data.message?.usage && data.message.model !== '<synthetic>';
 
@@ -426,7 +431,7 @@ const withoutUsage = (reply) => reply && { ...reply, usage: null };
 // change or truncation (size < scannedUpTo).
 
 function readSessionInfoFromJsonl(jsonlPath) {
-  const result = { slug: null, projectPath: null, cwd: null, gitBranch: null, customTitle: null, agentName: null, logicalParentUuid: null, compactBoundaryUuid: null, permissionMode: null, cacheTtl: null, lastReply: null };
+  const result = { slug: null, projectPath: null, cwd: null, gitBranch: null, customTitle: null, agentName: null, logicalParentUuid: null, compactBoundaryUuid: null, permissionMode: null, cacheTtl: null, lastReply: null, scratchpadDir: null };
   let stat;
   let fd;
   try {
@@ -449,6 +454,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
       permissionMode: cached.permissionMode || null,
       cacheTtl: cached.cacheTtl || null,
       lastReply: cached.lastReply || null,
+      scratchpadDir: cached.scratchpadDir || null,
       ...pickTitles(readTitles(jsonlPath, stat))
     };
   }
@@ -463,6 +469,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
     result.permissionMode = cached.permissionMode || null;
     result.cacheTtl = cached.cacheTtl || null;
     result.lastReply = cached.lastReply || null;
+    result.scratchpadDir = cached.scratchpadDir || null;
   }
 
   let lastCwdSeen = result.cwd;
@@ -480,6 +487,8 @@ function readSessionInfoFromJsonl(jsonlPath) {
       if (mode) result.permissionMode = mode;
       const ttl = cacheTtlOf(data);
       if (ttl) result.cacheTtl = ttl;
+      const scratchpad = scratchpadOf(data);
+      if (scratchpad) result.scratchpadDir = scratchpad;
       if (isMainUser(data)) lastUserTs = data.timestamp;
       else if (isMainReply(data)) result.lastReply = replyOf(data, lastUserTs);
       if (data.subtype === 'compact_boundary') result.lastReply = withoutUsage(result.lastReply);
@@ -556,6 +565,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
         let latestTailCwd = null;
         let latestTailMode = null;
         let latestTailTtl = null;
+        let latestTailScratchpad = null;
         let tailReply = null;
         let tailRequestTs = null;
         let compactedAfterReply = false;
@@ -583,6 +593,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
             try {
               const data = JSON.parse(lines[i]);
               if (!latestTailTtl) latestTailTtl = cacheTtlOf(data);
+              if (!latestTailScratchpad) latestTailScratchpad = scratchpadOf(data);
               if (!result.slug && data.slug) result.slug = data.slug;
               if (!result.projectPath && data.cwd) result.projectPath = data.cwd;
               if (!result.gitBranch && data.gitBranch) result.gitBranch = data.gitBranch;
@@ -601,6 +612,8 @@ function readSessionInfoFromJsonl(jsonlPath) {
         if (latestTailCwd) lastCwdSeen = latestTailCwd;
         if (latestTailMode) result.permissionMode = latestTailMode;
         if (latestTailTtl) result.cacheTtl = latestTailTtl;
+        // A record in the unread middle would be newer than the head's, so the head's cannot be trusted.
+        if (latestTailScratchpad || !reachedHead) result.scratchpadDir = latestTailScratchpad;
         if (latestTailUserTs || !reachedHead) lastUserTs = latestTailUserTs;
         if (tailReply) {
           const reply = replyOf(tailReply, tailRequestTs);
@@ -635,6 +648,7 @@ function readSessionInfoFromJsonl(jsonlPath) {
       permissionMode: result.permissionMode,
       cacheTtl: result.cacheTtl,
       lastReply: result.lastReply,
+      scratchpadDir: result.scratchpadDir,
       lastUserTs
     });
     if (sessionInfoCache.size > SESSION_INFO_CACHE_MAX) {
@@ -1620,7 +1634,7 @@ async function readCompactSummaries(jsonlPath) {
         if (!text) continue;
         // Strip the "This session is being continued..." preamble if present.
         text = text.replace(/^This session is being continued[^\n]*\n+(The summary below[^\n]*\n+)?/i, '').trim();
-        if (text) results.push({ timestamp: obj.timestamp, summary: text });
+        if (text) results.push({ timestamp: obj.timestamp, summary: text, source: 'inline' });
       } catch (_) {}
     }
   } catch (_) {}
@@ -1651,7 +1665,7 @@ async function readCompactSummaries(jsonlPath) {
           for (const b of blocks) {
             if (b.type !== 'text' || !b.text) continue;
             const match = b.text.match(/<summary>([\s\S]*?)(?:<\/summary>|$)/);
-            if (match) { results.push({ timestamp: lastTs, summary: match[1].trim() }); found = true; break; }
+            if (match) { results.push({ timestamp: lastTs, summary: match[1].trim(), source: 'subagent' }); found = true; break; }
           }
           if (found) break;
         } catch (_) {}
@@ -1661,6 +1675,30 @@ async function readCompactSummaries(jsonlPath) {
   return results.sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
 }
 
+// A subagent summary's timestamp is the compact agent's last record, written just
+// before the parent's isCompactSummary record; compactions are minutes apart.
+const COMPACT_SUMMARY_MATCH_MS = 2 * 60 * 1000;
+
+function fillCompactSummaries(chips, summaries) {
+  const candidates = summaries.filter(s => s.source === 'subagent' && s.timestamp);
+  const used = new Set();
+  for (const chip of chips) {
+    if (chip.compactSummary || !chip.timestamp) continue;
+    const at = Date.parse(chip.timestamp);
+    let best = null;
+    let bestGap = COMPACT_SUMMARY_MATCH_MS;
+    for (const s of candidates) {
+      if (used.has(s)) continue;
+      const gap = Math.abs(Date.parse(s.timestamp) - at);
+      if (gap <= bestGap) { best = s; bestGap = gap; }
+    }
+    if (best) {
+      used.add(best);
+      chip.compactSummary = best.summary;
+    }
+  }
+}
+
 async function findTerminatedTeammates(jsonlPath) {
   return (await buildSessionDigest(jsonlPath)).terminated;
 }
@@ -2014,6 +2052,7 @@ module.exports = {
   buildAgentProgressMap,
   buildSessionDigest,
   readCompactSummaries,
+  fillCompactSummaries,
   readArtifactLinks,
   readScratchpadCreations,
   findTerminatedTeammates,

package/lib/retention.js

@@ -38,11 +38,24 @@ function pruneMap(map, atOf, { known, maxAgeMs, now }) {
   return removed;
 }
 
+const textOrNull = (v) => (typeof v === 'string' && v ? v : null);
+
+function dispatchedEntry(e) {
+  return {
+    parent: textOrNull(e.parent),
+    at: e.at,
+    name: textOrNull(e.name),
+    group: textOrNull(e.group),
+    cwd: textOrNull(e.cwd),
+    worktree: e.worktree === true ? true : textOrNull(e.worktree),
+  };
+}
+
 /**
  * Sessions started through `dispatch start`, kept after their terminal ends so the card
- * keeps its marker.
+ * keeps its marker, and across a restart so `dispatch list` finds a session cck resumes.
  * @param {object} o
- * @param {() => object|null} o.load returns `{version: 1, sessions: {[id]: {parent, at}}}` or null
+ * @param {() => object|null} o.load returns `{version: 1, sessions: {[id]: {parent, at, name, group, cwd, worktree}}}` or null
  * @param {(data: object) => void} o.save
  */
 function createDispatchedStore({ load, save, now = Date.now }) {
@@ -52,15 +65,15 @@ function createDispatchedStore({ load, save, now = Date.now }) {
   if (saved && typeof saved === 'object') {
     for (const [id, e] of Object.entries(saved)) {
       if (!e || !Number.isFinite(e.at)) continue;
-      entries.set(id, { parent: typeof e.parent === 'string' ? e.parent : null, at: e.at });
+      entries.set(id, dispatchedEntry(e));
     }
   }
 
   const persist = () => save({ version: 1, sessions: Object.fromEntries(entries) });
 
-  function record(id, parent) {
+  function record(id, info = {}) {
     entries.delete(id);
-    entries.set(id, { parent: parent || null, at: now() });
+    entries.set(id, dispatchedEntry({ ...info, at: now() }));
     if (entries.size > MAX_DISPATCHED) entries.delete(entries.keys().next().value);
     persist();
   }
@@ -72,7 +85,17 @@ function createDispatchedStore({ load, save, now = Date.now }) {
     return removed;
   }
 
-  return { record, prune, get: (id) => entries.get(id) || null, entries: () => entries.entries() };
+  // Derived, not kept: cck resumes every terminal on restart, and a list kept in memory
+  // would lose those sessions.
+  function running(isRunning, { parent } = {}) {
+    const out = [];
+    for (const [session, { at, ...m }] of entries) {
+      if (isRunning(session) && (!parent || m.parent === parent)) out.push({ session, ...m, startedAt: at });
+    }
+    return out;
+  }
+
+  return { record, prune, running, get: (id) => entries.get(id) || null, entries: () => entries.entries() };
 }
 
 // Names only, no stat or parse: the sweep needs which transcripts exist, not what they hold.
@@ -163,12 +186,37 @@ async function pruneContextStatus(dir, { known, maxAgeMs, now = Date.now(), max
   return removed;
 }
 
+// `<dir>/<task list id>.json` maps session id → `{project, updatedAt}`, written by the plugin mod.
+// A file with no sessions left is deleted.
+async function pruneTaskMaps(dir, { known, maxAgeMs, now = Date.now() }) {
+  let names;
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return 0;
+  }
+  let removed = 0;
+  for (const f of names.filter((n) => n.endsWith('.json'))) {
+    const file = path.join(dir, f);
+    try {
+      const map = new Map(Object.entries(JSON.parse(await fs.readFile(file, 'utf8'))));
+      const n = pruneMap(map, (e) => Date.parse(e?.updatedAt), { known, maxAgeMs, now });
+      if (!n) continue;
+      removed += n;
+      if (map.size) await fs.writeFile(file, JSON.stringify(Object.fromEntries(map)));
+      else await fs.rm(file, { force: true });
+    } catch {}
+  }
+  return removed;
+}
+
 module.exports = {
   pruneMap,
   createDispatchedStore,
   scanTranscripts,
   pruneSessionDirs,
   pruneContextStatus,
+  pruneTaskMaps,
   retentionMs,
   GRACE_MS,
   MAX_DISPATCHED,

package/lib/scratchpad-dir.js

@@ -4,6 +4,15 @@ const path = require('node:path');
 const { existsSync, opendirSync } = require('node:fs');
 const { encodeProjectDirName } = require('./claude-dir');
 
+// Claude Code's rule, from code.claude.com/docs/en/env-vars (CLAUDE_CODE_TMPDIR) and its 2.1.294
+// macOS, Linux and Windows builds. `overrides` are
+// candidate CLAUDE_CODE_TMPDIR values, first wins; a relative one is skipped.
+function scratchpadRoot({ platform, overrides, tmpdir, uid }) {
+  const p = platform === 'win32' ? path.win32 : path.posix;
+  const base = overrides.find((v) => typeof v === 'string' && p.isAbsolute(v)) || (platform === 'darwin' ? '/tmp' : tmpdir);
+  return p.join(base, platform === 'win32' || uid == null ? 'claude' : `claude-${uid}`);
+}
+
 function isEmptyDir(dir) {
   let handle;
   try {
@@ -16,11 +25,19 @@ function isEmptyDir(dir) {
   }
 }
 
-function createScratchpadDirResolver({ root, resolveWorktree, exists = existsSync, isEmpty = isEmptyDir }) {
+function createScratchpadDirResolver({ root, resolveWorktree, toLong = (p) => p, exists = existsSync, isEmpty = isEmptyDir }) {
   // A by-project dir that holds an entry always wins, so that answer is kept and never probed again.
   const settled = new Map();
+  // Long form per root, not per session: the recorded dir is <root>/<project>/<id>/scratchpad.
+  const longRoots = new Map();
 
   return function getScratchpadDir(id, meta) {
+    const recorded = meta.scratchpadDir;
+    if (recorded) {
+      const root = path.dirname(path.dirname(path.dirname(recorded)));
+      if (!longRoots.has(root)) longRoots.set(root, toLong(root));
+      return longRoots.get(root) + recorded.slice(root.length);
+    }
     if (!meta.jsonlPath) return null;
     const byProject = path.join(root, path.basename(path.dirname(meta.jsonlPath)), id, 'scratchpad');
     if (settled.get(id) === byProject) return byProject;
@@ -38,4 +55,4 @@ function createScratchpadDirResolver({ root, resolveWorktree, exists = existsSyn
   };
 }
 
-module.exports = { createScratchpadDirResolver };
+module.exports = { createScratchpadDirResolver, scratchpadRoot };

package/lib/session-cache.js

@@ -4,7 +4,7 @@ const { exportParentVerdicts, importParentVerdicts, parentVerdictsDirty } = requ
 const { exportTaskCounts, importTaskCounts, taskCountsDirty } = require('./task-counts');
 
 // Bump when an entry's shape or meaning changes: a file with another version is ignored.
-const VERSION = 6;
+const VERSION = 7;
 // A cache this large is not one cck wrote for a normal set of transcripts. Rebuild it cold.
 const MAX_BYTES = 8 * 1024 * 1024;