claude-code-kanban 7.3.0 → 7.5.0

package/lib/terminal.js

@@ -23,7 +23,7 @@ const priority = require('./priority');
 
 const WS_PATH = '/api/terminal/ws';
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const MODES = new Set(['auto', 'resume', 'fork', 'shell', 'new', 'pick']);
+const MODES = new Set(['auto', 'resume', 'shell', 'new', 'pick']);
 const PICK_POLL_MS = 1000;
 // How long before the PTY a registry entry may claim to have started (clock skew between the two).
 const PICK_START_SLACK_MS = 2000;
@@ -59,7 +59,6 @@ const RESTORE_GAP_MS = 2000;
 // The hub stops cck with `taskkill /f /t`, which can deliver the PTY exits to cck a moment
 // before cck itself dies. The delay keeps that teardown out of the saved list.
 const SAVE_DELAY_MS = 1000;
-// A fork runs under its parent's id until claude names the new one, so it has no id to resume.
 const RESTORABLE_MODES = new Set(['resume', 'new']);
 // Quitting claude drops the PTY to its shell, so the PTY's exit cannot tell cck that claude is gone.
 const CLAUDE_EXIT_POLL_MS = 5000;
@@ -177,10 +176,11 @@ function shellArgs(shell, claudeArgs) {
 
 function claudeArgsFor(mode, id, spec) {
   if (mode === 'shell') return null;
-  if (mode === 'fork') return ['--resume', id, '--fork-session'];
   if (mode === 'pick') return ['--resume'];
   if (mode === 'new') {
-    const args = ['--session-id', id, ...(spec.extraArgs || [])];
+    // claude takes --session-id with --resume only together with --fork-session.
+    const fork = spec.forkOf ? ['--resume', spec.forkOf, '--fork-session'] : [];
+    const args = [...fork, '--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.
@@ -203,7 +203,9 @@ function extraArgsError(args) {
 
 // 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';
+  const forkOf = msg.forkOf ?? null;
+  if (forkOf !== null && (typeof forkOf !== 'string' || !UUID_RE.test(forkOf))) return 'session to fork';
+  if (!forkOf && (typeof msg.cwd !== 'string' || !msg.cwd)) return 'folder';
   const name = typeof msg.name === 'string' ? msg.name.trim() : '';
   if (name && !NAME_RE.test(name)) return 'name';
   const worktree = msg.worktree ?? false;
@@ -222,7 +224,8 @@ function parseNewSpec(msg) {
   const extraArgs = msg.extraArgs ?? [];
   const bad = extraArgsError(extraArgs);
   if (bad) return bad;
-  return { cwd: msg.cwd, name: name || null, worktree, model, taskList, prompt: prompt || null, extraArgs, edit };
+  if (forkOf && worktree) return 'worktree: a fork runs in its parent session folder';
+  return { cwd: forkOf ? null : msg.cwd, forkOf, name: name || null, worktree, model, taskList, prompt: prompt || null, extraArgs, edit };
 }
 
 function samePath(a, b) {
@@ -248,7 +251,7 @@ function screenText(term) {
 
 // Claude Code keeps .claude.json beside ~/.claude when CLAUDE_CONFIG_DIR is unset but
 // inside the dir when set, so the default dir must stay unset, not be spelled out.
-// CCK_URL pins the CLI and the postman to this board: two boards on one config dir share
+// CCK_URL pins the CLI and the doorbell mod to this board: two boards on one config dir share
 // one server.json, and the last one started owns it.
 function ptyEnv({ claudeDir, isDefaultDir, noFlicker, cckUrl }) {
   const env = { ...process.env };
@@ -489,13 +492,7 @@ function createTerminalService(o) {
     if (s.claudeExitedAt) return null;
     if (s.claudePid || s.mode === 'pick') return s.claudePid;
     const live = registry || o.liveSessions();
-    const own = ownEntry(live, s, s.startedAt);
-    if (own || s.mode !== 'fork') {
-      s.claudePid = own?.pid;
-      return s.claudePid;
-    }
-    const claimed = new Set([...sessions.values()].map((x) => x.claudePid).filter(Boolean));
-    s.claudePid = findPickProcess(live, s, claimed);
+    s.claudePid = ownEntry(live, s, s.startedAt)?.pid;
     return s.claudePid;
   }
 
@@ -578,6 +575,7 @@ function createTerminalService(o) {
     const s = {
       id, mode, cwd, pty: proc, term, serializer, sockets: new Set(), exited: false, ended: false, paused: false, startedAt: Date.now(),
       name: spec?.name || null, worktree: spec?.worktree || false, taskList, onOutput: null, edit: !!spec?.edit,
+      forkOf: spec?.forkOf || null,
     };
     if (s.edit) queueText(s, claudeCommand(shell, claudeArgs, spec.prompt), false);
     else if (spec?.prompt) queueText(s, spec.prompt, true);
@@ -730,14 +728,16 @@ function createTerminalService(o) {
         return { code: 4002, status: 400, error: 'cmd cannot take a typed prompt; clear the prompt or set the terminal shell to pwsh or gitbash' };
       }
     }
-    const known = await o.resolveCwd(id);
+    // `claude --resume` finds a fork's parent only from the parent's own project folder.
+    const [known, forkCwd] = await Promise.all([o.resolveCwd(id), spec?.forkOf ? o.resolveCwd(spec.forkOf) : null]);
     let cwd = known;
     if (mode === 'new' || mode === 'pick') {
       if (known !== null) return { code: 4006, status: 409, error: 'session id already in use' };
-      if (typeof msg.cwd !== 'string' || !(await o.isAllowedFolder(msg.cwd))) {
+      cwd = spec?.forkOf ? forkCwd : msg.cwd;
+      if (spec?.forkOf && cwd === null) return { code: 4004, status: 404, error: 'unknown session to fork' };
+      if (!spec?.forkOf && (typeof cwd !== 'string' || !(await o.isAllowedFolder(cwd)))) {
         return { code: 4004, status: 403, error: 'folder is not a known project or a folder picked in this run' };
       }
-      cwd = msg.cwd;
     } else if (mode !== 'shell' && known === null) {
       return { code: 4004, status: 404, error: 'unknown session' };
     }
@@ -783,7 +783,7 @@ function createTerminalService(o) {
   function list() {
     return [...sessions.values()].filter((s) => !s.ended).map((s) => ({
       id: s.id, mode: s.mode, cwd: s.cwd, pid: s.pty.pid, clients: s.sockets.size, startedAt: s.startedAt,
-      name: s.name, worktree: s.worktree, edit: s.edit,
+      name: s.name, worktree: s.worktree, edit: s.edit, forkOf: s.forkOf,
     }));
   }
 
@@ -827,12 +827,11 @@ function createTerminalService(o) {
   }
 
   // Pastes into claude's input box and stops there: Enter would also submit whatever the
-  // user had half-typed, and over a permission dialog it would answer it. A fork runs under
-  // a new session id, so its terminal id does not name the session the text is for. A
-  // pending queued prompt owns the input box until it is sent.
+  // user had half-typed, and over a permission dialog it would answer it. A pending queued
+  // prompt owns the input box until it is sent.
   function paste(id, text) {
     const s = sessions.get(id);
-    if (!s || s.ended || s.exited || s.claudeExitedAt || s.onOutput || s.mode === 'shell' || s.mode === 'fork') return false;
+    if (!s || s.ended || s.exited || s.claudeExitedAt || s.onOutput || s.mode === 'shell') return false;
     if (onTrustScreen(s)) return false;
     // Until the user runs the typed command, the input box is the shell's command line.
     if (s.edit && !s.claudePid) return false;

package/package.json

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

package/plugin/plugins/claude-code-kanban/.claude-plugin/plugin.json

@@ -1,8 +1,5 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.25.2",
-  "description": "claude-code-kanban dashboard integration: agent activity tracking, context and cost tracking, skills to drive the board from a session and to follow it",
-  "experimental": {
-    "monitors": "./monitors.json"
-  }
+  "version": "3.0.1",
+  "description": "claude-code-kanban dashboard integration: agent activity tracking, context and cost tracking, board moves and reviews delivered to the session, and skills to drive the board from a session"
 }

package/plugin/plugins/claude-code-kanban/hooks/doorbell.ts

@@ -0,0 +1,80 @@
+import type { EngineInterface, Register } from 'claude-code'
+import { cckRoot } from './context'
+
+// $.http.fetch gives up on a request after 30 s, so the poll asks the board to answer sooner.
+export const WAIT_SEC = 25
+export const RETRY_MS = 10_000
+
+export function boardUrl(cckUrl: string | undefined, serverJson: string | undefined) {
+  if (cckUrl) return cckUrl.replace(/\/+$/, '')
+  try {
+    const { port } = JSON.parse(serverJson ?? '')
+    return Number.isInteger(port) ? `http://127.0.0.1:${port}` : undefined
+  } catch {
+    return undefined
+  }
+}
+
+let cck: Promise<string> | undefined
+
+// The engine does not follow $ into an imported function, so only the path rule is shared.
+function cckDir($: EngineInterface) {
+  cck ??= Promise.all([$.env.get('CLAUDE_CONFIG_DIR'), $.env.get('HOME'), $.env.get('USERPROFILE')]).then(
+    ([configDir, home, userProfile]) => cckRoot(configDir, home, userProfile),
+  )
+  return cck
+}
+
+// Read on every poll, so the mod follows a board that restarted on another port. CCK_URL comes
+// from the board whose terminal started this session, which owns the session's queue.
+async function findBoard($: EngineInterface) {
+  const cckUrl = await $.env.get('CCK_URL')
+  if (cckUrl) return boardUrl(cckUrl, undefined)
+  try {
+    return boardUrl(undefined, await $.fs.read(`${await cckDir($)}/server.json`))
+  } catch {
+    return undefined
+  }
+}
+
+async function poll($: EngineInterface, url: string, sessionId: string, first: boolean) {
+  const query = `wait=${WAIT_SEC}${first ? '&first=1' : ''}`
+  const r = await $.http.fetch(`${url}/api/sessions/${encodeURIComponent(sessionId)}/events?${query}`)
+  if (!r.ok) throw new Error(`HTTP ${r.status}`)
+  const { events } = JSON.parse(r.text) as { events?: unknown }
+  return Array.isArray(events) ? events.filter((e): e is string => typeof e === 'string') : []
+}
+
+// The session id changes on /clear, so it is read for every poll. The first poll for an id drops
+// what the board queued before this session listened: a move from hours ago is not an instruction.
+async function listen($: EngineInterface) {
+  let attached: string | undefined
+  for (;;) {
+    const [url, sessionId] = await Promise.all([findBoard($), $.session.id()])
+    let events: string[] | undefined
+    try {
+      if (url) events = await poll($, url, sessionId, attached !== sessionId)
+    } catch {}
+    if (!events) {
+      await $.clock.sleep(RETRY_MS)
+      continue
+    }
+    attached = sessionId
+    // A submit waits until the session is idle, and one prompt keeps a burst of moves in one turn.
+    if (events.length) await $.prompt.submit({ text: events.join('\n') }).catch(() => {})
+  }
+}
+
+let listening = false
+
+// Only a session with a person at the prompt listens: a -p run ends on its own and must not wait on an open poll.
+export const register: Register = on => {
+  on('session.start', { isInteractive: true }, async ($, e, next) => {
+    const result = await next(e)
+    if (!listening) {
+      listening = true
+      void listen($)
+    }
+    return result
+  })
+}

package/plugin/plugins/claude-code-kanban/hooks/index.ts

@@ -1,8 +1,10 @@
 import type { Register } from 'claude-code'
 import { register as activity } from './activity'
 import { register as context } from './context'
+import { register as doorbell } from './doorbell'
 
 export const register: Register = (on, options) => {
   context(on, options)
   activity(on, options)
+  doorbell(on, options)
 }

package/plugin/plugins/claude-code-kanban/skills/kanban/SKILL.md

@@ -19,7 +19,7 @@ This session id is `${CLAUDE_SESSION_ID}`. `--session` defaults to it through `$
 | `session` | `list` · `search <text>` · `open <id>` focuses it · `view <id>` stats and transcript path · `plan <id>` · `agents <id>` · `pin <id>` |
 | `task` | `list` for a session, a project or the whole board |
 | `project` | `list` |
-| `dispatch` | `start`, `list` — run `/claude-code-kanban:dispatch` instead |
+| `dispatch` | `start`, `list`, `end` — run `/claude-code-kanban:dispatch` instead |
 
 ## Run a command
 
@@ -38,8 +38,6 @@ To show the user a page, a prototype or a collage of screenshots, write it as HT
 
 Read its transcript. `session view <id>` and `session search <text> --json` print the path.
 
-To have card moves arrive in this session as instructions, the user types `/claude-code-kanban:follow`.
-
 ## Troubleshooting
 
 - **"Cannot reach cck server…"** → the error names the config dir and the port it tried. Ask the user to start the server with `claude-code-kanban`. If it runs elsewhere, set `PORT=<n>` or `CCK_URL=<url>` when invoking the CLI.

package/plugin/plugins/claude-code-kanban/tests/doorbell.test.ts

@@ -0,0 +1,74 @@
+import type { On } from 'claude-code'
+import { expect, mock, test } from 'claude-code/testing'
+import { boardUrl, RETRY_MS } from '../hooks/doorbell'
+
+test('the board URL comes from CCK_URL, else from server.json', async () => {
+  expect(boardUrl('http://127.0.0.1:4000/', '{"port":3541}')).toBe('http://127.0.0.1:4000')
+  expect(boardUrl(undefined, '{"port":3541}')).toBe('http://127.0.0.1:3541')
+  expect(boardUrl(undefined, '{"port":"3541"}')).toBe(undefined)
+  expect(boardUrl(undefined, 'not json')).toBe(undefined)
+  expect(boardUrl(undefined, undefined)).toBe(undefined)
+})
+
+function engine(on: On, replies: (() => { status: number; events?: string[] })[]) {
+  const urls: string[] = []
+  const prompts: string[] = []
+  let sessionId = 'sid-1'
+  on('fs.read', (_$, e) => {
+    if (e.path.replaceAll('\\', '/') === 'C:/cfg/.cck/server.json') return { value: '{"port":3541}' }
+    throw new Error(`ENOENT: ${e.path}`)
+  })
+  on('env.get', (_$, e) => ({ value: { CLAUDE_CONFIG_DIR: 'C:/cfg' }[e.name] }))
+  on('session.id', () => ({ value: sessionId }))
+  on('session.start', (_$, e) => ({ cwd: e.cwd }))
+  on('http.fetch', async (_$, e) => {
+    urls.push(e.url)
+    const reply = replies.shift()
+    if (!reply) return new Promise(() => {})
+    const { status, events = [] } = reply()
+    return { value: { status, ok: status < 300, headers: {}, text: JSON.stringify({ events }) } }
+  })
+  on('prompt.submit', (_$, e) => {
+    prompts.push(e.text)
+    return { text: e.text }
+  })
+  return { urls, prompts, clear: () => (sessionId = 'sid-2') }
+}
+
+test('a -p run does not poll the board', async ($, on) => {
+  const clock = mock.clock(on)
+  const board = engine(on, [])
+  await $.session.start({ cwd: 'C:/proj', surface: null, isInteractive: false })
+  await clock.settle()
+  expect(board.urls).toEqual([])
+})
+
+test('polls the board, submits a burst as one prompt, and drops the backlog for a new session id', async ($, on) => {
+  const clock = mock.clock(on)
+  const replies = [
+    () => ({ status: 200, events: ['line one', 'line two'] }),
+    () => ({ status: 503 }),
+    () => {
+      board.clear()
+      return { status: 200 }
+    },
+    () => ({ status: 200, events: ['after clear'] }),
+  ]
+  const board = engine(on, replies)
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  await clock.settle()
+
+  expect(board.prompts).toEqual(['line one\nline two'])
+  expect(board.urls).toEqual([
+    'http://127.0.0.1:3541/api/sessions/sid-1/events?wait=25&first=1',
+    'http://127.0.0.1:3541/api/sessions/sid-1/events?wait=25',
+  ])
+
+  await clock.advance(RETRY_MS)
+  expect(board.urls.slice(2)).toEqual([
+    'http://127.0.0.1:3541/api/sessions/sid-1/events?wait=25',
+    'http://127.0.0.1:3541/api/sessions/sid-2/events?wait=25&first=1',
+    'http://127.0.0.1:3541/api/sessions/sid-2/events?wait=25',
+  ])
+  expect(board.prompts).toEqual(['line one\nline two', 'after clear'])
+})