claude-code-kanban 4.14.0 → 4.16.0

package/server.js

@@ -20,6 +20,8 @@ const {
   findTerminatedTeammates,
   extractPromptFromTranscript,
   extractModelFromTranscript,
+  extractStructuredResultFromTranscript,
+  extractTranscriptStats,
   readFullToolResult,
   readUserImage,
   readToolResultImage,
@@ -30,7 +32,8 @@ const {
 
 if (process.argv.includes("--install") || process.argv.includes("--uninstall")) {
   const { runInstall, runUninstall } = require("./install");
-  (process.argv.includes("--install") ? runInstall() : runUninstall())
+  const pluginOnly = process.argv.includes("--plugin-only");
+  (process.argv.includes("--install") ? runInstall({ pluginOnly }) : runUninstall())
     .then(() => process.exit(0))
     .catch(e => { console.error(e.message); process.exit(1); });
   return;
@@ -106,6 +109,10 @@ const PERMISSION_TTL_MS = 30 * 60 * 1000;
 const AGENT_TTL_MS = 60 * 60 * 1000;
 const AGENT_STALE_MS = 30 * 60 * 1000; // safety net for crashed sessions
 const SESSION_STALE_MS = 5 * 60 * 1000;
+// Keep an idle session in the active list this long after its last log write, so it
+// doesn't vanish the instant a turn ends. Ungated by registry-idle — visibility only,
+// never the "active" status (which stays accurate via hasRecentLog).
+const SESSION_GRACE_MS = 2 * 60 * 1000;
 const WAITING_RESOLVE_GRACE_MS = 15 * 1000;
 const CTX_CLEANUP_MAX_AGE_MS = 2 * 60 * 60 * 1000;
 const CLEANUP_MAX_AGE_MS = 2 * 24 * 60 * 60 * 1000;
@@ -333,6 +340,13 @@ function hasRecentLogActivity(sessionId, logAge) {
   return logAge <= SESSION_STALE_MS && !isRegistryIdle(sessionId);
 }
 
+// Visibility-only recency: hasRecentLogActivity widened by the post-turn grace
+// window (ungated by registry-idle). Drives whether a session appears in the
+// active list — never the "active" status badges, which stay on hasRecentLog.
+function hasVisibleLogActivity(sessionId, logAge) {
+  return logAge <= SESSION_GRACE_MS || hasRecentLogActivity(sessionId, logAge);
+}
+
 // Given a self-team config, return the live interactive session id that owns it
 // (same cwd, startedAt within the boot window of the team's createdAt), or null.
 function resolveSelfTeamOwner(cfg) {
@@ -351,11 +365,20 @@ function resolveSelfTeamOwner(cfg) {
   return best;
 }
 
-// Attach a team-named task dir's counts to a session card, preferring it over an empty or
-// smaller task dir (a team session can also have a near-empty UUID-named dir). Caller passes
-// the already-computed counts.
+// Attach a team-named task dir's counts to a session card, preferring the most recently written
+// dir (see taskDirBeats — "latest wins"). A resumed session owns several team dirs: a stale
+// prior-boot dir plus the current run's dir; the older "most tasks wins" rule attached the stale
+// dir when it had more tasks than the live one. The incumbent's mtime comes from the path-cached
+// counts (every card.tasksDir was already passed through getTaskCounts by the caller, so this is a
+// cache hit, not disk I/O). Caller passes the already-computed candidate counts.
 function attachTeamTasks(card, teamTaskDir, teamName, counts) {
-  if (!card.tasksDir || counts.taskCount > (card.taskCount || 0)) {
+  let curMtime = -1, curCount = -1;
+  if (card.tasksDir) {
+    const cur = getTaskCounts(card.tasksDir);
+    curMtime = taskDirMtime(cur);
+    curCount = cur.taskCount;
+  }
+  if (taskDirBeats(taskDirMtime(counts), counts.taskCount, curMtime, curCount)) {
     Object.assign(card, {
       taskCount: counts.taskCount,
       completed: counts.completed,
@@ -467,13 +490,14 @@ function getCustomTaskDir(sessionId) {
   // Check team-named task directory (teams store tasks under ~/.claude/tasks/<teamName>/).
   // Match either the recorded leadSessionId, or — for 2.1.x self-teams whose lead is a
   // team-lead agent id — the live interactive session that owns the team (see resolveSelfTeamOwner).
-  // A live session can own several team dirs at once — its own (often empty) self-team plus a
-  // resumed session's dir holding the real tasks — so pick the richest, mirroring attachTeamTasks'
-  // "prefer more tasks" rule. Returning the first match (readdir order) can pick the empty dir,
-  // making the board show 0 tasks while the session card counts the other dir.
+  // A live session can own several team dirs at once: a stale dir from a prior boot of the same
+  // session id, plus the current run's dir (a resume creates a fresh self-team). Pick the most
+  // recently written dir ("latest wins") — the old "most tasks wins" rule picked the stale dir
+  // whenever a completed prior run had accumulated more tasks than the live one. taskCount breaks
+  // ties; empty dirs (no task mtime) lose, so a real dir still beats an empty self-team.
   if (existsSync(TEAMS_DIR)) {
     try {
-      let bestDir = null, bestCount = -1;
+      let bestDir = null, bestMtime = -1, bestCount = -1;
       for (const dir of readdirSync(TEAMS_DIR, { withFileTypes: true })) {
         if (!dir.isDirectory()) continue;
         const cfg = loadTeamConfig(dir.name);
@@ -483,9 +507,11 @@ function getCustomTaskDir(sessionId) {
         if (!owns) continue;
         const teamTaskDir = path.join(TASKS_DIR, dir.name);
         if (!existsSync(teamTaskDir)) continue;
-        const count = getTaskCounts(teamTaskDir).taskCount;
-        if (count > bestCount) {
-          bestCount = count;
+        const counts = getTaskCounts(teamTaskDir);
+        const mtime = taskDirMtime(counts);
+        if (taskDirBeats(mtime, counts.taskCount, bestMtime, bestCount)) {
+          bestMtime = mtime;
+          bestCount = counts.taskCount;
           bestDir = teamTaskDir;
         }
       }
@@ -501,6 +527,11 @@ function getTaskCounts(sessionPath) {
 
   const taskFiles = readdirSync(sessionPath).filter(f => f.endsWith('.json'));
   let completed = 0, inProgress = 0, pending = 0, newestTaskMtime = null;
+  // Directory mtime bumps when task files are added/removed, so it stays fresh even for an
+  // emptied dir (task list closed) that has no files left to date. Task-file mtime alone would
+  // report 0 for such a dir and lose "latest wins" to a stale prior-boot dir.
+  let dirMtime = 0;
+  try { dirMtime = statSync(sessionPath).mtimeMs; } catch (_) {}
 
   for (const file of taskFiles) {
     try {
@@ -518,11 +549,27 @@ function getTaskCounts(sessionPath) {
   }
 
   const taskCount = completed + inProgress + pending;
-  const result = { taskCount, completed, inProgress, pending, newestTaskMtime };
+  const result = { taskCount, completed, inProgress, pending, newestTaskMtime, dirMtime };
   taskCountsCache.set(sessionPath, result);
   return result;
 }
 
+// Last-write recency of a getTaskCounts() result, in ms: the newer of the directory mtime (bumps
+// on add/remove, so it survives an emptied dir) and the newest task-file mtime (bumps on in-place
+// status edits, which don't touch the dir). An emptied current dir thus still ranks by when it was
+// cleared, letting it win "latest wins" over a stale prior-boot dir instead of reporting 0.
+function taskDirMtime(counts) {
+  const fileMtime = counts.newestTaskMtime ? counts.newestTaskMtime.getTime() : 0;
+  return Math.max(counts.dirMtime || 0, fileMtime);
+}
+
+// "Latest wins" ranking for two owned task dirs of the same session: more recently written wins,
+// taskCount breaks ties. Callers seed the incumbent with mtime/count -1 so the first candidate
+// always wins.
+function taskDirBeats(candMtime, candCount, curMtime, curCount) {
+  return candMtime > curMtime || (candMtime === curMtime && candCount > curCount);
+}
+
 function cachedByMtime(cache, cacheKey, filePath, loadFn, fallback) {
   try {
     const cached = cache.get(cacheKey);
@@ -900,6 +947,7 @@ function buildSessionObject(id, meta, overrides = {}) {
     hasRunningAgents: false,
     hasWaitingForUser: false,
     hasRecentLog: hasRecentLogActivity(id, logAge),
+    hasRecentActivity: hasVisibleLogActivity(id, logAge),
     jsonlPath: meta.jsonlPath || null,
     tasksDir: null,
     projectDir: meta.jsonlPath ? path.dirname(meta.jsonlPath) : null,
@@ -958,9 +1006,8 @@ 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)) {
-            const hasRecentLog = hasRecentLogActivity(entry.name, logAge);
             const cheaplyActive = logStat.hasMessages && (
-              hasRecentLog
+              hasVisibleLogActivity(entry.name, logAge)
               || agentStatus.hasActive
               || !!agentStatus.waitingForUser
               || (pending > 0 || inProgress > 0)
@@ -1059,9 +1106,8 @@ app.get('/api/sessions', async (req, res) => {
 
         // Cheap-probe: no tasks here (metadata-only), so active = recent log OR live agent.
         if (activeFilter && !pinnedIds.has(sessionId)) {
-          const hasRecentLog = hasRecentLogActivity(sessionId, logAge);
           const cheaplyActive = logStat.hasMessages && (
-            hasRecentLog || metaAgentStatus.hasActive || !!metaAgentStatus.waitingForUser
+            hasVisibleLogActivity(sessionId, logAge) || metaAgentStatus.hasActive || !!metaAgentStatus.waitingForUser
           );
           if (!cheaplyActive) continue;
         }
@@ -1117,26 +1163,30 @@ app.get('/api/sessions', async (req, res) => {
           if (isAutoSelfTeam(cfg)) {
             // Self-teams are normally noise with an empty team-named task dir. But 2.1.x stores a
             // session's tasks in the self-team list (tasks/session-<id>/), so when it's non-empty
-            // the tasks would be silently orphaned. Recover them (gated on taskCount > 0 to keep
-            // the empty-self-team noise case suppressed): attach to the owning card — the recorded
-            // leadSessionId when it has one, else the live session continuing it (resolved from the
-            // session registry), else a freshly-built fallback lead card.
+            // the tasks would be silently orphaned. Recover them: attach to the owning card — the
+            // recorded leadSessionId when it has one, else the live session continuing it (resolved
+            // from the session registry), else a freshly-built fallback lead card.
             const teamTaskDir = path.join(TASKS_DIR, dir.name);
             if (!existsSync(teamTaskDir)) continue;
             const counts = getTaskCounts(teamTaskDir);
-            if (counts.taskCount === 0) continue;
 
             const ownerCard = sessionsMap.get(leaderId) || sessionsMap.get(resolveSelfTeamOwner(cfg));
             if (ownerCard) {
+              // Attach even when empty: a resumed session's freshly-emptied current dir (task list
+              // closed) must be allowed to win "latest wins" and suppress its stale prior-boot dir,
+              // otherwise the card resurfaces the previous tasks. attachTeamTasks ranks by recency.
               attachTeamTasks(ownerCard, teamTaskDir, dir.name, counts);
             } else {
+              // No owner card to attach to — don't fabricate one for an empty stale self-team
+              // (that is the original noise case the skip suppressed).
+              if (counts.taskCount === 0) continue;
               const meta = metadata[leaderId] || {};
               const logStat = getSessionLogStat(meta);
               const logMtime = logStat.mtime;
               const logAge = logMtime ? Date.now() - logMtime : Infinity;
               const agentDir = path.join(AGENT_ACTIVITY_DIR, leaderId);
               const agentStatus = checkAgentStatus(agentDir, logAge > AGENT_STALE_MS, logMtime, false);
-              const taskMtime = counts.newestTaskMtime ? counts.newestTaskMtime.getTime() : 0;
+              const taskMtime = taskDirMtime(counts);
               const card = buildSessionObject(leaderId, meta, {
                 _logStat: logStat,
                 name: getSessionDisplayName(leaderId, meta) || cfg.name || dir.name,
@@ -1246,7 +1296,7 @@ app.get('/api/sessions', async (req, res) => {
           (!s.sharedTaskList && (s.pending > 0 || s.inProgress > 0))
           || s.hasActiveAgents
           || s.hasWaitingForUser
-          || s.hasRecentLog
+          || s.hasRecentActivity
         );
       for (const [id, s] of sessionsMap) {
         if (pinnedIds.has(id)) continue;
@@ -1411,14 +1461,23 @@ app.get('/api/sessions/:sessionId/loop', (req, res) => {
   }
 });
 
-// API: List workflow scripts for a session
-app.get('/api/sessions/:sessionId/workflows', (req, res) => {
+// 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) => {
   try {
-    const workflows = getWorkflowScripts(req.params.sessionId).map((w) => ({
-      id: w.id,
-      name: w.name,
-      modifiedAt: w.mtimeMs ? new Date(w.mtimeMs).toISOString() : null,
-    }));
+    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,
+        };
+      }),
+    );
     res.json({ workflows });
   } catch (error) {
     console.error('Error listing workflows:', error);
@@ -1440,6 +1499,159 @@ app.get('/api/sessions/:sessionId/workflows/:wfId', async (req, res) => {
   }
 });
 
+// meta.phases and meta.name/description are pure literals per the Workflow tool
+// contract, so pull them by regex rather than executing the untrusted script.
+// name/description take the first match (the meta block is at the top of the file).
+// Pull a quoted string value for `key` out of `src` (matches ', ", or `).
+function matchStr(src, key) {
+  const m = src.match(new RegExp(`${key}\\s*:\\s*(['"\`])([\\s\\S]*?)\\1`));
+  return m ? m[2] : null;
+}
+
+function parseWorkflowMeta(source) {
+  const meta = { name: matchStr(source, 'name'), description: matchStr(source, 'description'), phases: [] };
+  const phasesM = source.match(/phases\s*:\s*\[([\s\S]*?)\]/);
+  if (phasesM) {
+    const re = /\{[\s\S]*?\}/g;
+    let m;
+    while ((m = re.exec(phasesM[1]))) {
+      const title = matchStr(m[0], 'title');
+      if (title) meta.phases.push({ title, detail: matchStr(m[0], 'detail') });
+    }
+  }
+  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.
+function readWorkflowJournal(runDir) {
+  const status = new Map();
+  let content;
+  try { content = readFileSync(path.join(runDir, 'journal.jsonl'), '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 };
+    if (o.type === 'started') e.started = true;
+    else if (o.type === 'result') e.done = true;
+    status.set(o.agentId, e);
+  }
+  return status;
+}
+
+// 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
+// path with no I/O — try that first. Fall back to the session dir from metadata,
+// 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) {
+  const rel = path.join('subagents', 'workflows', wfId);
+  if (scriptPath) {
+    const sessionDir = path.dirname(path.dirname(path.dirname(scriptPath)));
+    const fromScript = path.join(sessionDir, rel);
+    if (existsSync(fromScript)) return fromScript;
+  }
+  if (meta.jsonlPath) {
+    const local = path.join(sessionDirFromMeta(meta), rel);
+    if (existsSync(local)) return local;
+  }
+  try {
+    for (const proj of readdirSync(PROJECTS_DIR, { withFileTypes: true })) {
+      if (!proj.isDirectory()) continue;
+      const projPath = path.join(PROJECTS_DIR, proj.name);
+      let sessDirs;
+      try { sessDirs = readdirSync(projPath, { withFileTypes: true }); } catch { continue; }
+      for (const s of sessDirs) {
+        if (!s.isDirectory()) continue;
+        const cand = path.join(projPath, s.name, rel);
+        if (existsSync(cand)) return cand;
+      }
+    }
+  } catch {}
+  return null;
+}
+
+// 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.
+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 sessionId = resolveSessionId(req.params.sessionId);
+    const meta = loadSessionMetadata()[sessionId] || {};
+    const runDir = resolveWorkflowRunDir(meta, wf.id, wf.path);
+    const journal = runDir ? readWorkflowJournal(runDir) : new Map();
+
+    const agents = [];
+    let stoppedAt = null;
+    if (runDir) {
+      let files = [];
+      try { files = readdirSync(runDir).filter((f) => /^agent-.+\.jsonl$/.test(f)); } catch (_) {}
+      for (const f of files) {
+        const agentId = f.slice('agent-'.length, -'.jsonl'.length);
+        const stats = extractTranscriptStats(path.join(runDir, f)) || {};
+        let type = null;
+        try {
+          type = JSON.parse(readFileSync(path.join(runDir, `agent-${agentId}.meta.json`), 'utf8')).agentType || null;
+        } catch (_) {}
+        const done = journal.get(agentId)?.done;
+        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,
+          model: stats.model || null,
+          outputTokens: stats.outputTokens || 0,
+          durationMs,
+          startedAt: stats.firstTs || null,
+          status: done ? 'done' : 'running',
+        });
+      }
+      agents.sort((a, b) => (a.startedAt || '').localeCompare(b.startedAt || ''));
+    }
+    // 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++;
+    }
+    if (!startedCount) {
+      startedCount = agents.length;
+      doneCount = agents.filter((a) => a.status === 'done').length;
+    }
+
+    res.json({
+      id: wf.id,
+      name: parsed.name || wf.name,
+      description: parsed.description,
+      phases: parsed.phases,
+      agents,
+      startedCount,
+      doneCount,
+      startedAt,
+      stoppedAt,
+    });
+  } catch (error) {
+    console.error('Error building workflow run view:', error);
+    res.status(500).json({ error: 'Failed to build workflow run view' });
+  }
+});
+
 function openInEditor(...targets) {
   const editor = process.env.EDITOR || 'code';
   spawn(editor, ['-n', ...targets], { shell: true, stdio: 'ignore', detached: true }).unref();
@@ -1680,6 +1892,27 @@ app.get('/api/sessions/:sessionId/agents', (req, res) => {
       }
     }
 
+    // Workflow-spawned subagents given a schema end on a forced StructuredOutput
+    // tool call and never emit a text lastMessage — surface that structured result
+    // as the agent's response. Only stopped agents (complete transcript); latch
+    // resultUnavailable so we tail-read at most once per agent. Workflow subagents
+    // are exempt from the latch: the poll that flips them to "stopped" can beat the
+    // transcript's final StructuredOutput line to disk, latching resultUnavailable
+    // against an incomplete transcript — so always re-attempt for them, mirroring
+    // the prompt/name/description reconcile above.
+    const agentsNeedingResult = agents.filter(
+      (a) => !a.lastMessage && !isAgentLive(a) && (!a.resultUnavailable || a.type === 'workflow-subagent'),
+    );
+    if (agentsNeedingResult.length && meta.jsonlPath) {
+      for (const agent of agentsNeedingResult) {
+        let result = null;
+        try { result = extractStructuredResultFromTranscript(subagentJsonlForExtraction(meta, agent.agentId)); } catch (_) {}
+        if (result) agent.lastMessage = result;
+        else agent.resultUnavailable = true;
+        dirty.add(agent);
+      }
+    }
+
     for (const agent of dirty) persistAgent(agentDir, agent);
     const teamColors = {};
     if (teamConfig?.members) {
@@ -2380,23 +2613,52 @@ app.delete('/api/tasks/:sessionId/:taskId', async (req, res) => {
   }
 });
 
-// API: Markdown preview — read file and broadcast to clients
-async function readMarkdownFile(absPath) {
-  const ext = path.extname(absPath).toLowerCase();
-  if (ext !== '.md' && ext !== '.markdown') {
-    const err = new Error('Only .md/.markdown files are allowed');
-    err.status = 400;
-    throw err;
-  }
+// API: File preview — read file and broadcast to clients
+const PREVIEW_KINDS = { '.md': 'markdown', '.markdown': 'markdown', '.html': 'html', '.htm': 'html' };
+// Whole files are pushed into a modal, so anything huge freezes the tab regardless of kind.
+const PREVIEW_MAX_BYTES = 8 * 1024 * 1024;
+
+function previewError(status, message) {
+  const err = new Error(message);
+  err.status = status;
+  return err;
+}
+
+// Existence + kind of a file target, with the HTTP status codes both the preview and
+// the link-a-file endpoints report. `kind` is null for anything the previewer can't
+// render — the caller decides whether that disqualifies the path.
+async function statFileTarget(absPath) {
   try {
-    return await fs.readFile(absPath, 'utf8');
+    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 };
   } catch (e) {
-    if (e.code === 'ENOENT') { const err = new Error('File not found'); err.status = 404; throw err; }
-    if (e.code === 'EISDIR') { const err = new Error('Not a file'); err.status = 400; throw err; }
+    if (e.status) throw e;
+    if (e.code === 'ENOENT') throw previewError(404, 'File not found');
+    if (e.code === 'EISDIR') throw previewError(400, 'Not a file');
     throw e;
   }
 }
 
+// Checks the file is previewable without reading it — 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)`
+    );
+  }
+  return { kind, size };
+}
+
+async function readPreviewFile(absPath) {
+  const { kind } = await validatePreviewFile(absPath);
+  return { content: await fs.readFile(absPath, 'utf8'), kind };
+}
+
 function resolvePreviewPath(filePath, base) {
   if (!filePath || typeof filePath !== 'string') return null;
   if (path.isAbsolute(filePath)) return filePath;
@@ -2418,8 +2680,10 @@ app.post('/api/preview', async (req, res) => {
     const { path: filePath, sessionId, base } = req.body || {};
     const abs = resolvePreviewPath(filePath, base);
     if (!abs) return res.status(400).json({ error: 'path is required' });
-    const content = await readMarkdownFile(abs);
-    broadcast({ type: 'preview:open', path: abs, content, sessionId: sessionId || null });
+    // Validate here so the CLI still gets 400/404, but broadcast the path only —
+    // each tab fetches the document itself instead of it being fanned out over SSE.
+    await validatePreviewFile(abs);
+    broadcast({ type: 'preview:open', path: abs, sessionId: sessionId || null });
     res.json({ success: true });
   } catch (error) {
     console.error('Error in /api/preview:', error);
@@ -2427,6 +2691,24 @@ app.post('/api/preview', async (req, res) => {
   }
 });
 
+// API: Link a file to a session's sidebar docs without opening the preview modal.
+// Not extension-restricted, matching /api/file/resolve — an unpreviewable link just
+// opens in the editor. Unlinking skips the stat so a deleted file can still be removed.
+app.post('/api/document/link', async (req, res) => {
+  try {
+    const { path: filePath, sessionId, unlink } = req.body || {};
+    if (typeof sessionId !== 'string' || !sessionId) return res.status(400).json({ error: 'sessionId is required' });
+    const abs = resolvePreviewPath(filePath);
+    if (!abs) return res.status(400).json({ error: 'path is required' });
+    if (!unlink) await statFileTarget(abs);
+    broadcast({ type: 'document:link', path: abs, sessionId, unlink: !!unlink });
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error in /api/document/link:', error);
+    res.status(error.status || 500).json({ error: error.message || 'Link failed' });
+  }
+});
+
 app.get('/api/session/resolve', (req, res) => {
   try {
     const idArg = (req.query.id || '').toString();
@@ -2499,14 +2781,29 @@ app.get('/api/preview', async (req, res) => {
   try {
     const abs = resolvePreviewPath(req.query.path, req.query.base);
     if (!abs) return res.status(400).json({ error: 'path is required' });
-    const content = await readMarkdownFile(abs);
-    res.json({ path: abs, content });
+    const { content, kind } = await readPreviewFile(abs);
+    res.json({ path: abs, content, kind });
   } catch (error) {
     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/file/resolve', async (req, res) => {
+  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)) });
+  } catch (error) {
+    console.error('Error in GET /api/file/resolve:', error);
+    res.status(error.status || 500).json({ error: error.message || 'Failed to resolve file' });
+  }
+});
+
 // SSE endpoint for live updates
 app.get('/api/events', (req, res) => {
   res.setHeader('Content-Type', 'text/event-stream');