claude-code-kanban 7.3.0 → 7.5.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/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) {
@@ -120,6 +126,9 @@ 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 }) {
     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 +139,7 @@ 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),
       addedAt: now(),
     };
     layout.panes.push(pane);
@@ -148,6 +157,18 @@ function createPaneStore({ load, save, onChange = () => {}, now = Date.now }) {
     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 +192,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, 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) {

package/lib/retention.js

@@ -163,12 +163,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;
 

package/lib/session-events.js

@@ -5,13 +5,13 @@
 
 const { oneLine } = require('./one-line');
 
-// Tells a live session that the board moved one of its tasks. The postman monitor
-// (plugin/plugins/claude-code-kanban/scripts/postman.js) drains this queue and prints
-// each line, which Claude Code delivers into that session as a task notification.
+// Tells a live session that the board moved one of its tasks. The plugin's doorbell mod
+// (plugin/plugins/claude-code-kanban/hooks/doorbell.ts) drains this queue and submits the
+// lines to that session as a prompt.
 //
 // Deliberately in-memory and lossy. The task file is the durable command -- a dropped
 // event only means the agent notices on its next turn instead of immediately -- so a
-// disk queue would buy nothing. Reading consumes, so a restarted postman never replays
+// disk queue would buy nothing. Reading consumes, so a restarted session never replays
 // a backlog and acts on the same move twice.
 //
 // A bucket exists only while it holds something: an undelivered line or a waiting
@@ -28,20 +28,36 @@ const sessionEventBuckets = new Map();
 // last: truncation eats its tail first and leaves the machine-readable head intact.
 const sanitizeEventLine = (line) => oneLine(line, 1500);
 
-// Lines are plain sentences so they still read right once the skill that explains them has
-// left the agent's context. EVENT_PREFIX marks the board as the sender.
+// No skill explains the lines, so each one says what the user means by it. EVENT_PREFIX
+// marks the board as the sender.
 const EVENT_PREFIX = '[kanban board]';
 
+function moveMeaning(from, to) {
+  if (to === 'in_progress') {
+    return 'Start this task now, and set it to completed with TaskUpdate when the work is done.';
+  }
+  if (from === 'in_progress' && to === 'pending') return 'Stop working on it and park it.';
+  if (to === 'completed') return 'The user considers it done: do not keep working on it.';
+  if (to === 'cancelled') return 'Abandon it. Undo nothing unless asked.';
+  return '';
+}
+
 // Everything after `Description:` is the description verbatim to end of line, so no amount
 // of board text can pose as a further part of the line. That leaves the subject as the only
 // value that needs delimiting.
 function formatTaskMoved(taskId, prevStatus, task) {
   const subject = String(task.subject || '').replace(/(["\\])/g, '\\$1');
   const from = prevStatus ? ` from ${prevStatus}` : '';
-  const head = `${EVENT_PREFIX} The user moved task ${taskId} "${subject}"${from} to ${task.status}.`;
+  const meaning = moveMeaning(prevStatus, task.status);
+  const head = `${EVENT_PREFIX} The user moved task ${taskId} "${subject}"${from} to ${task.status}.${meaning ? ` ${meaning}` : ''}`;
   return task.description ? `${head} Description: ${task.description}` : head;
 }
 
+// The `boardEvents` section of <CCK_DIR>/config.json. On unless it says enabled: false.
+function boardEventsOn(cfg) {
+  return cfg?.boardEvents?.enabled !== false;
+}
+
 // The comments themselves live in the review file; the line only points at it, because a
 // batch of quotes would not survive the one-line cap. The path comes last and runs to end
 // of line, so a space in the config dir cannot split it.
@@ -50,7 +66,7 @@ function formatReviewSubmitted(count, label, reviewFile) {
   return `${EVENT_PREFIX} The user left ${comments} on ${label}. Address them: ${reviewFile}`;
 }
 
-// A postman between two polls has no waiter for a moment, so this can miss a live one.
+// A doorbell between two polls has no waiter for a moment, so this can miss a live one.
 // The caller then falls back to another route, which only costs a duplicate route, never
 // a lost review.
 function hasSessionListener(sessionId) {
@@ -66,7 +82,7 @@ function enqueueSessionEvent(sessionId, line) {
     sessionEventBuckets.set(sessionId, bucket);
   }
   bucket.queue.push(text);
-  // A session with no postman attached must not grow without bound.
+  // A session with no doorbell attached must not grow without bound.
   if (bucket.queue.length > 50) bucket.queue.splice(0, bucket.queue.length - 50);
   for (const wake of [...bucket.waiters]) wake();
 }
@@ -78,14 +94,13 @@ function clampWait(sec) {
   return Math.min(Math.max(Number(sec) || 0, 0), MAX_WAIT_SEC);
 }
 
-// Each topic rides its own bucket, so a postman on a topic never prints task moves the
-// user did not grant with the follow skill. No topic is the task-move bucket. Plugins
-// before 2.22.0 run a `--topic dispatch` postman, which must keep getting nothing.
+// Each topic rides its own bucket. No topic is the task-move bucket. Plugins before 2.22.0
+// run a `--topic dispatch` monitor, which must keep getting nothing.
 function topicKey(topic, sessionId) {
   return topic ? `${topic}:${sessionId}` : sessionId;
 }
 
-// Long-poll drained by the postman monitor. Routing stays in server.js; this is the handler.
+// Long-poll drained by the doorbell mod. Routing stays in server.js; this is the handler.
 function handleSessionEvents(req, res) {
   const topic = req.query.topic;
   if (topic !== undefined && !(typeof topic === 'string' && TOPIC_RE.test(topic))) {
@@ -95,11 +110,10 @@ function handleSessionEvents(req, res) {
   const bucket = sessionEventBuckets.get(sessionId);
   const wait = clampWait(req.query.wait);
 
-  // A postman is armed by a skill invocation, so it can attach long after the board moved
-  // something. Those lines are read as instructions, and an hours-old instruction is worse
-  // than no instruction, so the grant starts the session's history rather than inheriting
-  // it: `first=1` drops the whole backlog. drain() (not a bare truncate) so an emptied
-  // bucket is still evicted from the map.
+  // A doorbell can attach long after the board moved something (a resumed session, a board
+  // that came up later). Those lines are read as instructions, and an hours-old instruction
+  // is worse than no instruction, so `first=1` drops the whole backlog. drain() (not a bare
+  // truncate) so an emptied bucket is still evicted from the map.
   if (bucket && req.query.first === '1') drain(sessionId, bucket);
 
   if (bucket?.queue.length) return res.json({ events: drain(sessionId, bucket) });
@@ -133,6 +147,7 @@ module.exports = {
   sessionEventBuckets,
   sanitizeEventLine,
   formatTaskMoved,
+  boardEventsOn,
   formatReviewSubmitted,
   hasSessionListener,
   enqueueSessionEvent,

package/lib/task-dir.js

@@ -0,0 +1,26 @@
+const fs = require('node:fs').promises;
+const path = require('node:path');
+
+async function readTaskDir(dir) {
+  let files;
+  try {
+    files = (await fs.readdir(dir)).filter((f) => f.endsWith('.json'));
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+  const entries = await Promise.all(
+    files.map(async (file) => {
+      try {
+        const task = JSON.parse(await fs.readFile(path.join(dir, file), 'utf8'));
+        return task && typeof task === 'object' ? { file, task } : null;
+      } catch (e) {
+        console.error(`Error parsing ${path.join(dir, file)}:`, e.message);
+        return null;
+      }
+    }),
+  );
+  return entries.filter(Boolean);
+}
+
+module.exports = { readTaskDir };