claude-code-kanban 5.4.0 → 6.1.0

package/README.md

@@ -21,25 +21,35 @@ Watch the tour on YouTube: [light](https://youtu.be/QbvDBFyfC7s), [dark](https:/
 
 You need Node.js 20 or later and the `claude` CLI.
 
-### 1. Install the integration (one time)
+### 1. Install the command
 
 ```bash
-npx claude-code-kanban --install
+npm install -g claude-code-kanban
+```
+
+To update, run the same command again.
+
+To try it without an install, run `npx claude-code-kanban --open`. npx keeps a copy of each version in its cache and can run an old copy, so use the global install to keep the board and to update it.
+
+### 2. Install the integration (one time)
+
+```bash
+claude-code-kanban --install
 ```
 
 The installer adds a Claude Code plugin with hooks, skills and a mod for context use and cost (Claude Code 2.1.287 or later). It asks before it installs and keeps your other settings. Without the hooks, the board shows tasks only: no agent log, no live activity, no waiting prompts.
 
-To remove it, run `npx claude-code-kanban --uninstall`. For another Claude config dir, pass the same `--dir=<path>` (or set `CLAUDE_CONFIG_DIR`) to `--install`, `--uninstall` and the server. See [Getting started](https://nikiforovall.blog/claude-code-kanban/getting-started/) for each install step.
+To remove it, run `claude-code-kanban --uninstall`. For another Claude config dir, pass the same `--dir=<path>` (or set `CLAUDE_CONFIG_DIR`) to `--install`, `--uninstall` and the server. See [Getting started](https://nikiforovall.blog/claude-code-kanban/getting-started/) for each install step.
 
-### 2. Start the board
+### 3. Start the board
 
 ```bash
-npx claude-code-kanban --open
+claude-code-kanban --open
 ```
 
-The board runs at `http://localhost:3541`. To install the command globally, run `npm install -g claude-code-kanban`, then `claude-code-kanban --open`.
+The board runs at `http://localhost:3541`.
 
-### 3. Use Claude Code as usual
+### 4. Use Claude Code as usual
 
 Run `claude` in any project. You do not configure anything per project. Claude Code writes task files and transcripts to the config dir, and the board watches them and sends each change to the browser.
 
@@ -71,7 +81,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,17 +110,17 @@ 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/).
 
 ## Configuration
 
 ```bash
-PORT=8080 npx claude-code-kanban               # Custom port. If it is busy, the server uses a random free port.
-npx claude-code-kanban --dir=~/.claude-work    # Another Claude config dir (or CLAUDE_CONFIG_DIR)
-npx claude-code-kanban --enable-terminal       # Turn on the embedded terminal
-EDITOR="code -w" npx claude-code-kanban        # Command for Open in editor (default: code)
+PORT=8080 claude-code-kanban               # Custom port. If it is busy, the server uses a random free port.
+claude-code-kanban --dir=~/.claude-work    # Another Claude config dir (or CLAUDE_CONFIG_DIR)
+claude-code-kanban --enable-terminal       # Turn on the embedded terminal
+EDITOR="code -w" claude-code-kanban        # Command for Open in editor (default: code)
 ```
 
 - The server listens on `127.0.0.1` only and has no authentication. To reach it from another machine, use `--host` and `--allowed-hosts`, and do it only on a network you trust.

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/live-sessions.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Claude Code's live-session registry: one <pid>.json per interactive claude.
+function readLiveSessions(sessionsDir) {
+  const sessions = [];
+  let files;
+  try {
+    files = fs.readdirSync(sessionsDir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return sessions;
+  }
+  for (const file of files) {
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(sessionsDir, file), 'utf8'));
+      if (s?.sessionId && s.kind === 'interactive') {
+        sessions.push({ sessionId: s.sessionId, pid: s.pid || null, cwd: s.cwd || null, startedAt: s.startedAt || 0, status: s.status || null, name: s.name || null });
+      }
+    } catch { /* skip invalid */ }
+  }
+  return sessions;
+}
+
+// EPERM means the process exists but belongs to someone else.
+function isPidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+// A registry file outlives a crashed claude, so the pid is probed rather than trusted.
+function isSessionLive(sessions, sessionId, exceptPid = null) {
+  return sessions.some((s) => {
+    if (s.sessionId !== sessionId || !s.pid || s.pid === exceptPid) return false;
+    return isPidAlive(s.pid);
+  });
+}
+
+module.exports = { readLiveSessions, isPidAlive, isSessionLive };