claude-code-kanban 5.3.0 → 6.0.0

package/plugin/plugins/claude-code-kanban/scripts/postman.js

@@ -26,13 +26,9 @@ const SERVER_INFO = path.join(CLAUDE_DIR, '.cck', 'server.json');
 // because an enqueue wakes the poll immediately.
 const WAIT_SEC = 120;
 const RETRY_MS = 15000;
-// Windows sometimes fails a loopback connect with ETIMEDOUT while the board is up, so that
-// error gets a few short waits before the normal one.
+// Windows sometimes fails a loopback connect with ETIMEDOUT, or resets it once open, while the
+// board is up, so those errors get a few short waits before the normal one.
 const CONNECT_RETRY_MS = [250, 500, 1000, 2000];
-// `--topic dispatch` is the dispatch inbox: reports from sessions this one started.
-const TOPIC = process.argv.includes('--topic') ? process.argv[process.argv.indexOf('--topic') + 1] : null;
-// A dispatch report is a result, not an instruction, so a late attach still wants it.
-const KEEP_BACKLOG = process.argv.includes('--keep-backlog');
 
 if (!SESSION_ID) process.exit(0);
 
@@ -53,12 +49,11 @@ function serverUrl() {
 // Once per process, not once per poll: the grant means "follow the board from here on", so
 // the first attach throws away whatever queued up before it. A later reconnect must not
 // discard again -- by then the queue holds events the user is owed.
-let firstAttach = !KEEP_BACKLOG;
+let firstAttach = true;
 
 async function poll(base) {
   const first = firstAttach ? '&first=1' : '';
-  const topic = TOPIC ? `&topic=${encodeURIComponent(TOPIC)}` : '';
-  const url = `${base}/api/sessions/${encodeURIComponent(SESSION_ID)}/events?wait=${WAIT_SEC}${first}${topic}`;
+  const url = `${base}/api/sessions/${encodeURIComponent(SESSION_ID)}/events?wait=${WAIT_SEC}${first}`;
   const res = await fetch(url, { signal: AbortSignal.timeout((WAIT_SEC + 15) * 1000) });
   if (!res.ok) throw new Error(`HTTP ${res.status}`);
   firstAttach = false;
@@ -75,8 +70,8 @@ async function poll(base) {
     } catch (e) {
       // No board yet, or it went away. It may come back later in the session, so keep
       // waiting quietly -- a missing server is the normal case, not an error.
-      const timedOut = e.cause?.code === 'ETIMEDOUT' && e.cause?.syscall === 'connect';
-      if (timedOut && connectRetries < CONNECT_RETRY_MS.length) {
+      const blip = (e.cause?.code === 'ETIMEDOUT' && e.cause?.syscall === 'connect') || e.cause?.code === 'ECONNRESET';
+      if (blip && connectRetries < CONNECT_RETRY_MS.length) {
         await sleep(CONNECT_RETRY_MS[connectRetries++]);
       } else {
         connectRetries = 0;

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

@@ -1,23 +1,29 @@
 ---
 name: dispatch
-description: Dispatch a task to another Claude Code session through the kanban board (cck), fire-and-forget or with a report back. Use when the user asks to dispatch, delegate, or start a session for a task, or to collect or check on a dispatched session's result.
-argument-hint: '<task> [--no-report] [--group <name>] [--model haiku|sonnet|opus|fable] [--worktree [name]]'
+description: Dispatch tasks to new Claude Code sessions in the kanban board's terminal. Use when the user asks to dispatch or delegate a task to another session.
+argument-hint: '<task> [--handoff] [--group <name>] [--model haiku|sonnet|opus|fable] [--worktree [name]] [-- <claude args>]'
 ---
 
 # Kanban dispatch
 
-This file only points at the guide. The guide ships with the `claude-code-kanban` binary, so it always matches the commands that binary accepts.
-
-Invoking this skill also arms this session's dispatch inbox: when a session you dispatched with `--report` reports or exits, a line arrives here:
-
-```
-[kanban board] Dispatch <dispatch-id> (session <uuid>) <reported success|reported failure|ended without a report>. Summary: <text>
-```
-
-Load the guide before running any dispatch command:
+The guide ships with the `claude-code-kanban` binary, so it always matches the commands that binary accepts. Load it before running any dispatch command:
 
 ```bash
 claude-code-kanban skills get dispatch
 ```
 
 Fall back to `npx claude-code-kanban` when the bare binary is not on PATH. If `skills get` is unknown, the installed cck is too old: tell the user to update it, and do not guess commands.
+
+## Reply
+
+End every spec with the reply line, because you usually need the result to continue:
+
+```text
+When you are done, or cannot finish, send the result to <your peer name> with the SendMessage tool, then stop.
+```
+
+`--handoff` is a skill argument that drops the reply line: the session owns the task, and the user follows it on the board. Keep it out of the `dispatch start` command.
+
+## Orchestration patterns
+
+Use request-reply, handoff or orchestrator-workers directly. When another shape fits better (a separate reviewer, steps that feed each other, a sub-orchestrator, a decision for the user), propose it in one line, the pattern and why, and dispatch only after the user agrees, unless the user named it. Details: [references/orchestration-patterns.md](references/orchestration-patterns.md).

package/plugin/plugins/claude-code-kanban/skills/dispatch/references/orchestration-patterns.md

@@ -0,0 +1,50 @@
+# Orchestration patterns
+
+Each pattern is only `dispatch start` plus `SendMessage`; the specs decide who talks to whom. A **worker** is a session you dispatch.
+
+## Select
+
+Use one of these directly:
+
+| Pattern | When |
+|---|---|
+| Request-reply | The default |
+| Handoff | The user passed `--handoff` or asked for no reply |
+| Orchestrator-workers | The task splits into parts that do not depend on each other |
+
+Propose these first, unless the user named one. Each adds steps, rounds or sessions the user did not ask for.
+
+| Pattern | Fits when |
+|---|---|
+| Prompt chaining | A step needs the previous step's output |
+| Evaluator-optimizer | There is a clear acceptance bar and a second look improves the result |
+| Hierarchical | A part is itself large enough to split |
+| Human-in-the-loop | The spec leaves a choice the user should make |
+
+## Request-reply
+
+One worker, one reply. The reply can go to any peer. When another session owns the work and should act on the result, name it in the reply line, and ask for a one-line note to you as well, so you know the worker finished.
+
+## Handoff
+
+One worker, no reply line. The worker owns the task, and you save the turn a reply costs.
+
+## Orchestrator-workers
+
+One worker per independent part, all started before you wait on any. They run at the same time, and each holds only its own part in context. Give each a unique `--name` and one shared `--group`, then combine the replies.
+
+## Prompt chaining
+
+Workers in sequence; each spec carries the previous reply. You check each output before you start the next step, and stop the chain when a check fails.
+
+## Evaluator-optimizer
+
+A generator and an evaluator that message each other until the evaluator accepts. A separate evaluator judges the work with fresh eyes. Give each the other's name, and cap the rounds in both specs: `stop after 3 rounds and send what you have`.
+
+## Hierarchical
+
+A worker that dispatches its own workers and replies once they all have. Your context then holds one reply per part instead of one per leaf. Its spec says to wait for its workers and to give them its own peer name.
+
+## Human-in-the-loop
+
+Add to the worker's spec: `When you need a decision, ask <your peer name> with the SendMessage tool and keep working on what does not depend on the answer.` Ask the user when the decision is theirs, and reply with `SendMessage`. You can steer a running worker the same way at any time.

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

@@ -0,0 +1,300 @@
+import type { On, ToolCallArgs, ToolCheckDecision } from 'claude-code'
+import { type Engine, expect, type MockClock, mock, test } from 'claude-code/testing'
+import { BOARD_ALLOWED, CLEARED } from '../hooks/activity'
+
+const ROOT = 'C:/cfg/.cck/agent-activity'
+const SESSION = `${ROOT}/sid-1`
+const MARKER = `${SESSION}/_waiting.json`
+const CONFIG = 'C:/cfg/.cck/config.json'
+
+type EngineOptions = { decision?: ToolCheckDecision; rule?: string; env?: Record<string, string> }
+
+// A test hook cannot raise tool.check, so the test raises it (askFor), and the engine's tool.call
+// holds the first call until the test answers the terminal prompt.
+function engine(on: On, files: Record<string, string>, { decision = 'allow', rule, env = {} }: EngineOptions = {}) {
+  const writes: { path: string; text: string }[] = []
+  const runs: unknown[] = []
+  const status: (string | undefined)[] = []
+  let answer = () => {}
+  const terminal = new Promise<void>(resolve => {
+    answer = resolve
+  })
+  const norm = (p: string) => p.replaceAll('\\', '/')
+  on('fs.read', (_$, e) => {
+    const text = files[norm(e.path)]
+    if (text === undefined) throw new Error(`ENOENT: ${e.path}`)
+    return { value: text }
+  })
+  on('fs.write', (_$, e) => {
+    writes.push({ path: norm(e.path), text: e.text })
+    files[norm(e.path)] = e.text
+    return { value: undefined }
+  })
+  on('env.get', (_$, e) => ({ value: { CLAUDE_CONFIG_DIR: 'C:/cfg', ...env }[e.name] }))
+  on('session.id', () => ({ value: 'sid-1' }))
+  on('session.cwd', () => ({ value: 'C:/proj' }))
+  on('ui.status', (_$, e) => {
+    status.push(e.text)
+    return { value: undefined }
+  })
+  on('tool.check', () => ({ decision, rule }))
+  let held = decision === 'ask'
+  on('tool.call', async (_$, e) => {
+    const { tool, tool_use_id, agentId, ...input } = e
+    if (held) {
+      held = false
+      await terminal
+    }
+    runs.push(input)
+    return { result: { stdout: 'ok' } }
+  })
+  on('session.start', (_$, e) => ({ cwd: e.cwd }))
+  on('agent.spawn', () => ({ model: 'haiku', agentId: 'a1' }))
+  on('turn.complete', (_$, e) => ({ text: e.answer }))
+  on('classic.*', () => ({}))
+  return { writes, runs, status, answer }
+}
+
+async function askFor($: Engine, clock: MockClock, args: { tool: string } & Record<string, unknown>) {
+  const { tool, ...input } = args
+  const call = $.tool.call(args as ToolCallArgs)
+  await clock.settle()
+  await $.tool.check({ tool, input })
+  await clock.settle()
+  return { call }
+}
+
+const marker = (files: Record<string, string>) => JSON.parse(files[MARKER]!)
+const decide = (files: Record<string, string>, decision: object) => {
+  files[`${SESSION}/_decision-${marker(files).id}.json`] = JSON.stringify(decision)
+}
+
+const lines = (text = '') => text.trim().split('\n').map(l => JSON.parse(l))
+
+const turn = (fields: { agentId?: string; answer?: string; isAborted?: boolean }) => ({
+  answer: '',
+  durationMs: 1,
+  isAborted: false,
+  turnId: 't',
+  reason: 'answer' as const,
+  ...fields,
+})
+
+const spawn = (subagentType: string, name?: string) => ({
+  tool_use_id: 'tu',
+  prompt: 'p',
+  description: 'd',
+  subagentType,
+  provider: { plugin: 'engine', tier: 'core' as const },
+  parentModel: 'opus',
+  background: false,
+  fork: false,
+  name,
+})
+
+test('an allowed tool call writes nothing', async ($, on) => {
+  const { writes } = engine(on, {})
+
+  const result = await $.tool.call({ tool: 'Bash', command: 'ls' })
+
+  expect(result.result).toEqual({ stdout: 'ok' })
+  expect(writes).toEqual([])
+})
+
+test('an ask writes the marker, and a terminal answer clears it', async ($, on) => {
+  const files: Record<string, string> = {}
+  const clock = mock.clock(on)
+  const { runs, answer } = engine(on, files, { decision: 'ask', rule: 'Bash(ls)' })
+
+  const { call } = await askFor($, clock, { tool: 'Bash', command: 'ls' })
+  expect(marker(files)).toMatchObject({
+    status: 'waiting',
+    kind: 'permission',
+    toolName: 'Bash',
+    toolInput: '{"command":"ls"}',
+    cwd: 'C:/proj',
+    rule: 'Bash(ls)',
+  })
+  await clock.advance(1500)
+  answer()
+
+  expect((await call).result).toEqual({ stdout: 'ok' })
+  expect(files[MARKER]).toBe(CLEARED)
+  expect(runs).toEqual([{ command: 'ls' }])
+})
+
+test('a board allow runs the tool with the board input and shows why', async ($, on) => {
+  const files: Record<string, string> = {}
+  const clock = mock.clock(on)
+  const { runs, status } = engine(on, files, { decision: 'ask' })
+
+  const { call } = await askFor($, clock, { tool: 'Bash', command: 'ls' })
+  decide(files, { behavior: 'allow', updatedInput: { command: 'ls -a' } })
+  await clock.advance(500)
+
+  expect((await call).result).toEqual({ stdout: 'ok' })
+  expect(runs).toEqual([{ command: 'ls -a' }])
+  expect(status).toEqual([BOARD_ALLOWED, undefined])
+  expect(files[MARKER]).toBe(CLEARED)
+})
+
+test('a board deny refuses the call with its message', async ($, on) => {
+  const files: Record<string, string> = {}
+  const clock = mock.clock(on)
+  const { runs } = engine(on, files, { decision: 'ask' })
+
+  const { call } = await askFor($, clock, { tool: 'Bash', command: 'rm -rf x' })
+  decide(files, { behavior: 'deny', message: 'not that' })
+  await clock.advance(500)
+
+  expect((await call).deny).toBe('not that')
+  expect(runs).toEqual([])
+  expect(files[MARKER]).toBe(CLEARED)
+})
+
+test('board answers to a question come back as the tool result', async ($, on) => {
+  const files: Record<string, string> = {}
+  const clock = mock.clock(on)
+  engine(on, files, { decision: 'ask' })
+  const questions = [{ question: 'Fruit?', header: 'Fruit', options: [], multiSelect: false }]
+
+  const { call } = await askFor($, clock, { tool: 'AskUserQuestion', questions })
+  expect(marker(files).kind).toBe('question')
+  decide(files, { answers: { 'Fruit?': 'Pear' } })
+  await clock.advance(500)
+
+  expect((await call).result).toEqual({ questions, answers: { 'Fruit?': 'Pear' } })
+})
+
+test('with approvals off the board only shows the ask', async ($, on) => {
+  const files: Record<string, string> = { [CONFIG]: '{"approvals":{"enabled":false}}' }
+  const clock = mock.clock(on)
+  const { runs, answer } = engine(on, files, { decision: 'ask' })
+
+  const { call } = await askFor($, clock, { tool: 'Bash', command: 'ls' })
+  decide(files, { behavior: 'deny' })
+  await clock.advance(2000)
+  answer()
+
+  expect((await call).result).toEqual({ stdout: 'ok' })
+  expect(runs).toEqual([{ command: 'ls' }])
+})
+
+test('the board stops waiting after waitSeconds', async ($, on) => {
+  const files: Record<string, string> = { [CONFIG]: '{"approvals":{"waitSeconds":1}}' }
+  const clock = mock.clock(on)
+  const { runs, answer } = engine(on, files, { decision: 'ask' })
+
+  const { call } = await askFor($, clock, { tool: 'Bash', command: 'ls' })
+  await clock.advance(1500)
+  decide(files, { behavior: 'deny' })
+  await clock.advance(1000)
+  answer()
+
+  expect((await call).result).toEqual({ stdout: 'ok' })
+  expect(runs).toEqual([{ command: 'ls' }])
+})
+
+test('a marker that a newer ask owns stays', async ($, on) => {
+  const files: Record<string, string> = {}
+  const clock = mock.clock(on)
+  const { answer } = engine(on, files, { decision: 'ask' })
+
+  const { call } = await askFor($, clock, { tool: 'Bash', command: 'ls' })
+  files[MARKER] = '{"status":"waiting","id":"newer"}'
+  answer()
+  await call
+
+  expect(files[MARKER]).toBe('{"status":"waiting","id":"newer"}')
+})
+
+test('a finished main turn marks the session unread', async ($, on) => {
+  const files: Record<string, string> = {}
+  engine(on, files)
+
+  await $.turn.complete(turn({}))
+
+  expect(files[`${SESSION}/_stop.json`]).toBe('')
+})
+
+test('an interrupted main turn does not mark the session unread', async ($, on) => {
+  const { writes } = engine(on, {})
+
+  await $.turn.complete(turn({ isAborted: true }))
+
+  expect(writes).toEqual([])
+})
+
+test('session start maps the session to a custom task list', async ($, on) => {
+  const map = `${ROOT}/_task-maps/list-1.json`
+  const files: Record<string, string> = { [map]: '{"old":{"project":"C:/x"}}' }
+  engine(on, files, { env: { CLAUDE_CODE_TASK_LIST_ID: 'list-1' } })
+
+  await $.session.start({ cwd: 'C:/proj', surface: null, isInteractive: false })
+
+  const maps = JSON.parse(files[map]!)
+  expect(maps.old).toEqual({ project: 'C:/x' })
+  expect(maps['sid-1'].project).toBe('C:/proj')
+})
+
+test('session start writes nothing without a custom task list', async ($, on) => {
+  const { writes } = engine(on, {})
+
+  await $.session.start({ cwd: 'C:/proj', surface: null, isInteractive: false })
+
+  expect(writes).toEqual([])
+})
+
+test('a subagent spawn then finish records start and stop', async ($, on) => {
+  const files: Record<string, string> = {}
+  engine(on, files)
+
+  await $.agent.spawn(spawn('general-purpose'))
+  await $.turn.complete(turn({ agentId: 'a1', answer: 'Task done with "quotes"' }))
+
+  const [start, stop] = lines(files[`${SESSION}/a1.jsonl`])
+  expect(start).toMatchObject({ agentId: 'a1', type: 'general-purpose', event: 'start', status: 'active' })
+  expect(stop).toMatchObject({ agentId: 'a1', event: 'stop', status: 'stopped', lastMessage: 'Task done with "quotes"' })
+  expect('type' in stop).toBe(false)
+  expect(files[`${SESSION}/_name-general-purpose.id`]).toBe('a1')
+  expect(files[`${SESSION}/_stop.json`]).toBeUndefined()
+})
+
+test('a subagent stop with an empty answer leaves lastMessage out', async ($, on) => {
+  const files: Record<string, string> = {}
+  engine(on, files)
+
+  await $.agent.spawn(spawn('general-purpose'))
+  await $.turn.complete(turn({ agentId: 'a1' }))
+
+  const [, stop] = lines(files[`${SESSION}/a1.jsonl`])
+  expect(stop).toMatchObject({ agentId: 'a1', event: 'stop' })
+  expect('lastMessage' in stop).toBe(false)
+})
+
+test('a finished loop that was never spawned writes nothing', async ($, on) => {
+  const { writes } = engine(on, {})
+
+  await $.turn.complete(turn({ agentId: 'internal' }))
+
+  expect(writes).toEqual([])
+})
+
+test('a named spawn maps the name, and TeammateIdle finds the agent by it', async ($, on) => {
+  const files: Record<string, string> = {}
+  engine(on, files)
+
+  await $.agent.spawn(spawn('general-purpose', 'researcher'))
+  await $.classic.TeammateIdle({ teammate_name: 'researcher', team_name: 'team' })
+
+  const idle = lines(files[`${SESSION}/a1.jsonl`])[1]
+  expect(idle).toMatchObject({ agentId: 'a1', type: 'researcher', event: 'idle', status: 'idle' })
+})
+
+test('TeammateIdle for an unknown teammate writes nothing', async ($, on) => {
+  const { writes } = engine(on, {})
+
+  await $.classic.TeammateIdle({ teammate_name: 'ghost', team_name: 'team' })
+
+  expect(writes).toEqual([])
+})

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

@@ -0,0 +1,72 @@
+import type { On, SessionMeasureInput } from 'claude-code'
+import { expect, test } from 'claude-code/testing'
+import { displayName } from '../hooks/context'
+
+const MEASURE: SessionMeasureInput = {
+  context: { tokens: 129_174, window: 1_000_000, percent: 13 },
+  rateLimits: [
+    { kind: 'five_hour', percentUsed: 1, resetsAt: '2026-10-02T13:10:00Z' },
+    { kind: 'seven_day', percentUsed: 7.5, resetsAt: '2026-10-09T00:00:00Z' },
+  ],
+  cost: { usd: 2.71 },
+  changed: ['context', 'rateLimits', 'cost'],
+}
+
+function engine(on: On, env: Record<string, string>, sessionId: string) {
+  const writes: { path: string; text: string }[] = []
+  on('fs.write', (_$, e) => {
+    writes.push({ path: e.path.replaceAll('\\', '/'), text: e.text })
+    return { value: undefined }
+  })
+  on('env.get', (_$, e) => ({ value: env[e.name] }))
+  on('session.id', () => ({ value: sessionId }))
+  on('session.model', () => ({ value: 'claude-opus-5-5' }))
+  on('session.measure', (_$, e) => ({ changed: [...e.changed] }))
+  return writes
+}
+
+test('session.measure writes the statusLine shape the board reads', async ($, on) => {
+  const writes = engine(on, { CLAUDE_CONFIG_DIR: 'C:/cfg' }, 'sid-1')
+
+  await $.session.measure(MEASURE)
+
+  expect(writes.length).toBe(1)
+  expect(writes[0]?.path).toBe('C:/cfg/.cck/context-status/sid-1.json')
+  const status = JSON.parse(writes[0]?.text ?? '{}')
+  expect(status.model).toEqual({ id: 'claude-opus-5-5', display_name: 'Opus 5.5' })
+  expect(status.cost.total_cost_usd).toBe(2.71)
+  expect(status.context_window).toEqual({
+    total_input_tokens: 129_174,
+    context_window_size: 1_000_000,
+    current_usage: null,
+    used_percentage: 13,
+  })
+  expect(status.rate_limits.five_hour).toEqual({ used_percentage: 1, resets_at: 1790946600 })
+  expect(status.rate_limits.seven_day.used_percentage).toBe(7.5)
+})
+
+test('skips a write when the status has not changed', async ($, on) => {
+  const writes = engine(on, { CLAUDE_CONFIG_DIR: 'C:/cfg' }, 'sid-3')
+
+  await $.session.measure(MEASURE)
+  await $.session.measure(MEASURE)
+  await $.session.measure({ ...MEASURE, cost: { usd: 3 } })
+
+  expect(writes.length).toBe(2)
+})
+
+test('display name from model id', async () => {
+  expect(displayName('claude-opus-5-5')).toBe('Opus 5.5')
+  expect(displayName('claude-haiku-4-5-20251001')).toBe('Haiku 4.5')
+  expect(displayName('claude-fable-5-1[1m]')).toBe('Fable 5.1')
+  expect(displayName('claude-opus-4-20250514')).toBe('Opus 4')
+  expect(displayName('gpt-x')).toBe('gpt-x')
+})
+
+test('falls back to ~/.claude when CLAUDE_CONFIG_DIR is unset', async ($, on) => {
+  const writes = engine(on, { USERPROFILE: 'C:/Users/me' }, 'sid-2')
+
+  await $.session.measure(MEASURE)
+
+  expect(writes.map(w => w.path)).toEqual(['C:/Users/me/.claude/.cck/context-status/sid-2.json'])
+})

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

@@ -0,0 +1,3 @@
+{
+  "extends": "./.claude-plugin/types/tsconfig.json"
+}