claude-code-kanban 6.0.0 → 6.1.1

package/lib/terminal.js

@@ -7,6 +7,10 @@
 // (net-guard upgradeVerdict), refusal when the server is exposed, and a per-launch
 // token sent in the first message. The token is the only one that stops a
 // non-browser local process.
+//
+// The service runs in its own process (lib/terminal-host.js): cck checks the first two
+// gates and hands the upgraded socket over, so no keystroke or output byte waits on
+// cck's main thread.
 
 const crypto = require('node:crypto');
 const fs = require('node:fs');
@@ -249,15 +253,43 @@ function refuse(socket, status, reason) {
   socket.end(`HTTP/1.1 ${status}\r\nConnection: close\r\nContent-Type: text/plain\r\n\r\n${reason}\n`);
 }
 
+function localUnavailableReason(config, net) {
+  if (!config.enabled) return 'disabled';
+  if (net.EXPOSED) return 'refused while listening on a non-loopback address';
+  return null;
+}
+
+function refuseUpgrade(req, socket, reasonFor) {
+  let pathname;
+  try { pathname = new URL(req.url, 'http://x').pathname; } catch { pathname = ''; }
+  if (pathname !== WS_PATH) {
+    refuse(socket, '404 Not Found', 'no such endpoint');
+    return true;
+  }
+  const reason = reasonFor();
+  if (reason) refuse(socket, '403 Forbidden', reason);
+  return !!reason;
+}
+
+function clientConfigFor(config, available) {
+  return {
+    available,
+    fontFamily: config.fontFamily,
+    fontSize: config.fontSize,
+    scrollback: config.scrollback,
+    maxSessions: config.maxSessions,
+  };
+}
+
 /**
  * @param {object} o
  * @param {ReturnType<typeof readTerminalConfig>} o.config
  * @param {{EXPOSED: boolean, upgradeVerdict: (req: any) => string|null}} o.net
  * @param {string} o.claudeDir
  * @param {boolean} o.isDefaultDir
- * @param {(id: string) => string|null} o.resolveCwd  null = unknown session
+ * @param {(id: string) => string|null|Promise<string|null>} o.resolveCwd  null = unknown session
  * @param {(id: string, exceptPid?: number) => boolean} o.isLiveElsewhere
- * @param {(dir: string) => boolean} o.isAllowedFolder  where a new session may start
+ * @param {(dir: string) => boolean|Promise<boolean>} o.isAllowedFolder  where a new session may start
  * @param {() => {pid: number|null, sessionId: string, cwd: string|null, startedAt: number}[]} o.liveSessions
  *   claude's live-session registry, read fresh
  * @param {(cmd: string) => string|null} o.which
@@ -310,10 +342,7 @@ function createTerminalService(o) {
   }
 
   function unavailableReason() {
-    if (!config.enabled) return 'disabled';
-    if (net.EXPOSED) return 'refused while listening on a non-loopback address';
-    if (!load()) return loadError;
-    return null;
+    return localUnavailableReason(config, net) || (load() ? null : loadError);
   }
 
   function changed() {
@@ -343,11 +372,11 @@ function createTerminalService(o) {
   function restore() {
     if (!restoreQueue.length || unavailableReason()) return;
     console.log(`Restoring ${restoreQueue.length} terminal(s)`);
-    const next = () => {
+    const next = async () => {
       while (restoreQueue.length && !shuttingDown) {
         const id = restoreQueue.shift();
         if (sessions.has(id) || o.isLiveElsewhere(id)) continue;
-        const r = start(id, 'resume', {}, HEADLESS_COLS, HEADLESS_ROWS);
+        const r = await start(id, 'resume', {}, HEADLESS_COLS, HEADLESS_ROWS);
         if (!r.error) break;
         console.log(`Could not restore terminal ${id}: ${r.error}`);
       }
@@ -498,7 +527,8 @@ function createTerminalService(o) {
   // Claude's registry entry keeps its pid and swaps its sessionId to the picked one; the entry
   // is found by folder and start time, and the pick shows as an id with a transcript behind it.
   function watchPick(s) {
-    s.pickTimer = setInterval(() => {
+    s.pickTimer = setInterval(async () => {
+      if (s.pickChecking) return;
       const live = o.liveSessions();
       const entry = s.claudePid && live.find((l) => l.pid === s.claudePid);
       if (!entry) {
@@ -509,7 +539,11 @@ function createTerminalService(o) {
         return;
       }
       const picked = entry.sessionId;
-      if (picked === s.id || o.resolveCwd(picked) === null) return;
+      if (picked === s.id) return;
+      s.pickChecking = true;
+      const known = await o.resolveCwd(picked);
+      s.pickChecking = false;
+      if (known === null || s.exited || s.mode !== 'pick') return;
       clearInterval(s.pickTimer);
       // Two claude processes on one session write the same transcript. When cck already runs it,
       // the pick is ended and its viewers move to that terminal; the sockets leave first so no
@@ -562,7 +596,7 @@ function createTerminalService(o) {
     });
   }
 
-  function onHello(ws, msg) {
+  async function onHello(ws, msg) {
     if (!msg || msg.t !== 'hello' || !tokenMatches(token, msg.token)) {
       send(ws, { t: 'error', msg: 'The terminal token is out of date. Reload the hub window.' });
       return ws.close(4001);
@@ -584,36 +618,43 @@ function createTerminalService(o) {
       send(ws, { t: 'live' });
       return ws.close(1000);
     }
-    const r = start(id, mode, msg, cols, rows);
+    const r = await start(id, mode, msg, cols, rows);
+    if (r.running) return attach(ws, r.running, true);
     if (r.error) {
       send(ws, { t: 'error', msg: r.error });
       return ws.close(r.code);
     }
+    // The viewer left while the PTY started; it runs headless until the next attach.
+    if (ws.readyState !== 1) return;
     attach(ws, r.session, false);
   }
 
   // The admission rules shared by the socket hello and startNew. A refusal carries both a
   // WebSocket close code and an HTTP status, so each caller maps it its own way.
-  function start(id, mode, msg, cols, rows, extraEnv) {
-    if (sessions.size >= config.maxSessions) {
-      return { code: 4003, status: 429, error: `${config.maxSessions} terminals are open; end one first` };
+  // resolveCwd and isAllowedFolder may answer later, so the limits are checked again after them.
+  async function start(id, mode, msg, cols, rows, extraEnv) {
+    const full = { code: 4003, status: 429, error: `${config.maxSessions} terminals are open; end one first` };
+    if (sessions.size >= config.maxSessions) return full;
+    let spec = null;
+    if (mode === 'new') {
+      spec = parseNewSpec(msg);
+      if (typeof spec === 'string') return { code: 4002, status: 400, error: `invalid ${spec}` };
     }
-    const known = o.resolveCwd(id);
+    const known = await o.resolveCwd(id);
     let cwd = known;
-    let spec = null;
     if (mode === 'new' || mode === 'pick') {
-      if (mode === 'new') {
-        spec = parseNewSpec(msg);
-        if (typeof spec === 'string') return { code: 4002, status: 400, error: `invalid ${spec}` };
-      }
       if (known !== null) return { code: 4006, status: 409, error: 'session id already in use' };
-      if (typeof msg.cwd !== 'string' || !o.isAllowedFolder(msg.cwd)) {
+      if (typeof msg.cwd !== 'string' || !(await o.isAllowedFolder(msg.cwd))) {
         return { code: 4004, status: 403, error: 'folder is not a known project or a folder picked in this run' };
       }
       cwd = msg.cwd;
     } else if (mode !== 'shell' && known === null) {
       return { code: 4004, status: 404, error: 'unknown session' };
     }
+    if (shuttingDown) return { code: 1001, status: 503, error: 'the terminal is shutting down' };
+    const running = sessions.get(id);
+    if (running && !running.ended) return { running, code: 4006, status: 409, error: 'session id already in use' };
+    if (sessions.size >= config.maxSessions) return full;
     try {
       return { session: spawnSession(id, mode === 'auto' ? 'resume' : mode, cwd, cols, rows, spec, extraEnv) };
     } catch (e) {
@@ -622,31 +663,24 @@ function createTerminalService(o) {
   }
 
   function handleUpgrade(req, socket, head) {
-    let pathname;
-    try { pathname = new URL(req.url, 'http://x').pathname; } catch { pathname = ''; }
-    if (pathname !== WS_PATH) return refuse(socket, '404 Not Found', 'no such endpoint');
-    const reason = unavailableReason() || net.upgradeVerdict(req);
-    if (reason) return refuse(socket, '403 Forbidden', reason);
+    if (refuseUpgrade(req, socket, () => unavailableReason() || net.upgradeVerdict(req))) return;
     wss.handleUpgrade(req, socket, head, (ws) => {
       const timer = setTimeout(() => ws.close(4001), HELLO_TIMEOUT_MS);
       ws.once('message', (raw, isBinary) => {
         clearTimeout(timer);
         let msg = null;
         if (!isBinary) { try { msg = JSON.parse(raw.toString()); } catch { /* treated as bad hello */ } }
-        onHello(ws, msg);
+        onHello(ws, msg).catch((e) => {
+          send(ws, { t: 'error', msg: `failed to start the terminal: ${e.message}` });
+          ws.close(1011);
+        });
       });
       ws.on('error', () => {});
     });
   }
 
   function clientConfig() {
-    return {
-      available: !unavailableReason(),
-      fontFamily: config.fontFamily,
-      fontSize: config.fontSize,
-      scrollback: config.scrollback,
-      maxSessions: config.maxSessions,
-    };
+    return clientConfigFor(config, !unavailableReason());
   }
 
   // kill() returns before the process is gone, so an ended session leaves list() at once.
@@ -693,10 +727,11 @@ function createTerminalService(o) {
 
   // A 'new' session for a caller with no socket. The PTY runs headless until a browser
   // attaches, and a later attach resizes it.
-  function startNew(msg, extraEnv) {
+  async function startNew(msg, extraEnv) {
     const reason = unavailableReason();
     if (reason) return { status: 403, error: reason };
-    const r = start(crypto.randomUUID(), 'new', msg, HEADLESS_COLS, HEADLESS_ROWS, extraEnv);
+    if (msg.id != null && !(typeof msg.id === 'string' && UUID_RE.test(msg.id))) return { status: 400, error: 'invalid session id' };
+    const r = await start(msg.id || crypto.randomUUID(), 'new', msg, HEADLESS_COLS, HEADLESS_ROWS, extraEnv);
     return r.error ? r : { id: r.session.id, cwd: r.session.cwd };
   }
 
@@ -724,4 +759,4 @@ function createTerminalService(o) {
   return { token, handleUpgrade, clientConfig, list, claudePids, isRunning, end, authorized, startNew, paste, restore, shutdown, unavailableReason };
 }
 
-module.exports = { createTerminalService, readTerminalConfig, ptyEnv, shellArgs, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };
+module.exports = { createTerminalService, readTerminalConfig, localUnavailableReason, refuseUpgrade, clientConfigFor, ptyEnv, shellArgs, resolveShell, claudeArgsFor, parseNewSpec, findPickProcess, tokenMatches };

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.22.0",
+  "version": "2.23.0",
   "description": "claude-code-kanban dashboard integration: agent activity tracking, context and cost tracking, skills to drive the board from a session and to follow it",
   "experimental": {
     "monitors": "./monitors.json"

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

@@ -12,9 +12,10 @@ export function displayName(model: string) {
 const toEpochSeconds = (iso?: string) => (iso ? Math.floor(Date.parse(iso) / 1000) : undefined)
 
 // The board reads the statusLine's JSON shape, so the file keeps its field names.
-export function toStatus(model: string, m: Measure, usage: ModelUsage | undefined) {
+export function toStatus(model: string, m: Measure, usage: ModelUsage | undefined, requestAt?: number) {
   const { context } = m
   return {
+    ...(requestAt && { cache: { last_request_at: requestAt } }),
     model: { id: model, display_name: displayName(model) },
     cost: { total_cost_usd: m.cost?.usd ?? 0 },
     context_window: {
@@ -43,6 +44,7 @@ function cckDir($: EngineInterface) {
 
 let lastUsage: ModelUsage | undefined
 let lastModel: string | undefined
+let lastRequestAt: number | undefined
 const lastWritten = new Map<string, string>()
 
 async function write($: EngineInterface, m: Measure) {
@@ -51,7 +53,7 @@ async function write($: EngineInterface, m: Measure) {
     lastModel ?? $.session.model(),
     cckDir($),
   ])
-  const text = JSON.stringify(toStatus(model, m, lastUsage))
+  const text = JSON.stringify(toStatus(model, m, lastUsage, lastRequestAt))
   const file = `${dir}/context-status/${sessionId}.json`
   if (lastWritten.get(file) === text) return
   await $.fs.write(file, text)
@@ -65,6 +67,7 @@ export const register: Register = on => {
       const { model, ...usage } = result.usage
       lastUsage = usage
       lastModel = model
+      lastRequestAt = Date.now()
       await write($, await $.session.usage())
     }
     return result

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

@@ -1,6 +1,6 @@
 import type { On, SessionMeasureInput } from 'claude-code'
 import { expect, test } from 'claude-code/testing'
-import { displayName } from '../hooks/context'
+import { displayName, toStatus } from '../hooks/context'
 
 const MEASURE: SessionMeasureInput = {
   context: { tokens: 129_174, window: 1_000_000, percent: 13 },
@@ -45,6 +45,19 @@ test('session.measure writes the statusLine shape the board reads', async ($, on
   expect(status.rate_limits.seven_day.used_percentage).toBe(7.5)
 })
 
+test('session.measure writes no cache entry before the first request', async ($, on) => {
+  const writes = engine(on, { CLAUDE_CONFIG_DIR: 'C:/cfg' }, 'sid-4')
+
+  await $.session.measure(MEASURE)
+
+  expect(JSON.parse(writes[0]?.text ?? '{}').cache).toBeUndefined()
+})
+
+test('toStatus adds the last request time', async () => {
+  const status = toStatus('claude-opus-5-5', MEASURE, undefined, 1_790_000_000_000)
+  expect(status.cache).toEqual({ last_request_at: 1_790_000_000_000 })
+})
+
 test('skips a write when the status has not changed', async ($, on) => {
   const writes = engine(on, { CLAUDE_CONFIG_DIR: 'C:/cfg' }, 'sid-3')
 

package/public/app.js

@@ -8931,6 +8931,73 @@ function formatCost(usd) {
   return `$${usd.toFixed(2)}`;
 }
 
+const CACHE_TTL = { '5m': { ms: 5 * 60000, write: 1.25 }, '1h': { ms: 60 * 60000, write: 2 } };
+// List input price, $ per million tokens. Most specific prefix first.
+const INPUT_PRICE_PER_MTOK = [
+  ['claude-fable-5', 10],
+  ['claude-mythos-5', 10],
+  ['claude-opus-5-5', 4],
+  ['claude-opus-5', 5],
+  ['claude-opus-4', 5],
+  ['claude-sonnet-5', 2],
+  ['claude-sonnet-4', 3],
+  ['claude-haiku-4', 1],
+];
+
+// Same token count Claude Code prices in its own estimated_cache_write_usd.
+function cacheRewrite(usage, modelId, writeRate) {
+  const price = INPUT_PRICE_PER_MTOK.find(([prefix]) => modelId?.startsWith(prefix))?.[1];
+  const tokens =
+    (usage.input_tokens || 0) +
+    (usage.cache_read_input_tokens || 0) +
+    (usage.cache_creation_input_tokens || 0) +
+    (usage.output_tokens || 0);
+  if (!price || !tokens) return null;
+  return { tokens, usd: (tokens / 1e6) * price * writeRate };
+}
+
+function formatCacheLeft(expiresAt, expiredText) {
+  const left = Math.max(0, Math.floor((expiresAt - Date.now()) / 1000));
+  if (left === 0) return { text: expiredText, color: 'var(--text-muted)' };
+  const text = `${Math.floor(left / 60)}:${String(left % 60).padStart(2, '0')}`;
+  const color = left < 120 ? CONTEXT_COLORS.red : left < 300 ? CONTEXT_COLORS.orange : CONTEXT_COLORS.green;
+  return { text, color };
+}
+
+let cacheTimerInterval = null;
+
+function tickCacheTimers() {
+  const els = document.querySelectorAll('.cache-timer');
+  if (!els.length) {
+    clearInterval(cacheTimerInterval);
+    cacheTimerInterval = null;
+    return;
+  }
+  if (!isOnScreen()) return;
+  for (const el of els) {
+    const { text, color } = formatCacheLeft(Number(el.dataset.expires), el.dataset.expiredText);
+    if (el.textContent === text) continue;
+    el.textContent = text;
+    el.style.color = color;
+  }
+}
+
+function renderCacheTimer(lastRequestAt, ttl, usage, modelId) {
+  const cache = CACHE_TTL[ttl];
+  if (!lastRequestAt || !cache) return '';
+  const expiresAt = lastRequestAt + cache.ms;
+  const rewrite = cacheRewrite(usage, modelId, cache.write);
+  const expiredText = rewrite ? `expired · ~${formatCost(rewrite.usd)}` : 'expired';
+  const { text, color } = formatCacheLeft(expiresAt, expiredText);
+  cacheTimerInterval ??= setInterval(tickCacheTimers, 1000);
+  const at = new Date(expiresAt).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+  const cost = rewrite
+    ? ` It writes ${formatTokens(rewrite.tokens / 1000)} tokens again, about ${formatCost(rewrite.usd)} at list price.`
+    : '';
+  const title = `Prompt cache, ${ttl} TTL. Expires at ${at}; the next request after that writes it again.${cost}`;
+  return `<div class="stat-item" title="${escapeHtml(title)}"><span class="stat-label">Cache</span><span class="stat-value cache-timer" data-expires="${escapeHtml(expiresAt)}" data-expired-text="${escapeHtml(expiredText)}" style="color:${color}">${text}</span></div>`;
+}
+
 function renderContextDetail(session, { tokens = true } = {}) {
   const ctx = getCtx(session);
   if (!ctx) return '';
@@ -8968,6 +9035,7 @@ function renderContextDetail(session, { tokens = true } = {}) {
           <div class="detail-context-stats">
             ${tokenRows}
             <div class="stat-item"><span class="stat-label">Cost</span><span class="stat-value" style="color:${getCostColor(cost.total_cost_usd)}">${formatCost(cost.total_cost_usd)}</span></div>
+            ${renderCacheTimer(raw.cache?.last_request_at, session.cacheTtl, usage, raw.model?.id)}
             ${cost.total_duration_ms != null ? `<div class="stat-item"><span class="stat-label">Duration</span><span class="stat-value">${formatDuration(cost.total_duration_ms)}</span></div>` : ''}
             ${cost.total_api_duration_ms != null ? `<div class="stat-item"><span class="stat-label">API time</span><span class="stat-value">${formatDuration(cost.total_api_duration_ms)}</span></div>` : ''}
             ${cost.total_lines_added != null ? `<div class="stat-item"><span class="stat-label">Lines</span><span class="stat-value"><span style="color:${CONTEXT_COLORS.green}">+${(cost.total_lines_added || 0).toLocaleString()}</span> / <span style="color:${CONTEXT_COLORS.red}">-${(cost.total_lines_removed || 0).toLocaleString()}</span></span></div>` : ''}
@@ -12455,14 +12523,16 @@ function formatTerminalProc(s) {
 async function pollTerminalProcStats() {
   if (!isOnScreen()) return;
   let cck;
+  let host;
   try {
     const res = await fetch('/api/terminals/stats', { cache: 'no-store' });
     if (!res.ok) return;
-    ({ cck, terminals: terminalProcStats } = await res.json());
+    ({ cck, host, terminals: terminalProcStats } = await res.json());
   } catch (_) {
     return;
   }
-  document.getElementById('terminal-manager-stats').textContent = cck ? `cck ${formatTerminalProc(cck)}` : '';
+  const parts = [cck && `cck ${formatTerminalProc(cck)}`, host && `terminal host ${formatTerminalProc(host)}`];
+  document.getElementById('terminal-manager-stats').textContent = parts.filter(Boolean).join(' · ');
   for (const el of document.querySelectorAll('#terminal-manager-body [data-proc]')) {
     el.textContent = formatTerminalProc(terminalProcStats[el.dataset.proc]);
   }
@@ -12568,7 +12638,8 @@ const newSpecs = new Map();
 // Sessions another session started (`dispatch start`), shown where they will stay until
 // their transcript appears. Kept apart from newSpecs: their prompt is already sent.
 const dispatchSpecs = new Map();
-const ns = { projects: [], picked: [], matches: [], idx: -1, folder: '', browsing: false, resume: false };
+const ns = { projects: [], picked: [], matches: [], idx: -1, folder: '', busy: false, resume: false };
+const NEW_SESSION_STAY_KEY = 'new-session-stay';
 
 const PLACEHOLDER_NAMES = { pick: 'Resume session', dispatch: 'Started session', new: 'New session' };
 const PLACEHOLDER_HINTS = {
@@ -12627,9 +12698,13 @@ async function loadDispatches() {
 
 async function onDispatchUpdate() {
   await loadDispatches();
+  refreshPlaceholders();
+  fetchSessions(false).catch(() => {});
+}
+
+function refreshPlaceholders() {
   sessions = mergePlaceholders(sessions.filter((s) => !s.placeholder));
   renderSessions();
-  fetchSessions(false).catch(() => {});
 }
 
 // With no first message there is no transcript, so an ended placeholder leaves nothing to come back to.
@@ -12708,6 +12783,7 @@ function openNewSession(folder, resume = false) {
   for (const id of ['ns-name', 'ns-wt-name', 'ns-prompt']) document.getElementById(id).value = '';
   document.getElementById('ns-wt').checked = false;
   document.getElementById('ns-model').value = '';
+  document.getElementById('ns-stay').checked = store.getItem(NEW_SESSION_STAY_KEY) === 'true';
   setNewSessionError('');
   const current = viewMode === 'session' ? sessions.find((s) => s.id === currentSessionId)?.project : null;
   setNewSessionFolder(folder || current || '');
@@ -12841,36 +12917,44 @@ function renderNewSessionForm() {
   const problem = newSessionProblem(v);
   setNewSessionError(problem);
   const start = document.getElementById('ns-start');
-  start.disabled = !v.cwd || !!problem || ns.browsing;
+  start.disabled = !v.cwd || !!problem || ns.busy;
   const verb = ns.resume ? 'Resume' : 'Start';
   start.textContent = v.cwd ? `${verb} in ${pathBasename(v.cwd)}` : verb;
 }
 
+// Resolves to the response body, or to { error } with the message for the dialog.
+async function newSessionPost(url, body, failure) {
+  try {
+    const res = await terminalFetch(url, 'POST', body);
+    const out = await res.json().catch(() => ({}));
+    if (res.ok) return out;
+    return { error: res.status === 401 ? STALE_TOKEN_MSG : out.error || `${failure} (${res.status})` };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+function setNewSessionBusy(on) {
+  ns.busy = on;
+  renderNewSessionForm();
+}
+
 async function browseNewSessionFolder() {
-  if (ns.browsing) return;
-  ns.browsing = true;
+  if (ns.busy) return;
   closeFolderList();
   const btn = document.getElementById('ns-browse');
   btn.textContent = 'Opening…';
-  renderNewSessionForm();
-  try {
-    const start = ns.folder || ns.picked[0] || ns.projects[0];
-    const res = await terminalFetch('/api/terminal/pick-folder', 'POST', start ? { start } : null);
-    const body = await res.json().catch(() => ({}));
-    if (res.status === 401) setNewSessionError(STALE_TOKEN_MSG);
-    else if (!res.ok) setNewSessionError(body.error || `Folder dialog failed (${res.status})`);
-    else if (body.path) {
-      ns.picked = [body.path, ...ns.picked.filter((p) => p !== body.path)];
-      setNewSessionFolder(body.path);
-    }
-  } catch (e) {
-    setNewSessionError(e.message);
-  } finally {
-    ns.browsing = false;
-    btn.textContent = 'Browse…';
-    renderNewSessionForm();
-    document.getElementById(ns.folder ? fieldAfterFolder() : 'ns-folder').focus();
+  setNewSessionBusy(true);
+  const start = ns.folder || ns.picked[0] || ns.projects[0];
+  const r = await newSessionPost('/api/terminal/pick-folder', start ? { start } : null, 'Folder dialog failed');
+  if (r.path) {
+    ns.picked = [r.path, ...ns.picked.filter((p) => p !== r.path)];
+    setNewSessionFolder(r.path);
   }
+  btn.textContent = 'Browse…';
+  setNewSessionBusy(false);
+  if (r.error) setNewSessionError(r.error);
+  document.getElementById(ns.folder ? fieldAfterFolder() : 'ns-folder').focus();
 }
 
 function fieldAfterFolder() {
@@ -12879,15 +12963,36 @@ function fieldAfterFolder() {
 
 function startNewSession() {
   const v = newSessionValues();
-  if (!v.cwd || newSessionProblem(v) || ns.browsing) return;
+  if (!v.cwd || newSessionProblem(v) || ns.busy) return;
   const id = crypto.randomUUID();
   newSpecs.set(id, { ...(ns.resume ? { cwd: v.cwd } : v), mode: ns.resume ? 'pick' : 'new', startedAt: Date.now() });
-  sessions = mergePlaceholders(sessions.filter((s) => !s.placeholder));
   setTerminalMode(id, true);
+  if (!ns.resume && document.getElementById('ns-stay').checked) return startNewSessionInBackground(id, v);
+  sessions = mergePlaceholders(sessions.filter((s) => !s.placeholder));
   closeNewSession();
   fetchTasks(id).then(() => sessionsList.querySelector('.session-item.active')?.scrollIntoView({ block: 'nearest' }));
 }
 
+async function startNewSessionInBackground(id, v) {
+  refreshPlaceholders();
+  setNewSessionBusy(true);
+  const r = await newSessionPost('/api/terminal/start', { id, ...v }, 'Start failed');
+  setNewSessionBusy(false);
+  if (r.error) {
+    dropPlaceholder(id);
+    return setNewSessionError(r.error);
+  }
+  // A server started before the page's code changed ignores the id and picks its own.
+  if (r.session !== id) {
+    const spec = newSpecs.get(id);
+    forgetPlaceholder(id);
+    newSpecs.set(r.session, spec);
+    setTerminalMode(r.session, true);
+    refreshPlaceholders();
+  }
+  closeNewSession();
+}
+
 const SpeechRecognitionApi = window.SpeechRecognition || window.webkitSpeechRecognition;
 const promptVoice = { rec: null };
 
@@ -12963,6 +13068,9 @@ function initNewSession() {
     renderNewSessionForm();
     if (e.target.checked) document.getElementById('ns-wt-name').focus();
   });
+  document
+    .getElementById('ns-stay')
+    .addEventListener('change', (e) => store.setItem(NEW_SESSION_STAY_KEY, String(e.target.checked)));
   for (const id of ['ns-name', 'ns-wt-name', 'ns-prompt', 'ns-model']) {
     document.getElementById(id).addEventListener('input', renderNewSessionForm);
   }

package/public/index.html

@@ -52,7 +52,7 @@
       </div>
       <h2>Server Not Running</h2>
       <p>The dashboard needs the Claude Code Kanban server to stream live task data. Start it with:</p>
-      <code>npx claude-code-kanban</code>
+      <code>claude-code-kanban</code>
       <button class="btn btn-primary" onclick="location.reload()">Retry Connection</button>
       <div class="offline-status" id="offline-status" aria-live="polite"></div>
     </div>
@@ -818,6 +818,7 @@
         <div id="ns-error" class="ns-error" hidden></div>
       </div>
       <div class="modal-footer ns-footer">
+        <label class="ns-check ns-stay" title="Start in the background and keep the current view"><input type="checkbox" id="ns-stay"> Stay here</label>
         <button type="button" class="btn btn-secondary" onclick="closeNewSession()">Cancel</button>
         <button type="button" id="ns-start" class="btn btn-primary" onclick="startNewSession()" disabled>Start</button>
       </div>

package/public/style.css

@@ -6861,6 +6861,17 @@ select.form-input option:checked {
 
 .ns-footer {
   align-items: center;
+  margin-top: 16px;
+  border-top: 1px solid var(--border);
+}
+
+.ns-stay {
+  margin-right: auto;
+  color: var(--text-tertiary);
+}
+
+.new-session-modal.ns-resume .ns-stay {
+  visibility: hidden;
 }
 
 .ns-footer .btn-primary:disabled {