claude-code-kanban 7.17.0 → 7.18.0

package/README.md

@@ -8,58 +8,45 @@ Start, watch and answer Claude Code sessions from one live board, with a termina
 
 **[Documentation](https://nikiforovall.blog/claude-code-kanban/)**
 
-<a href="https://youtu.be/QbvDBFyfC7s">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="website/public/video/cck-dark.webp">
-    <img alt="Claude Code Kanban tour video (74 seconds). Opens on YouTube." src="website/public/video/cck-light.webp">
-  </picture>
-</a>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-01-board-session-log-dark.webp">
+  <img alt="The board with the session list, task columns, the agents log and the session log of tool calls." src="website/public/shots/themes/ember-01-board-session-log-light.webp">
+</picture>
 
-Watch the tour on YouTube: [light](https://youtu.be/QbvDBFyfC7s), [dark](https://youtu.be/bXZ4_QCmD7k).
+<table>
+  <tr>
+    <td width="33%"><picture><source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-terminal-dark.webp"><img alt="The embedded terminal with a show card checklist next to it." src="website/public/shots/themes/ember-terminal-light.webp"></picture></td>
+    <td width="33%"><picture><source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-13b-split-view-dark.webp"><img alt="The board split with an HTML preview pane." src="website/public/shots/themes/ember-13b-split-view-light.webp"></picture></td>
+    <td width="33%"><picture><source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-14b-show-chart-dark.webp"><img alt="A show card with a spend chart over the terminal." src="website/public/shots/themes/ember-14b-show-chart-light.webp"></picture></td>
+  </tr>
+  <tr>
+    <td align="center">Embedded terminal</td>
+    <td align="center">Panes and split view</td>
+    <td align="center">Show cards</td>
+  </tr>
+</table>
+
+Watch the 74-second tour on YouTube: [light](https://youtu.be/QbvDBFyfC7s), [dark](https://youtu.be/bXZ4_QCmD7k).
 
 ## Getting started
 
 You need Node.js 20 or later and the `claude` CLI.
 
-### 1. Install the command
-
-```bash
-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 `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.
+### 1. Run it in Claude Code Hub
 
-### 3. Start the board
+[Claude Code Hub](https://nikiforovall.blog/claude-code-hub/) runs the board as a tab next to Cost, Marketplace and Memory, in one window with keyboard switching. The embedded terminal is on by default, and the board opens a session's cost, plugins and memory in the other tabs.
 
 ```bash
-claude-code-kanban --open
+npm install -g claude-code-hub
+claude-code-hub --install   # one time: installs this board's plugin
+claude-code-hub --open
 ```
 
-The board runs at `http://localhost:3541`.
+The hub runs at `http://localhost:3540`. See [Claude Code Hub](https://nikiforovall.blog/claude-code-kanban/guides/claude-code-hub/) for how the board works there. To run the board without the hub, see [Appendix: run the board standalone](#appendix-run-the-board-standalone).
 
-### 4. Use Claude Code as usual
+### 2. 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.
-
-> **Empty board?** Claude Code ships the task tools off by default on some models, so Claude writes no tasks. Turn them on in the `env` block of Claude Code `settings.json`, then restart Claude Code:
->
-> ```json
-> { "env": { "CLAUDE_CODE_ENABLE_TODO_TOOLS": "true" } }
-> ```
->
-> You can also add a task by hand with **Add task** in the Pending column.
+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. If the board stays empty, see [Appendix: empty board](#appendix-empty-board).
 
 ## Features
 
@@ -133,7 +120,45 @@ EDITOR="code -w" claude-code-kanban        # Command for Open in editor (default
 
 See [Configuration](https://nikiforovall.blog/claude-code-kanban/reference/configuration/) for every setting, and [Troubleshooting](https://nikiforovall.blog/claude-code-kanban/troubleshooting/) for common problems.
 
-Claude Code Kanban also runs as a tab in [Claude Code Hub](https://nikiforovall.blog/claude-code-kanban/guides/claude-code-hub/), where the terminal is on by default.
+## Appendix: run the board standalone
+
+### 1. Install the command
+
+```bash
+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 `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.
+
+### 3. Start the board
+
+```bash
+claude-code-kanban --open
+```
+
+The board runs at `http://localhost:3541`. Then use Claude Code as usual.
+
+## Appendix: empty board
+
+Claude Code ships the task tools off by default on some models, so Claude writes no tasks. Turn them on in the `env` block of Claude Code `settings.json`, then restart Claude Code:
+
+```json
+{ "env": { "CLAUDE_CODE_ENABLE_TODO_TOOLS": "true" } }
+```
+
+You can also add a task by hand with **Add task** in the Pending column.
 
 ## License
 

package/hub-app.json

@@ -5,6 +5,29 @@
   "icon": "columns",
   "run": { "entry": "server.js", "defaultPort": 3541 },
   "publishes": ["session.changed"],
+  "settings": [
+    {
+      "key": "zenCentered",
+      "type": "boolean",
+      "label": "Center zen mode",
+      "help": "In zen mode, centers the session card and its panel in the sidebar's height.",
+      "default": false
+    },
+    {
+      "key": "zenPattern",
+      "type": "choice",
+      "label": "Zen mode pattern",
+      "help": "In zen mode, fills the sidebar's free space with a pattern tinted by the session's state.",
+      "options": [
+        { "value": "none", "label": "None" },
+        { "value": "dots", "label": "Dots" },
+        { "value": "diagonal", "label": "Diagonal" },
+        { "value": "rings", "label": "Rings" },
+        { "value": "grid", "label": "Grid" }
+      ],
+      "default": "dots"
+    }
+  ],
   "keys": { "keeps": ["ctrl+alt+1", "ctrl+alt+2", "ctrl+alt+3", "ctrl+alt+4", "ctrl+alt+5", "ctrl+alt+6", "ctrl+alt+7", "ctrl+alt+8", "ctrl+alt+9", "ctrl+alt+n", "ctrl+alt+r", "ctrl+alt+s", "ctrl+shift+d", "ctrl+shift+k", "ctrl+shift+l", "ctrl+shift+m", "ctrl+shift+p", "ctrl+shift+z"] },
   "plugin": {
     "marketplace": "plugin",

package/package.json

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

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

@@ -1,5 +1,5 @@
 {
   "name": "claude-code-kanban",
-  "version": "3.7.11",
+  "version": "3.7.14",
   "description": "claude-code-kanban dashboard integration: agent activity tracking, context and cost tracking, board moves and reviews delivered to the session, and skills to drive the board from a session"
 }

package/plugin/plugins/claude-code-kanban/hooks/activity.ts

@@ -150,14 +150,19 @@ async function markStopped($: EngineInterface) {
 
 // The name map lets TeammateIdle, which names the teammate, find its agent id. The prompt is on
 // the start line because a resume runs a new prompt, and the server's own lookup finds the first.
-async function agentStarted($: EngineInterface, e: AgentSpawnInput, agentId: string, model: string) {
+async function agentStarted(
+  $: EngineInterface,
+  e: Partial<Pick<AgentSpawnInput, 'subagentType' | 'prompt' | 'description' | 'name'>>,
+  agentId: string,
+  model?: string,
+) {
   const dir = await sessionDir($)
   const ts = new Date().toISOString()
   await Promise.all([
     appendLine($, `${dir}/${agentId}.jsonl`, {
       agentId,
       type: e.subagentType,
-      model,
+      ...(model && { model }),
       event: 'start',
       status: 'active',
       ...(e.prompt && { prompt: e.prompt }),
@@ -169,6 +174,27 @@ async function agentStarted($: EngineInterface, e: AgentSpawnInput, agentId: str
   ])
 }
 
+// A forked skill fires no agent.spawn, but $.agent.list() names it; internal loops (compaction,
+// memory) and workflow agents it does not. A spawned agent's turn.start runs inside its spawn's
+// next(), and a second start line would reset the server's fold, so turn.start leaves the agents
+// of a spawn in flight to the spawn; turn.complete catches a fork that started in that window.
+const tracked = new Map<string, Promise<void>>()
+let spawning = 0
+
+function trackAgent($: EngineInterface, agentId: string, prompt?: string) {
+  const found = tracked.get(agentId) ?? startUnspawned($, agentId, prompt).catch(() => {})
+  tracked.set(agentId, found)
+  return found
+}
+
+async function startUnspawned($: EngineInterface, agentId: string, prompt?: string) {
+  if (await $.fs.exists(`${await sessionDir($)}/${agentId}.jsonl`)) return
+  const agent = (await $.agent.list()).find(a => a.id === agentId)
+  if (!agent) return
+  const { type: subagentType, description, name } = agent
+  await agentStarted($, { subagentType, description, name, prompt }, agentId)
+}
+
 // turn.complete also ends loops agent.spawn never started (internal agents): those have no file.
 async function agentStopped($: EngineInterface, agentId: string, lastMessage: string) {
   const ts = new Date().toISOString()
@@ -251,13 +277,26 @@ export const register: Register = on => {
     return next(e)
   })
   on('agent.spawn', async ($, e, next) => {
-    const result = await next(e)
-    if (result.agentId) await agentStarted($, e, result.agentId, result.model)
-    return result
+    spawning++
+    try {
+      const result = await next(e)
+      if (result.agentId) await agentStarted($, e, result.agentId, result.model)
+      return result
+    } finally {
+      spawning--
+    }
+  })
+  on('turn.start', async ($, e, next) => {
+    if (e.agentId && !spawning) await trackAgent($, e.agentId, e.text || undefined)
+    return next(e)
   })
   // An interrupted turn fires no Stop hook, so it does not mark the session unread either.
   on('turn.complete', async ($, e, next) => {
-    if (e.agentId) await agentStopped($, e.agentId, e.answer)
+    if (e.agentId) {
+      await trackAgent($, e.agentId)
+      tracked.delete(e.agentId)
+      await agentStopped($, e.agentId, e.answer)
+    }
     else if (!e.isAborted) await markStopped($)
     return next(e)
   })

package/plugin/plugins/claude-code-kanban/hooks/show.ts

@@ -1,8 +1,8 @@
 import type { EngineInterface, Register } from 'claude-code'
 import { cckRoot } from './context'
+import { boardUrl } from './doorbell'
 
 export const TOOL = 'mcp__claude-code-kanban__show'
-export const SKILL_LINE = /^\s*-\s*claude-code-kanban:show(?=:|\s*$)/
 
 type ShowInput = { title: string; key?: string; kind?: 'markdown' | 'html'; file?: string; base?: string }
 type Shown = { title: string; key?: string | null; index: number; count: number; path?: string | null }
@@ -16,13 +16,6 @@ export function shownText({ title, key, index, count, path }: Shown, claim = fal
   return claim ? `Card ${at} is ready. Write it to ${path}; the card refreshes on each save.` : `Shown ${at}`
 }
 
-export function dropSkillLine(listing: string) {
-  return listing
-    .split('\n')
-    .filter(l => !SKILL_LINE.test(l))
-    .join('\n')
-}
-
 let cck: Promise<string> | undefined
 
 function cckDir($: EngineInterface) {
@@ -62,64 +55,111 @@ function errorText(status: number, text: string) {
   return `cck answered HTTP ${status}`
 }
 
-async function post($: EngineInterface, input: ShowInput) {
-  const t = await terminal($)
-  if (!t) return { deny: 'The overlay needs a Claude Code session started in the cck terminal.' }
-  const token = await terminalToken($, t.url)
-  if (!token) return { deny: `No terminal token for the cck server at ${t.url}. It must run with the terminal enabled.` }
-  const { title, key, kind, file, base } = input
-  const body = JSON.stringify({ sessionId: await $.session.id(), title, key, kind, file, base })
-  let res: Awaited<ReturnType<EngineInterface['http']['fetch']>>
+async function send(
+  $: EngineInterface,
+  url: string,
+  path: string,
+  headers: Record<string, string>,
+  body: unknown,
+): Promise<{ text: string } | { deny: string }> {
   try {
-    res = await $.http.fetch(`${t.url}/api/terminals/${encodeURIComponent(t.terminalId)}/show`, {
+    const res = await $.http.fetch(`${url}${path}`, {
       method: 'POST',
-      headers: { 'content-type': 'application/json', 'x-terminal-token': token },
-      body,
+      headers: { 'content-type': 'application/json', ...headers },
+      body: JSON.stringify(body),
     })
+    return res.ok ? { text: res.text } : { deny: errorText(res.status, res.text) }
   } catch (err) {
-    return { deny: `Cannot reach cck at ${t.url}: ${err instanceof Error ? err.message : String(err)}` }
+    return { deny: `Cannot reach cck at ${url}: ${err instanceof Error ? err.message : String(err)}` }
   }
-  if (!res.ok) return { deny: errorText(res.status, res.text) }
+}
+
+async function post($: EngineInterface, t: { url: string; terminalId: string }, input: ShowInput) {
+  const token = await terminalToken($, t.url)
+  if (!token) return { deny: `No terminal token for the cck server at ${t.url}. It must run with the terminal enabled.` }
+  const { title, key, kind, file, base } = input
+  const body = { sessionId: await $.session.id(), title, key, kind, file, base }
+  const res = await send($, t.url, `/api/terminals/${encodeURIComponent(t.terminalId)}/show`, { 'x-terminal-token': token }, body)
+  if ('deny' in res) return res
   return { result: shownText(JSON.parse(res.text) as Shown, file == null) }
 }
 
+// Read on every post, as the doorbell does, so a board that restarted on another port is found.
+async function findBoard($: EngineInterface) {
+  try {
+    return boardUrl(undefined, await $.fs.read(`${await cckDir($)}/server.json`))
+  } catch {
+    return undefined
+  }
+}
+
+export const CLAIM_OFF_TERMINAL =
+  'No overlay here: write the card to a markdown or HTML file in your scratchpad directory, then call show again with file.'
+
+export function paneText(title: string, added: boolean) {
+  return added
+    ? `Added "${title}" as a tab of this session on the cck board, in the background. Tell the user it waits there; the tab refreshes on each save.`
+    : `The board already has a tab for this file; it refreshes on each save.`
+}
+
+async function postPane($: EngineInterface, { title, file }: ShowInput) {
+  if (file == null) return { result: CLAIM_OFF_TERMINAL }
+  const [url, sessionId] = await Promise.all([findBoard($), $.session.id()])
+  if (!url) return { deny: 'The cck board is not running. Ask the user to start it, or give them the file path.' }
+  const res = await send($, url, `/api/panes/${encodeURIComponent(sessionId)}`, {}, { target: file, title, show: true })
+  if ('deny' in res) return res
+  const { added } = JSON.parse(res.text) as { added: boolean }
+  return { result: paneText(title, added) }
+}
+
+const WHEN =
+  'Post one when the user asks you to show, draw or visualize something, or when your answer is a comparison of 4 or more rows, a flow, or numbers over time. Pick the form that makes the point best: a table, chart, diagram, mockup, small widget or a mix.'
+
+const FILE = { type: 'string', description: 'Absolute path of an existing markdown, HTML, image or text file' }
+
+const PANE_TOOL = {
+  description: `Show a card as a tab of this session on the cck board. ${WHEN} Write the card to a markdown or HTML file in your scratchpad directory, then pass it as file; post again after a new file, and edit the same file to update its tab, which refreshes on each save. For an HTML card, load the claude-code-kanban:show skill first for the HTML contract. The tab opens in the background: in your reply, say what the card shows and that it waits on the board.`,
+  inputSchema: {
+    type: 'object',
+    properties: { title: { type: 'string', description: 'Tab title' }, file: FILE },
+    required: ['title', 'file'],
+  },
+}
+
+const OVERLAY_TOOL = {
+  description: `Show a card in the cck overlay above this terminal. ${WHEN} Give each card a key that names what it shows (for example latency-chart), and post again with that key to update the card in place instead of adding a new one. Without file, the tool answers with a path: write the card there with Write, and change it with Edit; the card refreshes on each save. Pass file to show a file that already exists. To explain code with a call stack or a tree, load the claude-code-kanban:show skill first for the notation. The user sees the rendered card and knows you do not; in your reply, say what the card shows, and take the render as given.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      title: { type: 'string', description: 'Card title' },
+      kind: {
+        type: 'string',
+        enum: ['markdown', 'html'],
+        description:
+          'markdown (default): mermaid, diff and code fences render. html: a body fragment; load the claude-code-kanban:show skill first for the HTML contract',
+      },
+      file: FILE,
+      key: { type: 'string', description: 'Card name: the same key replaces the card in place and keeps its file' },
+      base: {
+        type: 'string',
+        description:
+          "Absolute path of the folder that the card's path:line links resolve against, usually the repo root. Always pass it with a call stack. Without it, links resolve against the session cwd, which is wrong for a worktree or another repo",
+      },
+    },
+    required: ['title'],
+  },
+}
+
 // A -p run is detached from the terminal, so only an interactive session gets the tool.
 export const register: Register = on => {
   on('session.start', { isInteractive: true }, async ($, e, next) => {
-    if (await terminal($)) {
-      await $.tool.register({
-        name: 'show',
-        description:
-          'Show a card in the cck overlay above this terminal. Post one when the user asks you to show, draw or visualize something, or when your answer is a comparison of 4 or more rows, a flow, or numbers over time. Pick the form that makes the point best: a table, chart, diagram, mockup, small widget or a mix. Give each card a key that names what it shows (for example latency-chart), and post again with that key to update the card in place instead of adding a new one. Without file, the tool answers with a path: write the card there with Write, and change it with Edit; the card refreshes on each save. Pass file to show a file that already exists. To explain code with a call stack or a tree, load the claude-code-kanban:show skill first for the notation. The user sees the rendered card and knows you do not; in your reply, say what the card shows, and take the render as given.',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            title: { type: 'string', description: 'Card title' },
-            kind: {
-              type: 'string',
-              enum: ['markdown', 'html'],
-              description:
-                'markdown (default): mermaid, diff and code fences render. html: a body fragment; load the claude-code-kanban:show skill first for the HTML contract',
-            },
-            file: { type: 'string', description: 'Absolute path of an existing markdown, HTML, image or text file' },
-            key: { type: 'string', description: 'Card name: the same key replaces the card in place and keeps its file' },
-            base: {
-              type: 'string',
-              description:
-                "Absolute path of the folder that the card's path:line links resolve against, usually the repo root. Always pass it with a call stack. Without it, links resolve against the session cwd, which is wrong for a worktree or another repo",
-            },
-          },
-          required: ['title'],
-        },
-      })
-    }
+    await $.tool.register({ name: 'show', ...((await terminal($)) ? OVERLAY_TOOL : PANE_TOOL) })
     return next(e)
   })
 
-  on('tool.call', { tool: TOOL }, async ($, e) => post($, e as unknown as ShowInput))
-
-  on('prompt.attachment', { type: 'skill_listing' }, async ($, e, next) => {
-    if (await terminal($)) return next(e)
-    return next({ ...e, text: dropSkillLine(e.text) })
+  on('tool.call', { tool: TOOL }, async ($, e) => {
+    const input = e as unknown as ShowInput
+    const t = await terminal($)
+    return t ? post($, t, input) : postPane($, input)
   })
 }

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

@@ -46,6 +46,7 @@ Every exhibit, ready or new, keeps these:
 - Colors come from the tokens on every draw, in canvas too, so a theme change needs no extra code.
 - Nothing runs while the reader does nothing, except a running model that is on screen.
 - Numbers from a model are marked as model numbers.
+- When the reader's choice should come back to the session, such as quiz answers or a pick, wrap the inputs in `<form data-cck-submit="<name>">`, or put `data-cck-action="<name>"` on one button. It works in a board pane: the session gets the fields as its next prompt. The board sends only on a real click. Give `type="button"` to buttons that must not send, and call `preventDefault` on the submit so the page also works outside cck.
 - The script goes at the end of `<body>`; its CSS goes in the second `<style>`.
 
 ## Blocks

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

@@ -1,4 +1,4 @@
-import type { On, ToolCallArgs, ToolCheckDecision } from 'claude-code'
+import type { AgentInfo, On, ToolCallArgs, ToolCheckDecision } from 'claude-code'
 import { type Engine, expect, type MockClock, mock, test } from 'claude-code/testing'
 import { BOARD_ALLOWED, CLEARED } from '../hooks/activity'
 
@@ -7,11 +7,20 @@ const SESSION = `${ROOT}/sid-1`
 const MARKER = `${SESSION}/_waiting.json`
 const CONFIG = 'C:/cfg/.cck/config.json'
 
-type EngineOptions = { decision?: ToolCheckDecision; rule?: string; env?: Record<string, string> }
+type EngineOptions = {
+  decision?: ToolCheckDecision
+  rule?: string
+  env?: Record<string, string>
+  agents?: AgentInfo[]
+}
 
-// A test hook cannot raise tool.check, so the test raises it (askFor), and the engine's tool.call
-// holds the first call until the test answers the terminal prompt.
-function engine(on: On, files: Record<string, string>, { decision = 'allow', rule, env = {} }: EngineOptions = {}) {
+// The engine raises tool.check inside the call, and its ask waits in classic.PermissionRequest
+// until the test answers the terminal prompt.
+function engine(
+  on: On,
+  files: Record<string, string>,
+  { decision = 'allow', rule, env = {}, agents = [] }: EngineOptions = {},
+) {
   const writes: { path: string; text: string }[] = []
   const runs: unknown[] = []
   const status: (string | undefined)[] = []
@@ -38,29 +47,28 @@ function engine(on: On, files: Record<string, string>, { decision = 'allow', rul
     return { value: undefined }
   })
   on('tool.check', () => ({ decision, rule }))
-  let held = decision === 'ask'
   on('tool.call', async (_$, e) => {
     const { tool, tool_use_id, agentId, ...input } = e
-    if (held) {
-      held = false
-      await terminal
-    }
     runs.push(input)
     return { result: { stdout: 'ok' } }
   })
   on('session.start', (_$, e) => ({ cwd: e.cwd }))
   on('agent.spawn', () => ({ model: 'haiku', agentId: 'a1' }))
+  on('agent.list', () => ({ value: agents }))
+  on('fs.exists', (_$, e) => ({ value: norm(e.path) in files }))
+  on('turn.start', (_$, e) => ({ turnId: e.turnId }))
   on('turn.complete', (_$, e) => ({ text: e.answer }))
+  on('classic.PermissionRequest', async () => {
+    await terminal
+    return { decision: { behavior: 'allow' as const } }
+  })
   on('classic.*', () => ({}))
   return { writes, runs, status, answer }
 }
 
 async function askFor($: Engine, clock: MockClock, args: { tool: string } & Record<string, unknown>) {
-  const { tool, ...input } = args
   const call = $.tool.call(args as ToolCallArgs)
   await clock.settle()
-  await $.tool.check({ tool, input })
-  await clock.settle()
   return { call }
 }
 
@@ -305,6 +313,64 @@ test('a finished loop that was never spawned writes nothing', async ($, on) => {
   expect(writes).toEqual([])
 })
 
+const forked: AgentInfo = {
+  id: 'f1',
+  type: 'general-purpose',
+  description: '/code-review high',
+  status: 'running',
+  name: 'code-review',
+}
+
+test('a forked skill is recorded at its turn start and stopped at its end', async ($, on) => {
+  const files: Record<string, string> = {}
+  engine(on, files, { agents: [forked] })
+
+  await $.turn.start({ text: 'review the MR', turnId: 't', agentId: 'f1' })
+  await $.turn.complete(turn({ agentId: 'f1', answer: 'review done' }))
+
+  const all = lines(files[`${SESSION}/f1.jsonl`])
+  expect(all.map(l => l.event)).toEqual(['start', 'stop'])
+  expect(all[0]).toMatchObject({
+    agentId: 'f1',
+    type: 'general-purpose',
+    description: '/code-review high',
+    prompt: 'review the MR',
+  })
+  expect('model' in all[0]).toBe(false)
+  expect(all[1]).toMatchObject({ status: 'stopped', lastMessage: 'review done' })
+  expect(files[`${SESSION}/_name-code-review.id`]).toBe('f1')
+})
+
+test('a forked skill whose start no hook heard is recorded at its end', async ($, on) => {
+  const files: Record<string, string> = {}
+  engine(on, files, { agents: [{ ...forked, id: 'f2' }] })
+
+  await $.turn.complete(turn({ agentId: 'f2' }))
+
+  expect(lines(files[`${SESSION}/f2.jsonl`]).map(l => l.event)).toEqual(['start', 'stop'])
+})
+
+test('a spawned subagent turn start adds no second start line', async ($, on) => {
+  const files: Record<string, string> = {}
+  engine(on, files, { agents: [{ ...forked, id: 'a1' }] })
+
+  await $.agent.spawn(spawn('general-purpose'))
+  await $.turn.start({ text: 'p', turnId: 't', agentId: 'a1' })
+
+  expect(lines(files[`${SESSION}/a1.jsonl`]).map(l => l.event)).toEqual(['start'])
+})
+
+test('a turn start inside its spawn leaves the start line to the spawn', async ($, on) => {
+  const files: Record<string, string> = {}
+  engine(on, files, { agents: [{ ...forked, id: 'a1' }] })
+
+  await Promise.all([$.agent.spawn(spawn('general-purpose')), $.turn.start({ text: 'p', turnId: 't', agentId: 'a1' })])
+
+  const all = lines(files[`${SESSION}/a1.jsonl`])
+  expect(all.map(l => l.event)).toEqual(['start'])
+  expect(all[0]).toMatchObject({ model: 'haiku' })
+})
+
 test('a named spawn maps the name, and TeammateIdle finds the agent by it', async ($, on) => {
   const files: Record<string, string> = {}
   engine(on, files)

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

@@ -23,6 +23,7 @@ function engine(on: On, replies: (() => Reply)[], submit?: () => Promise<unknown
   on('env.get', (_$, e) => ({ value: { CLAUDE_CONFIG_DIR: 'C:/cfg' }[e.name] }))
   on('session.id', () => ({ value: sessionId }))
   on('session.start', (_$, e) => ({ cwd: e.cwd }))
+  on('tool.register', (_$, e) => ({ value: { tool: `mcp__claude-code-kanban__${e.name}` } }))
   on('http.fetch', async (_$, e) => {
     urls.push(e.url)
     const reply = replies.shift()

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

@@ -1,26 +1,20 @@
 import type { On, ToolCallArgs } from 'claude-code'
-import { expect, test } from 'claude-code/testing'
-import { boardPort, dropSkillLine, shownText, TOOL } from '../hooks/show'
+import { expect, mock, test } from 'claude-code/testing'
+import { boardPort, CLAIM_OFF_TERMINAL, paneText, shownText, TOOL } from '../hooks/show'
 
 const CCK_URL = 'http://127.0.0.1:4100'
 const TERMINAL_ID = 'term-1'
 const TOKEN_FILE = 'C:/cfg/.cck/terminal-tokens/4100.json'
-const LISTING = [
-  'The following skills are available for use with the Skill tool:',
-  '',
-  '- claude-code-kanban:dispatch',
-  '- claude-code-kanban:show',
-  '- claude-code-kanban:kanban: Kanban board CLI',
-  '- meta:show-me: Help the user understand the current topic visually',
-].join('\n')
+const SERVER_FILE = 'C:/cfg/.cck/server.json'
 
 type Reply = { status: number; body: unknown } | Error
 type Request = { url: string; method?: string; headers?: Record<string, string>; body?: unknown }
 
 function engine(on: On, env: Record<string, string>, reply?: Reply) {
-  const registered: string[] = []
+  const registered: { name: string; required: unknown }[] = []
   const requests: Request[] = []
-  const files: Record<string, string> = { [TOKEN_FILE]: '{"token":"tok-abc"}' }
+  const files: Record<string, string> = { [TOKEN_FILE]: '{"token":"tok-abc"}', [SERVER_FILE]: '{"pid":1,"port":4100}' }
+  mock.clock(on)
   on('env.get', (_$, e) => ({ value: { CLAUDE_CONFIG_DIR: 'C:/cfg', ...env }[e.name] }))
   on('fs.read', (_$, e) => {
     const text = files[e.path.replaceAll('\\', '/')]
@@ -30,12 +24,11 @@ function engine(on: On, env: Record<string, string>, reply?: Reply) {
   on('session.id', () => ({ value: 'sid-1' }))
   on('session.start', (_$, e) => ({ cwd: e.cwd }))
   on('tool.register', (_$, e) => {
-    registered.push(e.name)
+    registered.push({ name: e.name, required: (e.inputSchema as { required?: unknown }).required })
     return { value: { tool: `mcp__claude-code-kanban__${e.name}` } }
   })
-  on('prompt.attachment', (_$, e) => ({ text: e.text }))
   on('http.fetch', (_$, e) => {
-    if (!e.url.includes('/show')) return new Promise(() => {})
+    if (!/\/show$|\/api\/panes\//.test(e.url)) return new Promise(() => {})
     const { method, headers, body } = (e.init ?? {}) as Omit<Request, 'url'>
     requests.push({ url: e.url, method, headers, body: typeof body === 'string' ? JSON.parse(body) : body })
     if (!reply) throw new Error('no reply')
@@ -46,10 +39,9 @@ function engine(on: On, env: Record<string, string>, reply?: Reply) {
 }
 
 const GATE = { CCK_URL, CCK_TERMINAL_ID: TERMINAL_ID }
-const listing = { type: 'skill_listing', text: LISTING, origin: { kind: 'engine' } } as const
 const call = (input: Record<string, unknown>) => ({ tool: TOOL, ...input }) as ToolCallArgs
 
-test('helpers: the port of CCK_URL, the answer line, the listing filter', async () => {
+test('helpers: the port of CCK_URL, the answer lines', async () => {
   expect(boardPort('http://127.0.0.1:4100')).toBe('4100')
   expect(boardPort('http://localhost:3541/')).toBe('3541')
   expect(boardPort('http://localhost')).toBe(undefined)
@@ -58,24 +50,67 @@ test('helpers: the port of CCK_URL, the answer line, the listing filter', async
   expect(shownText({ title: 'Plan', key: 'plan', index: 1, count: 1, path: 'C:/s/p1.md' }, true)).toBe(
     'Card "Plan" (plan, 1/1) is ready. Write it to C:/s/p1.md; the card refreshes on each save.',
   )
-  expect(dropSkillLine(LISTING)).toBe(LISTING.replace('- claude-code-kanban:show\n', ''))
-  expect(dropSkillLine('- claude-code-kanban:show: Show a diagram\n- x')).toBe('- x')
+  expect(paneText('Plan', false)).toBe('The board already has a tab for this file; it refreshes on each save.')
 })
 
-test('gate off: no tool, and the skill line is dropped', async ($, on) => {
+test('in the terminal: the overlay tool, file optional', async ($, on) => {
+  const board = engine(on, GATE)
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  expect(board.registered).toEqual([{ name: 'show', required: ['title'] }])
+})
+
+test('outside the terminal: the pane tool, file required', async ($, on) => {
   const board = engine(on, { CCK_URL })
   await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
-  expect(board.registered).toEqual([])
-  const { text } = await $.prompt.attachment(listing)
-  expect(text).toBe(LISTING.replace('- claude-code-kanban:show\n', ''))
+  expect(board.registered).toEqual([{ name: 'show', required: ['title', 'file'] }])
 })
 
-test('gate on: the tool is registered and the skill line stays', async ($, on) => {
-  const board = engine(on, GATE)
+test('outside the terminal: a file post adds a show pane on the board of server.json', async ($, on) => {
+  const board = engine(on, {}, { status: 200, body: { pane: { id: 'p1' }, added: true } })
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  const res = await $.tool.call(call({ title: 'Plan', file: 'C:/s/plan.html' }))
+  expect(res.result).toBe(paneText('Plan', true))
+  expect(board.requests).toEqual([
+    {
+      url: 'http://127.0.0.1:4100/api/panes/sid-1',
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: { target: 'C:/s/plan.html', title: 'Plan', show: true },
+    },
+  ])
+})
+
+test('outside the terminal: the same file again answers that the tab exists', async ($, on) => {
+  engine(on, {}, { status: 200, body: { pane: { id: 'p1' }, added: false } })
   await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
-  expect(board.registered).toEqual(['show'])
-  const { text } = await $.prompt.attachment(listing)
-  expect(text).toBe(LISTING)
+  const res = await $.tool.call(call({ title: 'Plan', file: 'C:/s/plan.html' }))
+  expect(res.result).toBe(paneText('Plan', false))
+})
+
+test('outside the terminal: a claim sends nothing and asks for a file', async ($, on) => {
+  const board = engine(on, {})
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  const res = await $.tool.call(call({ title: 'Plan' }))
+  expect(res.result).toBe(CLAIM_OFF_TERMINAL)
+  expect(board.requests).toEqual([])
+})
+
+test('outside the terminal: no board, no request, an error that says so', async ($, on) => {
+  // CCK_URL keeps the doorbell on its open poll: without a board it sleeps, and the unload rejects that sleep.
+  const board = engine(on, { CCK_URL })
+  delete board.files[SERVER_FILE]
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  const res = await $.tool.call(call({ title: 'Plan', file: 'C:/s/plan.md' }))
+  expect(res.deny).toContain('not running')
+  expect(board.requests).toEqual([])
+})
+
+test('outside the terminal: a board refusal reaches the model with its text', async ($, on) => {
+  const error = 'Not a previewable text, markdown, HTML or image file'
+  engine(on, {}, { status: 400, body: { error } })
+  await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
+  const res = await $.tool.call(call({ title: 'Zip', file: 'C:/s/a.zip' }))
+  expect(res.deny).toBe(error)
 })
 
 test('a -p run gets no tool', async ($, on) => {

package/public/app.js

@@ -571,6 +571,9 @@ function sessionBarClass(s) {
 function isActiveSession(s) {
   return !isWaitingSession(s) && (s.inProgress > 0 || s.hasRecentLog || s.hasRunningAgents);
 }
+function sessionState(s) {
+  return isWaitingSession(s) ? 'waiting' : isActiveSession(s) ? 'working' : 'idle';
+}
 // hasRecentLog carries the server's registry-idle correction: an open-but-idle
 // terminal keeps touching its JSONL, so mtime alone is not proof of activity.
 function isSessionLive(s) {
@@ -815,6 +818,7 @@ async function fetchTasks(sessionId) {
 //#region TIMINGS
 const WAITING_TTL_MS = 30 * 60 * 1000;
 const AGENT_LOG_MAX = 8;
+const ZEN_AGENTS_MAX = 5;
 const LIVE_INDICATOR_MS = 10 * 1000;
 const JUST_NOW_MS = 60 * 1000;
 //#endregion
@@ -3397,17 +3401,63 @@ function formatDuration(ms) {
 //#endregion
 
 //#region AGENTS
-function renderAgentFooter() {
-  const footer = document.getElementById('agent-footer');
-  const content = document.getElementById('agent-footer-content');
-  const label = document.getElementById('agent-footer-label');
+function agentTypeParts(a) {
+  const raw = a.type || 'unknown';
+  const colonIdx = raw.indexOf(':');
+  return colonIdx > 0
+    ? { raw, ns: raw.substring(0, colonIdx + 1), name: raw.substring(colonIdx + 1) }
+    : { raw, ns: '', name: raw };
+}
+
+function agentTaskText(a) {
+  if (a.description) return a.description;
+  const prompt = stripAnsi(stripTeammateWrapper((a.prompt || '').trim())).replace(/[\r\n]+/g, ' ');
+  return prompt || agentTypeParts(a).name;
+}
+
+function agentElapsed(a, now) {
+  return a.status === 'stopped' && a.stoppedAt
+    ? new Date(a.stoppedAt).getTime() - new Date(a.startedAt || a.stoppedAt).getTime()
+    : now - new Date(a.startedAt || a.updatedAt).getTime();
+}
+
+function agentIdentHtml(a) {
+  const { raw, ns, name } = agentTypeParts(a);
+  const fullModel = agentModel(a);
+  const model = shortModelName(fullModel);
+  const modelHtml = model
+    ? `<span class="agent-card-model" title="${escapeHtml(fullModel)}">${escapeHtml(model)}</span><span class="agent-ident-sep">·</span>`
+    : '';
+  return `${modelHtml}<span class="agent-type-name" title="${escapeHtml(raw)}">${ns ? `<span class="agent-type-ns">${escapeHtml(ns)}</span>` : ''}${escapeHtml(name)}</span>`;
+}
+
+// The count names every running agent; the rows stop at ZEN_AGENTS_MAX, and the Agents Log
+// below the board lists the rest.
+function zenAgentsHtml(agents) {
+  const active = agents.filter((a) => a.status === 'active');
+  if (!active.length) return '';
   const now = Date.now();
+  const rows = active.slice(0, ZEN_AGENTS_MAX).map((a) => {
+    const task = truncateAtWord(agentTaskText(a), 200);
+    return `<button type="button" class="zen-agent" title="${escapeHtml(task)}" onclick="showAgentModal('${escAttrJs(a.agentId)}')">
+      <span class="agent-dot active"></span>
+      <span class="zen-agent-text"><span class="zen-agent-task">${escapeHtml(task)}</span><span class="agent-ident-row">${agentIdentHtml(a)}</span></span>
+      <span class="zen-agent-time">${formatDuration(agentElapsed(a, now))}</span>
+    </button>`;
+  });
+  return `<div class="panel-section-header"><span>Agents</span><span class="panel-section-count">${active.length}</span></div>${rows.join('')}`;
+}
 
-  const agents = currentAgents;
-  // Filter shutdown ghosts: for same-type agents, keep if they overlapped (parallel)
-  // or started >30s after previous stopped (legitimate re-spawn). Filter the rest.
+function renderZenAgents(agents) {
+  const el = zenMode && sessionsList.querySelector('.zen-agents');
+  if (el) el.innerHTML = zenAgentsHtml(agents);
+}
+
+// Filter shutdown ghosts: for same-type agents, keep if they overlapped (parallel)
+// or started >30s after previous stopped (legitimate re-spawn). Filter the rest.
+function visibleAgents() {
   const byType = {};
-  for (const a of agents) {
+  for (const a of currentAgents) {
     const groupKey = a.agentName || a.type;
     if (!byType[groupKey]) byType[groupKey] = [];
     byType[groupKey].push(a);
@@ -3431,13 +3481,21 @@ function renderAgentFooter() {
   }
   // Sort: active/idle first, then by updatedAt desc
   const statusOrder = { active: 0, idle: 1, stopped: 2 };
-  const visible = filtered
-    .sort(
-      (a, b) =>
-        (statusOrder[a.status] ?? 2) - (statusOrder[b.status] ?? 2) ||
-        new Date(b.updatedAt || 0) - new Date(a.updatedAt || 0),
-    )
-    .slice(0, AGENT_LOG_MAX);
+  return filtered.sort(
+    (a, b) =>
+      (statusOrder[a.status] ?? 2) - (statusOrder[b.status] ?? 2) ||
+      new Date(b.updatedAt || 0) - new Date(a.updatedAt || 0),
+  );
+}
+
+function renderAgentFooter() {
+  const footer = document.getElementById('agent-footer');
+  const content = document.getElementById('agent-footer-content');
+  const label = document.getElementById('agent-footer-label');
+  const now = Date.now();
+  const agents = visibleAgents();
+  renderZenAgents(agents);
+  const visible = agents.slice(0, AGENT_LOG_MAX);
 
   const permFresh = isWaitingFresh();
 
@@ -3461,23 +3519,14 @@ function renderAgentFooter() {
     permHtml +
     visible
       .map((a) => {
-        const elapsed =
-          a.status === 'stopped' && a.stoppedAt
-            ? new Date(a.stoppedAt).getTime() - new Date(a.startedAt || a.stoppedAt).getTime()
-            : now - new Date(a.startedAt || a.updatedAt).getTime();
+        const elapsed = agentElapsed(a, now);
         const statusText =
           a.status === 'stopped'
             ? `stopped · ${formatDuration(elapsed)}`
             : a.status === 'idle'
               ? `idle · ${formatDuration(elapsed)}`
               : `active · ${formatDuration(elapsed)}`;
-        const descText = a.description || '';
-        const promptTrimmed = stripAnsi(stripTeammateWrapper((a.prompt || '').trim())).replace(/[\r\n]+/g, ' ');
-        const rawType = a.type || 'unknown';
-        const colonIdx = rawType.indexOf(':');
-        const typeNs = colonIdx > 0 ? rawType.substring(0, colonIdx + 1) : '';
-        const typeName = colonIdx > 0 ? rawType.substring(colonIdx + 1) : rawType;
-        const displayText = descText || promptTrimmed || typeName;
+        const displayText = agentTaskText(a);
         const taskHtml = `<div class="agent-task" title="${escapeHtml(displayText)}">${escapeHtml(displayText)}</div>`;
         const agentNameVal = a.agentName || null;
         const nameColor = agentNameVal ? getOwnerColor(agentNameVal) : null;
@@ -3487,15 +3536,10 @@ function renderAgentFooter() {
         const agentColor = resolveNamedColor(a.color);
         const colorStyle = agentColor ? ` style="border-left:3px solid ${agentColor.color}"` : '';
         const selectedClass = a.agentId === currentAgentModalId ? ' selected' : '';
-        const fullModel = agentModel(a);
-        const cardModel = shortModelName(fullModel);
-        const modelHtml = cardModel
-          ? `<span class="agent-card-model" title="${escapeHtml(fullModel)}">${escapeHtml(cardModel)}</span><span class="agent-ident-sep">·</span>`
-          : '';
         return `<div class="agent-card${selectedClass}" data-agent-id="${escapeHtml(a.agentId)}"${colorStyle} onclick="showAgentModal('${escAttrJs(a.agentId)}')">
           ${agentLogButton(a.agentId, 'agent-card-log-btn')}
           ${taskHtml}
-          <div class="agent-ident-row">${modelHtml}<span class="agent-type-name" title="${escapeHtml(rawType)}">${typeNs ? `<span class="agent-type-ns">${escapeHtml(typeNs)}</span>` : ''}${escapeHtml(typeName)}</span>${nameBadgeHtml}</div>
+          <div class="agent-ident-row">${agentIdentHtml(a)}${nameBadgeHtml}</div>
           <div class="agent-status-row"><span class="agent-dot ${a.status}"></span><span class="agent-status">${statusText}</span></div>
         </div>`;
       })
@@ -3889,6 +3933,8 @@ function renderSessions() {
   // and still offers everything, or there would be no way to switch sessions without leaving zen.
   // Group zen renders only its subtree's buckets, so it takes every session unfiltered.
   const zenSession = zenMode && currentSessionId ? sessions.find((s) => s.id === currentSessionId) : null;
+  sessionsList.classList.toggle('zen', !!zenSession);
+  sessionsList.dataset.zenState = zenSession ? sessionState(zenSession) : '';
   let filteredSessions;
   if (zenGroup) filteredSessions = applyStableSessionOrder(sessions);
   else if (zenMode) filteredSessions = zenSession ? [zenSession] : [];
@@ -4064,7 +4110,8 @@ function renderSessions() {
         ${renderArtifactsHtml(zenSession.id)}
         ${renderZenBookmarksHtml(zenSession.id)}
       </div>
-      ${zenSession.hasWorkflow ? renderWorkflowLiveHtml(zenSession.id) : ''}`;
+      ${zenSession.hasWorkflow ? renderWorkflowLiveHtml(zenSession.id) : ''}
+      <div class="zen-agents">${zenAgentsHtml(visibleAgents())}</div>`;
     bindLinkedDocsHandlers(sessionsList.querySelector('.linked-docs-section'), zenSession.id);
     artifactsSection.load(zenSession.id);
     scratchFilesSection.load(zenSession.id);
@@ -11569,6 +11616,12 @@ function toggleZenMode() {
   if (!leavingSessionZen) fetchSessions(false);
 }
 
+function applyHubSettings(s) {
+  sessionsList.classList.toggle('zen-centered', s.zenCentered === true);
+  if (s.zenPattern) sessionsList.dataset.zenPattern = s.zenPattern;
+  else delete sessionsList.dataset.zenPattern;
+}
+
 function renderZenState() {
   const btn = document.getElementById('zen-mode-btn');
   if (!btn) return;
@@ -16067,17 +16120,18 @@ async function terminalFetch(url, method, body) {
   return res.status === 401 && (await refreshTerminalToken()) ? send() : res;
 }
 
-const TERMINAL_STATE_LABEL = { busy: 'working', wait: 'waiting', idle: 'idle' };
+const TERMINAL_DOT_STATE = { working: 'busy', waiting: 'wait', idle: 'idle' };
 
 // biome-ignore lint/correctness/noUnusedVariables: used in HTML
 async function endAllTerminals() {
   const items = [...document.querySelectorAll('#terminal-manager-body [data-end]')].map((b) => {
     const id = b.dataset.end;
     const session = sessions.find((s) => s.id === id);
-    const state = !session ? 'idle' : isWaitingSession(session) ? 'wait' : isActiveSession(session) ? 'busy' : 'idle';
+    const label = session ? sessionState(session) : 'idle';
+    const state = TERMINAL_DOT_STATE[label];
     const started = Number(b.dataset.started);
     const meta = [
-      TERMINAL_STATE_LABEL[state],
+      label,
       started && `up ${formatDuration(Date.now() - started)}`,
       formatTerminalProc(terminalProcStats[id]),
     ]
@@ -16775,9 +16829,13 @@ function withHeadFirst(content, head) {
   return content.slice(0, cut) + inject + content.slice(cut);
 }
 
+// The board's scrollbar rules do not reach into a frame, which would show the OS default.
+// Grey, not a board token, because the page paints its own background.
+const FRAME_SCROLLBAR_CSS = ':where(html){scrollbar-width:thin;scrollbar-color:rgba(128,128,128,.45) transparent}';
+
 // A whole document gets the tokens and base styles first in its head, so its own styles win.
 function showSrcdoc(content, restoreY) {
-  const head = `<meta http-equiv="Content-Security-Policy" content="${SHOW_CSP}"><style>:root{${showTokenCss()}}${SHOW_FRAME_BASE}</style>`;
+  const head = `<meta http-equiv="Content-Security-Policy" content="${SHOW_CSP}"><style>:root{${showTokenCss()}}${SHOW_FRAME_BASE}${FRAME_SCROLLBAR_CSS}</style>`;
   const bridge = `<script>(${showBridge})(${Math.max(0, Math.round(restoreY) || 0)}, ${modalZoom});</script>${REVIEW_BRIDGE_TAG}`;
   if (!/^\s*(<!doctype|<html)/i.test(content)) {
     return `<!doctype html><html><head><meta charset="utf-8">${head}</head><body>${content}${bridge}</body></html>`;
@@ -16788,7 +16846,7 @@ function showSrcdoc(content, restoreY) {
 // An HTML file preview gets only the tokens, first in its head: its own :root rules win, and
 // a page that declares its defaults in :where(:root) follows the board theme.
 function themedSrcdoc(content) {
-  const head = `<style id="cck-tokens">:root{${showTokenCss()}}</style>`;
+  const head = `<style id="cck-tokens">:root{${showTokenCss()}}${FRAME_SCROLLBAR_CSS}</style>`;
   return withHeadFirst(content, head) + THEME_BRIDGE_TAG + REVIEW_BRIDGE_TAG;
 }
 
@@ -18105,6 +18163,7 @@ hub.onActive((active) => {
   pushTerminalClaims();
 });
 hub.onStatus(pushTerminalClaims);
+hub.onSettings(applyHubSettings);
 
 // session.changed goes out once the switch settles, so arrowing through the list sends one event.
 let publishTimer = 0;

package/public/style.css

@@ -834,6 +834,111 @@ body::before {
   padding: 0 14px 12px;
 }
 
+.sessions-list.zen {
+  --zen-dot: var(--border);
+  display: flex;
+  flex-direction: column;
+}
+
+.sessions-list.zen[data-zen-state='working'] {
+  --zen-dot: color-mix(in srgb, var(--success) 45%, var(--border));
+}
+
+.sessions-list.zen[data-zen-state='waiting'] {
+  --zen-dot: color-mix(in srgb, var(--warning) 55%, var(--border));
+}
+
+/* The spacers fill the free space. Centered, they split it 1:2, so a growing panel moves the card up by a third of the growth, not a half. With no free space they are 0 and the list scrolls from the top. */
+.sessions-list.zen::after,
+.sessions-list.zen.zen-centered::before {
+  content: '';
+  flex: 1 0 0;
+}
+
+/* Dots unless the hub's zenPattern setting names another pattern. Line patterns use a lighter color, because a line has more ink than a dot. */
+.sessions-list.zen {
+  --zen-line: color-mix(in srgb, var(--zen-dot) 50%, transparent);
+  --zen-fill: radial-gradient(circle, var(--zen-dot) 1px, transparent 1.5px) 0 0 / 20px 20px;
+  --zen-glow-y: 0;
+}
+
+.sessions-list.zen[data-zen-pattern='diagonal'] {
+  --zen-fill: repeating-linear-gradient(-45deg, var(--zen-line) 0 1px, transparent 1px 14px);
+}
+
+.sessions-list.zen[data-zen-pattern='rings'] {
+  --zen-fill: radial-gradient(circle, transparent 2.5px, var(--zen-line) 3px 3.5px, transparent 4px) 0 0 / 28px 28px;
+}
+
+.sessions-list.zen[data-zen-pattern='grid'] {
+  --zen-fill:
+    linear-gradient(var(--zen-line) 1px, transparent 1px) 0 0 / 24px 24px,
+    linear-gradient(90deg, var(--zen-line) 1px, transparent 1px) 0 0 / 24px 24px;
+}
+
+/* The pattern glows out from the card. The glow has a fixed height, so it looks the same in a short space and a tall one. */
+.sessions-list.zen:not([data-zen-pattern='none'])::after,
+.sessions-list.zen.zen-centered:not([data-zen-pattern='none'])::before {
+  background: var(--zen-fill);
+  mask-image: radial-gradient(110% 260px at 50% var(--zen-glow-y), rgb(0 0 0 / 0.9), transparent);
+}
+
+.sessions-list.zen.zen-centered::before {
+  --zen-glow-y: 100%;
+}
+
+.sessions-list.zen.zen-centered::after {
+  flex-grow: 2;
+}
+
+.sessions-list.zen > * {
+  flex-shrink: 0;
+}
+
+/* After the ::after spacer, so the agents sit at the bottom of the free space. */
+.zen-agents {
+  order: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-top: 6px;
+}
+.zen-agents:empty {
+  display: none;
+}
+.zen-agent {
+  display: grid;
+  grid-template-columns: 5px 1fr auto;
+  align-items: center;
+  gap: 8px;
+  padding: 5px 8px;
+  background: none;
+  border: none;
+  border-radius: 6px;
+  font: inherit;
+  font-size: 12px;
+  text-align: left;
+  cursor: pointer;
+}
+.zen-agent:hover {
+  background: var(--bg-hover);
+}
+.zen-agent-text {
+  min-width: 0;
+}
+.zen-agent-task {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--text-primary);
+}
+.zen-agent-time {
+  font-size: 10.5px;
+  font-variant-numeric: tabular-nums;
+  color: var(--text-tertiary);
+}
+
 .session-item {
   position: relative;
   display: block;

package/public/vendor/claude-hub-sdk.js

@@ -1,4 +1,4 @@
-// claude-hub-sdk 1.6.0 (sha256 71a58022516d). Copied by npm run sdk:sync in claude-code-hub. Do not edit.
+// claude-hub-sdk 1.7.0 (sha256 904e53d87ec4). Copied by npm run sdk:sync in claude-code-hub. Do not edit.
 // Claude Code Hub SDK: the one rule that names a key press, shared by the hub page, client.js and
 // stub.js. The hub serves it to its page as /sdk/keys.js; mount() and sdk:sync put it in front of
 // client.js and stub.js, so an app still loads one file.
@@ -60,6 +60,8 @@ if (typeof module === 'object' && module.exports) module.exports = ClaudeHubKeys
         status: 'standalone',
         themes: [],
         inHub: false,
+        settings: null,
+        onSettings: () => off,
         onStatus: () => off,
         onActive: () => off,
         onThemes: () => off,