claude-code-kanban 4.25.0 → 4.27.0

package/server.js

@@ -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 {
@@ -21,6 +22,8 @@ const {
   readSessionInfoFromJsonl,
   buildSessionDigest,
   readCompactSummaries,
+  readArtifactLinks,
+  readScratchpadCreations,
   extractPromptFromTranscript,
   extractModelFromTranscript,
   extractStructuredResultFromTranscript,
@@ -32,8 +35,8 @@ const {
   updateLoopInfo,
   buildLoopInfoFromState
 } = require('./lib/parsers');
-const { inlineHtmlAssets } = require('./lib/inline-assets');
-const { buildDecision, decisionFileName, isDecisionFile, waitSecondsFrom, isLapsed } = require('./lib/approvals');
+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');
 
 if (process.argv.includes("--install") || process.argv.includes("--uninstall")) {
@@ -105,12 +108,33 @@ function writePins(pins) {
   writeJsonAtomic(PINS_FILE, pins);
 }
 
-// Port discovery for out-of-process helpers (the postman monitor). The pid rides along
-// so a reader can tell a live server from a file left behind by a crashed one.
+// Port discovery for out-of-process helpers (the postman monitor, approval-gate.sh).
+// The pid rides along so a reader can tell a live server from a file left behind by
+// a crashed one.
 function writeServerInfo(port) {
   writeJsonAtomic(SERVER_INFO_FILE, { port, pid: process.pid });
 }
 
+// A beacon that outlives its server disarms UI approvals silently: approval-gate.sh
+// probes the port, finds it closed and never waits. The hub spawns every sub-app on
+// an ephemeral port, so a stale beacon never comes back on its own — drop ours on
+// the way out. Only when the file is still ours: a newer server on the same config
+// dir has already claimed it.
+function removeServerInfo() {
+  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 */ }
+}
+
+process.on('exit', removeServerInfo);
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(sig, () => {
+    removeServerInfo();
+    process.exit(0);
+  });
+}
+
 // #endregion
 
 // #region TIMINGS
@@ -155,23 +179,30 @@ function persistAgent(dir, agent) {
   fs.appendFile(file, `${JSON.stringify({ ...agent, event: 'server-update' })}\n`, 'utf8').catch(() => {});
 }
 
-// Lapse math lives in lib/approvals (kept in sync with the gate's own parse);
-// this only reads the config, cached so the polled session list doesn't re-read
-// it per hit (marker stays visible for the badge until TTL).
-const APPROVALS_CONFIG_FILE = path.join(CCK_DIR, 'approvals.json');
-let approvalsWaitCache = { ts: 0, ms: 30 * 1000 };
-function approvalsWaitMs() {
-  if (Date.now() - approvalsWaitCache.ts < 10 * 1000) return approvalsWaitCache.ms;
-  let cfg = null;
-  try {
-    cfg = JSON.parse(readFileSync(APPROVALS_CONFIG_FILE, 'utf8'));
-  } catch { /* missing config — gate default */ }
-  approvalsWaitCache = { ts: Date.now(), ms: waitSecondsFrom(cfg) * 1000 };
-  return approvalsWaitCache.ms;
+// <CCK_DIR>/config.json — cck's own settings, per Claude config dir.
+// Normalization lives in lib/approvals (kept in sync with the gate's own parse).
+const CCK_CONFIG_FILE = path.join(CCK_DIR, 'config.json');
+const LEGACY_APPROVALS_FILE = path.join(CCK_DIR, 'approvals.json');
+const cckConfigCache = new Map();
+function approvalsConfig() {
+  return cachedByMtime(cckConfigCache, 'approvals', CCK_CONFIG_FILE,
+    () => approvalsFrom(JSON.parse(readFileSync(CCK_CONFIG_FILE, 'utf8'))), approvalsFrom(null));
 }
 
-function isWaitingLapsed(data) {
-  return isLapsed(data.timestamp, approvalsWaitMs());
+// approvals.json predates config.json (and was opt-in). Fold it into
+// config.json once so an existing opt-in keeps its tuning, then drop it.
+function migrateLegacyApprovalsConfig() {
+  if (!existsSync(LEGACY_APPROVALS_FILE)) return;
+  try {
+    const legacy = JSON.parse(readFileSync(LEGACY_APPROVALS_FILE, 'utf8'));
+    let cfg = {};
+    try { cfg = JSON.parse(readFileSync(CCK_CONFIG_FILE, 'utf8')) || {}; } catch { /* absent */ }
+    if (!cfg.approvals) writeJsonAtomic(CCK_CONFIG_FILE, { ...cfg, approvals: legacy });
+    unlinkSync(LEGACY_APPROVALS_FILE);
+    cckConfigCache.clear();
+  } catch (e) {
+    console.error(`[cck] could not migrate ${LEGACY_APPROVALS_FILE}: ${e.message}`);
+  }
 }
 
 function checkWaitingForUser(agentDir, logMtime) {
@@ -183,7 +214,9 @@ function checkWaitingForUser(agentDir, logMtime) {
       if (age >= PERMISSION_TTL_MS) return null;
       // After grace period, check if session resumed activity (user already responded)
       if (logMtime && age >= WAITING_RESOLVE_GRACE_MS && logMtime > waitTime + WAITING_RESOLVE_GRACE_MS) return null;
-      if (isWaitingLapsed(data)) return { ...data, lapsed: true };
+      // Opted out reads the same as lapsed to the board: the ask is only
+      // answerable in the terminal, so no buttons.
+      if (boardRefusal(data, approvalsConfig())) return { ...data, lapsed: true };
       return data;
     }
   } catch { /* skip — missing or invalid */ }
@@ -246,6 +279,34 @@ function getGitBranch(cwd) {
   return branch;
 }
 
+// A linked worktree's `.git` is a file holding `gitdir: <main>/.git/worktrees/<name>`, so the
+// main checkout is readable without spawning git. Path shape alone would not do: only some
+// worktrees live under `<repo>/.claude/worktrees/`, the rest sit beside the repo.
+// Cached without a TTL, misses included: a directory cannot turn from an ordinary checkout into
+// a linked worktree without being recreated, and a recreated path is a new cache key.
+const worktreeCache = new Map();
+const WORKTREE_CACHE_MAX = 500;
+const GITDIR_WORKTREE_RE = /^gitdir:\s*(.*)[/\\]\.git[/\\]worktrees[/\\]([^/\\]+)[/\\]?$/;
+
+function resolveWorktree(dir) {
+  if (!dir) return null;
+  if (worktreeCache.has(dir)) return worktreeCache.get(dir);
+
+  let worktree = null;
+  try {
+    // An ordinary checkout's `.git` is a directory, so the read throws EISDIR — that is the
+    // answer, and it costs one syscall instead of a stat followed by a read.
+    const m = GITDIR_WORKTREE_RE.exec(readFileSync(path.join(dir, '.git'), 'utf8').trim());
+    if (m) worktree = { repo: m[1], name: m[2] };
+  } catch (_) {}
+
+  worktreeCache.set(dir, worktree);
+  if (worktreeCache.size > WORKTREE_CACHE_MAX) {
+    worktreeCache.delete(worktreeCache.keys().next().value);
+  }
+  return worktree;
+}
+
 // Only spawn git when cwd has diverged from the launch project — that's the
 // only case the JSONL value is wrong. Saves N spawns on a typical list build.
 function resolveSessionGitBranch(meta) {
@@ -1015,12 +1076,30 @@ function getSessionDisplayName(_sessionId, meta) {
   return null;
 }
 
+// The harness spells a project path into a temp/log dir name by replacing every
+// non-alphanumeric character with a dash, drive colon and separators included.
+function encodeProjectDirName(p) {
+  return p.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
 // Derived by convention, not looked up: the harness creates the dir lazily, so a
 // stat here would report "missing" for every session that has not written a temp
 // file yet — and it would put IO on the session-list hot path. Pure string join.
 function getScratchpadDir(id, meta) {
   if (!meta.jsonlPath) return null;
-  return path.join(SCRATCHPAD_ROOT, path.basename(path.dirname(meta.jsonlPath)), id, 'scratchpad');
+  const byProject = path.join(SCRATCHPAD_ROOT, path.basename(path.dirname(meta.jsonlPath)), id, 'scratchpad');
+
+  // A session launched with `claude -w` starts in the main checkout and enters the
+  // worktree afterwards, so the harness keys its scratchpad on the repo while the
+  // transcript ends up filed under the worktree. Neither the project nor any `cwd`
+  // in the log records that, so the two candidates are told apart by which one the
+  // harness actually created. Probed only for worktree sessions, and only until one
+  // of them exists — before that there is nothing to disambiguate and `byProject`,
+  // right for a session started inside the worktree, stands.
+  const wt = resolveWorktree(meta.project);
+  if (!wt || existsSync(byProject)) return byProject;
+  const byRepo = path.join(SCRATCHPAD_ROOT, encodeProjectDirName(wt.repo), id, 'scratchpad');
+  return existsSync(byRepo) ? byRepo : byProject;
 }
 
 function buildSessionObject(id, meta, overrides = {}) {
@@ -1035,6 +1114,7 @@ function buildSessionObject(id, meta, overrides = {}) {
     cwd: meta.cwd || null,
     description: meta.description || null,
     gitBranch: resolveSessionGitBranch(meta),
+    worktree: resolveWorktree(meta.project),
     customTitle: meta.customTitle || null,
     goal: meta.goal || null,
     taskCount: 0,
@@ -1081,7 +1161,9 @@ 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 metadata = loadSessionMetadata();
@@ -1424,8 +1506,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
@@ -1466,8 +1552,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'));
@@ -1543,11 +1631,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 });
@@ -1574,23 +1664,181 @@ 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) {
+  return cachedByFileStat(artifactsByPath, jsonlPath, () => readArtifactLinks(jsonlPath)) || [];
+}
+
+app.get('/api/sessions/:sessionId/artifacts', (req, res) => {
+  try {
+    const metadata = loadSessionMetadata();
+    const meta = metadata[req.params.sessionId] || metadata[resolveSessionId(req.params.sessionId)];
+    if (!meta?.jsonlPath) return res.json({ artifacts: [] });
+    res.json({ artifacts: getArtifactLinks(meta.jsonlPath) });
+  } catch (error) {
+    console.error('Error reading artifacts:', error);
+    res.status(500).json({ error: 'Failed to read artifacts' });
+  }
+});
+
+// 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);
@@ -1624,6 +1872,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]*?)\]/);
@@ -1636,26 +1898,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
@@ -1663,8 +1960,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)));
@@ -1675,6 +1973,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;
@@ -1693,15 +1992,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] || {};
@@ -1720,17 +2017,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 || ''));
@@ -1738,12 +2037,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;
@@ -1766,6 +2060,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 {
@@ -1841,11 +2187,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) {
@@ -2161,9 +2502,8 @@ app.post('/api/sessions/:sessionId/waiting/respond', (req, res) => {
   catch { /* missing or invalid → buildDecision reports 410 */ }
   // The gate stopped polling after waitSeconds — an orphaned decision file would
   // sit unconsumed while the card pretends the click worked.
-  if (marker && isWaitingLapsed(marker)) {
-    return res.status(410).json({ error: 'Ask lapsed — answer it in the terminal' });
-  }
+  const refusal = marker && boardRefusal(marker, approvalsConfig());
+  if (refusal) return res.status(refusal.status).json({ error: refusal.error });
   const result = buildDecision(marker, req.body || {});
   if (result.error) return res.status(result.status).json({ error: result.error });
   try {
@@ -2913,9 +3253,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);
@@ -2930,7 +3330,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');
@@ -2939,22 +3340,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
@@ -2987,7 +3397,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 {
@@ -3104,27 +3517,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' });
   }
@@ -3454,6 +3891,7 @@ 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);
+    migrateLegacyApprovalsConfig();
     const warning = net.exposureWarning();
     if (warning) console.log(warning);