claude-code-kanban 4.26.0 → 4.28.0-rc.1

package/lib/dispatch.js

@@ -0,0 +1,171 @@
+// 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.
+
+const crypto = require('node:crypto');
+const { tokenMatches } = require('./terminal');
+const { clampWait } = require('./session-events');
+
+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.
+function formatDispatchLine(r) {
+  const head = `cck:1 dispatch.${r.status} ${r.id} session=${r.session}`;
+  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'),
+      parent: parent || null,
+      session: null,
+      cwd: null,
+      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' };
+    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));
+    });
+  }
+
+  return { create, attach, discard, settle, sessionExited, list, wait };
+}
+
+module.exports = { createDispatchRegistry, formatPreamble, formatDispatchLine, isPeerName };

package/lib/folder-dialog.js

@@ -0,0 +1,91 @@
+'use strict';
+
+// Opens the OS folder picker on the machine running cck. The page cannot do this: a
+// browser's directory input hands over file contents, never the folder's path.
+
+const { spawn } = require('node:child_process');
+const { statSync } = require('node:fs');
+const path = require('node:path');
+
+const PROMPT = 'Choose a folder for the new session';
+
+// The owner form keeps the dialog above the browser; without it the dialog opens behind.
+// The start folder arrives in an env var, never spliced into the script.
+const WIN_SCRIPT = [
+  'Add-Type -AssemblyName System.Windows.Forms',
+  '[Console]::OutputEncoding = [Text.Encoding]::UTF8',
+  '$owner = New-Object System.Windows.Forms.Form -Property @{ TopMost = $true }',
+  '$d = New-Object System.Windows.Forms.FolderBrowserDialog',
+  `$d.Description = "${PROMPT}"`,
+  '$d.ShowNewFolderButton = $true',
+  'if ($env:CCK_PICK_START) { $d.SelectedPath = $env:CCK_PICK_START }',
+  'if ($d.ShowDialog($owner) -eq "OK") { [Console]::Out.Write($d.SelectedPath) }',
+].join('; ');
+
+// argv, not string interpolation, so a quote in the path cannot end the AppleScript literal.
+const MAC_SCRIPT = [
+  'on run argv',
+  'if (count of argv) > 0 then',
+  `return POSIX path of (choose folder with prompt "${PROMPT}" default location (POSIX file (item 1 of argv)))`,
+  'end if',
+  `return POSIX path of (choose folder with prompt "${PROMPT}")`,
+  'end run',
+];
+
+function candidates(platform, start) {
+  // No `.exe`: whichSync appends PATHEXT itself, so `powershell.exe` is never found.
+  // pwsh first: on .NET Core the same FolderBrowserDialog is the Explorer-style picker, while
+  // Windows PowerShell (.NET Framework) shows the old tree view.
+  if (platform === 'win32') {
+    const args = ['-NoProfile', '-STA', '-Command', WIN_SCRIPT];
+    return [['pwsh', args], ['powershell', args]];
+  }
+  if (platform === 'darwin') return [['osascript', [...MAC_SCRIPT.flatMap((l) => ['-e', l]), ...(start ? [start] : [])]]];
+  return [
+    ['zenity', ['--file-selection', '--directory', `--title=${PROMPT}`, ...(start ? [`--filename=${start}${path.sep}`] : [])]],
+    ['kdialog', ['--getexistingdirectory', start || '.', '--title', PROMPT]],
+  ];
+}
+
+// The page sends any text the user typed; only an existing absolute folder is worth opening at.
+function startFolder(dir) {
+  if (typeof dir !== 'string' || !path.isAbsolute(dir)) return null;
+  try {
+    return statSync(dir).isDirectory() ? dir : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {(cmd: string) => string|null} which
+ * @param {{ start?: string }} [opts] folder the dialog opens at, ignored unless it exists
+ * @returns {Promise<string|null>} the chosen folder, or null when the user cancels
+ * @throws when this machine has no folder dialog
+ */
+function pickFolder(which, opts = {}, platform = process.platform, env = process.env) {
+  if (platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY) {
+    return Promise.reject(new Error('no display for a folder dialog'));
+  }
+  const start = startFolder(opts.start);
+  const found = candidates(platform, start).find(([cmd]) => which(cmd));
+  if (!found) return Promise.reject(new Error('no folder dialog on this machine (install zenity or kdialog)'));
+  const [cmd, args] = found;
+  return new Promise((resolve, reject) => {
+    const child = spawn(which(cmd), args, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+      env: start ? { ...env, CCK_PICK_START: start } : env,
+    });
+    let out = '';
+    child.stdout.on('data', (d) => { out += d; });
+    child.on('error', reject);
+    // Every picker exits non-zero on cancel and prints nothing.
+    child.on('close', () => {
+      const dir = out.trim();
+      resolve(dir ? dir.replace(/(.)[/\\]$/, '$1') : null);
+    });
+  });
+}
+
+module.exports = { pickFolder, candidates, startFolder };

package/lib/inline-assets.js

@@ -235,4 +235,4 @@ async function inlineHtmlAssets(html, absHtmlPath) {
   return { html: out, bytes: ctx.spent, skipped: ctx.skipped };
 }
 
-module.exports = { inlineHtmlAssets, MAX_ASSET_BYTES };
+module.exports = { inlineHtmlAssets, MIME_BY_EXT, MAX_ASSET_BYTES };

package/lib/net-guard.js

@@ -181,6 +181,16 @@ function createNetGuard(config = {}) {
     return next();
   }
 
+  // For a WebSocket upgrade, which originGuard must not judge: the handshake is a
+  // GET, and WebSocket has no CORS, so any page can open one. Browsers always send
+  // Origin on the handshake, so a missing or `null` one is refused, not trusted.
+  // Returns null when allowed, or the reason it was refused.
+  function upgradeVerdict(req) {
+    if (!hostAllowed(parseHostHeader(req.headers.host))) return 'unrecognized Host header';
+    if (originVerdict(req.headers.origin) !== true) return 'cross-origin or missing Origin';
+    return null;
+  }
+
   // Constant for the life of the process, and frameGuard runs ahead of
   // express.static — so this is built once rather than per asset fetch.
   //
@@ -229,12 +239,19 @@ function createNetGuard(config = {}) {
    * @param {any} app express app (or any http request handler)
    * @param {number} port 0 selects a free port
    * @param {(port: number) => void} [onReady]
-   * @param {{maxHeaderSize?: number}} [opts]
+   * `onUpgrade` is attached to both servers; a caller that attached it to the
+   * returned one alone would drop every WebSocket that arrives over the other family.
+   *
+   * @param {{maxHeaderSize?: number, onUpgrade?: (req: any, socket: any, head: Buffer) => void}} [opts]
    */
   function listenLoopback(app, port, onReady, opts = {}) {
     const http = require('http');
     const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
-    const makeServer = (handler) => http.createServer(serverOpts, handler);
+    const makeServer = (handler) => {
+      const s = http.createServer(serverOpts, handler);
+      if (opts.onUpgrade) s.on('upgrade', opts.onUpgrade);
+      return s;
+    };
     const server = makeServer(app);
     let secondary = null;
 
@@ -261,7 +278,7 @@ function createNetGuard(config = {}) {
     return `WARNING: listening on ${BIND_HOST} - reachable from your network, with no authentication.`;
   }
 
-  return { BIND_HOST, ALLOWED_HOSTS, hostGuard, originGuard, frameGuard, listenLoopback, exposureWarning };
+  return { BIND_HOST, ALLOWED_HOSTS, EXPOSED, hostGuard, originGuard, upgradeVerdict, frameGuard, listenLoopback, exposureWarning };
 }
 
 module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress };

package/lib/parsers.js

@@ -185,6 +185,14 @@ function pushUserMessage(messages, text, timestamp, sysLabel, extras) {
     label = base + formatTaskUsage(notif.usage);
     safeText = notif.result || base;
   }
+  // A subagent, teammate or peer session handing work back through SendMessage is
+  // also model output, not user input. Callers on the `origin` path pass the parts
+  // ready-made; the text paths (type:'user', queued enqueue) parse the envelope.
+  const agentMsg = extras?.agent || (notif ? null : parseAgentMessage(safeText));
+  if (agentMsg) {
+    label = agentMsg.label;
+    safeText = agentMsg.body;
+  }
   const truncated = safeText.length > USER_TEXT_MAX;
   const msg = {
     type: 'user',
@@ -200,12 +208,26 @@ function pushUserMessage(messages, text, timestamp, sysLabel, extras) {
     if (notif.taskId) msg.taskId = notif.taskId;
     if (notif.status) msg.taskStatus = notif.status;
   }
+  if (agentMsg) {
+    msg.agentMessage = true;
+    if (agentMsg.from) msg.agentFrom = agentMsg.from;
+  }
   if (extras) {
     if (extras.uuid) msg.uuid = extras.uuid;
     if (extras.images && extras.images.length) msg.images = extras.images;
     if (extras.toolResultRefs && extras.toolResultRefs.length) msg.toolResultRefs = extras.toolResultRefs;
     if (extras.queued) msg.queued = true;
   }
+  // One agent message reaches the log twice: the queued enqueue record and the
+  // delivered one right after it. Keep the first and drop the twin here, so no
+  // renderer has to know about the double write.
+  if (agentMsg) {
+    const prev = messages[messages.length - 1];
+    if (prev?.agentMessage && (prev.agentFrom || null) === (msg.agentFrom || null) && prev.text === msg.text) {
+      if (!msg.queued) delete prev.queued;
+      return;
+    }
+  }
   messages.push(msg);
 }
 
@@ -587,6 +609,43 @@ function parseTaskNotification(text) {
   };
 }
 
+// A message another agent sent into this session (a subagent hand-back, a teammate
+// or a peer session using SendMessage) is model output, not user input. Turn the
+// sender and the raw body into the chip label plus the body alone, so it never
+// renders under a person icon.
+function agentMessageParts(from, rawBody, handback) {
+  let body = (rawBody || '').trimEnd();
+  // A hand-back frames the report with the harness note that it carries no user
+  // authority, and indents every line of the report by two spaces so a forged
+  // frame at column zero is impossible. Strip the frame and that indent.
+  const framed = body.match(/^\[Subagent hand-back\][\s\S]*?report follows:\n([\s\S]*)$/);
+  if (framed) body = framed[1].replace(/^ {2}/gm, '').trim();
+  const handBack = !!framed || !!handback;
+  const kind = handBack ? 'Subagent hand-back' : 'Agent message';
+  // Harness agent ids are long hex; a named sender ("code-review") is shown whole.
+  const short = from && /^[0-9a-f]{12,}$/i.test(from) ? from.slice(0, 8) : from;
+  return { from: from || null, handBack, label: short ? `${kind} · ${short}` : kind, body };
+}
+
+// The text delivery paths carry the body inside an <agent-message from="..."> envelope,
+// with the harness notes outside it. The envelope must open the message (after the
+// harness preamble, if any): prose that merely quotes the tag is a user message.
+// The body is unescaped agent text that can quote the envelope it describes, so the
+// real closing tag is the last one.
+function parseAgentMessage(text) {
+  if (typeof text !== 'string' || !text.includes('<agent-message')) return null;
+  const start = text.indexOf('<agent-message');
+  const preamble = text.slice(0, start).trim();
+  if (preamble && !/^Another Claude session sent a message[^\n]*:$/.test(preamble)) return null;
+  const gt = text.indexOf('>', start);
+  const end = text.lastIndexOf('</agent-message>');
+  if (gt === -1 || end < gt) return null;
+  const from = (text.slice(start, gt).match(/from="([^"]*)"/) || [])[1] || null;
+  let bodyStart = gt + 1;
+  while (text[bodyStart] === '\n') bodyStart++;
+  return agentMessageParts(from, text.slice(bodyStart, end));
+}
+
 function getSystemMessageLabel(text) {
   const taskMatch = text.match(/<summary>([^<]+)<\/summary>/);
   if (taskMatch) return taskMatch[1].trim();
@@ -801,6 +860,15 @@ function readRecentMessages(jsonlPath, limit = 10) {
                 messages.push(msg);
               }
             }
+          } else if (obj.type === 'user' && obj.origin?.kind === 'peer') {
+            // Claude Code >= 2.1 files the delivered copy as isMeta (dropped by the
+            // branch below) and repeats the envelope's fields on `origin`. That
+            // record is always written; the queued enqueue is not, so read it from
+            // here and let pushUserMessage drop whichever twin arrives second.
+            pushUserMessage(messages, '', obj.timestamp, null, {
+              uuid: obj.uuid,
+              agent: agentMessageParts(obj.origin.from, obj.origin.body, obj.origin.handback)
+            });
           } else if (obj.type === 'user' && obj.message?.role === 'user' && !obj.isMeta) {
             if (obj.isCompactSummary) {
               // Surface the compaction summary as a single expandable "Compacted"
@@ -1359,6 +1427,49 @@ function readArtifactLinks(jsonlPath) {
   return [...byUrl.values()].sort((x, y) => (x.firstSeen < y.firstSeen ? -1 : x.firstSeen > y.firstSeen ? 1 : 0));
 }
 
+const SCRATCH_NEW_RE = /\bscratch new\b/;
+// `scratch new` reports where it put the pad; the two spaces are the CLI's own column
+// padding, which is what makes the prefilter below narrow enough to be worth having.
+const SCRATCH_MANIFEST_RE = /^\s*manifest\s*:\s*(.+?)\s*$/m;
+// The name must sit immediately after `new`, and the bare-word branch must refuse a
+// leading `-`, so that a flag or a flag's value cannot be read as the name.
+const SCRATCH_NAME_RE = /\bscratch\s+new\s+(?:"([^"]+)"|'([^']+)'|(?!-)(\S+))/;
+
+// The `scratch new` calls in a transcript, `{ ts, path, name }` per call. `path` is null
+// whenever the command piped the CLI's output away — the common case, not an edge one:
+// the manifest is the 4th of ~13 printed lines, so any `| tail -N` cuts it off. `name`
+// stands in because it is what the manifest stores as its own `name`; the path is not
+// recovered from the command, which would mean tracking the `cd` and a relative `--dir`.
+function readScratchpadCreations(jsonlPath) {
+  const calls = new Map();
+  try {
+    const content = readFileSync(jsonlPath, 'utf8');
+    for (const line of content.split('\n')) {
+      // Substring reject before JSON.parse: transcripts reach tens of megabytes and
+      // only a handful of lines can ever match.
+      const isCall = line.includes('scratch new');
+      if (!isCall && !line.includes('manifest  :')) continue;
+      let obj;
+      try { obj = JSON.parse(line); } catch (_) { continue; }
+      const blocks = obj?.message?.content;
+      if (!Array.isArray(blocks)) continue;
+      const ts = Date.parse(obj.timestamp);
+      for (const b of blocks) {
+        if (b?.type === 'tool_use' && b.name === 'Bash' && SCRATCH_NEW_RE.test(b.input?.command || '')) {
+          if (b.id && Number.isFinite(ts)) {
+            const named = SCRATCH_NAME_RE.exec(b.input.command);
+            calls.set(b.id, { ts, path: null, name: named?.slice(1).find(Boolean) ?? null });
+          }
+        } else if (b?.type === 'tool_result' && calls.has(b.tool_use_id)) {
+          const m = SCRATCH_MANIFEST_RE.exec(toolResultText(b.content));
+          if (m) calls.get(b.tool_use_id).path = m[1];
+        }
+      }
+    }
+  } catch (_) {}
+  return [...calls.values()];
+}
+
 function readCompactSummaries(jsonlPath) {
   const results = [];
   // Inline format: newer Claude Code stores the summary directly in the parent
@@ -1684,6 +1795,7 @@ module.exports = {
   parseSessionsIndex,
   parseJsonlLine,
   parseTaskNotification,
+  parseAgentMessage,
   getSystemMessageLabel,
   readSessionInfoFromJsonl,
   readRecentMessages,
@@ -1698,6 +1810,7 @@ module.exports = {
   buildSessionDigest,
   readCompactSummaries,
   readArtifactLinks,
+  readScratchpadCreations,
   findTerminatedTeammates,
   extractPromptFromTranscript,
   extractModelFromTranscript,

package/lib/scratch-files.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const fs = require('node:fs').promises;
+const path = require('node:path');
+const { isContained } = require('./contain');
+
+// Resolves a folder inside a session's scratchpad dir from the path the client sends
+// back — the absolute path a listing handed out, or one relative to the root. Returns
+// null when it escapes the root (`..`, another dir, a symlink out), so the endpoint
+// never lists anything the root did not hand out.
+function resolveScratchSubdir(root, sub) {
+  if (!sub) return root;
+  if (typeof sub !== 'string') return null;
+  const full = path.resolve(root, sub);
+  return isContained(full, root) ? full : null;
+}
+
+// One level of a scratchpad dir, newest first whatever the kind. Not recursive on
+// purpose: sessions drop clones and build output in here, and the client asks for a
+// folder's children only when the user opens it.
+async function listScratchDir(dir) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (_) {
+    return [];
+  }
+  const rows = await Promise.all(
+    entries
+      .filter((entry) => entry.isFile() || entry.isDirectory())
+      .map(async (entry) => {
+        const full = path.join(dir, entry.name);
+        try {
+          const { mtimeMs } = await fs.stat(full);
+          return { name: entry.name, path: full, kind: entry.isDirectory() ? 'dir' : 'file', mtimeMs };
+        } catch (_) {
+          return null;
+        }
+      }),
+  );
+  return rows
+    .filter(Boolean)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .map(({ mtimeMs, ...row }) => ({ ...row, modifiedAt: new Date(mtimeMs).toISOString() }));
+}
+
+module.exports = { resolveScratchSubdir, listScratchDir };

package/lib/session-events.js

@@ -51,11 +51,28 @@ function enqueueSessionEvent(sessionId, line) {
   for (const wake of [...bucket.waiters]) wake();
 }
 
+const MAX_WAIT_SEC = 120;
+const TOPIC_RE = /^[a-z]+$/;
+
+function clampWait(sec) {
+  return Math.min(Math.max(Number(sec) || 0, 0), MAX_WAIT_SEC);
+}
+
+// Each topic rides its own bucket, so the kanban-dispatch postman never prints task moves
+// the user did not grant with kanban-follow. No topic is the task-move bucket.
+function topicKey(topic, sessionId) {
+  return topic ? `${topic}:${sessionId}` : sessionId;
+}
+
 // Long-poll drained by the postman monitor. Routing stays in server.js; this is the handler.
 function handleSessionEvents(req, res) {
-  const { sessionId } = req.params;
+  const topic = req.query.topic;
+  if (topic !== undefined && !(typeof topic === 'string' && TOPIC_RE.test(topic))) {
+    return res.status(400).json({ error: 'invalid topic' });
+  }
+  const sessionId = topicKey(topic, req.params.sessionId);
   const bucket = sessionEventBuckets.get(sessionId);
-  const wait = Math.min(Math.max(Number(req.query.wait) || 0, 0), 120);
+  const wait = clampWait(req.query.wait);
 
   // A postman is armed by a skill invocation, so it can attach long after the board moved
   // something. Those lines are read as instructions, and an hours-old instruction is worse
@@ -96,4 +113,7 @@ module.exports = {
   formatTaskMoved,
   enqueueSessionEvent,
   handleSessionEvents,
+  topicKey,
+  clampWait,
+  MAX_WAIT_SEC,
 };