claude-code-kanban 5.4.0 → 6.0.0

package/README.md

@@ -71,7 +71,7 @@ Run `claude` in any project. You do not configure anything per project. Claude C
 - **Answer prompts from the board.** When Claude asks for permission, asks a question or waits for plan approval, the session gets an amber highlight and the ask shows with Allow and Deny buttons or an answer form. The terminal prompt stays open, and the first answer wins. [Answer prompts from the board](https://nikiforovall.blog/claude-code-kanban/guides/waiting-prompts/)
 - **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. Add `--report` to get the outcome back. Needs the terminal. [Dispatch tasks to other sessions](https://nikiforovall.blog/claude-code-kanban/guides/dispatch/)
+- **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/)
 - **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/)
 
@@ -100,7 +100,7 @@ With no subcommand, `claude-code-kanban` starts the server. Subcommands talk to
 - `session list|search|open|view|plan|agents|pin|pins|peek` to read and focus sessions.
 - `task list` and `project list` to read tasks and projects.
 - `preview-doc` and `link-doc` to show or link a file on the board.
-- `dispatch start|done|wait|list` to start sessions with a task and collect their reports.
+- `dispatch start|list` to start sessions with a task in the board's terminal.
 
 Run `claude-code-kanban --help` or see the [CLI reference](https://nikiforovall.blog/claude-code-kanban/reference/cli/).
 

package/cli.js

@@ -180,58 +180,30 @@ const COMMANDS = {
     },
   },
   dispatch: {
-    summary: 'Start a Claude Code session for a task in cck and collect its report',
+    summary: 'Start a Claude Code session for a task in cck\'s terminal',
     verbs: {
       start: {
-        summary: 'Start a session with a task; prints the dispatch id',
-        usage: 'claude-code-kanban dispatch start --cwd <dir> (--spec <text> | --spec-file <path>) [--name <n>] [--group <g>] [--report] [--peer <name>] [--model <m>] [--worktree [name]] [--json]',
+        summary: 'Start claude in cck\'s terminal with a task; prints the session id',
+        usage: 'claude-code-kanban dispatch start --cwd <dir> (--spec <text> | --spec-file <path>) [--name <n>] [--group <g>] [--model <m>] [--worktree [name]] [--json] [-- <claude args>...]',
         flags: {
           '--cwd <dir>': 'Folder to run in (a known project, default: current dir)',
-          '--spec <text>': 'The task, self-contained',
+          '--spec <text>': 'The task, self-contained; sent as the first message',
           '--spec-file <path>': 'Read the task from a file',
-          '--name <n>': 'Session name',
+          '--name <n>': 'Session name; also its peer name for SendMessage',
           '--group <g>': 'Show it with this session in a kebab-case group (default: this session\'s group)',
-          '--report': 'Ask it to report its outcome back to this session',
-          '--peer <name>': 'This session\'s peer name; it sends questions and findings there with SendMessage',
           '--model <m>': 'fable, opus, sonnet or haiku',
           '--worktree [name]': 'Run in a new git worktree',
           '--json': 'Output JSON',
+          '-- <claude args>': 'Passed to claude as they are, e.g. --permission-mode auto. No quotes, % or control characters; cck sets --session-id, --name, --model and --worktree',
         },
-        notes: 'Needs the terminal token, so it runs on the machine of the cck server. Run `claude-code-kanban skills get dispatch` for how to write the spec.',
+        notes: 'Needs the terminal token, so it runs on the machine of the cck server. cck sends no report: say in the spec how the session reports back. Run `claude-code-kanban skills get dispatch` for how to write the spec.',
         examples: [
-          'claude-code-kanban dispatch start --cwd . --spec-file spec.md --name fix-login-redirect --group auth-refactor --peer my-peer --report --json',
+          'claude-code-kanban dispatch start --cwd . --spec-file spec.md --name fix-login-redirect --group auth-refactor --model sonnet -- --permission-mode auto',
         ],
         run: runDispatchStartCli,
       },
-      done: {
-        summary: 'Report the outcome of a dispatch (run by the started session)',
-        usage: 'claude-code-kanban dispatch done <id> --cap <cap> --outcome succeeded|failed (--summary <text> | --summary-file <path>)',
-        flags: {
-          '<id>': 'Dispatch id from the preamble',
-          '--cap <cap>': 'Capability from the preamble',
-          '--outcome <o>': 'succeeded or failed',
-          '--summary <text>': 'What changed, what was found, what remains',
-          '--summary-file <path>': 'Read the summary from a file',
-        },
-        examples: [
-          'claude-code-kanban dispatch done d_1a2b3c --cap <cap> --outcome succeeded --summary-file summary.md',
-        ],
-        run: runDispatchDoneCli,
-      },
-      wait: {
-        summary: 'Wait until a dispatch settles; a timeout is a checkpoint, not a failure',
-        usage: 'claude-code-kanban dispatch wait [<id>...] [--timeout <dur>] [--json]',
-        flags: {
-          '<id>': 'Dispatches to wait on (default: all started by this session)',
-          '--timeout <dur>': 'How long to wait, e.g. 90s, 15m, 1h (default: 10m)',
-          '--json': 'Output JSON',
-        },
-        notes: 'Returns as soon as any watched dispatch settles, with settled, running and timeout.',
-        examples: ['claude-code-kanban dispatch wait --timeout 15m --json'],
-        run: runDispatchWaitCli,
-      },
       list: {
-        summary: 'List dispatches started by this session',
+        summary: 'List sessions this session started that still run in cck\'s terminal',
         usage: 'claude-code-kanban dispatch list [--all] [--json]',
         flags: {
           '--all': 'Every dispatch on this board',
@@ -1042,19 +1014,10 @@ function textArg(args, name) {
   return file ? fs.readFileSync(path.resolve(file), 'utf8') : getArgValue(args, name);
 }
 
-function parseDuration(raw, fallbackSec) {
-  if (!raw) return fallbackSec;
-  const m = /^(\d+(?:\.\d+)?)(s|m|h)?$/.exec(raw);
-  if (!m) return null;
-  return Number(m[1]) * ({ s: 1, m: 60, h: 3600 }[m[2] || 's']);
-}
-
-function printDispatch(r) {
-  const head = `${r.id}  ${r.status.padEnd(9)} session=${r.session}${r.name ? `  ${r.name}` : ''}`;
-  console.log(r.summary ? `${head}\n  ${r.summary}` : head);
-}
-
-async function runDispatchStartCli(args) {
+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 port = cliTargetPort();
   if (port === null) {
     console.error(unreachable());
@@ -1085,73 +1048,27 @@ async function runDispatchStartCli(args) {
     model: getArgValue(args, 'model'),
     worktree,
     group,
-    report: args.includes('--report'),
-    peer: getArgValue(args, 'peer') || null,
+    claudeArgs,
     parent: process.env.CLAUDE_CODE_SESSION_ID || null,
   };
   try {
     const out = await cliPostJson('/api/dispatch', body, 'Dispatch', { 'x-terminal-token': token });
     if (!out) return 1;
     if (args.includes('--json')) console.log(JSON.stringify(out, null, 2));
-    else console.log(`Started ${out.dispatch} (session ${out.session}) in ${out.cwd}${out.group ? ` [${out.group}]` : ''}`);
-    return 0;
-  } catch (e) { reportCliError(e); return 1; }
-}
-
-async function runDispatchDoneCli(args) {
-  const [id] = positionals(args, ['--cap', '--outcome', '--summary', '--summary-file']);
-  let summary;
-  try { summary = textArg(args, 'summary'); } catch (e) { console.error(e.message); return 1; }
-  const body = { cap: getArgValue(args, 'cap'), outcome: getArgValue(args, 'outcome'), summary };
-  if (!id || !body.cap || !body.outcome) {
-    printLeafHelp(COMMANDS.dispatch.verbs.done);
-    return 1;
-  }
-  try {
-    if (!await cliPostJson(`/api/dispatch/${encodeURIComponent(id)}/done`, body, 'Report')) return 1;
-    console.log(`Reported ${id}: ${body.outcome}`);
-    return 0;
-  } catch (e) { reportCliError(e); return 1; }
-}
-
-function dispatchQuery(ids, all = false) {
-  const q = new URLSearchParams();
-  if (ids.length) q.set('ids', ids.join(','));
-  else if (!all && process.env.CLAUDE_CODE_SESSION_ID) q.set('parent', process.env.CLAUDE_CODE_SESSION_ID);
-  return q;
-}
-
-async function runDispatchWaitCli(args) {
-  const timeoutRaw = getArgValue(args, 'timeout');
-  const timeoutSec = parseDuration(timeoutRaw, 600);
-  if (timeoutSec === null) return usageError(COMMANDS.dispatch.verbs.wait, `Invalid --timeout value: ${timeoutRaw}`);
-  const q = dispatchQuery(positionals(args, ['--timeout']));
-  const deadline = Date.now() + timeoutSec * 1000;
-  try {
-    let out;
-    do {
-      q.set('wait', String(Math.max(1, Math.min(120, Math.ceil((deadline - Date.now()) / 1000)))));
-      const res = await cliFetch(`/api/dispatch?${q}`);
-      out = await res.json();
-    } while (out.timeout && Date.now() < deadline);
-    if (args.includes('--json')) console.log(JSON.stringify(out, null, 2));
-    else {
-      for (const r of out.settled) printDispatch(r);
-      if (out.running.length) console.log(`${out.timeout ? 'Timed out; still running' : 'Still running'}: ${out.running.map(r => r.id).join(' ')}`);
-      if (!out.settled.length && !out.running.length) console.log('No dispatches to wait on.');
-    }
+    else console.log(`Started session ${out.session} in ${out.cwd}${out.group ? ` [${out.group}]` : ''}`);
     return 0;
   } catch (e) { reportCliError(e); return 1; }
 }
 
 async function runDispatchListCli(args) {
+  const q = new URLSearchParams();
+  if (!args.includes('--all') && process.env.CLAUDE_CODE_SESSION_ID) q.set('parent', process.env.CLAUDE_CODE_SESSION_ID);
   try {
-    const res = await cliFetch(`/api/dispatch?${dispatchQuery([], args.includes('--all'))}`);
-    const { settled, running } = await res.json();
-    const rows = [...running, ...settled].sort((a, b) => b.startedAt - a.startedAt);
+    const res = await cliFetch(`/api/dispatch?${q}`);
+    const rows = (await res.json()).running.sort((a, b) => b.startedAt - a.startedAt);
     if (args.includes('--json')) console.log(JSON.stringify(rows, null, 2));
     else if (!rows.length) console.log('No dispatches.');
-    else rows.forEach(printDispatch);
+    else for (const r of rows) console.log(`${r.session}${r.name ? `  ${r.name}` : ''}${r.group ? `  [${r.group}]` : ''}`);
     return 0;
   } catch (e) { reportCliError(e); return 1; }
 }

package/lib/dispatch-groups.js

@@ -1,6 +1,5 @@
-// Transient session groups: `dispatch start --group` (or the starter's own group) puts
-// the started session in a group. The starter is not moved: it is only remembered, so its
-// later dispatches default to the same group. A group lives while any member's claude
+// Transient session groups: `dispatch start --group` puts the started session in a group,
+// and only an explicit `--group` does. A group lives while any member's claude
 // runs, and for a grace period after; once none runs, only pinned members stay in it.
 // The map is on disk so a pinned group outlives a server restart.
 
@@ -25,39 +24,28 @@ function suggestGroupName(s) {
 
 /**
  * @param {object} o
- * @param {() => object|null} o.load returns `{sessions: {[id]: group}, starters?: {[id]: starterId}}` or null
+ * @param {() => object|null} o.load returns `{sessions: {[id]: group}}` or null
  * @param {(data: object) => void} o.save
  * @param {(id: string) => boolean} o.isAlive
  * @param {() => Set<string>} o.pinnedIds
  */
 function createGroupStore({ load, save, isAlive, pinnedIds, now = Date.now }) {
   const members = new Map();
-  const starterOf = new Map();
   const liveAt = new Map();
   const saved = load();
   if (saved?.sessions && typeof saved.sessions === 'object') {
     for (const [id, g] of Object.entries(saved.sessions)) if (isGroupName(g)) members.set(id, g);
   }
-  if (saved?.starters && typeof saved.starters === 'object') {
-    for (const [id, s] of Object.entries(saved.starters)) if (members.has(id) && typeof s === 'string') starterOf.set(id, s);
-  }
   for (const g of members.values()) liveAt.set(g, now());
 
-  const persist = () =>
-    save({ version: 1, sessions: Object.fromEntries(members), starters: Object.fromEntries(starterOf) });
+  const persist = () => save({ version: 1, sessions: Object.fromEntries(members) });
 
-  function join(group, ids, starter) {
+  function join(group, ids) {
     let changed = false;
     for (const id of ids) {
-      if (!id) continue;
-      if (members.get(id) !== group) {
-        members.set(id, group);
-        changed = true;
-      }
-      if (starter && starterOf.get(id) !== starter) {
-        starterOf.set(id, starter);
-        changed = true;
-      }
+      if (!id || members.get(id) === group) continue;
+      members.set(id, group);
+      changed = true;
     }
     liveAt.set(group, now());
     if (changed) persist();
@@ -82,7 +70,6 @@ function createGroupStore({ load, save, isAlive, pinnedIds, now = Date.now }) {
       for (const id of ids) {
         if (pinned.has(id)) continue;
         members.delete(id);
-        starterOf.delete(id);
         changed = true;
       }
       if (!ids.some((id) => pinned.has(id))) liveAt.delete(g);
@@ -90,21 +77,12 @@ function createGroupStore({ load, save, isAlive, pinnedIds, now = Date.now }) {
     if (changed) persist();
   }
 
-  // A starter is not a member; it defaults to the group of a session it started.
-  function groupOf(id) {
-    refresh();
-    if (members.has(id)) return members.get(id);
-    let group = null;
-    for (const [child, starter] of starterOf) if (starter === id) group = members.get(child);
-    return group;
-  }
-
   function snapshot() {
     refresh();
     return members;
   }
 
-  return { join, groupOf, snapshot };
+  return { join, snapshot };
 }
 
 module.exports = { createGroupStore, isGroupName, suggestGroupName, GRACE_MS };

package/lib/dispatch.js

@@ -1,179 +1,32 @@
-// Dispatch: one Claude Code session started by another through cck, and the report it
-// settles with. In memory on purpose: the PTYs die with the server, so nothing a
-// restart drops could still settle.
-//
-// The child holds a per-dispatch capability, never the terminal token, so it can
-// report its own outcome and nothing else. A stale or duplicate child is refused
-// because a record settles once.
+// Dispatch: a Claude Code session one session started in cck's terminal. In memory on
+// purpose: an entry lives as long as its PTY, which dies with the server.
 
-const crypto = require('node:crypto');
-const { tokenMatches } = require('./terminal');
-const { clampWait, EVENT_PREFIX } = require('./session-events');
+function createDispatchRegistry({ now = Date.now } = {}) {
+  const entries = new Map();
 
-const OUTCOMES = new Set(['succeeded', 'failed']);
-const MAX_SUMMARY = 4000;
-// Settled records outlive their session long enough for a parent to collect them.
-const KEEP_SETTLED_MS = 24 * 60 * 60 * 1000;
-const ID_RE = /^d_[0-9a-f]{12}$/;
-// The peer name lands verbatim in the started session's prompt.
-const PEER_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-
-const isPeerName = (v) => typeof v === 'string' && PEER_RE.test(v);
-
-// With neither --report nor --peer the started session gets the task alone, like one the user typed.
-function formatPreamble(record, cli = 'claude-code-kanban') {
-  if (!record.report && !record.peer) return record.spec;
-  const lines = [`[cck dispatch ${record.id}] Another Claude Code session started you through claude-code-kanban to do the task below.`];
-  if (record.peer) {
-    lines.push(
-      `That session is the peer "${record.peer}". Ask it, not the user: when you need a decision, or find something that changes the task, send a short message with the SendMessage tool to "${record.peer}".`,
-      'Keep working on what does not depend on the answer. The reply arrives as a new message.',
-    );
-  }
-  if (record.report) {
-    lines.push(
-      'When the task is done, or you cannot finish it, report exactly once with this command, then stop:',
-      `${cli} dispatch done ${record.id} --cap ${record.cap} --outcome succeeded --summary "<what changed, what you found, what remains>"`,
-      record.peer
-        ? 'Use --outcome failed when the task cannot be finished. If the command refuses because the dispatch already ended, send the summary to the peer instead.'
-        : 'Use --outcome failed when the task is not done. Do not ask the user questions the other session must answer; report failed with the question instead.',
-    );
-  }
-  lines.push('', 'Task:', record.spec);
-  return lines.join('\n');
-}
-
-// The line reaches the parent through the postman at hook trust level; the summary is
-// last so no summary text can pose as a further field.
-const DISPATCH_OUTCOME = {
-  succeeded: 'reported success',
-  failed: 'reported failure',
-  exited: 'ended without a report',
-};
-
-function formatDispatchLine(r) {
-  const outcome = DISPATCH_OUTCOME[r.status] || r.status;
-  const head = `${EVENT_PREFIX} Dispatch ${r.id} (session ${r.session}) ${outcome}.`;
-  return r.summary ? `${head} Summary: ${r.summary}` : head;
-}
-
-function publicView(r) {
-  const { cap: _cap, ...rest } = r;
-  return rest;
-}
-
-function createDispatchRegistry({ onSettle, now = Date.now } = {}) {
-  const records = new Map();
-  const waiters = new Set();
-
-  function prune() {
-    const cutoff = now() - KEEP_SETTLED_MS;
-    for (const [id, r] of records) if (r.settledAt && r.settledAt < cutoff) records.delete(id);
-  }
-
-  function create({ parent, spec, name, report, peer, group, worktree }) {
-    prune();
-    const r = {
-      id: `d_${crypto.randomBytes(6).toString('hex')}`,
-      cap: crypto.randomBytes(16).toString('hex'),
+  function add({ session, parent, cwd, name, group, worktree }) {
+    entries.set(session, {
+      session,
       parent: parent || null,
-      session: null,
-      cwd: null,
+      cwd,
       name: name || null,
-      report: !!report,
-      peer: peer || null,
       group: group || null,
       worktree: worktree || null,
-      spec,
-      status: 'running',
-      summary: null,
       startedAt: now(),
-      settledAt: null,
-    };
-    records.set(r.id, r);
-    return r;
-  }
-
-  // The preamble carries the id, so the record exists before its session does.
-  function attach(id, { session, cwd }) {
-    const r = records.get(id);
-    if (r) Object.assign(r, { session, cwd });
-  }
-
-  function discard(id) {
-    records.delete(id);
-  }
-
-  function finish(r, status, summary) {
-    r.status = status;
-    r.summary = summary;
-    r.settledAt = now();
-    onSettle?.(r);
-    for (const wake of [...waiters]) wake();
-  }
-
-  // Returns null when settled, or {status, error} naming the refusal.
-  function settle(id, cap, outcome, summary) {
-    const r = typeof id === 'string' && ID_RE.test(id) ? records.get(id) : null;
-    if (!r) return { status: 404, error: 'no such dispatch' };
-    if (!tokenMatches(r.cap, cap)) return { status: 403, error: 'wrong capability' };
-    if (r.status !== 'running') return { status: 409, error: `already ${r.status}` };
-    if (!OUTCOMES.has(outcome)) return { status: 400, error: 'outcome must be succeeded or failed' };
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: strips control characters on purpose
-    const text = typeof summary === 'string' ? summary.replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, MAX_SUMMARY) : '';
-    finish(r, outcome, text || null);
-    return null;
-  }
-
-  // The PTY ended with no report: the parent must not wait on it forever.
-  function sessionExited(sessionId) {
-    for (const r of records.values()) if (r.session === sessionId && r.status === 'running') finish(r, 'exited', null);
-  }
-
-  function select({ ids, parent } = {}) {
-    prune();
-    let out = [...records.values()];
-    if (ids?.length) out = out.filter((r) => ids.includes(r.id));
-    else if (parent) out = out.filter((r) => r.parent === parent);
-    return out;
-  }
-
-  function list(filter) {
-    return select(filter).map(publicView);
+    });
   }
 
-  // Resolves once any selected record is settled, or after `waitSec`. Stateless for the
-  // caller: it passes the ids still running on the next call. `onClose(stop)` returns an
-  // unsubscribe, called once the wait ends.
-  function wait(filter, waitSec, onClose) {
-    const sec = clampWait(waitSec);
-    const snapshot = () => {
-      const rows = select(filter);
-      return {
-        settled: rows.filter((r) => r.status !== 'running').map(publicView),
-        running: rows.filter((r) => r.status === 'running').map(publicView),
-      };
-    };
-    const first = snapshot();
-    if (first.settled.length || !first.running.length || !sec) return Promise.resolve({ ...first, timeout: false });
-    return new Promise((resolve) => {
-      let unsubscribe;
-      const done = (timeout) => {
-        if (!waiters.delete(wake)) return;
-        clearTimeout(timer);
-        unsubscribe?.();
-        resolve({ ...snapshot(), timeout });
-      };
-      const wake = () => {
-        if (select(filter).some((r) => r.status !== 'running')) done(false);
-      };
-      const timer = setTimeout(() => done(true), sec * 1000);
-      waiters.add(wake);
-      unsubscribe = onClose?.(() => done(true));
-    });
+  function list({ parent } = {}) {
+    const out = [...entries.values()];
+    return parent ? out.filter((e) => e.parent === parent) : out;
   }
 
-  return { create, attach, discard, settle, sessionExited, list, wait };
+  return {
+    add,
+    list,
+    has: (session) => entries.has(session),
+    remove: (session) => entries.delete(session),
+  };
 }
 
-module.exports = { createDispatchRegistry, formatPreamble, formatDispatchLine, isPeerName, DISPATCH_OUTCOME };
+module.exports = { createDispatchRegistry };

package/lib/git-branch.js

@@ -44,4 +44,19 @@ function readGitBranch(cwd, readFile = (f) => fs.readFileSync(f, 'utf8')) {
   }
 }
 
-module.exports = { readGitBranch };
+/**
+ * Reads HEAD only where the transcript's `gitBranch` is wrong: cwd moved away from the launch
+ * project, or the project is a worktree (a `claude -w` session records the main checkout's
+ * branch on every line).
+ * @param {{cwd?: string, project?: string, gitBranch?: string}} meta
+ * @param {boolean} isWorktree whether `meta.project` is a linked worktree
+ * @param {(cwd: string) => string|null} branchAt
+ */
+function sessionGitBranch(meta, isWorktree, branchAt) {
+  if (meta.cwd && meta.project && (meta.cwd !== meta.project || isWorktree)) {
+    return branchAt(meta.cwd) || meta.gitBranch || null;
+  }
+  return meta.gitBranch || null;
+}
+
+module.exports = { readGitBranch, sessionGitBranch };

package/lib/retention.js

@@ -3,7 +3,6 @@
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const { readSettings } = require('./claude-settings');
-const { DISPATCH_OUTCOME } = require('./dispatch');
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_CLEANUP_DAYS = 30;
@@ -11,7 +10,6 @@ const DEFAULT_CLEANUP_DAYS = 30;
 // read that gap as a deleted transcript.
 const GRACE_MS = 60 * 60 * 1000;
 const MAX_DISPATCHED = 500;
-const OUTCOMES = new Set(Object.keys(DISPATCH_OUTCOME));
 
 // Only the config dir's settings: retention is per config dir, not per project.
 function retentionMs(claudeDir) {
@@ -28,10 +26,10 @@ function isExpired(id, at, { known, maxAgeMs, now }) {
 }
 
 /**
- * Sessions started through `dispatch start`, kept after the dispatch settles so the card
+ * Sessions started through `dispatch start`, kept after their terminal ends so the card
  * keeps its marker.
  * @param {object} o
- * @param {() => object|null} o.load returns `{version: 1, sessions: {[id]: {parent, status, at}}}` or null
+ * @param {() => object|null} o.load returns `{version: 1, sessions: {[id]: {parent, at}}}` or null
  * @param {(data: object) => void} o.save
  */
 function createDispatchedStore({ load, save, now = Date.now }) {
@@ -41,10 +39,7 @@ 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;
-      // The dispatch registry is in memory: a dispatch that was running when the server
-      // stopped can never settle, so it reads as ended.
-      const status = OUTCOMES.has(e.status) ? e.status : 'exited';
-      entries.set(id, { parent: typeof e.parent === 'string' ? e.parent : null, status, at: e.at });
+      entries.set(id, { parent: typeof e.parent === 'string' ? e.parent : null, at: e.at });
     }
   }
 
@@ -52,18 +47,11 @@ function createDispatchedStore({ load, save, now = Date.now }) {
 
   function record(id, parent) {
     entries.delete(id);
-    entries.set(id, { parent: parent || null, status: 'running', at: now() });
+    entries.set(id, { parent: parent || null, at: now() });
     if (entries.size > MAX_DISPATCHED) entries.delete(entries.keys().next().value);
     persist();
   }
 
-  function settle(id, status) {
-    const e = entries.get(id);
-    if (!e || e.status !== 'running' || !OUTCOMES.has(status)) return;
-    e.status = status;
-    persist();
-  }
-
   // Returns how many entries went; writes only when one did.
   function prune({ known, maxAgeMs }) {
     const t = now();
@@ -78,7 +66,7 @@ function createDispatchedStore({ load, save, now = Date.now }) {
     return removed;
   }
 
-  return { record, settle, prune, get: (id) => entries.get(id) || null };
+  return { record, prune, get: (id) => entries.get(id) || null };
 }
 
 // Names only, no stat or parse: the sweep needs which transcripts exist, not what they hold.

package/lib/session-events.js

@@ -79,8 +79,9 @@ function clampWait(sec) {
   return Math.min(Math.max(Number(sec) || 0, 0), MAX_WAIT_SEC);
 }
 
-// Each topic rides its own bucket, so the dispatch postman never prints task moves
-// the user did not grant with the follow skill. No topic is the task-move bucket.
+// 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.
 function topicKey(topic, sessionId) {
   return topic ? `${topic}:${sessionId}` : sessionId;
 }

package/lib/terminal.js

@@ -26,6 +26,17 @@ const PICK_START_SLACK_MS = 2000;
 const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9 ._-]{0,79}$/;
 const WORKTREE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const MODELS = new Set(['fable', 'opus', 'sonnet', 'haiku']);
+// Extra claude args reach the command line inside plain quotes (quoteArg), so a character
+// that ends or expands those quotes in any of the shells is refused.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: refuses control characters on purpose
+const EXTRA_ARG_RE = /^[^\x00-\x1f\x7f'"%]*$/;
+const MAX_EXTRA_ARGS = 64;
+const MAX_EXTRA_ARG = 4096;
+// cck sets these itself, or they would start something other than a new session.
+const OWNED_FLAGS = new Set([
+  '--session-id', '-n', '--name', '--model', '-w', '--worktree',
+  '-r', '--resume', '-c', '--continue', '--fork-session', '-p', '--print',
+]);
 const MAX_PROMPT = 32 * 1024;
 const PROMPT_QUIET_MS = 400;
 // Watermarks from https://xtermjs.org/docs/guides/flowcontrol/ — pause the PTY while a
@@ -118,8 +129,8 @@ function resolveShell(value, which, platform = process.platform, env = process.e
 }
 
 // claudeArgs is null for a plain shell. Its items are fixed flags, a validated UUID, or
-// values that passed NAME_RE / WORKTREE_RE, so plain quoting is enough to keep a space
-// from splitting an argument and nothing can break out of the quotes.
+// values that passed NAME_RE / WORKTREE_RE / EXTRA_ARG_RE, so plain quoting is enough to
+// keep a space from splitting an argument and nothing can break out of the quotes.
 function quoteArg(arg, family) {
   if (/^[A-Za-z0-9._-]+$/.test(arg)) return arg;
   return family === 'cmd' ? `"${arg}"` : `'${arg}'`;
@@ -142,7 +153,7 @@ function claudeArgsFor(mode, id, spec) {
   if (mode === 'fork') return ['--resume', id, '--fork-session'];
   if (mode === 'pick') return ['--resume'];
   if (mode === 'new') {
-    const args = ['--session-id', id];
+    const args = ['--session-id', id, ...(spec.extraArgs || [])];
     if (spec.name) args.push('--name', spec.name);
     if (spec.model) args.push('--model', spec.model);
     // Last, because its value is optional and a following flag must not be taken for it.
@@ -153,6 +164,16 @@ function claudeArgsFor(mode, id, spec) {
   return ['--resume', id];
 }
 
+function extraArgsError(args) {
+  if (!Array.isArray(args) || args.length > MAX_EXTRA_ARGS) return `claude args (at most ${MAX_EXTRA_ARGS})`;
+  for (const a of args) {
+    if (typeof a !== 'string' || a.length > MAX_EXTRA_ARG || !EXTRA_ARG_RE.test(a)) return 'claude arg: no quotes, % or control characters';
+    const flag = a.split('=')[0];
+    if (OWNED_FLAGS.has(flag)) return `claude arg: cck sets ${flag}`;
+  }
+  return null;
+}
+
 // Returns the new-session options from a hello, or a string naming the bad field.
 function parseNewSpec(msg) {
   if (typeof msg.cwd !== 'string' || !msg.cwd) return 'folder';
@@ -165,7 +186,10 @@ function parseNewSpec(msg) {
   // biome-ignore lint/suspicious/noControlCharactersInRegex: strips ESC so a prompt cannot carry terminal sequences
   const prompt = typeof msg.prompt === 'string' ? msg.prompt.replace(/\x1b/g, '').trim() : '';
   if (prompt.length > MAX_PROMPT) return 'prompt';
-  return { cwd: msg.cwd, name: name || null, worktree, model, prompt: prompt || null };
+  const extraArgs = msg.extraArgs ?? [];
+  const bad = extraArgsError(extraArgs);
+  if (bad) return bad;
+  return { cwd: msg.cwd, name: name || null, worktree, model, prompt: prompt || null, extraArgs };
 }
 
 function samePath(a, b) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "5.4.0",
+  "version": "6.0.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
   "type": "commonjs",