claude-code-kanban 7.6.1 → 7.8.0

package/cli.js

@@ -1,8 +1,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { getClaudeDir, displayPath } = require('./lib/claude-dir');
-const { isGroupName, suggestGroupName } = require('./lib/dispatch-groups');
 const { linkUrl } = require('./public/link-url');
+const { sessionProjectKey } = require('./public/project-match');
 // Help is auto-generated from this table — keep flags/usage in sync with `run` behavior.
 const SESSION_FLAG = '--session <id>';
 const SESSION_FLAG_HELP = 'Session, full id or unique prefix (default: $PREVIEW_SESSION, else $CLAUDE_CODE_SESSION_ID)';
@@ -99,22 +99,23 @@ const COMMANDS = {
     },
   },
   session: {
-    summary: 'List, search, open and inspect Claude Code sessions',
+    summary: 'List, search, open, inspect and group Claude Code sessions',
     verbs: {
       list: {
-        summary: 'List sessions (pinned/sticky always included)',
-        usage: 'claude-code-kanban session list [--active] [--days <n>] [--project <name>] [--limit <n|all>] [--no-pins] [--json]',
+        summary: 'List the active sessions, as the sidebar\'s Active view shows them (pinned/sticky always included)',
+        usage: 'claude-code-kanban session list [--all] [--days <n>] [--project <name>] [--limit <n|all>] [--no-pins] [--json]',
         flags: {
-          '--active': 'Only sessions with recent activity (sidebar-style filter)',
+          '--all': 'Every session, active or not',
           '--days <n>': 'Only sessions modified within the last N days (fractional ok, e.g. 0.5)',
           '--project <name>': 'Filter by project: an absolute path selects one project, other text matches a part of the path',
-          '--limit <n|all>': 'Max rows to display (default: 10). Use "all" for no cap.',
+          '--limit <n|all>': 'Max rows to display (default: every active row; 20 with --all). Pinned sessions are kept past it.',
           '--no-pins': 'Disable always-include and sticky-first ordering for pinned sessions',
           '--json': 'Output JSON instead of a table',
         },
+        notes: 'Active: running in the terminal, or with messages and open tasks, live agents, a wait on the user or recent activity. STATUS is idle, active, busy (a task in progress) or wait. When --limit cuts the list, a last line says how many rows it shows of how many (on stderr with --json).',
         examples: [
-          'claude-code-kanban session list --active',
-          'claude-code-kanban session list --days 0.5 --limit all --project my-repo',
+          'claude-code-kanban session list',
+          'claude-code-kanban session list --all --days 0.5 --limit 20 --project my-repo',
         ],
         run: runSessionListCli,
       },
@@ -173,11 +174,11 @@ const COMMANDS = {
         run: runSessionAgentsCli,
       },
       pin: {
-        summary: 'Pin (or unpin) a session in the sidebar of connected browser tabs',
+        summary: 'Pin (or unpin) a session in the sidebar; every board on this config dir shows it',
         usage: 'claude-code-kanban session pin <id> [--sticky] [--unpin]',
         flags: {
           '<id>': 'Full session id, or a unique prefix',
-          '--sticky': 'Set sticky state (always shown, top of list)',
+          '--sticky': 'Set sticky state (always shown in the list)',
           '--unpin': 'Clear pin/sticky state',
         },
         examples: [
@@ -186,6 +187,99 @@ const COMMANDS = {
         ],
         run: runSessionPinCli,
       },
+      group: {
+        summary: 'Move a session into a group in the sidebar',
+        usage: 'claude-code-kanban session group <id> (<group> | --with <session> | --parent <session>) [--no-parent] [--create] [--json]',
+        flags: {
+          '<id>': 'Full session id, or a unique prefix',
+          '<group>': 'Group name (any case), path from the top (parent/child) or id, from `group list`',
+          '--with <session>': 'Join the group this other session shows in (id or unique prefix)',
+          '--parent <session>': 'Show the session under this one, indented, when both are in the same list; alone, it also joins its group',
+          '--no-parent': 'Show the session on its own again',
+          '--create': 'Make the group, and the missing parents of a path, when none matches; with --with, it holds both sessions',
+          '--json': 'Output JSON ({group, name, path, created, left, rev})',
+        },
+        notes: 'The session leaves the group it was in. In a group that holds its project, it shows in that project\'s block.',
+        examples: [
+          'claude-code-kanban session group $CLAUDE_SESSION_ID "Auth refactor"',
+          'claude-code-kanban session group 3fa9c1 auth-refactor/swarm-1 --create',
+          'claude-code-kanban session group 3fa9c1 --with $CLAUDE_SESSION_ID --create',
+          'claude-code-kanban session group 3fa9c1 --parent $CLAUDE_SESSION_ID',
+        ],
+        run: runSessionGroupCli,
+      },
+      ungroup: {
+        summary: 'Take a session out of its group',
+        usage: 'claude-code-kanban session ungroup <id> [--json]',
+        flags: {
+          '<id>': 'Full session id, or a unique prefix',
+          '--json': 'Output JSON ({left, rev})',
+        },
+        notes: 'A session whose project is in a group still shows there; move the project on the board.',
+        examples: ['claude-code-kanban session ungroup $CLAUDE_SESSION_ID'],
+        run: runSessionUngroupCli,
+      },
+    },
+  },
+  group: {
+    summary: 'Read and change the session groups in the sidebar',
+    verbs: {
+      list: {
+        summary: 'List the groups in sidebar order, nested groups under their parent, with the members the sidebar\'s Active view shows (active, pinned or sticky)',
+        usage: 'claude-code-kanban group list [--all] [--json]',
+        flags: {
+          '--all': 'Every member, active or not',
+          '--json': 'Output JSON ({rev, groups: [{id, name, parent, transient?, visible, total, members}]}); a session member has title, branch, status, pinned and age, or missing: true; a project member has sessions (its shown sessions)',
+        },
+        notes: 'A project member shows when it has a session the Active view shows. visible/total counts the members shown. A group marked (transient) goes when the board\'s Active view shows none of its sessions; Keep or a rename on the board, or `group rename`, keeps it. `dispatch start --group` and `group create --transient` make transient groups. Pass a group\'s name, path (parent/child) or id to `session group`.',
+        examples: ['claude-code-kanban group list', 'claude-code-kanban group list --all --json'],
+        run: runGroupListCli,
+      },
+      create: {
+        summary: 'Make a group, and the missing parents of a path',
+        usage: 'claude-code-kanban group create <name|path> [--transient] [--json]',
+        flags: {
+          '<name|path>': 'Name of a new top-level group, or a path from the top (parent/child)',
+          '--transient': 'The groups it makes go when the Active view shows none of their sessions',
+          '--json': 'Output JSON ({group, name, path, rev})',
+        },
+        notes: 'Fails when the group exists.',
+        examples: ['claude-code-kanban group create "Auth refactor"', 'claude-code-kanban group create auth-refactor/swarm-1'],
+        run: runGroupCreateCli,
+      },
+      rename: {
+        summary: 'Rename a group; it keeps its place, parent and members',
+        usage: 'claude-code-kanban group rename <group> <new name> [--json]',
+        flags: {
+          '<group>': 'Group name (any case), path from the top (parent/child) or id, from `group list`',
+          '<new name>': 'The new name',
+          '--json': 'Output JSON ({group, name, path, rev})',
+        },
+        examples: ['claude-code-kanban group rename auth-refactor "Auth v2"'],
+        run: runGroupRenameCli,
+      },
+      rm: {
+        summary: 'Remove a group, as Delete on the board does',
+        usage: 'claude-code-kanban group rm <group> [--json]',
+        flags: {
+          '<group>': 'Group name (any case), path from the top (parent/child) or id, from `group list`',
+          '--json': 'Output JSON ({removed: {id, name, path}, ungrouped, rev})',
+        },
+        notes: 'Its members leave the group and show as with no group: in their project\'s group or the top level. Its child groups move up one level.',
+        examples: ['claude-code-kanban group rm presales-cloud'],
+        run: runGroupRmCli,
+      },
+      prune: {
+        summary: 'Remove every empty group',
+        usage: 'claude-code-kanban group prune [--dry-run] [--json]',
+        flags: {
+          '--dry-run': 'List the groups it would remove, and remove none',
+          '--json': 'Output JSON ({removed: [{id, name, path}], dryRun, rev})',
+        },
+        notes: 'Empty: no session whose transcript still exists, no project, and no child group that is not empty. It checks every member, not only the ones the Active view shows.',
+        examples: ['claude-code-kanban group prune --dry-run', 'claude-code-kanban group prune'],
+        run: runGroupPruneCli,
+      },
     },
   },
   task: {
@@ -230,11 +324,11 @@ const COMMANDS = {
         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]] [--task-list [id]] [--json] [-- <claude args>...]',
         flags: {
-          '--cwd <dir>': 'Folder to run in (a known project, default: current dir)',
+          '--cwd <dir>': 'Folder to run in (any existing folder, default: current dir)',
           '--spec <text>': 'The task, self-contained; sent as the first message',
           '--spec-file <path>': 'Read the task from a file',
           '--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)',
+          '--group <g>': 'Add it to this group: a name, path or id. The groups it makes are transient (see `help group list`)',
           '--model <m>': 'fable, opus, sonnet or haiku',
           '--worktree [name]': 'Run in a new git worktree',
           '--task-list [id]': 'Use this task list instead of its own (default: this session\'s list), so its cards show on one board with yours. Off unless given',
@@ -271,6 +365,20 @@ const COMMANDS = {
       },
     },
   },
+  terminal: {
+    summary: 'Read the terminals running in cck',
+    verbs: {
+      list: {
+        summary: 'List every terminal in cck: dispatched, opened by hand, and Kanbot',
+        usage: 'claude-code-kanban terminal list [--json]',
+        flags: {
+          '--json': 'Output JSON',
+        },
+        notes: 'Read-only. `dispatch end` ends a terminal this session dispatched; the user ends the others from the board.',
+        run: runTerminalListCli,
+      },
+    },
+  },
   skills: {
     summary: 'Print a skill guide bundled with this version',
     verbs: {
@@ -359,26 +467,30 @@ const SERVER_FLAGS = [
   ['--yes', '', 'With --install: no prompt'],
 ];
 
-function printTopHelp() {
-  console.log('Usage: claude-code-kanban <command> [args] [--flags]\n');
-  console.log('Commands:');
+function topHelp() {
+  const lines = ['Usage: claude-code-kanban <command> [args] [--flags]\n', 'Commands:'];
   for (const [name, cmd] of Object.entries(COMMANDS)) {
     const verbs = cmd.verbs ? ` (${Object.keys(cmd.verbs).join(', ')})` : '';
-    console.log(`  ${name.padEnd(20)}${cmd.summary}${verbs}`);
+    lines.push(`  ${name.padEnd(20)}${cmd.summary}${verbs}`);
   }
-  console.log(`  ${'help'.padEnd(20)}Show help for a command (claude-code-kanban help <command>)`);
-  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 (no command; a flag wins over its env var):');
+  lines.push(`  ${'help'.padEnd(20)}Show help for a command (claude-code-kanban help <command>)`);
+  lines.push('\nFlags:');
+  lines.push('  --help, -h            Show help (top-level, noun-level, or leaf-level)');
+  lines.push('  --version, -v         Print version and exit');
+  lines.push('\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');
-  console.log('\nRun `claude-code-kanban help <command>` for its subcommands, and `help <command> <subcommand>` for flags and examples.');
+  for (const [flag, env, desc] of SERVER_FLAGS) lines.push(`  ${flag.padEnd(flagPad)}${env.padEnd(envPad)}${desc}`);
+  lines.push('\nCommand env:');
+  lines.push('  CCK_URL               Server base URL, e.g. http://127.0.0.1:4795 (wins over PORT)');
+  lines.push('  PORT                  Server port (default: the one this config dir\'s server reports, else 3541)');
+  lines.push('  CLAUDE_CONFIG_DIR     Claude config dir whose board to use');
+  lines.push('\nRun `claude-code-kanban help <command>` for its subcommands, and `help <command> <subcommand>` for flags and examples.');
+  return lines.join('\n');
+}
+
+function printTopHelp() {
+  console.log(topHelp());
 }
 
 function printNounHelp(noun) {
@@ -653,13 +765,13 @@ async function printLinkedDocs(sessionId, asJson) {
   } catch (e) { reportCliError(e); return 1; }
 }
 
-// Mirror of `isSessionActive` in public/app.js — keep in sync (different runtimes, no shared module).
-function isSessionActive(s) {
-  return s.hasRecentLog || s.inProgress > 0 || s.hasActiveAgents || s.hasWaitingForUser;
+function sessionTitle(s) {
+  return s.customTitle || s.name || s.slug || '';
 }
 
+// The board's badge rule (docs/session-states.md). `active` is a wider rule, for which rows show.
 function sessionStatus(s) {
-  if (!isSessionActive(s)) return 'idle';
+  if (!(s.hasRecentLog || s.inProgress > 0 || s.hasActiveAgents || s.hasWaitingForUser)) return 'idle';
   if (s.hasWaitingForUser) return 'wait';
   if (s.inProgress > 0) return 'busy';
   return 'active';
@@ -674,24 +786,29 @@ function parseLimit(args, { fallback, allowAll = false }) {
   return { ok: true, limit: n };
 }
 
-async function fetchSessionsList(limit, pinnedIds = [], project = null) {
+// `lite` leaves out the fields that can read a whole transcript (loopInfo).
+function sessionsListPath({ limit, noPins = false, include = [], project = null, activeOnly = false, lite = false }) {
   const q = limit === null ? 'all' : String(limit);
-  const pinnedQ = pinnedIds.length ? `&pinned=${pinnedIds.join(',')}` : '';
+  const pinsQ = noPins ? '&pins=off' : '';
+  const includeQ = include.length ? `&include=${include.map(encodeURIComponent).join(',')}` : '';
   const projectQ = project ? `&project=${encodeURIComponent(project)}` : '';
-  return cliGetJson(`/api/sessions?limit=${q}${pinnedQ}${projectQ}`, 'Session list');
+  const filterQ = activeOnly ? '&filter=active' : '';
+  const liteQ = lite ? '&lite=1' : '';
+  return `/api/sessions?limit=${q}${pinsQ}${includeQ}${projectQ}${filterQ}${liteQ}`;
 }
 
-function fetchSessionsByIds(ids, label) {
-  return cliGetJson(`/api/sessions?limit=1&include=${ids.map(encodeURIComponent).join(',')}`, label);
-}
+const fetchSessionsList = (opts, label = 'Session list') => cliGetJson(sessionsListPath(opts), label);
 
-async function fetchPinsMap() {
-  try {
-    const res = await cliFetch('/api/session/pins');
-    if (!res.ok) return {};
-    const { pins = {} } = await res.json();
-    return pins;
-  } catch { return {}; }
+const uniqueById = (list) => [...new Map(list.map((s) => [s.id, s])).values()];
+
+// The server refuses a request line above about 16 KB (431), about 430 ids, so the ids go in batches.
+const IDS_PER_REQUEST = 100;
+
+async function fetchSessionsByIds(ids, label, { lite = false } = {}) {
+  const batches = [];
+  for (let i = 0; i < ids.length; i += IDS_PER_REQUEST) batches.push(ids.slice(i, i + IDS_PER_REQUEST));
+  const lists = await Promise.all(batches.map((include) => fetchSessionsList({ limit: 1, include, lite }, label)));
+  return uniqueById(lists.flat());
 }
 
 async function resolveSessionByIdOrPrefix(idArg) {
@@ -720,7 +837,7 @@ async function resolveSessionByIdOrPrefix(idArg) {
 }
 
 async function runSessionListCli(args) {
-  const activeOnly = args.includes('--active');
+  const activeOnly = !args.includes('--all');
   const noPins = args.includes('--no-pins');
   const projectFilter = getArgValue(args, 'project');
   const daysArg = getArgValue(args, 'days');
@@ -728,40 +845,43 @@ async function runSessionListCli(args) {
   if (daysArg !== null && (Number.isNaN(days) || days <= 0)) {
     return usageError(COMMANDS.session.verbs.list, `Invalid --days value: ${daysArg}`);
   }
-  const parsed = parseLimit(args, { fallback: 10, allowAll: true });
+  // The Active view is short, so it has no cap. The server reads a whole transcript for some
+  // fields of each row it sends, so --all keeps one.
+  const parsed = parseLimit(args, { fallback: activeOnly ? null : 20, allowAll: true });
   if (!parsed.ok) return usageError(COMMANDS.session.verbs.list, parsed.error);
   const limit = parsed.limit;
   const asJson = args.includes('--json');
-  const pinsMap = noPins ? {} : await fetchPinsMap();
-  const pinnedIds = Object.keys(pinsMap);
-  const hasClientFilter = activeOnly || days !== null;
   let list;
+  let total;
   try {
-    list = await fetchSessionsList(hasClientFilter ? null : limit, pinnedIds, projectFilter);
+    const res = await cliGet(sessionsListPath({ limit: days !== null ? null : limit, noPins, project: projectFilter, activeOnly, lite: !asJson }), 'Session list');
+    list = await res.json();
+    total = Number(res.headers.get('x-total-count')) || list.length;
   } catch (e) {
     reportCliError(e);
     return 1;
   }
-  const pinOf = id => pinsMap[id] || null;
-  if (activeOnly) list = list.filter(s => pinOf(s.id) || isSessionActive(s));
   if (days !== null) {
     const cutoff = Date.now() - days * 86_400_000;
-    list = list.filter(s => pinOf(s.id) || (s.modifiedAt && new Date(s.modifiedAt).getTime() >= cutoff));
+    list = list.filter(s => s.pin || (s.modifiedAt && new Date(s.modifiedAt).getTime() >= cutoff));
+    total = list.length;
   }
-  const pinRank = id => pinOf(id) === 'sticky' ? 0 : pinOf(id) === 'pinned' ? 1 : 2;
+  const pinRank = s => s.pin === 'sticky' ? 0 : s.pin === 'pinned' ? 1 : 2;
   list.sort((a, b) => {
-    const r = pinRank(a.id) - pinRank(b.id);
+    const r = pinRank(a) - pinRank(b);
     if (r !== 0) return r;
     return new Date(b.modifiedAt || 0) - new Date(a.modifiedAt || 0);
   });
   if (limit !== null && list.length > limit) {
     const top = list.slice(0, limit);
     const topIds = new Set(top.map(s => s.id));
-    const extraPinned = list.filter(s => pinOf(s.id) && !topIds.has(s.id));
+    const extraPinned = list.filter(s => s.pin && !topIds.has(s.id));
     list = [...top, ...extraPinned];
   }
+  const cut = list.length < total ? `${list.length} of ${total} shown; --limit all shows every row` : null;
   if (asJson) {
-    console.log(JSON.stringify(list.map(s => ({ ...s, pinState: pinOf(s.id) })), null, 2));
+    console.log(JSON.stringify(list.map(({ pin, ...s }) => ({ ...s, pinState: pin || null })), null, 2));
+    if (cut) console.error(cut);
     return 0;
   }
   if (!list.length) {
@@ -770,12 +890,12 @@ async function runSessionListCli(args) {
   }
   const rows = list.map(s => ({
     id: s.id.slice(0, 8),
-    pin: pinOf(s.id) || '',
+    pin: s.pin || '',
     status: sessionStatus(s),
     age: s.modifiedAt ? formatAge(Date.now() - new Date(s.modifiedAt).getTime()) : '-',
     tasks: `${s.completed}/${s.taskCount}`,
     project: path.basename(s.project || ''),
-    title: s.customTitle || s.name || s.slug || '',
+    title: sessionTitle(s),
   }));
   const w = {
     id: 8,
@@ -789,6 +909,7 @@ async function runSessionListCli(args) {
   for (const r of rows) {
     console.log(`${r.id.padEnd(w.id)}  ${r.pin.padEnd(w.pin)}  ${r.status.padEnd(w.status)}  ${r.age.padEnd(w.age)}  ${r.tasks.padEnd(w.tasks)}  ${r.project.padEnd(w.project)}  ${r.title}`);
   }
+  if (cut) console.log(cut);
   return 0;
 }
 
@@ -829,13 +950,186 @@ async function runSessionPinCli(args) {
   const resolved = await resolveSessionByIdOrPrefix(idArg);
   if (!resolved) return 1;
   try {
-    if (!await cliPostJson('/api/session/pin', { id: resolved.id, state }, 'Pin')) return 1;
+    if (!await cliPostJson('/api/session/pin', { ids: [resolved.id], state }, 'Pin')) return 1;
     const label = state === 'none' ? 'unpinned' : state;
     console.log(`Session ${label}: ${resolved.id}${resolved.customTitle ? ` (${resolved.customTitle})` : ''}`);
     return 0;
   } catch (e) { reportCliError(e); return 1; }
 }
 
+const postSessionGroup = (id, body, label) => cliPostJson(`/api/sessions/${encodeURIComponent(id)}/group`, body, label);
+
+async function runSessionGroupCli(args, entry) {
+  const [idArg, groupArg] = positionals(args, ['--with', '--parent']);
+  const parentArg = getArgValue(args, 'parent');
+  const withFlag = getArgValue(args, 'with');
+  const noParent = args.includes('--no-parent');
+  if (!idArg || (!groupArg && !withFlag && !parentArg)) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  if (groupArg && withFlag) return usageError(entry, 'Give one of <group> or --with.');
+  if (parentArg && noParent) return usageError(entry, 'Give one of --parent or --no-parent.');
+  const [resolved, withPeer, parent] = await Promise.all([idArg, withFlag, parentArg].map((a) => a && resolveSessionByIdOrPrefix(a)));
+  if (!resolved || (withFlag && !withPeer) || (parentArg && !parent)) return 1;
+  // With no group, --parent also names the group to join.
+  const peer = withPeer || (!groupArg && parent);
+  const create = args.includes('--create');
+  const body = peer ? { with: peer.id, create } : { group: groupArg, create };
+  if (parent) body.parent = parent.id;
+  else if (noParent) body.parent = null;
+  try {
+    const out = await postSessionGroup(resolved.id, body, 'Group');
+    if (!out) return 1;
+    const { group, name, path, created, left, rev } = out;
+    if (args.includes('--json')) console.log(JSON.stringify({ group, name, path, created, left, rev }, null, 2));
+    else console.log(`Session ${resolved.id.slice(0, 8)} moved to ${created ? 'new ' : ''}group "${path}" (${group})`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runSessionUngroupCli(args, entry) {
+  const [idArg] = positionals(args, []);
+  if (!idArg) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  const resolved = await resolveSessionByIdOrPrefix(idArg);
+  if (!resolved) return 1;
+  try {
+    const out = await postSessionGroup(resolved.id, { group: null }, 'Ungroup');
+    if (!out) return 1;
+    const { left, rev } = out;
+    const short = resolved.id.slice(0, 8);
+    if (args.includes('--json')) console.log(JSON.stringify({ left, rev }, null, 2));
+    else console.log(left ? `Session ${short} left group "${left}"` : `Session ${short} was in no group`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function groupVerb(args, urlPath, body, label, line) {
+  try {
+    const out = await cliPostJson(urlPath, body, label);
+    if (!out) return 1;
+    console.log(args.includes('--json') ? JSON.stringify(out, null, 2) : line(out));
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runGroupCreateCli(args, entry) {
+  const [pathArg] = positionals(args, []);
+  if (!pathArg) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  const transient = args.includes('--transient');
+  return groupVerb(args, '/api/groups/path', { path: pathArg, transient }, 'Create', (r) => `Created group "${r.path}" (${r.group})${transient ? ', transient' : ''}`);
+}
+
+async function runGroupRenameCli(args, entry) {
+  const [groupArg, nameArg] = positionals(args, []);
+  if (!groupArg || !nameArg) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  return groupVerb(args, '/api/groups/rename', { group: groupArg, name: nameArg }, 'Rename', (r) => `Renamed group to "${r.path}" (${r.group})`);
+}
+
+async function runGroupRmCli(args, entry) {
+  const [groupArg] = positionals(args, []);
+  if (!groupArg) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  return groupVerb(args, '/api/groups/remove', { group: groupArg }, 'Remove', (r) =>
+    `Removed group "${r.removed.path}" (${r.removed.id})${r.ungrouped ? `; ${r.ungrouped} member${r.ungrouped === 1 ? '' : 's'} left it` : ''}`);
+}
+
+async function runGroupPruneCli(args) {
+  const dryRun = args.includes('--dry-run');
+  return groupVerb(args, '/api/groups/prune', { dryRun }, 'Prune', (r) => {
+    if (!r.removed.length) return 'No empty groups.';
+    return r.removed.map((g) => `${dryRun ? 'Would remove' : 'Removed'} "${g.path}" (${g.id})`).join('\n');
+  });
+}
+
+// A session member carries the session's metadata; a project member carries the count of its
+// sessions that are shown. With activeOnly, a member is shown when the sidebar's Active view
+// shows it: an active or pinned session, a project with one. A project counts the sessions the
+// sidebar puts under it: keyed as the board keys them, without those a group holds by id.
+function describeGroupMembers(groups, sessions, activeOnly) {
+  const byId = new Map(sessions.map((s) => [s.id, s]));
+  const shown = (s) => !activeOnly || s.active || !!s.pin;
+  const heldById = new Set(groups.flatMap((g) => g.members.filter((m) => m.type === 'session').map((m) => m.ref)));
+  const shownByProject = new Map();
+  for (const s of sessions) {
+    const key = sessionProjectKey(s);
+    if (!shown(s) || !key || heldById.has(s.id)) continue;
+    shownByProject.set(key, (shownByProject.get(key) || 0) + 1);
+  }
+  const describe = (m) => {
+    if (m.type === 'project') {
+      const count = shownByProject.get(m.ref) || 0;
+      return [!activeOnly || count > 0, { ...m, sessions: count }];
+    }
+    const s = byId.get(m.ref);
+    if (!s) return [!activeOnly, { ...m, missing: true }];
+    return [shown(s), {
+      ...m,
+      title: sessionTitle(s),
+      branch: s.gitBranch || null,
+      status: sessionStatus(s),
+      pinned: s.pin || null,
+      age: ageOf(s.modifiedAt),
+    }];
+  };
+  return groups.map((g) => {
+    const members = g.members.map(describe).filter(([visible]) => visible).map(([, m]) => m);
+    return { ...g, visible: members.length, total: g.members.length, members };
+  });
+}
+
+async function runGroupListCli(args) {
+  const activeOnly = !args.includes('--all');
+  let rev;
+  let groups;
+  try {
+    ({ rev, groups } = await cliGetJson('/api/groups', 'Group list'));
+    const sessionRefs = [...new Set(groups.flatMap((g) => g.members.filter((m) => m.type === 'session').map((m) => m.ref)))];
+    // An inactive session held by id is still listed, so only the active list needs the id lookups.
+    const lists = await Promise.all([
+      fetchSessionsList({ limit: null, activeOnly, lite: true }, 'Group list'),
+      activeOnly ? fetchSessionsByIds(sessionRefs, 'Group list', { lite: true }) : [],
+    ]);
+    const sessions = uniqueById(lists.flat());
+    groups = describeGroupMembers(groups, sessions, activeOnly);
+  } catch (e) { reportCliError(e); return 1; }
+  if (args.includes('--json')) {
+    console.log(JSON.stringify({ rev, groups }, null, 2));
+    return 0;
+  }
+  if (!groups.length) {
+    console.log('No groups.');
+    return 0;
+  }
+  const rows = [];
+  const add = (parent, depth) => {
+    const pad = '  '.repeat(depth);
+    for (const g of groups.filter((x) => x.parent === parent)) {
+      rows.push([g.id, '', '', '', `${pad}${g.name}${g.transient ? ' (transient)' : ''} (${g.visible}/${g.total})`]);
+      for (const m of g.members) {
+        if (m.type === 'project') rows.push(['project', '', '', '', `${pad}  ${m.ref} (${m.sessions} sessions)`]);
+        else if (m.missing) rows.push([m.ref.slice(0, 8), 'gone', '-', '', `${pad}  (no such session)`]);
+        else rows.push([m.ref.slice(0, 8), m.status, m.age, m.pinned || '', `${pad}  ${m.title}`]);
+      }
+      add(g.id, depth + 1);
+    }
+  };
+  add(null, 0);
+  printTable(['ID', 'STATUS', 'AGE', 'PIN', 'NAME'], rows);
+  return 0;
+}
+
 async function runSessionViewCli(args) {
   const idArg = args.find(a => !a.startsWith('--'));
   if (!idArg) {
@@ -860,7 +1154,7 @@ async function runSessionViewCli(args) {
     return 0;
   }
   const status = sessionStatus(s);
-  const title = s.customTitle || s.name || s.slug || '';
+  const title = sessionTitle(s);
   const age = s.modifiedAt ? formatAge(Date.now() - new Date(s.modifiedAt).getTime()) : '-';
   const fmtTok = (n) => typeof n === 'number' ? (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n)) : '-';
   const fmtCost = (n) => typeof n === 'number' ? `$${n.toFixed(2)}` : '-';
@@ -907,12 +1201,14 @@ function printTable(header, rows) {
 
 const ageOf = (iso) => (iso ? formatAge(Date.now() - new Date(iso).getTime()) : '-');
 
-async function cliGetJson(urlPath, label) {
+async function cliGet(urlPath, label) {
   const res = await cliFetch(urlPath);
   if (!res.ok) throw new Error(`${label} failed (${res.status}): ${await res.text()}`);
-  return res.json();
+  return res;
 }
 
+const cliGetJson = async (urlPath, label) => (await cliGet(urlPath, label)).json();
+
 async function runSessionSearchCli(args) {
   const entry = COMMANDS.session.verbs.search;
   const text = positionals(args, ['--limit']).join(' ').trim();
@@ -941,7 +1237,7 @@ async function runSessionSearchCli(args) {
       byId.has(s.id) ? sessionStatus(s) : '-',
       ageOf(s.modifiedAt),
       path.basename(s.project || ''),
-      s.customTitle || s.name || s.slug || '',
+      sessionTitle(s),
     ]));
     return 0;
   } catch (e) { reportCliError(e); return 1; }
@@ -1107,10 +1403,7 @@ async function runDispatchStartCli(argv) {
   }
   const hasGroup = args.some(a => a === '--group' || a.startsWith('--group='));
   const group = hasGroup ? getArgValue(args, 'group') || '' : null;
-  if (hasGroup && !isGroupName(group)) {
-    const hint = suggestGroupName(group);
-    return usageError(COMMANDS.dispatch.verbs.start, `Group names are kebab-case${hint ? `: try --group ${hint}` : ', e.g. auth-refactor'}`);
-  }
+  if (hasGroup && !group.trim()) return usageError(COMMANDS.dispatch.verbs.start, '--group needs a group name, path or id');
   const worktree = args.includes('--worktree') ? getArgValue(args, 'worktree') || true : false;
   const hasTaskList = args.some(a => a === '--task-list' || a.startsWith('--task-list='));
   const ownList = process.env.CLAUDE_CODE_TASK_LIST_ID || process.env.CLAUDE_CODE_SESSION_ID;
@@ -1133,7 +1426,8 @@ async function runDispatchStartCli(argv) {
     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 session ${out.session} in ${out.cwd}${out.group ? ` [${out.group}]` : ''}`);
+    else console.log(`Started session ${out.session} in ${out.cwd}${out.group ? ` [${out.group}${out.transient ? ', transient' : ''}]` : ''}`);
+    if (out.groupError) console.error(`Not grouped: ${out.groupError}`);
     return 0;
   } catch (e) { reportCliError(e); return 1; }
 }
@@ -1186,6 +1480,33 @@ async function runDispatchEndCli(args) {
   } catch (e) { reportCliError(e); return 1; }
 }
 
+function terminalKind(t, self) {
+  if (t.kanbot) return 'kanbot';
+  if (t.dispatched) return self && t.dispatched.parent === self ? 'dispatch (yours)' : 'dispatch';
+  return t.mode === 'shell' ? 'shell' : 'claude';
+}
+
+async function runTerminalListCli(args) {
+  let rows;
+  try {
+    rows = (await cliGetJson('/api/terminals', 'Terminal list')).sessions.sort((a, b) => b.startedAt - a.startedAt);
+  } catch (e) { reportCliError(e); return 1; }
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  if (!rows.length) {
+    console.log('No terminals.');
+    return 0;
+  }
+  const self = process.env.CLAUDE_CODE_SESSION_ID;
+  printTable(['SESSION', 'AGE', 'KIND', 'NAME', 'CWD'], rows.map(t => [t.id, ageOf(t.startedAt), terminalKind(t, self), t.name || '-', t.cwd || '-']));
+  if (rows.some(t => self && t.dispatched?.parent === self)) {
+    console.log('\nEnd one of yours with `claude-code-kanban dispatch end <session>`. The user ends the others from the board.');
+  }
+  return 0;
+}
+
 async function runSkillsGetCli(args) {
   const name = args.find(a => !a.startsWith('--'));
   const file = name && /^[a-z][a-z-]*$/.test(name) ? path.join(__dirname, 'skill-guides', `${name}.md`) : null;
@@ -1197,4 +1518,4 @@ async function runSkillsGetCli(args) {
   return 0;
 }
 
-module.exports = { runCli, COMMANDS, SERVER_FLAGS };
+module.exports = { runCli, topHelp, COMMANDS, SERVER_FLAGS };