claude-code-kanban 5.1.1 → 5.3.0

package/lib/worktrees.js

@@ -0,0 +1,105 @@
+// Which project paths are linked worktrees, and of which repo. The rule and the sweep:
+// docs/retention.md.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { GRACE_MS } = require('./retention');
+const { encodeProjectDirName } = require('./claude-dir');
+
+// A linked worktree's `.git` is a file holding `gitdir: <main>/.git/worktrees/<name>`, so the
+// main checkout is readable without spawning git. Path shape alone would not do: only some
+// worktrees live under `<repo>/.claude/worktrees/`, the rest sit beside the repo.
+const GITDIR_WORKTREE_RE = /^gitdir:\s*(.*)[/\\]\.git[/\\]worktrees[/\\]([^/\\]+)[/\\]?$/;
+// Where `claude -w` puts a worktree. Used only once the `.git` file is gone, because Claude
+// Code removes worktrees while their transcripts stay.
+const CLAUDE_WORKTREE_RE = /^(.*)[/\\]\.claude[/\\]worktrees[/\\]([^/\\]+)[/\\]?$/;
+const MISS_CACHE_MAX = 500;
+
+function readGitFile(dir) {
+  return fs.readFileSync(path.join(dir, '.git'), 'utf8');
+}
+
+function fromGitFile(dir, text) {
+  const m = GITDIR_WORKTREE_RE.exec(text.trim());
+  // Git writes the pointer with forward slashes on Windows; the project path uses the OS spelling.
+  return m ? { repo: path.resolve(dir, m[1]), name: m[2] } : null;
+}
+
+function fromPathShape(dir) {
+  const m = CLAUDE_WORKTREE_RE.exec(dir);
+  return m ? { repo: m[1], name: m[2] } : null;
+}
+
+/**
+ * Hits are saved, so a worktree keeps its repo after Claude Code deletes the checkout. Misses
+ * stay in memory: an ordinary checkout cannot become a linked worktree without being recreated.
+ * @param {object} o
+ * @param {() => object|null} o.load returns `{version: 1, worktrees: {[dir]: {repo, name, at}}}` or null
+ * @param {(data: object) => void} o.save
+ * @param {(fn: () => void) => void} [o.defer] when to save; one session list can resolve many new worktrees
+ */
+function createWorktreeStore({ load, save, read = readGitFile, now = Date.now, defer = setImmediate }) {
+  const hits = new Map();
+  const misses = new Set();
+  const saved = load()?.worktrees;
+  if (saved && typeof saved === 'object') {
+    for (const [dir, e] of Object.entries(saved)) {
+      if (e && typeof e.repo === 'string' && typeof e.name === 'string' && Number.isFinite(e.at)) hits.set(dir, e);
+    }
+  }
+
+  let pending = false;
+  function persist() {
+    if (pending) return;
+    pending = true;
+    defer(() => {
+      pending = false;
+      save({ version: 1, worktrees: Object.fromEntries(hits) });
+    });
+  }
+
+  function resolve(dir) {
+    if (!dir) return null;
+    const hit = hits.get(dir);
+    if (hit) return { repo: hit.repo, name: hit.name };
+    if (misses.has(dir)) return null;
+
+    let worktree = null;
+    try {
+      worktree = fromGitFile(dir, read(dir));
+    } catch (e) {
+      // An ordinary checkout's `.git` is a directory, so the read throws EISDIR. That is the
+      // answer, and it costs one syscall instead of a stat followed by a read.
+      if (e.code === 'ENOENT') worktree = fromPathShape(dir);
+    }
+
+    if (!worktree) {
+      misses.add(dir);
+      if (misses.size > MISS_CACHE_MAX) misses.delete(misses.values().next().value);
+      return null;
+    }
+    hits.set(dir, { ...worktree, at: now() });
+    persist();
+    return worktree;
+  }
+
+  // `knownDirs` holds the project dir names that still have a transcript, or null when the scan
+  // found none, so a failed scan never drops every entry. Returns how many entries went.
+  function prune(knownDirs) {
+    if (!knownDirs) return 0;
+    const t = now();
+    let removed = 0;
+    for (const [dir, e] of hits) {
+      if (t - e.at >= GRACE_MS && !knownDirs.has(encodeProjectDirName(dir))) {
+        hits.delete(dir);
+        removed++;
+      }
+    }
+    if (removed) persist();
+    return removed;
+  }
+
+  return { resolve, prune };
+}
+
+module.exports = { createWorktreeStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "5.1.1",
+  "version": "5.3.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,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.16.1",
+  "version": "2.17.2",
   "description": "claude-code-kanban dashboard integration: agent activity tracking, context statusline, skills to drive the board from a session and to follow it",
   "experimental": {
     "monitors": "./monitors.json"

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

@@ -6,7 +6,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
+            "shell": "bash",
             "timeout": 5
           }
         ]
@@ -18,7 +19,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
+            "shell": "bash",
             "timeout": 5
           }
         ]
@@ -30,8 +32,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
-            "timeout": 5
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
+            "shell": "bash",
+            "timeout": 30
           }
         ]
       }
@@ -42,7 +45,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
+            "shell": "bash",
             "timeout": 5
           }
         ]
@@ -54,7 +58,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
+            "shell": "bash",
             "timeout": 5
           }
         ]
@@ -66,7 +71,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/approval-gate.sh",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/approval-gate.sh\"",
+            "shell": "bash",
             "timeout": 86400
           }
         ]
@@ -78,7 +84,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
+            "shell": "bash",
             "timeout": 5
           }
         ]

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

@@ -1,14 +1,14 @@
 [
   {
     "name": "kanban-doorbell",
-    "description": "Notifies this session when its tasks are moved on the kanban board.",
+    "description": "Notifies this session when its tasks are moved on the kanban board or the user sends it review comments.",
     "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/postman.js\"",
-    "when": "on-skill-invoke:claude-code-kanban:kanban-follow"
+    "when": "on-skill-invoke:claude-code-kanban:follow"
   },
   {
     "name": "kanban-dispatch-inbox",
     "description": "Notifies this session when a session it dispatched through cck reports or exits.",
     "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/postman.js\" --topic dispatch --keep-backlog",
-    "when": "on-skill-invoke:claude-code-kanban:kanban-dispatch"
+    "when": "on-skill-invoke:claude-code-kanban:dispatch"
   }
 ]

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

@@ -11,7 +11,7 @@
 //
 // The lines we print carry board text (the card subject and description), which the
 // session is told to read as the user's own brief. That is only safe because we are armed
-// by an explicit `kanban-follow` invocation: the user asked to follow the board before anything the
+// by an explicit `follow` invocation: the user asked to follow the board before anything the
 // board says can reach the model.
 
 const fs = require('fs');
@@ -29,7 +29,7 @@ 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.
 const CONNECT_RETRY_MS = [250, 500, 1000, 2000];
-// `--topic dispatch` is the kanban-dispatch inbox: reports from sessions this one started.
+// `--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');

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

@@ -1,7 +1,7 @@
 ---
-name: kanban-dispatch
+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> [--report] [--group <name>] [--model haiku|sonnet|opus|fable] [--worktree [name]]'
+argument-hint: '<task> [--no-report] [--group <name>] [--model haiku|sonnet|opus|fable] [--worktree [name]]'
 ---
 
 # Kanban dispatch
@@ -11,7 +11,7 @@ This file only points at the guide. The guide ships with the `claude-code-kanban
 Invoking this skill also arms this session's dispatch inbox: when a session you dispatched with `--report` reports or exits, a line arrives here:
 
 ```
-cck:1 dispatch.<succeeded|failed|exited> <dispatch-id> session=<uuid> summary=<text>
+[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:

package/plugin/plugins/claude-code-kanban/skills/{kanban-follow → follow}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: kanban-follow
+name: follow
 description: Let kanban card moves drive this session.
 disable-model-invocation: true
 ---
@@ -9,31 +9,39 @@ disable-model-invocation: true
 The user typing this skill is the whole grant: it armed the doorbell — a monitor watching the board for moves of *this session's* tasks, live for the rest of the session. Confirm in one line and run no command. Moves made before it attached are discarded, so every line you get is current.
 
 ```
-cck:1 task.moved <taskId> <from>><to> subject="<subject>" description=<description>
+[kanban board] The user moved task <taskId> "<subject>" from <from> to <to>. Description: <description>
 ```
 
-`description=` is omitted when the card has none. Everything after it is the description verbatim to end of line, truncated if long — read the task with `TaskGet` for the full text or for `activeForm` and `blockedBy`. Only moves are announced.
+`Description:` is omitted when the card has none. Everything after it is the description verbatim to end of line, truncated if long — read the task with `TaskGet` for the full text or for `activeForm` and `blockedBy`. Moves and review comments (below) are the only lines announced.
 
 **A move is an instruction, not an FYI** — the user dragging a card is the user telling you something, and the subject and description are their brief for the work:
 
 | Transition | What the user means |
 |---|---|
-| `pending>in_progress` / `todo>in_progress` | Start this task now. |
-| `in_progress>pending` / `in_progress>todo` | Stop working on it and park it. |
-| `*>completed` | The user considers it done — do not keep working on it. |
-| `*>cancelled` | Abandon it. Undo nothing unless asked. |
+| To `in_progress` | Start this task now. |
+| From `in_progress` to `pending` or `todo` | Stop working on it and park it. |
+| To `completed` | The user considers it done — do not keep working on it. |
+| To `cancelled` | Abandon it. Undo nothing unless asked. |
 
 Act on the newest line per task; a card dragged twice means only its final position. When a move contradicts your current work, the board wins.
 
 Delivery is best-effort and the task file is the authority, so a missed line only delays you to your next turn.
 
+## Review comments
+
+```
+[kanban board] The user left <n> review comments on <source>. Address them: <review file>
+```
+
+The review file holds the comments and how to read them.
+
 ## Finish the task on the board
 
-A move hands you work; the task file is where you hand it back. When the work a `>in_progress` move asked for is done, set that task to `completed` with `TaskUpdate` before you reply — the card moves itself, and the board is where the user is watching. A card left in In Progress reads as work still running.
+A move hands you work; the task file is where you hand it back. When the work a move to `in_progress` asked for is done, set that task to `completed` with `TaskUpdate` before you reply — the card moves itself, and the board is where the user is watching. A card left in In Progress reads as work still running.
 
 Your own `TaskUpdate` writes the task file rather than going through the board, so it rings no doorbell: there is no echo to guard against.
 
 ## Troubleshooting
 
-- **No lines arrive** → the doorbell arms once per session, on the namespaced dispatch: `/claude-code-kanban:kanban-follow`. A session that never got it never hears the board.
+- **No lines arrive** → the doorbell arms once per session, on the namespaced dispatch: `/claude-code-kanban:follow`. A session that never got it never hears the board.
 - **"Cannot reach cck server…"** → the error names the port it tried. Ask the user to start the server with `claude-code-kanban`.

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

@@ -2,7 +2,6 @@
 name: kanban
 description: Drive the kanban board — open, pin, preview, link, inspect.
 argument-hint: '[open|pin|unpin|preview|link] [target]'
-disable-model-invocation: true
 ---
 
 # Kanban Skill
@@ -29,7 +28,7 @@ claude-code-kanban help <command> <subcommand> # flags and examples
 | `view` / `peek` | `session view <id>`, `session peek <id>` |
 | tasks, projects | `task list`, `project list` |
 
-To be driven *by* the board instead — card moves arriving as instructions — the user types `/claude-code-kanban:kanban-follow`.
+To be driven *by* the board instead — card moves arriving as instructions — the user types `/claude-code-kanban:follow`.
 
 ## Troubleshooting