claude-code-kanban 4.18.0 → 4.20.0

package/README.md

@@ -30,7 +30,15 @@ npx claude-code-kanban --open
 
 ### 3. Use Claude Code as usual
 
-Tasks, agents, and messages appear on the board automatically — Claude Code writes task files and conversation logs to `~/.claude`, the dashboard watches them and streams updates to the browser via SSE. It never directs Claude's work.
+Tasks, agents, and messages appear on the board automatically — Claude Code writes task files and conversation logs to `~/.claude`, the dashboard watches them and streams updates to the browser via SSE. Moving a card is the one thing that flows the other way: the board notifies the owning session with the card subject and description, so the agent can act on it.
+
+> **Empty board?** Claude Code ships the task tools off by default on some models — currently Opus 5, Fable 5 — so nothing writes task files and the board stays empty. Turn them on in `~/.claude/settings.json`:
+>
+> ```json
+> { "env": { "CLAUDE_CODE_ENABLE_TODO_TOOLS": "true" } }
+> ```
+>
+> Then restart Claude Code. You can also add a task by hand from the board's Pending column.
 
 ## Features
 

package/lib/session-events.js

@@ -0,0 +1,99 @@
+// Session event doorbell: tells a live session that the board moved one of its tasks.
+// Its own module so the behaviour is unit-testable without booting the server -- the
+// bucket-map invariants here are the difference between a bounded queue and a map that
+// grows one permanent entry per session id ever named in a request path.
+
+// Tells a live session that the board moved one of its tasks. The postman monitor
+// (plugin/plugins/claude-code-kanban/scripts/postman.js) drains this queue and prints
+// each line, which Claude Code delivers into that session as a task notification.
+//
+// Deliberately in-memory and lossy. The task file is the durable command -- a dropped
+// event only means the agent notices on its next turn instead of immediately -- so a
+// disk queue would buy nothing. Reading consumes, so a restarted postman never replays
+// a backlog and acts on the same move twice.
+//
+// A bucket exists only while it holds something: an undelivered line or a waiting
+// poller. Without that, the map would grow one permanent entry per session id ever
+// asked for -- and the id comes straight off the request path.
+const sessionEventBuckets = new Map();
+
+// The line reaches the model verbatim at hook trust level. The task id is caller-supplied
+// and the subject and description are board-authored, so the length cap and the
+// control-character scrub are what hold the one-line-per-event contract: a newline inside
+// a description becomes a space rather than a second forged event.
+//
+// One cap for the whole line rather than one per field, because the description comes
+// last: truncation eats its tail first and leaves the machine-readable head intact.
+function sanitizeEventLine(line) {
+  return line.replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 1500);
+}
+
+// Everything after `description=` is the description verbatim to end of line, so no amount
+// of board text can pose as a further field. That leaves the subject as the only value
+// that needs delimiting.
+function formatTaskMoved(taskId, prevStatus, task) {
+  const subject = String(task.subject || '').replace(/(["\\])/g, '\\$1');
+  const head = `cck:1 task.moved ${taskId} ${prevStatus || 'none'}>${task.status} subject="${subject}"`;
+  return task.description ? `${head} description=${task.description}` : head;
+}
+
+function enqueueSessionEvent(sessionId, line) {
+  const text = sanitizeEventLine(line);
+  if (!sessionId || !text) return;
+  let bucket = sessionEventBuckets.get(sessionId);
+  if (!bucket) {
+    bucket = { queue: [], waiters: new Set() };
+    sessionEventBuckets.set(sessionId, bucket);
+  }
+  bucket.queue.push(text);
+  // A session with no postman attached must not grow without bound.
+  if (bucket.queue.length > 50) bucket.queue.splice(0, bucket.queue.length - 50);
+  for (const wake of [...bucket.waiters]) wake();
+}
+
+// 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 bucket = sessionEventBuckets.get(sessionId);
+  const wait = Math.min(Math.max(Number(req.query.wait) || 0, 0), 120);
+
+  // 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
+  // than no instruction, so the grant starts the session's history rather than inheriting
+  // it: `first=1` drops the whole backlog. drain() (not a bare truncate) so an emptied
+  // bucket is still evicted from the map.
+  if (bucket && req.query.first === '1') drain(sessionId, bucket);
+
+  if (bucket && bucket.queue.length) return res.json({ events: drain(sessionId, bucket) });
+  if (!wait) return res.json({ events: [] });
+
+  const pending = bucket || { queue: [], waiters: new Set() };
+  sessionEventBuckets.set(sessionId, pending);
+
+  const send = () => {
+    // Set.delete is the whole idempotency story: whichever of enqueue, timeout, or
+    // client disconnect gets here first is the one that answers.
+    if (!pending.waiters.delete(send)) return;
+    clearTimeout(timer);
+    req.removeListener('close', send);
+    const events = drain(sessionId, pending);
+    if (!res.writableEnded) res.json({ events });
+  };
+  const timer = setTimeout(send, wait * 1000);
+  pending.waiters.add(send);
+  req.on('close', send);
+}
+
+function drain(sessionId, bucket) {
+  const events = bucket.queue.splice(0);
+  if (!bucket.queue.length && !bucket.waiters.size) sessionEventBuckets.delete(sessionId);
+  return events;
+}
+
+module.exports = {
+  sessionEventBuckets,
+  sanitizeEventLine,
+  formatTaskMoved,
+  enqueueSessionEvent,
+  handleSessionEvents,
+};

package/package.json

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

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

@@ -1,5 +1,8 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.3.3",
-  "description": "claude-code-kanban dashboard integration: agent activity tracking, context statusline, and a skill to drive the board from a session"
+  "version": "2.7.1",
+  "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/monitors.json

@@ -0,0 +1,8 @@
+[
+  {
+    "name": "kanban-doorbell",
+    "description": "Notifies this session when its tasks are moved on the kanban board.",
+    "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/postman.js\"",
+    "when": "on-skill-invoke:claude-code-kanban:kanban-follow"
+  }
+]

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

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Kanban -> session doorbell.
+//
+// Claude Code delivers every line a monitor prints to the owning session as a task
+// notification, so this process is the only way board activity can reach a session that
+// is sitting idle. It long-polls the kanban server for events addressed to this session
+// and prints them one per line.
+//
+// Pairing is free: CLAUDE_CODE_SESSION_ID is inherited from the session that spawned us,
+// so the id we poll with is the same id the hooks report. No cwd or pid guessing.
+//
+// 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
+// board says can reach the model.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SESSION_ID = process.env.CLAUDE_CODE_SESSION_ID;
+const SERVER_INFO = path.join(os.homedir(), '.claude', '.cck', 'server.json');
+// The server caps its own wait at 120s. Sitting at the ceiling halves every recurring
+// cost -- handshake, route walk, timer, empty response -- and costs no event latency,
+// because an enqueue wakes the poll immediately.
+const WAIT_SEC = 120;
+const RETRY_MS = 15000;
+
+if (!SESSION_ID) process.exit(0);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Re-read every cycle rather than caching: it is how we follow the board across a
+// restart onto a different port. A file left behind by a crashed server names a port
+// something else may now hold, so trust it only while its pid is alive.
+function serverUrl() {
+  const { port, pid } = JSON.parse(fs.readFileSync(SERVER_INFO, 'utf8'));
+  if (pid) process.kill(pid, 0);
+  return `http://127.0.0.1:${port}`;
+}
+
+// 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 = true;
+
+async function poll(base) {
+  const first = firstAttach ? '&first=1' : '';
+  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;
+  const { events } = await res.json();
+  return Array.isArray(events) ? events : [];
+}
+
+(async () => {
+  for (;;) {
+    try {
+      for (const line of await poll(serverUrl())) console.log(line);
+    } catch (_) {
+      // 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.
+      await sleep(RETRY_MS);
+    }
+  }
+})();

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

@@ -1,60 +1,53 @@
 ---
 name: kanban
-description: Drive the claude-code-kanban dashboard from this session — focus the current session in the browser, pin/unpin it in the sidebar, preview a markdown or HTML file, link a document to the session, or inspect session stats and messages. Use when the user mentions kanban or cck.
+description: Drive the kanban board — open, pin, preview, link, inspect.
 argument-hint: '[open|pin|unpin|preview|link] [target]'
+disable-model-invocation: true
 ---
 
 # Kanban Skill
 
-The current Claude session id is `${CLAUDE_SESSION_ID}` (substituted when this skill loads), so the user never needs to look it up.
+This session id is `${CLAUDE_SESSION_ID}`, substituted when the skill loads.
 
-When the user passes arguments, map them to the matching command below (`open` → `session open`, `pin`/`unpin`/`pins` → `session pin`/`--unpin`/`session pins`, `preview` → `preview-doc`, `link` → `link-doc`, `list`/`view`/`peek` → the read-only verbs); with no arguments, open the current session.
+An argument names the section below that handles it; with no argument, open the current session. Prefer the bare `claude-code-kanban` binary, falling back to `npx claude-code-kanban` when it is off PATH or the user asks for npx.
 
-Prefer the bare `claude-code-kanban` binary; fall back to `npx claude-code-kanban` when it is not on PATH, or when the user asks for npx explicitly.
+To be driven *by* the board instead — card moves arriving as instructions — the user types `/claude-code-kanban:kanban-follow`.
 
-## Open the current session in kanban
+## `open` — the current session
 
-Primary use case. Pins the active session in the sidebar and switches to the Active tab.
+Pins the session and switches the board to the Active tab.
 
 ```bash
 claude-code-kanban session open ${CLAUDE_SESSION_ID}
 ```
 
-## Pin the current session
-
-Pins the session so it stays visible regardless of filters. Three states: `pinned` (default), `sticky` (always at the top), or cleared with `--unpin`.
+## `pin` — keep the session visible
 
 ```bash
 claude-code-kanban session pin ${CLAUDE_SESSION_ID}            # pin
-claude-code-kanban session pin ${CLAUDE_SESSION_ID} --sticky   # sticky at top
+claude-code-kanban session pin ${CLAUDE_SESSION_ID} --sticky   # always at the top
 claude-code-kanban session pin ${CLAUDE_SESSION_ID} --unpin    # clear
+claude-code-kanban session pins                                # list pinned; --sticky narrows
 ```
 
-## List pinned sessions
-
-```bash
-claude-code-kanban session pins              # all pinned/sticky
-claude-code-kanban session pins --sticky     # sticky only
-```
-
-## Preview a file in kanban
+## `preview` — open a file in the modal
 
-Opens a markdown or standalone HTML file in the preview modal (HTML renders live in a sandboxed iframe, so sibling assets like `./style.css` do not load). Relative paths are fine — the server resolves to absolute.
+Markdown or standalone HTML. HTML renders in a sandboxed iframe, so sibling assets like `./style.css` do not load. Relative paths are fine — the server resolves them.
 
 ```bash
-claude-code-kanban preview-doc <path-to-file.md|.html> --session ${CLAUDE_SESSION_ID}
+claude-code-kanban preview-doc <file.md|.html> --session ${CLAUDE_SESSION_ID}
 ```
 
-## Link a document to the session (no modal)
+## `link` — attach a doc without the modal
 
-Same idea as `preview-doc`, but it only attaches the file to the session's linked docs in the sidebar — nothing pops up, so it is the safe choice while the user is working. Any extension is linkable.
+Adds the file to the session's linked docs in the sidebar. Any extension, and nothing pops up, so it is the safe choice while the user is working.
 
 ```bash
-claude-code-kanban link-doc <path-to-file> --session ${CLAUDE_SESSION_ID}            # link
-claude-code-kanban link-doc <path-to-file> --session ${CLAUDE_SESSION_ID} --unlink   # remove
+claude-code-kanban link-doc <path> --session ${CLAUDE_SESSION_ID}            # link
+claude-code-kanban link-doc <path> --session ${CLAUDE_SESSION_ID} --unlink   # remove
 ```
 
-## Inspect sessions (read-only)
+## `list` / `view` / `peek` — read-only
 
 ```bash
 claude-code-kanban session list --active                            # recent active sessions
@@ -64,12 +57,10 @@ claude-code-kanban session view ${CLAUDE_SESSION_ID}                # full stats
 claude-code-kanban session peek ${CLAUDE_SESSION_ID} --limit 20     # last 20 messages (server caps at 50)
 ```
 
-`session list` shows 10 rows by default and always includes pinned sessions, sticky first — `--no-pins` disables both.
-
-Add `--json` to any list-style verb for machine-readable output.
+`session list` shows 10 rows and always includes pinned sessions, sticky first (`--no-pins` disables both). `--json` works on any list-style verb.
 
 ## Troubleshooting
 
-`claude-code-kanban help <command>` prints the authoritative flags for any command — read it instead of guessing.
+`claude-code-kanban help <command>` prints the authoritative flags — read it instead of guessing.
 
 - **"Cannot reach cck server…"** → the error names the port it tried. Ask the user to start the server with `claude-code-kanban`. If they run it elsewhere, set `PORT=<n>` when invoking the CLI.

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

@@ -0,0 +1,39 @@
+---
+name: kanban-follow
+description: Let kanban card moves drive this session.
+disable-model-invocation: true
+---
+
+# Follow the kanban board
+
+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>
+```
+
+`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.
+
+**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. |
+
+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.
+
+## 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.
+
+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.
+- **"Cannot reach cck server…"** → the error names the port it tried. Ask the user to start the server with `claude-code-kanban`.

package/public/app.js

@@ -1425,6 +1425,7 @@ function toggleAgentPin(agentId) {
   }
   savePins(currentSessionId, currentPins);
   renderMessages(currentMessages);
+  renderSessions();
   renderAgentFooter();
 }
 
@@ -1476,6 +1477,7 @@ function togglePin(msgIndex) {
   }
   savePins(currentSessionId, currentPins);
   renderMessages(currentMessages);
+  renderSessions();
   updateMsgDetailPinState();
 }
 
@@ -1485,6 +1487,7 @@ function unpinById(pinIdx) {
   currentPins.splice(pinIdx, 1);
   savePins(currentSessionId, currentPins);
   renderMessages(currentMessages);
+  renderSessions();
   if (wasAgent) renderAgentFooter();
   updateMsgDetailPinState();
 }
@@ -1900,8 +1903,22 @@ function _setModalWidth(modal, slot, on, maxWidth, width) {
   }
 }
 
+function _modalEl(modalId) {
+  return document.querySelector(`#${modalId} .modal`);
+}
+
+// The opt-in marker for fullscreen and drag-resize alike: the presence of a
+// `<modalId>-fullscreen-btn` button in the markup.
+function _forEachFullscreenModal(cb) {
+  for (const btn of document.querySelectorAll('[id$="-fullscreen-btn"]')) {
+    const modalId = btn.id.replace(/-fullscreen-btn$/, '');
+    const modal = _modalEl(modalId);
+    if (modal) cb(modalId, modal);
+  }
+}
+
 function _applyModalFullscreen(modalId, on) {
-  const modal = document.querySelector(`#${modalId} .modal`);
+  const modal = _modalEl(modalId);
   modal.classList.toggle('fullscreen', on);
   _setModalWidth(modal, 'Fs', on, '', '');
   updateFullscreenBtnIcon(`${modalId}-fullscreen-btn`, on);
@@ -1909,16 +1926,15 @@ function _applyModalFullscreen(modalId, on) {
 
 // biome-ignore lint/correctness/noUnusedVariables: used in HTML
 function toggleModalFullscreen(modalId) {
-  const on = !document.querySelector(`#${modalId} .modal`).classList.contains('fullscreen');
+  const on = !_modalEl(modalId).classList.contains('fullscreen');
   _applyModalFullscreen(modalId, on);
   localStorage.setItem(`modal-fullscreen-${modalId}`, String(on));
 }
 
 function loadModalFullscreen() {
-  for (const btn of document.querySelectorAll('[id$="-fullscreen-btn"]')) {
-    const modalId = btn.id.replace(/-fullscreen-btn$/, '');
+  _forEachFullscreenModal((modalId) => {
     if (localStorage.getItem(`modal-fullscreen-${modalId}`) === 'true') _applyModalFullscreen(modalId, true);
-  }
+  });
 }
 
 // Hides the overlay only — the fullscreen state stays on the dialog, it is a
@@ -1937,6 +1953,72 @@ function updateFullscreenBtnIcon(btnId, isFullscreen) {
     : '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="16" height="16"><polyline points="15 3 21 3 21 9"/><polyline points="9 21 3 21 3 15"/><line x1="21" y1="3" x2="14" y2="10"/><line x1="3" y1="21" x2="10" y2="14"/></svg>';
 }
 
+// Free-form modal resize: drag the bottom-right grip, double-click it to reset.
+// The size lives in CSS custom properties + `.user-sized` (see style.css) rather
+// than inline width/height, so it never collides with the inline-style stash
+// that fullscreen and "Show more" do via _setModalWidth. The viewport cap lives
+// only in the CSS min(); JS clamps just the minimums.
+const MODAL_MIN_W = 360;
+const MODAL_MIN_H = 240;
+
+function _setModalUserSize(modal, w, h) {
+  modal.style.setProperty('--user-modal-w', w);
+  modal.style.setProperty('--user-modal-h', h);
+}
+
+function initModalResize() {
+  _forEachFullscreenModal((modalId, modal) => {
+    const wKey = `modal-width-${modalId}`;
+    const hKey = `modal-height-${modalId}`;
+    const savedW = localStorage.getItem(wKey);
+    const savedH = localStorage.getItem(hKey);
+    if (savedW && savedH) {
+      _setModalUserSize(modal, savedW, savedH);
+      modal.classList.add('user-sized');
+    }
+
+    const handle = document.createElement('div');
+    handle.className = 'modal-resize-handle';
+    handle.title = 'Drag to resize · double-click to reset';
+    modal.appendChild(handle);
+
+    let startW, startH, w, h;
+    _initDragResize(handle, {
+      onStart() {
+        startW = modal.offsetWidth;
+        startH = modal.offsetHeight;
+        // autoSizeModal / "Show more" may have widened the dialog inline
+        // before the first drag; inline width beats the .user-sized CSS.
+        modal.style.width = '';
+        modal.style.maxWidth = '';
+        // Vars and class land together, so `.user-sized` never reads an
+        // undefined var.
+        _setModalUserSize(modal, `${startW}px`, `${startH}px`);
+        modal.classList.add('user-sized');
+      },
+      // The overlay centers the modal, so both edges move — double the delta
+      // to keep the grip under the cursor.
+      onMove(dx, dy) {
+        w = Math.max(MODAL_MIN_W, startW + dx * 2);
+        h = Math.max(MODAL_MIN_H, startH + dy * 2);
+        _setModalUserSize(modal, `${w}px`, `${h}px`);
+      },
+      onEnd() {
+        if (w && h) {
+          localStorage.setItem(wKey, `${w}px`);
+          localStorage.setItem(hKey, `${h}px`);
+        }
+      },
+    });
+
+    handle.addEventListener('dblclick', () => {
+      modal.classList.remove('user-sized');
+      localStorage.removeItem(wKey);
+      localStorage.removeItem(hKey);
+    });
+  });
+}
+
 const MODAL_ZOOM_KEY = 'modal-zoom';
 const MODAL_ZOOM_MIN = 0.7;
 const MODAL_ZOOM_MAX = 2.0;
@@ -2325,7 +2407,8 @@ function _applyExpandToggle(btn, fullEl) {
   const panel = btn.closest('.message-panel');
   if (panel) panel.classList.toggle('msg-expanded-wide', expand);
   const modal = btn.closest('.modal');
-  if (modal) _setModalWidth(modal, 'Expand', expand, '60vw', '60vw');
+  // A user-dragged size is an explicit choice — don't widen over it.
+  if (modal && !modal.classList.contains('user-sized')) _setModalWidth(modal, 'Expand', expand, '60vw', '60vw');
 }
 function _toggleExpand(btn) {
   const f = document.getElementById(btn.dataset.expandId);
@@ -2343,7 +2426,7 @@ function makeExpandToggle(_truncatedHtml, fullHtml, opts = {}) {
 }
 
 function autoSizeModal(modal, body) {
-  if (modal.classList.contains('fullscreen')) return;
+  if (modal.classList.contains('fullscreen') || modal.classList.contains('user-sized')) return;
   modal.style.maxWidth = '';
   modal.classList.remove('has-mermaid');
   const hasMermaid = body.querySelector('pre.mermaid') !== null;
@@ -3299,11 +3382,19 @@ function renderKanban() {
   completedCount.textContent = completed.length;
 
   const emptyIcon = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2"/></svg>`;
+  const plusIcon = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M12 5v14M5 12h14"/></svg>`;
 
-  pendingTasks.innerHTML =
-    pending.length > 0
-      ? pending.map(renderTaskCard).join('')
-      : `<div class="column-empty">${emptyIcon}<div>No pending tasks</div></div>`;
+  // Adding is a live text input inside the column, so a background refresh would blow it
+  // away mid-typing -- leave the column alone until the input is gone.
+  if (!addingTask) {
+    const addTile = canAddTask()
+      ? `<button type="button" class="column-add${pending.length ? '' : ' empty'}" onclick="startAddTask(this)">${plusIcon}<span>Add task</span></button>`
+      : '';
+    pendingTasks.innerHTML =
+      pending.length > 0
+        ? pending.map(renderTaskCard).join('') + addTile
+        : addTile || `<div class="column-empty">${emptyIcon}<div>No pending tasks</div></div>`;
+  }
 
   inProgressTasks.innerHTML =
     inProgress.length > 0
@@ -3334,6 +3425,78 @@ function renderKanban() {
 
 //#endregion
 
+//#region ADD_TASK
+let addingTask = false;
+
+// A task the user types is theirs to place, and the only session it can belong to is the
+// one on screen -- the project and all-sessions views span many task dirs, so there is no
+// single target to write into.
+function canAddTask() {
+  return viewMode === 'session' && !!currentSessionId;
+}
+
+// biome-ignore lint/correctness/noUnusedVariables: used in HTML
+function startAddTask(tile) {
+  if (addingTask) return;
+  addingTask = true;
+
+  const input = document.createElement('input');
+  input.type = 'text';
+  input.className = 'form-input column-add-input';
+  input.placeholder = 'Task subject, Enter to add';
+  tile.replaceWith(input);
+  input.focus();
+
+  const reset = () => {
+    addingTask = false;
+    renderKanban();
+  };
+
+  const save = async () => {
+    // Enter and blur both submit, and Enter's own save disables the input -- which blurs
+    // it. Dropping both handlers first is what keeps that from posting the subject twice.
+    input.onkeydown = null;
+    input.onblur = null;
+
+    const subject = input.value.trim();
+    if (!subject) return reset();
+    input.disabled = true;
+    const sessionId = currentSessionId;
+    try {
+      const res = await fetch(`/api/tasks/${sessionId}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ subject }),
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      // The response carries the finished task, and the watcher will resend it within the
+      // SSE debounce anyway -- so show it now rather than paying a session refetch for it.
+      const { task } = await res.json();
+      currentTasks.push({ ...task, sessionId });
+      addingTask = false;
+      renderKanban();
+    } catch (error) {
+      console.error('Failed to create task:', error);
+      showToast('Failed to create task', 'error');
+      reset();
+    }
+  };
+
+  input.onkeydown = (e) => {
+    e.stopPropagation();
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      save();
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      input.onblur = null;
+      reset();
+    }
+  };
+  input.onblur = () => save();
+}
+//#endregion
+
 //#region DRAG_DROP
 // biome-ignore lint/correctness/noUnusedVariables: used in HTML
 function onCardDragStart(e) {
@@ -6313,68 +6476,79 @@ function loadSidebarState() {
   }
 }
 
-function initSidebarResize() {
-  const sidebar = document.querySelector('.sidebar');
-  const handle = document.getElementById('sidebar-resize');
-  let startX, startWidth;
+// Shared drag-session lifecycle for every resize grip (sidebar, panels, modal):
+// the `.dragging` class, text-selection suppression, and document-level
+// listener add/remove live here once. Callers keep only their geometry.
+// onStart may return false to veto the drag.
+function _initDragResize(handle, { onStart, onMove, onEnd }) {
+  let startX, startY;
 
   handle.addEventListener('mousedown', (e) => {
-    if (sidebar.classList.contains('collapsed')) return;
+    if (onStart && onStart() === false) return;
     startX = e.clientX;
-    startWidth = sidebar.offsetWidth;
-    sidebar.classList.add('resizing');
+    startY = e.clientY;
     handle.classList.add('dragging');
     document.body.style.userSelect = 'none';
-    document.addEventListener('mousemove', onMove);
-    document.addEventListener('mouseup', onUp);
+    document.addEventListener('mousemove', move);
+    document.addEventListener('mouseup', up);
     e.preventDefault();
   });
 
-  function onMove(e) {
-    const w = Math.min(600, Math.max(200, startWidth + e.clientX - startX));
-    sidebar.style.setProperty('--sidebar-width', `${w}px`);
-    sidebar.style.width = `${w}px`;
+  function move(e) {
+    onMove(e.clientX - startX, e.clientY - startY);
   }
 
-  function onUp() {
-    sidebar.classList.remove('resizing');
+  function up() {
     handle.classList.remove('dragging');
     document.body.style.userSelect = '';
-    document.removeEventListener('mousemove', onMove);
-    document.removeEventListener('mouseup', onUp);
-    localStorage.setItem('sidebar-width', sidebar.style.getPropertyValue('--sidebar-width'));
+    document.removeEventListener('mousemove', move);
+    document.removeEventListener('mouseup', up);
+    onEnd();
   }
 }
 
+function initSidebarResize() {
+  const sidebar = document.querySelector('.sidebar');
+  const handle = document.getElementById('sidebar-resize');
+  let startWidth;
+
+  _initDragResize(handle, {
+    onStart() {
+      if (sidebar.classList.contains('collapsed')) return false;
+      startWidth = sidebar.offsetWidth;
+      sidebar.classList.add('resizing');
+    },
+    onMove(dx) {
+      const w = Math.min(600, Math.max(200, startWidth + dx));
+      sidebar.style.setProperty('--sidebar-width', `${w}px`);
+      sidebar.style.width = `${w}px`;
+    },
+    onEnd() {
+      sidebar.classList.remove('resizing');
+      localStorage.setItem('sidebar-width', sidebar.style.getPropertyValue('--sidebar-width'));
+    },
+  });
+}
+
 function initPanelResize(panelId, handleId, cssVar, storageKey) {
   const panel = document.getElementById(panelId);
   const handle = document.getElementById(handleId);
-  let startX, startWidth;
+  let startWidth;
 
-  handle.addEventListener('mousedown', (e) => {
-    startX = e.clientX;
-    startWidth = panel.offsetWidth;
-    panel.classList.add('resizing');
-    handle.classList.add('dragging');
-    document.body.style.userSelect = 'none';
-    document.addEventListener('mousemove', onMove);
-    document.addEventListener('mouseup', onUp);
-    e.preventDefault();
+  _initDragResize(handle, {
+    onStart() {
+      startWidth = panel.offsetWidth;
+      panel.classList.add('resizing');
+    },
+    onMove(dx) {
+      const w = Math.max(200, startWidth - dx);
+      panel.style.setProperty(cssVar, `${w}px`);
+    },
+    onEnd() {
+      panel.classList.remove('resizing');
+      localStorage.setItem(storageKey, panel.style.getPropertyValue(cssVar));
+    },
   });
-
-  function onMove(e) {
-    const w = Math.max(200, startWidth - (e.clientX - startX));
-    panel.style.setProperty(cssVar, `${w}px`);
-  }
-
-  function onUp() {
-    panel.classList.remove('resizing');
-    handle.classList.remove('dragging');
-    document.body.style.userSelect = '';
-    document.removeEventListener('mousemove', onMove);
-    document.removeEventListener('mouseup', onUp);
-    localStorage.setItem(storageKey, panel.style.getPropertyValue(cssVar));
-  }
 }
 
 function loadPanelWidths() {
@@ -6453,6 +6627,14 @@ function updateStickyBtnState() {
   if (svg) svg.setAttribute('fill', isSticky ? 'currentColor' : 'none');
 }
 
+// Purely cosmetic: the tmp root is identical for every session and the encoded
+// project segment is already shown in the Path row, so only the last two segments
+// carry information. The full path stays in the tooltip and the copy button.
+function abbreviateScratchpadDir(dir) {
+  const sep = dir.includes('\\') ? '\\' : '/';
+  return ['$tmp', '…', ...dir.split(/[/\\]/).slice(-2)].join(sep);
+}
+
 function showInfoModal(session, teamConfig, tasks, planContent, parentInfo) {
   const modal = document.getElementById('team-modal');
   const titleEl = document.getElementById('team-modal-title');
@@ -6470,7 +6652,8 @@ function showInfoModal(session, teamConfig, tasks, planContent, parentInfo) {
   let html = '';
 
   // Session & project details as compact key-value rows
-  // Each row: [label, displayValue, { openPath?, copyValue? }]
+  // Each row: [label, value, { openPath?, abbrev? }] — `value` is authoritative
+  // (tooltip + copy); `abbrev` only replaces the rendered text.
   const infoRows = [];
   infoRows.push(['Session', session.id, { openClaudeDir: true, openFile: session.jsonlPath }]);
   if (parentInfo?.parentSessionId) {
@@ -6500,6 +6683,13 @@ function showInfoModal(session, teamConfig, tasks, planContent, parentInfo) {
   if (session.tasksDir) {
     infoRows.push(['Tasks Dir', session.tasksDir, { openPath: session.tasksDir }]);
   }
+  if (session.scratchpadDir) {
+    infoRows.push([
+      'Scratchpad',
+      session.scratchpadDir,
+      { openPath: session.scratchpadDir, abbrev: abbreviateScratchpadDir(session.scratchpadDir) },
+    ]);
+  }
   if (session.sharedTaskList) {
     infoRows.push(['Shared Tasks', session.sharedTaskList]);
   }
@@ -6517,7 +6707,7 @@ function showInfoModal(session, teamConfig, tasks, planContent, parentInfo) {
     if (opts?.openSession) {
       html += `<span onclick="openSessionFromInfo('${escAttrJs(opts.openSession)}')" style="${clickableStyle}" title="Open session in app">${escapeHtml(value)}</span>`;
     } else {
-      html += `<span style="${plainStyle}" title="${escapeHtml(value)}">${escapeHtml(value)}</span>`;
+      html += `<span style="${plainStyle}" title="${escapeHtml(value)}">${escapeHtml(opts?.abbrev || value)}</span>`;
     }
     const copyBtn = `<button onclick="copyWithFeedback('${escAttrJs(value)}', this)" title="Copy">${ICON_COPY}</button>`;
     let openBtn = '';
@@ -7312,6 +7502,7 @@ try {
 initSidebarResize();
 applyModalZoom();
 loadModalFullscreen();
+initModalResize();
 loadPanelWidths();
 initPanelResize('detail-panel', 'detail-panel-resize', '--detail-panel-width', 'detail-panel-width');
 initPanelResize('message-panel', 'message-panel-resize', '--message-panel-width', 'message-panel-width');

package/public/index.html

@@ -285,7 +285,7 @@
 
   <!-- Message Detail Modal -->
   <div id="msg-detail-modal" class="modal-overlay" onclick="closeMsgDetailModal()">
-    <div class="modal" onclick="event.stopPropagation()" style="max-width: 860px; width: 90vw; max-height: 90vh; display: flex; flex-direction: column;">
+    <div class="modal msg-detail-dialog" onclick="event.stopPropagation()">
       <div class="modal-header">
         <h3 class="modal-title" id="msg-detail-title">Message</h3>
         <div style="display:flex;gap:4px;align-items:center;">

package/public/style.css

@@ -1172,9 +1172,8 @@ body::before {
   padding-right: 8px;
 }
 
-.column-empty {
-  text-align: center;
-  padding: 32px 16px;
+.column-empty,
+.column-add {
   color: var(--text-muted);
   font-size: 12px;
   border: 1px dashed var(--border);
@@ -1182,13 +1181,62 @@ body::before {
   margin-top: 4px;
 }
 
-.column-empty svg {
+.column-empty {
+  text-align: center;
+  padding: 32px 16px;
+}
+
+.column-add {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  width: 100%;
+  padding: 8px 16px;
+  font-family: inherit;
+  background: none;
+  cursor: pointer;
+  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.column-add.empty {
+  flex-direction: column;
+  padding: 32px 16px;
+}
+
+.column-add:hover,
+.column-add:focus-visible {
+  outline: none;
+  color: var(--text-primary);
+  border-color: var(--text-muted);
+  background: var(--bg-hover);
+}
+
+.column-empty svg,
+.column-add.empty svg {
   width: 24px;
   height: 24px;
-  opacity: 0.5;
   margin-bottom: 8px;
 }
 
+.column-empty svg {
+  opacity: 0.5;
+}
+
+.column-add svg {
+  width: 16px;
+  height: 16px;
+  opacity: 0.7;
+  flex-shrink: 0;
+}
+
+.column-add-input {
+  margin-top: 4px;
+  font-size: 12px;
+  background: var(--bg-surface);
+  border-color: var(--accent);
+}
+
 /* #endregion */
 
 /* #region TASK_CARD */
@@ -2805,6 +2853,9 @@ body::before {
 }
 .rendered-md blockquote {
   margin: 0.6em 0;
+  padding-left: 10px;
+  border-left: 2px solid var(--border);
+  color: var(--text-secondary);
 }
 .rendered-md table {
   margin: 0.6em 0;
@@ -3718,6 +3769,7 @@ body.light .msg-assistant .msg-text {
 }
 
 .modal {
+  position: relative;
   background: var(--bg-surface);
   border: 1px solid var(--border);
   border-radius: 12px;
@@ -3731,6 +3783,16 @@ body.light .msg-assistant .msg-text {
   overflow-y: auto;
 }
 
+/* Before .modal.fullscreen on purpose: at equal specificity the later
+   fullscreen rule must win, same as for every other per-modal size. */
+.modal.msg-detail-dialog {
+  width: 90vw;
+  max-width: 860px;
+  max-height: 90vh;
+  display: flex;
+  flex-direction: column;
+}
+
 /* Height is a cap, not a floor — a two-line message should not sit in a 92vh box.
    The HTML preview keeps its explicit height below: its iframe is `height: 100%`
    and needs a resolvable parent height. */
@@ -3740,6 +3802,39 @@ body.light .msg-assistant .msg-text {
   max-height: 92vh;
 }
 
+.modal-resize-handle {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  width: 18px;
+  height: 18px;
+  cursor: nwse-resize;
+  z-index: 1;
+  color: var(--text-muted);
+  opacity: 0.55;
+  border-bottom-right-radius: 11px;
+  background: linear-gradient(
+    135deg,
+    transparent 0 50%,
+    currentColor 50% 56%,
+    transparent 56% 64%,
+    currentColor 64% 70%,
+    transparent 70% 78%,
+    currentColor 78% 84%,
+    transparent 84%
+  );
+}
+
+.modal-resize-handle:hover,
+.modal-resize-handle.dragging {
+  opacity: 1;
+  color: var(--accent);
+}
+
+.modal.fullscreen .modal-resize-handle {
+  display: none;
+}
+
 .modal.plan-modal {
   width: 60vw;
   max-width: 60vw;
@@ -3836,6 +3931,19 @@ body.light .msg-assistant .msg-text {
   max-height: 98vh;
 }
 
+/* User-dragged size (bottom-right grip, app.js initModalResize). Last of the
+   modal sizing rules on purpose: at equal specificity, source order lets it
+   beat every per-modal size above; fullscreen still wins via :not() while
+   active, and JS keeps inline sizing off user-sized modals (autoSizeModal and
+   "Show more" skip them, the drag clears leftovers). Height is a cap, not a
+   floor (same rule as .fullscreen) — short content still collapses. min()
+   keeps a size saved on a large screen inside the current viewport. */
+.modal.user-sized:not(.fullscreen) {
+  width: min(var(--user-modal-w), 98vw);
+  max-width: min(var(--user-modal-w), 98vw);
+  max-height: min(var(--user-modal-h), 95vh);
+}
+
 .preview-html .modal-body,
 .preview-html #preview-modal-body {
   flex: 1 1 auto;

package/server.js

@@ -94,6 +94,9 @@ const CCK_DIR = path.join(CLAUDE_DIR, '.cck');
 const AGENT_ACTIVITY_DIR = path.join(CCK_DIR, 'agent-activity');
 const CONTEXT_STATUS_DIR = path.join(CCK_DIR, 'context-status');
 const PINS_FILE = path.join(CCK_DIR, 'pins.json');
+const SERVER_INFO_FILE = path.join(CCK_DIR, 'server.json');
+// Harness-owned scratchpad root; the per-session dir under it is created lazily.
+const SCRATCHPAD_ROOT = path.join(os.tmpdir(), 'claude');
 
 // Server-side pin mirror (UI authoritative, server stores latest pushed state for CLI queries).
 function readPins() {
@@ -104,17 +107,27 @@ function readPins() {
   return {};
 }
 
-function writePins(pins) {
+function writeJsonAtomic(file, obj) {
   try {
     mkdirSync(CCK_DIR, { recursive: true });
-    const tmp = `${PINS_FILE}.${process.pid}.${Date.now()}.tmp`;
-    writeFileSync(tmp, JSON.stringify(pins, null, 2), 'utf8');
-    renameSync(tmp, PINS_FILE);
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(obj, null, 2), 'utf8');
+    renameSync(tmp, file);
   } catch (e) {
-    console.error('Failed to write pins.json:', e.message);
+    console.error(`Failed to write ${path.basename(file)}:`, e.message);
   }
 }
 
+function writePins(pins) {
+  writeJsonAtomic(PINS_FILE, pins);
+}
+
+// Port discovery for out-of-process helpers (the postman monitor). The pid rides along
+// so a reader can tell a live server from a file left behind by a crashed one.
+function writeServerInfo(port) {
+  writeJsonAtomic(SERVER_INFO_FILE, { port, pid: process.pid });
+}
+
 // #region TIMINGS
 const PERMISSION_TTL_MS = 30 * 60 * 1000;
 const AGENT_TTL_MS = 60 * 60 * 1000;
@@ -560,6 +573,13 @@ function getCustomTaskDir(sessionId) {
   return null;
 }
 
+// Where a session's task files live. The custom-list and team lookups can both miss, and
+// the fallback is the plain per-session dir -- every route that touches a task file needs
+// that same resolution, so it lives in one place.
+function taskDirFor(sessionId) {
+  return getCustomTaskDir(sessionId) || path.join(TASKS_DIR, sessionId);
+}
+
 function getTaskCounts(sessionPath) {
   const cached = taskCountsCache.get(sessionPath);
   if (cached) return cached;
@@ -961,6 +981,14 @@ function getSessionDisplayName(sessionId, meta) {
   return null;
 }
 
+// Derived by convention, not looked up: the harness creates the dir lazily, so a
+// stat here would report "missing" for every session that has not written a temp
+// file yet — and it would put IO on the session-list hot path. Pure string join.
+function getScratchpadDir(id, meta) {
+  if (!meta.jsonlPath) return null;
+  return path.join(SCRATCHPAD_ROOT, path.basename(path.dirname(meta.jsonlPath)), id, 'scratchpad');
+}
+
 function buildSessionObject(id, meta, overrides = {}) {
   const logStat = overrides._logStat || getSessionLogStat(meta);
   const logMtime = logStat.mtime;
@@ -992,6 +1020,7 @@ function buildSessionObject(id, meta, overrides = {}) {
     jsonlPath: meta.jsonlPath || null,
     tasksDir: null,
     projectDir: meta.jsonlPath ? path.dirname(meta.jsonlPath) : null,
+    scratchpadDir: getScratchpadDir(id, meta),
     contextStatus: getContextStatus(id, meta),
     ...getPlanInfo(meta.slug),
     ...getWorkflowInfoSummary(id),
@@ -1398,8 +1427,7 @@ app.get('/api/projects', (req, res) => {
 // API: Get tasks for a session
 app.get('/api/sessions/:sessionId', async (req, res) => {
   try {
-    const customDir = getCustomTaskDir(req.params.sessionId);
-    const sessionPath = customDir || path.join(TASKS_DIR, req.params.sessionId);
+    const sessionPath = taskDirFor(req.params.sessionId);
 
     if (!existsSync(sessionPath)) {
       return res.status(404).json({ error: 'Session not found' });
@@ -2625,13 +2653,54 @@ app.get('/api/tasks/all', async (req, res) => {
   }
 });
 
+const { enqueueSessionEvent, formatTaskMoved, handleSessionEvents } = require('./lib/session-events');
+app.get('/api/sessions/:sessionId/events', handleSessionEvents);
+
+// API: Create a task
+app.post('/api/tasks/:sessionId', async (req, res) => {
+  try {
+    const { sessionId } = req.params;
+    const subject = (req.body.subject || '').trim();
+    if (!subject) return res.status(400).json({ error: 'Subject is required' });
+
+    const sessionDir = taskDirFor(sessionId);
+    if (!existsSync(sessionDir)) mkdirSync(sessionDir, { recursive: true });
+
+    // Ids are the agent's own numbering scheme, so a hand-made task has to keep counting
+    // from the highest one on disk -- reusing a number would overwrite that task's file.
+    const ids = readdirSync(sessionDir)
+      .filter((f) => f.endsWith('.json'))
+      .map((f) => parseInt(path.basename(f, '.json'), 10))
+      .filter((n) => Number.isInteger(n));
+    const id = String(Math.max(0, ...ids) + 1);
+
+    const task = {
+      id,
+      subject,
+      description: (req.body.description || '').trim(),
+      activeForm: subject,
+      status: 'pending',
+      blocks: [],
+      blockedBy: [],
+    };
+
+    // No doorbell here, unlike a move: the user typed this task, so telling their session
+    // about it would only repeat what they just said. Dragging it to In Progress rings.
+    await fs.writeFile(path.join(sessionDir, `${id}.json`), JSON.stringify(task, null, 2));
+    res.json({ success: true, task });
+  } catch (error) {
+    console.error('Error creating task:', error);
+    res.status(500).json({ error: 'Failed to create task' });
+  }
+});
+
 // API: Update task fields (subject, description)
 app.put('/api/tasks/:sessionId/:taskId', async (req, res) => {
   try {
     const { sessionId, taskId } = req.params;
     const { subject, description } = req.body;
 
-    const sessionDir = getCustomTaskDir(sessionId) || path.join(TASKS_DIR, sessionId);
+    const sessionDir = taskDirFor(sessionId);
     const taskPath = path.join(sessionDir, `${taskId}.json`);
 
     if (!existsSync(taskPath)) {
@@ -2639,6 +2708,7 @@ app.put('/api/tasks/:sessionId/:taskId', async (req, res) => {
     }
 
     const task = JSON.parse(await fs.readFile(taskPath, 'utf8'));
+    const prevStatus = task.status;
 
     if (subject !== undefined) task.subject = subject;
     if (description !== undefined) task.description = description;
@@ -2646,6 +2716,17 @@ app.put('/api/tasks/:sessionId/:taskId', async (req, res) => {
 
     await fs.writeFile(taskPath, JSON.stringify(task, null, 2));
 
+    // Ring the session only for a move. The direction has to ride in the line because
+    // the write above destroyed the old status -- nothing downstream can recover it, and
+    // which way a task moved is what decides whether to start work or stop it.
+    if (task.status !== prevStatus) {
+      // The route param is a task *directory*, which for a shared list or team board is
+      // not a session id -- and the postman polls with its own session id, so an unresolved
+      // name would queue the line where nobody drains it.
+      const line = formatTaskMoved(taskId, prevStatus, task);
+      for (const sid of resolveSessionsForTaskDir(sessionId)) enqueueSessionEvent(sid, line);
+    }
+
     res.json({ success: true, task });
   } catch (error) {
     console.error('Error updating task:', error);
@@ -2657,7 +2738,7 @@ app.put('/api/tasks/:sessionId/:taskId', async (req, res) => {
 app.delete('/api/tasks/:sessionId/:taskId', async (req, res) => {
   try {
     const { sessionId, taskId } = req.params;
-    const sessionPath = getCustomTaskDir(sessionId) || path.join(TASKS_DIR, sessionId);
+    const sessionPath = taskDirFor(sessionId);
     const taskPath = path.join(sessionPath, `${taskId}.json`);
 
     if (!existsSync(taskPath)) {
@@ -2953,27 +3034,27 @@ watcher.on('all', (event, filePath) => {
 
     taskCountsCache.delete(path.join(TASKS_DIR, dirName));
 
-    if (isUUID(dirName)) {
-      broadcast({ type: 'update', event, sessionId: dirName, file: path.basename(filePath) });
-    } else {
-      broadcastToMappedSessions(dirName, event, filePath);
-    }
+    broadcastToMappedSessions(dirName, event, filePath);
   }
 });
 
-function broadcastToMappedSessions(taskListName, event, filePath) {
+// Which sessions own a task directory. Usually the dir name IS the session id, but a
+// shared list or a team dir is one directory several sessions map onto -- so anything
+// addressing a session from a task path has to fan out the same way. One resolver for
+// both readers of that mapping: the SSE broadcast and the doorbell.
+function resolveSessionsForTaskDir(name) {
+  if (isUUID(name)) return [name];
   const { listToSessions } = loadAllTaskMaps();
-  const map = listToSessions[taskListName];
-  if (map) {
-    for (const sid of Object.keys(map)) {
-      broadcast({ type: 'update', event, sessionId: sid, file: path.basename(filePath) });
-    }
-    return;
-  }
-  // Fallback: check if taskListName is a team name
-  const cfg = loadTeamConfig(taskListName);
-  if (cfg?.leadSessionId) {
-    broadcast({ type: 'update', event, sessionId: cfg.leadSessionId, file: path.basename(filePath) });
+  const map = listToSessions[name];
+  if (map) return Object.keys(map);
+  // Fallback: check if name is a team name
+  const cfg = loadTeamConfig(name);
+  return cfg?.leadSessionId ? [cfg.leadSessionId] : [];
+}
+
+function broadcastToMappedSessions(taskListName, event, filePath) {
+  for (const sid of resolveSessionsForTaskDir(taskListName)) {
+    broadcast({ type: 'update', event, sessionId: sid, file: path.basename(filePath) });
   }
 }
 
@@ -3202,6 +3283,9 @@ async function prewarmCaches() {
 
   const onReady = (actualPort) => {
     console.log(`Claude Task Kanban running at http://localhost:${actualPort}`);
+    // The port is configurable and falls back to a random one when taken, so the postman
+    // monitor cannot assume it -- publish the live one where it can read it.
+    writeServerInfo(actualPort);
     const warning = net.exposureWarning();
     if (warning) console.log(warning);