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

package/server.js

@@ -4,7 +4,7 @@
 const express = require('express');
 const path = require('node:path');
 const fs = require('node:fs').promises;
-const { existsSync, readdirSync, readFileSync, writeFileSync, statSync, unlinkSync, mkdirSync, renameSync, openSync, readSync, closeSync } = require('node:fs');
+const { existsSync, readdirSync, readFileSync, writeFileSync, statSync, unlinkSync, mkdirSync, renameSync, openSync, readSync, closeSync, realpathSync } = require('node:fs');
 const _readline = require('node:readline');
 const chokidar = require('chokidar');
 const os = require('node:os');
@@ -13,6 +13,7 @@ const { spawnSync, spawn } = require('node:child_process');
 const { assertOpenTarget, openInEditor, whichSync, exeBehindShim } = require('./lib/open-editor');
 const { createNetGuard } = require('./lib/net-guard');
 const { isContained } = require('./lib/contain');
+const { resolveScratchSubdir, listScratchDir } = require('./lib/scratch-files');
 const { fileUrlToPath } = require('./lib/file-url');
 
 const {
@@ -22,6 +23,7 @@ const {
   buildSessionDigest,
   readCompactSummaries,
   readArtifactLinks,
+  readScratchpadCreations,
   extractPromptFromTranscript,
   extractModelFromTranscript,
   extractStructuredResultFromTranscript,
@@ -33,9 +35,13 @@ const {
   updateLoopInfo,
   buildLoopInfoFromState
 } = require('./lib/parsers');
-const { inlineHtmlAssets } = require('./lib/inline-assets');
+const { inlineHtmlAssets, MIME_BY_EXT } = require('./lib/inline-assets');
 const { buildDecision, decisionFileName, isDecisionFile, approvalsFrom, boardRefusal } = require('./lib/approvals');
-const { getClaudeDir, getArgValue, storageNamespace } = require('./lib/claude-dir');
+const { getClaudeDir, getArgValue, storageNamespace, isDefaultClaudeDir } = require('./lib/claude-dir');
+const { createTerminalService, readTerminalConfig } = require('./lib/terminal');
+const { createDispatchRegistry, formatPreamble, formatDispatchLine, isPeerName } = require('./lib/dispatch');
+const { createGroupStore, isGroupName, suggestGroupName } = require('./lib/dispatch-groups');
+const { pickFolder } = require('./lib/folder-dialog');
 
 if (process.argv.includes("--install") || process.argv.includes("--uninstall")) {
   const { runInstall, runUninstall } = require("./install");
@@ -75,7 +81,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 DISPATCH_GROUPS_FILE = path.join(CCK_DIR, 'dispatch-groups.json');
 const SERVER_INFO_FILE = path.join(CCK_DIR, 'server.json');
+const TERMINAL_TOKEN_FILE = path.join(CCK_DIR, 'terminal-token.json');
 // Harness-owned scratchpad root; the per-session dir under it is created lazily.
 const SCRATCHPAD_ROOT = path.join(os.tmpdir(), 'claude');
 
@@ -91,11 +99,11 @@ function readPins() {
   return {};
 }
 
-function writeJsonAtomic(file, obj) {
+function writeJsonAtomic(file, obj, mode) {
   try {
     mkdirSync(CCK_DIR, { recursive: true });
     const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-    writeFileSync(tmp, JSON.stringify(obj, null, 2), 'utf8');
+    writeFileSync(tmp, JSON.stringify(obj, null, 2), { encoding: 'utf8', mode });
     renameSync(tmp, file);
   } catch (e) {
     console.error(`Failed to write ${path.basename(file)}:`, e.message);
@@ -111,6 +119,14 @@ function writePins(pins) {
 // a crashed one.
 function writeServerInfo(port) {
   writeJsonAtomic(SERVER_INFO_FILE, { port, pid: process.pid });
+  writeTerminalToken();
+}
+
+// For `dispatch start`: a local process as the same user can already run claude itself,
+// so handing it the token adds little. A browser still cannot read the file.
+function writeTerminalToken() {
+  if (terminal.unavailableReason()) return;
+  writeJsonAtomic(TERMINAL_TOKEN_FILE, { pid: process.pid, token: terminal.token }, 0o600);
 }
 
 // A beacon that outlives its server disarms UI approvals silently: approval-gate.sh
@@ -119,10 +135,22 @@ function writeServerInfo(port) {
 // the way out. Only when the file is still ours: a newer server on the same config
 // dir has already claimed it.
 function removeServerInfo() {
+  for (const file of [SERVER_INFO_FILE, TERMINAL_TOKEN_FILE]) {
+    try {
+      const info = JSON.parse(readFileSync(file, 'utf8'));
+      if (info.pid === process.pid) unlinkSync(file);
+    } catch (_) { /* gone, unreadable, or not ours */ }
+  }
+}
+
+// A second server on the same config dir (a test hub, say) takes the beacon and removes it on
+// exit, which leaves this live server undiscoverable. A newer live owner keeps it.
+function reclaimServerInfo(port) {
   try {
-    const info = JSON.parse(readFileSync(SERVER_INFO_FILE, 'utf8'));
-    if (info.pid === process.pid) unlinkSync(SERVER_INFO_FILE);
-  } catch (_) { /* gone, unreadable, or not ours */ }
+    const { pid } = JSON.parse(readFileSync(SERVER_INFO_FILE, 'utf8'));
+    if (pid === process.pid || isPidAlive(pid)) return;
+  } catch (_) { /* missing or unreadable beacon */ }
+  writeServerInfo(port);
 }
 
 process.on('exit', removeServerInfo);
@@ -420,9 +448,9 @@ let liveSessionsCache = null;
 let lastLiveSessionsScan = 0;
 const LIVE_SESSIONS_TTL = 5000;
 
-function loadLiveSessions() {
+function loadLiveSessions(fresh = false) {
   const now = Date.now();
-  if (liveSessionsCache && now - lastLiveSessionsScan < LIVE_SESSIONS_TTL) return liveSessionsCache;
+  if (!fresh && liveSessionsCache && now - lastLiveSessionsScan < LIVE_SESSIONS_TTL) return liveSessionsCache;
   const sessions = [];
   if (existsSync(SESSIONS_DIR)) {
     try {
@@ -430,7 +458,7 @@ function loadLiveSessions() {
         try {
           const s = JSON.parse(readFileSync(path.join(SESSIONS_DIR, file), 'utf8'));
           if (s?.sessionId && s.kind === 'interactive') {
-            sessions.push({ sessionId: s.sessionId, cwd: s.cwd || null, startedAt: s.startedAt || 0, status: s.status || null });
+            sessions.push({ sessionId: s.sessionId, pid: s.pid || null, cwd: s.cwd || null, startedAt: s.startedAt || 0, status: s.status || null });
           }
         } catch (_) { /* skip invalid */ }
       }
@@ -451,6 +479,19 @@ function isRegistryIdle(sessionId) {
   return live?.status === 'idle';
 }
 
+// A registry file outlives a crashed claude, so the pid is probed rather than trusted.
+function isSessionProcessAlive(sessionId, exceptPid = null) {
+  return loadLiveSessions().some((s) => {
+    if (s.sessionId !== sessionId || !s.pid || s.pid === exceptPid) return false;
+    return isPidAlive(s.pid);
+  });
+}
+
+// EPERM means the process exists but belongs to someone else.
+function isPidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
 function hasRecentLogActivity(sessionId, logAge) {
   return logAge <= SESSION_STALE_MS && !isRegistryIdle(sessionId);
 }
@@ -1159,8 +1200,11 @@ app.get('/api/sessions', async (req, res) => {
     const limit = limitParam === 'all' ? null : parseInt(limitParam, 10);
 
     const pinnedParam = req.query.pinned;
+    const includeIds = req.query.include ? new Set(req.query.include.split(',').filter(Boolean)) : new Set();
     const pinnedIds = pinnedParam ? new Set(pinnedParam.split(',').filter(Boolean)) : new Set();
+    for (const id of includeIds) pinnedIds.add(id);
     const activeFilter = req.query.filter === 'active';
+    const terminalIds = activeFilter ? new Set(terminal.list().map((t) => t.id)) : new Set();
 
     const metadata = loadSessionMetadata();
     const sessionsMap = new Map();
@@ -1190,7 +1234,7 @@ app.get('/api/sessions', async (req, res) => {
 
           // Cheap-probe: when filter=active, skip expensive enrichment for inactive non-pinned sessions.
           // Mirrors the post-filter predicate using only signals already computed above.
-          if (activeFilter && !pinnedIds.has(entry.name)) {
+          if (activeFilter && !pinnedIds.has(entry.name) && !terminalIds.has(entry.name)) {
             const cheaplyActive = logStat.hasMessages && (
               hasVisibleLogActivity(entry.name, logAge)
               || agentStatus.hasActive
@@ -1290,7 +1334,7 @@ app.get('/api/sessions', async (req, res) => {
         const metaAgentStatus = checkAgentStatus(metaAgentDir, stale, logMtime, metaIsTeam);
 
         // Cheap-probe: no tasks here (metadata-only), so active = recent log OR live agent.
-        if (activeFilter && !pinnedIds.has(sessionId)) {
+        if (activeFilter && !pinnedIds.has(sessionId) && !terminalIds.has(sessionId)) {
           const cheaplyActive = logStat.hasMessages && (
             hasVisibleLogActivity(sessionId, logAge) || metaAgentStatus.hasActive || !!metaAgentStatus.waitingForUser
           );
@@ -1491,7 +1535,7 @@ app.get('/api/sessions', async (req, res) => {
           || s.hasRecentActivity
         );
       for (const [id, s] of sessionsMap) {
-        if (pinnedIds.has(id)) continue;
+        if (pinnedIds.has(id) || terminalIds.has(id)) continue;
         if (!isActive(s)) sessionsMap.delete(id);
       }
     }
@@ -1502,8 +1546,12 @@ app.get('/api/sessions', async (req, res) => {
 
     // Apply project filter before limit so the limit is per-project
     const projectFilter = req.query.project;
+    // `include` is narrower than `pinned`: pinned rows survive the limit but still obey
+    // the project filter, because pinning is a preference and the filter is an intent.
+    // The client sends the session it currently has open, which it cannot render at all
+    // if the row is missing — that one is not a preference.
     if (projectFilter) {
-      sessions = sessions.filter(s => s.project === projectFilter);
+      sessions = sessions.filter(s => s.project === projectFilter || includeIds.has(s.id));
     }
 
     // Apply limit if specified, but always include pinned sessions
@@ -1514,13 +1562,22 @@ app.get('/api/sessions', async (req, res) => {
       sessions = [...top, ...missingPinned];
     }
 
-    res.json(sessions);
+    res.json(withDispatchPlacement(sessions));
   } catch (error) {
     console.error('Error listing sessions:', error);
     res.status(500).json({ error: 'Failed to list sessions' });
   }
 });
 
+// os.tmpdir() can be an 8.3 short path on Windows; transcripts record the long form.
+const TEMP_ROOT = (() => {
+  try { return realpathSync.native(os.tmpdir()); } catch { return os.tmpdir(); }
+})();
+function isTempPath(p) {
+  const rel = path.relative(TEMP_ROOT, p);
+  return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
 // API: Get distinct project paths with last-modified timestamps
 app.get('/api/projects', (_req, res) => {
   res.setHeader('Cache-Control', 'no-store');
@@ -1534,7 +1591,11 @@ app.get('/api/projects', (_req, res) => {
     }
   }
   const projects = Object.entries(projectMap)
-    .map(([path, mtime]) => ({ path, modifiedAt: mtime ? new Date(mtime).toISOString() : null }))
+    .map(([path, mtime]) => ({
+      path,
+      modifiedAt: mtime ? new Date(mtime).toISOString() : null,
+      ...(isTempPath(path) && { temp: true }),
+    }))
     .sort((a, b) => a.path.localeCompare(b.path));
   res.json(projects);
 });
@@ -1544,8 +1605,10 @@ app.get('/api/sessions/:sessionId', async (req, res) => {
   try {
     const sessionPath = taskDirFor(req.params.sessionId);
 
+    // A session that never used the board has no task dir. That is the common case and
+    // an answer, not a failure; a 404 only reached the browser console.
     if (!existsSync(sessionPath)) {
-      return res.status(404).json({ error: 'Session not found' });
+      return res.json([]);
     }
 
     const taskFiles = readdirSync(sessionPath).filter(f => f.endsWith('.json'));
@@ -1621,11 +1684,13 @@ app.get('/api/sessions/:sessionId/plan', async (req, res) => {
   try {
     const metadata = loadSessionMetadata();
     const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+    // Most sessions have no saved plan, and the info modal asks for one every time it
+    // opens, so "no plan" is a normal answer rather than a 404 in the console.
     const slug = meta?.slug;
-    if (!slug) return res.status(404).json({ error: 'No plan found' });
+    if (!slug) return res.json({ content: null });
 
     const planPath = path.join(PLANS_DIR, `${slug}.md`);
-    if (!existsSync(planPath)) return res.status(404).json({ error: 'No plan found' });
+    if (!existsSync(planPath)) return res.json({ content: null });
 
     const content = await fs.readFile(planPath, 'utf8');
     res.json({ content, slug });
@@ -1652,18 +1717,25 @@ app.get('/api/sessions/:sessionId/loop', (req, res) => {
   }
 });
 
+// Memo for a cold read keyed on the file's identity, so a repeat ask costs the one stat
+// it already pays to notice the file grew. `load` may return a promise: the promise is
+// what gets cached, so concurrent callers share a single read. Null when the file is gone.
+function cachedByFileStat(cache, filePath, load) {
+  let stat;
+  try { stat = statSync(filePath); } catch (_) { return null; }
+  const hit = cache.get(filePath);
+  if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) return hit.value;
+  const value = load();
+  cache.set(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, value });
+  return value;
+}
+
 // Cold path — a full transcript scan, so the result is held until the file grows.
 // The zen panel asks again on every re-render, which then costs one stat.
 const artifactsByPath = new Map();
 
 function getArtifactLinks(jsonlPath) {
-  let stat;
-  try { stat = statSync(jsonlPath); } catch (_) { return []; }
-  const hit = artifactsByPath.get(jsonlPath);
-  if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) return hit.artifacts;
-  const artifacts = readArtifactLinks(jsonlPath);
-  artifactsByPath.set(jsonlPath, { mtimeMs: stat.mtimeMs, size: stat.size, artifacts });
-  return artifacts;
+  return cachedByFileStat(artifactsByPath, jsonlPath, () => readArtifactLinks(jsonlPath)) || [];
 }
 
 app.get('/api/sessions/:sessionId/artifacts', (req, res) => {
@@ -1678,23 +1750,148 @@ app.get('/api/sessions/:sessionId/artifacts', (req, res) => {
   }
 });
 
+// A scratchpad is a folder plus a `scratchpad.json` manifest, rendered by the
+// external `scratch` CLI. cck only recognizes the shape and launches the viewer —
+// it reads nothing from the manifest but `name`, `created` and `id`, so the two stay
+// independently versioned.
+const SCRATCHPAD_MANIFEST = 'scratchpad.json';
+
+// Fallback only, for a `scratch new` whose output the transcript never captured. A pad
+// has no central registry — the CLI treats the folder path as the pad's identity and
+// finds pads by scanning — and `_scratchpads/` is one user's habit, not a convention it
+// knows, so there is no layout to guess. Depth 3 rather than a deeper walk for the
+// reason docs/session-scanning.md records: pruned, it measures 0-3 ms on the worst-case
+// project dirs, while an unpruned walk of the same dirs costs ~800 ms.
+const PAD_SCAN_IGNORE = new Set(['node_modules', '.git', '.hg', '.svn', 'dist', 'build']);
+const PAD_SCAN_MAX_DEPTH = 3;
+// A pad manifest's `created` is written after the tool call starts, so the match is
+// a window, not an instant. Measured lag on a real `scratch new` was 4.1 s; the
+// window is wide enough to survive a slow disk and far too narrow to reach a pad
+// made in an earlier session.
+const PAD_CREATE_WINDOW_MS = 120000;
+
+async function findPads(root, depth = 0) {
+  let entries;
+  try { entries = await fs.readdir(root, { withFileTypes: true }); } catch (_) { return []; }
+  // A pad is never nested inside another pad, so a manifest ends the descent.
+  if (entries.some((e) => e.isFile() && e.name === SCRATCHPAD_MANIFEST)) return [root];
+  if (depth >= PAD_SCAN_MAX_DEPTH) return [];
+  const nested = await Promise.all(
+    entries
+      .filter((e) => e.isDirectory() && !PAD_SCAN_IGNORE.has(e.name))
+      .map((e) => findPads(path.join(root, e.name), depth + 1)),
+  );
+  return nested.flat();
+}
+
+// The pads a session made, as linked-doc rows. Derived on every read rather than
+// stored, so re-reading a transcript cannot drift; the client links each pad once
+// and records that it did, which is what stops a re-read undoing an unlink.
+async function readCreatedPads(meta) {
+  const creations = readScratchpadCreations(meta.jsonlPath);
+  // No `scratch new` in the transcript means no disk work at all, so sessions that
+  // never touch the CLI pay a substring pass over the transcript and nothing more.
+  if (!creations.length) return [];
+  const reported = new Set(creations.filter((c) => c.path).map((c) => c.path));
+  const unresolved = creations.filter((c) => !c.path);
+  const askedFor = new Set(unresolved.map((c) => c.name).filter(Boolean));
+  // Only a call whose name could not be read falls back to the clock, and it compares
+  // against the call's second, not the call: the manifest records `created` to the
+  // second while the transcript timestamps to the millisecond, so a pad written during
+  // the same second as its own command otherwise reads as older than it.
+  const byClock = unresolved.filter((c) => !c.name).map((c) => Math.floor(c.ts / 1000) * 1000);
+  const sessionId = path.basename(meta.jsonlPath, '.jsonl');
+  // The project, not `meta.cwd`: cwd is wherever the session last stood, which drifts
+  // into subdirectories — a session that made a pad and then worked inside it reports
+  // a cwd below the pad, and a scan from there finds nothing above it.
+  const root = meta.project || meta.cwd;
+  const scanned = unresolved.length && root ? await findPads(root) : [];
+  const candidates = [...new Set([...reported, ...scanned.map((dir) => path.join(dir, SCRATCHPAD_MANIFEST))])];
+  const rows = await Promise.all(
+    candidates.map(async (file) => {
+      let manifest;
+      try { manifest = JSON.parse(await fs.readFile(file, 'utf8')); } catch (_) { return null; }
+      const created = Date.parse(manifest?.created);
+      if (!Number.isFinite(created)) return null;
+      const name = manifest.name || path.basename(path.dirname(file));
+      // A path the CLI printed names its pad outright. Otherwise `scratch new --id`
+      // settles it: the flag stamps the session that asked for the pad into the
+      // manifest, so an id decides ownership both ways — one naming another session
+      // disowns the pad whatever the name or the clock say. Only a pad with no id is
+      // guessed at, by the name the command asked for and then by the clock.
+      const claimed =
+        reported.has(file) ||
+        (manifest.id
+          ? manifest.id === sessionId
+          : askedFor.has(name) || byClock.some((from) => created >= from && created - from <= PAD_CREATE_WINDOW_MS));
+      if (!claimed) return null;
+      return { path: file, name, created: manifest.created, ts: created };
+    }),
+  );
+  return rows
+    .filter(Boolean)
+    .sort((a, b) => a.ts - b.ts)
+    .map(({ ts: _ts, ...row }) => row);
+}
+
+// Cold path — a full transcript scan, and a directory walk when the transcript did not
+// carry the pad paths, so the result is held until the transcript grows.
+const padsByPath = new Map();
+
+function getCreatedPads(meta) {
+  return cachedByFileStat(padsByPath, meta.jsonlPath, () => readCreatedPads(meta)) || [];
+}
+
+app.get('/api/sessions/:sessionId/pads', async (req, res) => {
+  try {
+    const metadata = loadSessionMetadata();
+    const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+    if (!meta?.jsonlPath) return res.json({ pads: [] });
+    res.json({ pads: await getCreatedPads(meta) });
+  } catch (error) {
+    console.error('Error reading created pads:', error);
+    res.status(500).json({ error: 'Failed to read created pads' });
+  }
+});
+
+// API: List one level of a session's scratchpad dir — the root, or the folder named by
+// `?path=`, which is the absolute path a previous listing handed out and must still sit
+// under the root. One readdir per request, never a walk: sessions drop clones and
+// build output in there, and an unpruned walk costs three orders of magnitude more than
+// the readdir. The client asks for a folder only when the user opens it. Measurements
+// in docs/session-scanning.md.
+app.get('/api/sessions/:sessionId/scratchpad-files', async (req, res) => {
+  try {
+    const metadata = loadSessionMetadata();
+    const id = metadata[req.params.sessionId] ? req.params.sessionId : resolveSessionId(req.params.sessionId);
+    const meta = metadata[id];
+    const root = meta ? getScratchpadDir(id, meta) : null;
+    if (!root) return res.json({ files: [] });
+
+    const dir = resolveScratchSubdir(root, req.query.path);
+    if (!dir) return res.status(400).json({ error: 'Path is outside the scratchpad dir' });
+
+    // The harness creates the dir lazily, so "missing" is the common case and lists as empty.
+    res.json({ files: await listScratchDir(dir) });
+  } catch (error) {
+    console.error('Error listing scratchpad files:', error);
+    res.status(500).json({ error: 'Failed to list scratchpad files' });
+  }
+});
+
 // API: List workflow scripts for a session. Parses each script's meta for the
 // canonical name + description (cold path — only when the workflow modal opens).
-app.get('/api/sessions/:sessionId/workflows', async (req, res) => {
+app.get('/api/sessions/:sessionId/workflows', (req, res) => {
   try {
-    const scripts = getWorkflowScripts(req.params.sessionId);
-    const workflows = await Promise.all(
-      scripts.map(async (w) => {
-        let meta = {};
-        try { meta = parseWorkflowMeta(await fs.readFile(w.path, 'utf8')); } catch (_) {}
-        return {
-          id: w.id,
-          name: meta.name || w.name,
-          description: meta.description || null,
-          modifiedAt: w.mtimeMs ? new Date(w.mtimeMs).toISOString() : null,
-        };
-      }),
-    );
+    const workflows = getWorkflowScripts(req.params.sessionId).map((w) => {
+      const meta = getWorkflowMeta(w.path);
+      return {
+        id: w.id,
+        name: meta.name || w.name,
+        description: meta.description || null,
+        modifiedAt: w.mtimeMs ? new Date(w.mtimeMs).toISOString() : null,
+      };
+    });
     res.json({ workflows });
   } catch (error) {
     console.error('Error listing workflows:', error);
@@ -1728,6 +1925,20 @@ function matchStr(src, key) {
   return m ? m[2] : null;
 }
 
+const workflowMetaCache = new Map();
+const EMPTY_WORKFLOW_META = { name: null, description: null, phases: [] };
+// A script never changes mid-run, and three endpoints parse the same file — one of them
+// on a poll — so key the parse by the script's mtime.
+function getWorkflowMeta(scriptPath) {
+  return cachedByMtime(
+    workflowMetaCache,
+    scriptPath,
+    scriptPath,
+    () => parseWorkflowMeta(readFileSync(scriptPath, 'utf8')),
+    EMPTY_WORKFLOW_META,
+  );
+}
+
 function parseWorkflowMeta(source) {
   const meta = { name: matchStr(source, 'name'), description: matchStr(source, 'description'), phases: [] };
   const phasesM = source.match(/phases\s*:\s*\[([\s\S]*?)\]/);
@@ -1740,26 +1951,61 @@ function parseWorkflowMeta(source) {
   return meta;
 }
 
-// journal.jsonl records {type:'started',agentId} then {type:'result',agentId,...}
-// per workflow agent. Map agentId → {started, done}; done count matches the
-// "N/M agents" ratio the /workflows viewer shows.
+// journal.jsonl records {type:'started',agentId,phase,label} then
+// {type:'result',agentId,...} per workflow agent. Map agentId →
+// {started, done, phase, label}; done count matches the "N/M agents" ratio the
+// /workflows viewer shows.
+const workflowJournalCache = new Map();
+function workflowJournalPath(runDir) {
+  return path.join(runDir, 'journal.jsonl');
+}
+
 function readWorkflowJournal(runDir) {
+  const journalPath = workflowJournalPath(runDir);
+  return cachedByMtime(workflowJournalCache, journalPath, journalPath, () => parseWorkflowJournal(journalPath), new Map());
+}
+
+function parseWorkflowJournal(journalPath) {
   const status = new Map();
   let content;
-  try { content = readFileSync(path.join(runDir, 'journal.jsonl'), 'utf8'); } catch { return status; }
+  try { content = readFileSync(journalPath, 'utf8'); } catch { return status; }
   for (const line of content.split('\n')) {
     if (!line.trim()) continue;
     let o;
     try { o = JSON.parse(line); } catch { continue; }
     if (!o.agentId) continue;
-    const e = status.get(o.agentId) || { started: false, done: false };
+    const e = status.get(o.agentId) || { started: false, done: false, phase: null, label: null };
     if (o.type === 'started') e.started = true;
     else if (o.type === 'result') e.done = true;
+    if (o.phase) e.phase = o.phase;
+    if (o.label) e.label = o.label;
     status.set(o.agentId, e);
   }
   return status;
 }
 
+// One definition of "how far along is this run", shared by the modal's /run view and
+// the sidebar widget, so the two can never disagree about what counts as done.
+function summarizeWorkflowJournal(journal) {
+  const byPhase = new Map();
+  const running = [];
+  let startedCount = 0;
+  let doneCount = 0;
+  for (const e of journal.values()) {
+    if (!e.started) continue;
+    const phase = e.phase || '';
+    const c = byPhase.get(phase) || { started: 0, done: 0 };
+    startedCount++;
+    c.started++;
+    if (e.done) {
+      doneCount++;
+      c.done++;
+    } else running.push(e.label || phase || 'agent');
+    byPhase.set(phase, c);
+  }
+  return { startedCount, doneCount, byPhase, running };
+}
+
 // A workflow's run artifacts (journal + agent transcripts) live at
 // <sessionDir>/subagents/workflows/<wfId>/. The script itself sits under
 // <sessionDir>/workflows/scripts/, so the run dir is derivable from the script
@@ -1767,8 +2013,9 @@ function readWorkflowJournal(runDir) {
 // then to scanning every project/session (the session dir can sit under a
 // different projEnc than the script when a workflow runs from another cwd). wfId
 // comes from the trusted script index (validated filename), so it can't
-// traverse. Cold path only.
-function resolveWorkflowRunDir(meta, wfId, scriptPath) {
+// traverse. That last scan is a cold path only — `skipScan` is what keeps it out
+// of the polled live view, where a script with no run dir would pay it every tick.
+function resolveWorkflowRunDir(meta, wfId, scriptPath, skipScan = false) {
   const rel = path.join('subagents', 'workflows', wfId);
   if (scriptPath) {
     const sessionDir = path.dirname(path.dirname(path.dirname(scriptPath)));
@@ -1779,6 +2026,7 @@ function resolveWorkflowRunDir(meta, wfId, scriptPath) {
     const local = path.join(sessionDirFromMeta(meta), rel);
     if (existsSync(local)) return local;
   }
+  if (skipScan) return null;
   try {
     for (const proj of readdirSync(PROJECTS_DIR, { withFileTypes: true })) {
       if (!proj.isDirectory()) continue;
@@ -1797,15 +2045,13 @@ function resolveWorkflowRunDir(meta, wfId, scriptPath) {
 
 // API: Workflow run state — declared phases (from the script) plus the agent
 // roster (type/model/output-tokens/duration/status) reconstructed from the run
-// dir's journal + transcripts. Phase↔agent mapping and per-agent labels are
-// runtime-only and never persisted, so the roster is flat by design.
+// dir's journal + transcripts. The roster is flat: the journal carries each
+// agent's phase and label, but the modal lists agents in start order.
 app.get('/api/sessions/:sessionId/workflows/:wfId/run', async (req, res) => {
   try {
     const wf = getWorkflowScripts(req.params.sessionId).find((w) => w.id === req.params.wfId);
     if (!wf) return res.status(404).json({ error: 'Workflow not found' });
-    let source = '';
-    try { source = await fs.readFile(wf.path, 'utf8'); } catch (_) {}
-    const parsed = parseWorkflowMeta(source);
+    const parsed = getWorkflowMeta(wf.path);
 
     const sessionId = resolveSessionId(req.params.sessionId);
     const meta = loadSessionMetadata()[sessionId] || {};
@@ -1824,17 +2070,19 @@ app.get('/api/sessions/:sessionId/workflows/:wfId/run', async (req, res) => {
         try {
           type = JSON.parse(readFileSync(path.join(runDir, `agent-${agentId}.meta.json`), 'utf8')).agentType || null;
         } catch (_) {}
-        const done = journal.get(agentId)?.done;
+        const entry = journal.get(agentId);
         const durationMs = stats.firstTs && stats.lastTs ? new Date(stats.lastTs) - new Date(stats.firstTs) : null;
         if (stats.lastTs && (!stoppedAt || stats.lastTs > stoppedAt)) stoppedAt = stats.lastTs;
         agents.push({
           agentId,
           type,
+          phase: entry?.phase || null,
+          label: entry?.label || null,
           model: stats.model || null,
           outputTokens: stats.outputTokens || 0,
           durationMs,
           startedAt: stats.firstTs || null,
-          status: done ? 'done' : 'running',
+          status: entry?.done ? 'done' : 'running',
         });
       }
       agents.sort((a, b) => (a.startedAt || '').localeCompare(b.startedAt || ''));
@@ -1842,12 +2090,7 @@ app.get('/api/sessions/:sessionId/workflows/:wfId/run', async (req, res) => {
     // Roster is start-ordered, so the earliest start is simply the first agent.
     const startedAt = agents[0]?.startedAt || null;
 
-    let startedCount = 0;
-    let doneCount = 0;
-    for (const e of journal.values()) {
-      if (e.started) startedCount++;
-      if (e.done) doneCount++;
-    }
+    let { startedCount, doneCount } = summarizeWorkflowJournal(journal);
     if (!startedCount) {
       startedCount = agents.length;
       doneCount = agents.filter((a) => a.status === 'done').length;
@@ -1870,6 +2113,58 @@ app.get('/api/sessions/:sessionId/workflows/:wfId/run', async (req, res) => {
   }
 });
 
+// A workflow has no terminal journal entry, so "still running" is every started
+// agent without a result plus a journal that moved recently — a run killed
+// mid-flight would otherwise stay live forever.
+const WORKFLOW_LIVE_MAX_IDLE_MS = 10 * 60 * 1000;
+// Only the newest few scripts can hold the live run, and each miss costs two
+// existsSync probes — a session that has accumulated scripts must not turn the
+// poll into a scan of all of them.
+const WORKFLOW_LIVE_MAX_SCRIPTS = 3;
+
+// API: The session's running workflow, or null. The zen panel polls this, so it
+// reads the journal only — never the agent transcripts the /run view parses.
+app.get('/api/sessions/:sessionId/workflow-live', (req, res) => {
+  try {
+    const sessionId = resolveSessionId(req.params.sessionId);
+    const meta = loadSessionMetadata()[sessionId] || {};
+    for (const wf of getWorkflowScripts(req.params.sessionId).slice(0, WORKFLOW_LIVE_MAX_SCRIPTS)) {
+      const runDir = resolveWorkflowRunDir(meta, wf.id, wf.path, true);
+      if (!runDir) continue;
+      let mtimeMs = 0;
+      try { mtimeMs = statSync(path.join(runDir, 'journal.jsonl')).mtimeMs; } catch { continue; }
+      if (Date.now() - mtimeMs > WORKFLOW_LIVE_MAX_IDLE_MS) continue;
+
+      const { startedCount, doneCount, byPhase, running } = summarizeWorkflowJournal(readWorkflowJournal(runDir));
+      if (!startedCount || doneCount >= startedCount) continue;
+
+      const parsed = getWorkflowMeta(wf.path);
+      const declared = parsed.phases.map((p) => p.title);
+      const extra = [...byPhase.keys()].filter((t) => t && !declared.includes(t));
+      const phases = [...declared, ...extra].map((title) => ({
+        title,
+        started: byPhase.get(title)?.started || 0,
+        done: byPhase.get(title)?.done || 0,
+      }));
+
+      return res.json({
+        workflow: {
+          id: wf.id,
+          name: parsed.name || wf.name,
+          startedCount,
+          doneCount,
+          phases,
+          running: running.slice(0, 4),
+        },
+      });
+    }
+    res.json({ workflow: null });
+  } catch (error) {
+    console.error('Error building live workflow view:', error);
+    res.status(500).json({ error: 'Failed to build live workflow view' });
+  }
+});
+
 // API: Open a workflow script in VS Code
 app.post('/api/sessions/:sessionId/workflows/:wfId/open', (req, res) => {
   try {
@@ -1945,11 +2240,6 @@ app.post('/api/open-in-editor', (req, res) => {
   }
 });
 
-// A scratchpad is a folder plus a `scratchpad.json` manifest, rendered by the
-// external `scratch` CLI. cck only recognizes the shape and launches the viewer —
-// it never parses the manifest, so the two stay independently versioned.
-const SCRATCHPAD_MANIFEST = 'scratchpad.json';
-
 // Resolve a linked path to the pad the viewer wants: `<parent>/<name>` where
 // `<name>/scratchpad.json` exists. Accepts either the manifest or its directory.
 function resolveScratchpad(value) {
@@ -2837,9 +3127,169 @@ app.get('/api/config', (_req, res) => {
     costUrl: COST_URL,
     memoryUrl: MEMORY_URL,
     scratchAvailable: !!whichSync('scratch'),
+    terminal: terminal.clientConfig(),
+  });
+});
+
+// #endregion
+
+// #region TERMINAL
+// A new session may start only in a folder the user has already worked in, or one they
+// chose in the native dialog during this run. Anything else would let a page script pick
+// the directory claude runs in.
+const pickedFolders = new Set();
+function isAllowedFolder(dir) {
+  const known = pickedFolders.has(dir) || Object.values(loadSessionMetadata()).some((m) => m.project === dir);
+  try { return known && statSync(dir).isDirectory(); } catch { return false; }
+}
+
+const terminal = createTerminalService({
+  config: readTerminalConfig({ getArgValue }),
+  net,
+  claudeDir: CLAUDE_DIR,
+  isDefaultDir: isDefaultClaudeDir(CLAUDE_DIR),
+  token: process.env.CCK_TERMINAL_TOKEN,
+  which: whichSync,
+  isLiveElsewhere: isSessionProcessAlive,
+  // The project, not the last cwd: `claude --resume` finds a session under the
+  // project dir it started in, and cwd drifts into subdirectories.
+  resolveCwd: (id) => {
+    const meta = loadSessionMetadata()[id];
+    return meta ? meta.project || meta.cwd || null : null;
+  },
+  isAllowedFolder,
+  liveSessions: () => loadLiveSessions(true),
+  onChange: () => broadcast({ type: 'terminals-update', ids: terminal.list().map((t) => t.id) }),
+  onExit: (id) => dispatches.sessionExited(id),
+});
+
+let folderDialogOpen = false;
+app.post('/api/terminal/pick-folder', async (req, res) => {
+  const reason = terminal.unavailableReason();
+  if (reason) return res.status(403).json({ error: reason });
+  if (!terminal.authorized(req.get('x-terminal-token'))) return res.status(401).json({ error: 'invalid terminal token' });
+  if (folderDialogOpen) return res.status(409).json({ error: 'a folder dialog is already open' });
+  folderDialogOpen = true;
+  try {
+    const dir = await pickFolder(whichSync, { start: req.body?.start });
+    if (dir) pickedFolders.add(dir);
+    res.json({ path: dir });
+  } catch (e) {
+    res.status(501).json({ error: e.message });
+  } finally {
+    folderDialogOpen = false;
+  }
+});
+
+// The hub's eviction check reads this to keep a pool with live PTYs alive.
+app.get('/api/terminals', (_req, res) => {
+  res.setHeader('Cache-Control', 'no-store');
+  res.json({ sessions: terminal.list() });
+});
+
+app.delete('/api/terminals/:id', (req, res) => {
+  const err = terminal.end(req.params.id, req.get('x-terminal-token'));
+  if (err === 'auth') return res.status(401).json({ error: 'invalid terminal token' });
+  if (err === 'not-found') return res.status(404).json({ error: 'no such terminal' });
+  res.status(204).end();
+});
+
+// Served from node_modules, never a CDN: any script on this page can use the token.
+const XTERM_FILES = {
+  'xterm.js': '@xterm/xterm/lib/xterm.js',
+  'xterm.css': '@xterm/xterm/css/xterm.css',
+  'addon-fit.js': '@xterm/addon-fit/lib/addon-fit.js',
+  'addon-webgl.js': '@xterm/addon-webgl/lib/addon-webgl.js',
+  'addon-unicode11.js': '@xterm/addon-unicode11/lib/addon-unicode11.js',
+};
+app.get('/vendor/xterm/:file', (req, res) => {
+  const rel = Object.hasOwn(XTERM_FILES, req.params.file) ? XTERM_FILES[req.params.file] : null;
+  if (!rel) return res.status(404).end();
+  let file;
+  try { file = require.resolve(rel); } catch { return res.status(404).end(); }
+  res.setHeader('Cache-Control', 'public, max-age=86400');
+  res.sendFile(file);
+});
+// #endregion
+
+// #region DISPATCH
+const dispatches = createDispatchRegistry({
+  onSettle: (r) => {
+    if (r.parent && r.report) enqueueSessionEvent(topicKey('dispatch', r.parent), formatDispatchLine(r));
+    broadcast({ type: 'dispatch-update' });
+  },
+});
+
+const dispatchGroups = createGroupStore({
+  load: () => {
+    try { return JSON.parse(readFileSync(DISPATCH_GROUPS_FILE, 'utf8')); } catch { return null; }
+  },
+  save: (data) => writeJsonAtomic(DISPATCH_GROUPS_FILE, data),
+  isAlive: (id) => terminal.isRunning(id) || isSessionProcessAlive(id),
+  pinnedIds: () => new Set(Object.keys(readPins())),
+});
+
+// The board places a session from these alone, so it never has to move it later.
+// `startedBy` lets it follow a starter the user put in a named group, which only the
+// browser knows; it goes once the dispatch settles.
+function withDispatchPlacement(sessions) {
+  const groups = dispatchGroups.snapshot();
+  const starters = new Map(
+    dispatches.list().filter((r) => r.status === 'running' && r.parent && r.session).map((r) => [r.session, r.parent]),
+  );
+  if (!groups.size && !starters.size) return sessions;
+  return sessions.map((s) => {
+    const dispatchGroup = groups.get(s.id);
+    const startedBy = starters.get(s.id);
+    return dispatchGroup || startedBy ? { ...s, dispatchGroup, startedBy } : s;
   });
+}
+
+// Starting a session needs the terminal token, as the browser does; the CLI reads it from
+// TERMINAL_TOKEN_FILE. The child gets only its dispatch capability through the preamble.
+app.post('/api/dispatch', (req, res) => {
+  if (!terminal.authorized(req.get('x-terminal-token'))) return res.status(401).json({ error: 'invalid terminal token' });
+  const { cwd, spec, name, model, worktree, parent, group, report, peer } = req.body || {};
+  if (typeof spec !== 'string' || !spec.trim()) return res.status(400).json({ error: 'spec is required' });
+  if (peer != null && !isPeerName(peer)) return res.status(400).json({ error: 'peer must be a peer name as ListAgents prints it' });
+  if (parent != null && !(typeof parent === 'string' && isUUID(parent))) return res.status(400).json({ error: 'invalid parent' });
+  if (group != null && !isGroupName(group)) {
+    return res.status(400).json({ error: `group must be kebab-case, e.g. ${suggestGroupName(group) || 'my-group'}` });
+  }
+  const starterGroup = parent ? dispatchGroups.groupOf(parent) : null;
+  const target = group || starterGroup;
+  const r = dispatches.create({ parent, name, spec: spec.trim(), report: report === true, peer, group: target, worktree });
+  const env = { CCK_DISPATCH_ID: r.id, ...(parent && { PARENT_SESSION_ID: parent }) };
+  const started = terminal.startNew({ cwd, name, model, worktree, prompt: formatPreamble(r) }, env);
+  if (started.error) {
+    dispatches.discard(r.id);
+    return res.status(started.status).json({ error: started.error });
+  }
+  dispatches.attach(r.id, { session: started.id, cwd: started.cwd });
+  // A starter already in a group stays where it is: moving it would jump it under the user.
+  if (target) dispatchGroups.join(target, [starterGroup ? null : parent, started.id]);
+  broadcast({ type: 'dispatch-update' });
+  res.status(201).json({ dispatch: r.id, session: started.id, cwd: started.cwd, group: target });
+});
+
+app.post('/api/dispatch/:id/done', (req, res) => {
+  const { cap, outcome, summary } = req.body || {};
+  const err = dispatches.settle(req.params.id, cap, outcome, summary);
+  if (err) return res.status(err.status).json({ error: err.error });
+  res.status(204).end();
 });
 
+app.get('/api/dispatch', async (req, res) => {
+  res.setHeader('Cache-Control', 'no-store');
+  const ids = typeof req.query.ids === 'string' && req.query.ids ? req.query.ids.split(',') : null;
+  const parent = typeof req.query.parent === 'string' && req.query.parent ? req.query.parent : null;
+  // res, not req: a GET's request stream can close before the response is sent.
+  const out = await dispatches.wait({ ids, parent }, req.query.wait, (stop) => {
+    res.on('close', stop);
+    return () => res.off('close', stop);
+  });
+  if (!res.writableEnded) res.json(out);
+});
 // #endregion
 
 // #region TASK_ROUTES
@@ -2897,7 +3347,7 @@ app.get('/api/tasks/all', async (_req, res) => {
   }
 });
 
-const { enqueueSessionEvent, formatTaskMoved, handleSessionEvents } = require('./lib/session-events');
+const { enqueueSessionEvent, formatTaskMoved, handleSessionEvents, topicKey } = require('./lib/session-events');
 app.get('/api/sessions/:sessionId/events', handleSessionEvents);
 
 // API: Create a task
@@ -3016,9 +3466,69 @@ app.delete('/api/tasks/:sessionId/:taskId', async (req, res) => {
 
 // #region PREVIEW
 // API: File preview — read file and broadcast to clients
-const PREVIEW_KINDS = { '.md': 'markdown', '.markdown': 'markdown', '.html': 'html', '.htm': 'html' };
+// `text` files are shown as source, highlighted by extension, so the value doubles as
+// the hljs language name where the two differ. An allowlist rather than byte sniffing:
+// the client puts the whole response in the DOM, and a mislabelled binary would land
+// there as megabytes of mojibake.
+const PREVIEW_TEXT_EXTS =
+  'txt log csv tsv json jsonl ndjson yml yaml toml ini cfg conf env js mjs cjs ts tsx jsx py rb go rs java kt cs c h cpp hpp php pl lua sh bash zsh ps1 psm1 bat cmd sql graphql css scss less xml svg patch diff';
+// Served as bytes by GET /api/preview/image, so the NUL sniff below does not apply.
+const PREVIEW_IMAGE_EXTS = 'png jpg jpeg gif webp avif bmp';
+const PREVIEW_KINDS = {
+  '.md': 'markdown',
+  '.markdown': 'markdown',
+  '.html': 'html',
+  '.htm': 'html',
+  ...Object.fromEntries(PREVIEW_TEXT_EXTS.split(' ').map((ext) => [`.${ext}`, 'text'])),
+  ...Object.fromEntries(PREVIEW_IMAGE_EXTS.split(' ').map((ext) => [`.${ext}`, 'image'])),
+};
+// A scratchpad collects files whose real extension is buried under a trailing one —
+// report.html.before, app.js.map, config.env.local, page.html~. One hop past an
+// extension the allowlist does not know asks the question that actually decides the
+// kind, "is the extension under it previewable", instead of enumerating the suffix
+// conventions a session might invent. Compressed suffixes stop the hop: the bytes
+// beneath them are binary, which is what the allowlist exists to keep out of the DOM.
+const PREVIEW_OPAQUE_EXTS = new Set(['.gz', '.br', '.zst', '.xz', '.bz2', '.zip', '.7z']);
+
+function previewExtFor(absPath) {
+  const trimmed = absPath.replace(/~+$/, '');
+  const ext = path.extname(trimmed).toLowerCase();
+  if (PREVIEW_KINDS[ext] || !ext || PREVIEW_OPAQUE_EXTS.has(ext)) return ext;
+  return path.extname(trimmed.slice(0, -ext.length)).toLowerCase();
+}
+
+function previewKindFor(absPath) {
+  return PREVIEW_KINDS[previewExtFor(absPath)] || null;
+}
+
+// The hop makes a claim about bytes from a name, and PREVIEW_OPAQUE_EXTS can only stop
+// it for suffixes it already knows: report.json.gpg, notes.md.enc and secrets.yml.age
+// all hop to the extension underneath and would render their ciphertext. Enumerating
+// the encryption conventions fails open the same way, so the claim is confirmed against
+// the bytes instead — a NUL in the head is git's test for "not text", and encrypted or
+// compressed output trips it immediately.
+const TEXT_SNIFF_BYTES = 8192;
+
+async function readHead(absPath) {
+  const fh = await fs.open(absPath, 'r');
+  try {
+    const buf = Buffer.alloc(TEXT_SNIFF_BYTES);
+    const { bytesRead } = await fh.read(buf, 0, TEXT_SNIFF_BYTES, 0);
+    return buf.subarray(0, bytesRead);
+  } finally {
+    await fh.close();
+  }
+}
+
+async function confirmKind(absPath, kind) {
+  if (!kind) return null;
+  return (await readHead(absPath)).includes(0) ? null : kind;
+}
+
 // Whole files are pushed into a modal, so anything huge freezes the tab regardless of kind.
 const PREVIEW_MAX_BYTES = 8 * 1024 * 1024;
+// Source in a modal is for reading, not for scrolling a generated bundle.
+const PREVIEW_TEXT_MAX_BYTES = 2 * 1024 * 1024;
 
 function previewError(status, message) {
   const err = new Error(message);
@@ -3033,7 +3543,8 @@ async function statFileTarget(absPath) {
   try {
     const stats = await fs.stat(absPath);
     if (!stats.isFile()) throw previewError(400, 'Not a file');
-    return { size: stats.size, kind: PREVIEW_KINDS[path.extname(absPath).toLowerCase()] || null };
+    const kind = previewKindFor(absPath);
+    return { size: stats.size, kind: kind === 'image' ? kind : await confirmKind(absPath, kind) };
   } catch (e) {
     if (e.status) throw e;
     if (e.code === 'ENOENT') throw previewError(404, 'File not found');
@@ -3042,22 +3553,31 @@ async function statFileTarget(absPath) {
   }
 }
 
-// Checks the file is previewable without reading it — the broadcast path needs the
+function enforcePreviewSize(kind, size) {
+  const max = kind === 'text' ? PREVIEW_TEXT_MAX_BYTES : PREVIEW_MAX_BYTES;
+  if (size > max) {
+    throw previewError(400, `Preview too large (${Math.round(size / 1048576)}MB, max ${max / 1048576}MB)`);
+  }
+}
+
+// Checks the file is previewable without reading it whole — the broadcast path needs the
 // validation (and its status codes) but never the content.
 async function validatePreviewFile(absPath) {
   const { kind, size } = await statFileTarget(absPath);
-  if (!kind) throw previewError(400, 'Only .md/.markdown/.html/.htm files are allowed');
-  if (size > PREVIEW_MAX_BYTES) {
-    throw previewError(
-      400,
-      `Preview too large (${Math.round(size / 1048576)}MB, max ${PREVIEW_MAX_BYTES / 1048576}MB)`
-    );
-  }
+  if (!kind) throw previewError(400, 'Not a previewable text, markdown, HTML or image file');
+  enforcePreviewSize(kind, size);
   return { kind, size };
 }
 
 async function readPreviewFile(absPath) {
-  const { kind } = await validatePreviewFile(absPath);
+  const { kind, size } = await statFileTarget(absPath);
+  // A kind the previewer can't render is an answer, not a failure, reported the way
+  // /api/file/resolve reports it: the caller opens the file in the editor instead. A 400
+  // would only reach the browser console. A size refusal stays a 400 — that one is real.
+  if (!kind) return { content: null, kind: null };
+  enforcePreviewSize(kind, size);
+  // Images travel as bytes through GET /api/preview/image; the client builds the URL from `path`.
+  if (kind === 'image') return { content: null, kind };
   const raw = await fs.readFile(absPath, 'utf8');
   if (kind !== 'html') return { content: raw, kind };
   // The client renders HTML into a `srcdoc` iframe, which has no base URL — sibling
@@ -3090,7 +3610,10 @@ function resolvePreviewPath(rawPath, base) {
   // Every path entering the preview/link surface passes through here, so accepting
   // `file://` once covers /api/preview, /api/document/link and /api/file/resolve.
   const filePath = fileUrlToPath(rawPath);
-  if (path.isAbsolute(filePath)) return dropUrlFragment(filePath);
+  // Normalized, not passed through: a linked document is identified by its path string,
+  // and `C:/a/b` typed into the link editor has to reach the same string as the `C:\a\b`
+  // a server-side `path.join` produces, or the same file is linked twice.
+  if (path.isAbsolute(filePath)) return dropUrlFragment(path.normalize(filePath));
   if (base && typeof base === 'string' && path.isAbsolute(base)) {
     let baseDir = base;
     try {
@@ -3207,27 +3730,51 @@ app.get('/api/session/pins', (_req, res) => {
 });
 
 app.get('/api/preview', async (req, res) => {
+  const abs = resolvePreviewPath(req.query.path, req.query.base);
+  if (!abs) return res.status(400).json({ error: 'path is required' });
   try {
-    const abs = resolvePreviewPath(req.query.path, req.query.base);
-    if (!abs) return res.status(400).json({ error: 'path is required' });
     const { content, kind } = await readPreviewFile(abs);
-    res.json({ path: abs, content, kind });
+    res.json({ path: abs, exists: true, content, kind });
   } catch (error) {
-    console.error('Error in GET /api/preview:', error);
+    // Reported the way /api/file/resolve reports it: a relative link inside a rendered
+    // document is followed without knowing the target is there, so a link to a deleted
+    // file would put a 404 in the browser console. The caller toasts it from `exists`.
+    if (error.status === 404) return res.json({ path: abs, exists: false, content: null, kind: null });
+    // A previewError carries the status it wants reported and is an answer, not a
+    // failure — a missing file or one too large to render is the user's doing.
+    if (!error.status) console.error('Error in GET /api/preview:', error);
     res.status(error.status || 500).json({ error: error.message || 'Preview failed' });
   }
 });
 
-// API: Resolve a hand-typed path to an absolute one that exists. Deliberately not
-// extension-restricted — a linked file the previewer can't render (kind: null) is
-// still linkable, the client just opens it in the editor instead.
+app.get('/api/preview/image', async (req, res) => {
+  const abs = resolvePreviewPath(req.query.path, req.query.base);
+  if (!abs) return res.status(400).json({ error: 'path is required' });
+  try {
+    const { kind } = await statFileTarget(abs);
+    if (kind !== 'image') throw previewError(400, 'Not an image');
+    res.type(MIME_BY_EXT[previewExtFor(abs)]);
+    res.sendFile(abs);
+  } catch (error) {
+    if (!error.status) console.error('Error in GET /api/preview/image:', error);
+    res.status(error.status || 500).json({ error: error.message || 'Preview failed' });
+  }
+});
+
+// API: Resolve a hand-typed path to an absolute one, reporting whether it exists and
+// what it is. Deliberately not extension-restricted — a linked file the previewer can't
+// render (kind: null) is still linkable, the client just opens it in the editor instead.
 app.get('/api/file/resolve', async (req, res) => {
+  const abs = resolvePreviewPath(req.query.path, req.query.base);
+  if (!abs) return res.status(400).json({ error: 'path is required' });
   try {
-    const abs = resolvePreviewPath(req.query.path, req.query.base);
-    if (!abs) return res.status(400).json({ error: 'path is required' });
     // No size cap here — an unpreviewable file of any size is still linkable.
-    res.json({ path: abs, ...(await statFileTarget(abs)) });
+    res.json({ path: abs, exists: true, ...(await statFileTarget(abs)) });
   } catch (error) {
+    // A path that is not there is an answer, not a transport failure: a linked-doc row
+    // classifies its file through this endpoint, so a file since deleted would put a 404
+    // in the browser console on every render. The link editor reports it from `exists`.
+    if (error.status === 404) return res.json({ path: abs, exists: false, kind: null });
     console.error('Error in GET /api/file/resolve:', error);
     res.status(error.status || 500).json({ error: error.message || 'Failed to resolve file' });
   }
@@ -3557,9 +4104,16 @@ async function prewarmCaches() {
     // 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);
+    setInterval(() => reclaimServerInfo(actualPort), 30000).unref();
     migrateLegacyApprovalsConfig();
     const warning = net.exposureWarning();
     if (warning) console.log(warning);
+    const terminalReason = terminal.unavailableReason();
+    if (terminalReason && terminalReason !== 'disabled') console.log(`Terminal unavailable: ${terminalReason}`);
+    // Under the hub the hub owns the token and hands it to the iframe itself.
+    if (!terminalReason && !process.env.CLAUDE_HUB) {
+      console.log(`Terminal enabled - open http://localhost:${actualPort}/#t=${terminal.token}`);
+    }
 
     if (process.argv.includes('--open')) {
       import('open').then(open => open.default(`http://localhost:${actualPort}`));
@@ -3567,12 +4121,14 @@ async function prewarmCaches() {
     setImmediate(prewarmCaches);
   };
 
-  const server = net.listenLoopback(app, PORT, onReady);
+  const listenOpts = { onUpgrade: terminal.handleUpgrade };
+  const server = net.listenLoopback(app, PORT, onReady, listenOpts);
+  process.on('exit', terminal.shutdown);
 
   server.on('error', (err) => {
     if (err.code === 'EADDRINUSE') {
       console.log(`Port ${PORT} in use, trying random port...`);
-      net.listenLoopback(app, 0, onReady);
+      net.listenLoopback(app, 0, onReady, listenOpts);
     } else {
       throw err;
     }