claude-code-kanban 3.2.3 → 3.3.0

package/cli.js

@@ -0,0 +1,458 @@
+const path = require('path');
+
+// Help is auto-generated from this table — keep flags/usage in sync with `run` behavior.
+const COMMANDS = {
+  preview: {
+    summary: 'Open a markdown file in the preview modal on connected browser tabs',
+    usage: 'claude-code-kanban preview <file.md> [--session <id>]',
+    flags: {
+      '--session <id>': 'Switch focused session in the browser (does not link the file)',
+    },
+    run: runPreviewCli,
+  },
+  session: {
+    summary: 'List or open Claude Code sessions',
+    verbs: {
+      list: {
+        summary: 'List sessions',
+        usage: 'claude-code-kanban session list [--active] [--days <n>] [--project <name>] [--limit <n|all>] [--json]',
+        flags: {
+          '--active': 'Only sessions with recent activity (sidebar-style filter)',
+          '--days <n>': 'Only sessions modified within the last N days (fractional ok, e.g. 0.5)',
+          '--project <name>': 'Filter by project name (substring match)',
+          '--limit <n|all>': 'Max rows to display (default: 10). Use "all" for no cap.',
+          '--json': 'Output JSON instead of a table',
+        },
+        run: runSessionListCli,
+      },
+      open: {
+        summary: 'Focus a session in the browser (Active tab)',
+        usage: 'claude-code-kanban session open <id>',
+        flags: {
+          '<id>': 'Full session id, or a unique prefix',
+        },
+        run: runSessionOpenCli,
+      },
+      view: {
+        summary: 'Show full session stats (metadata + context window + cost)',
+        usage: 'claude-code-kanban session view <id> [--json]',
+        flags: {
+          '<id>': 'Full session id, or a unique prefix',
+          '--json': 'Output JSON instead of formatted sections',
+        },
+        run: runSessionViewCli,
+      },
+      peek: {
+        summary: 'Show the last N messages from a session',
+        usage: 'claude-code-kanban session peek <id> [--limit <n>] [--json]',
+        flags: {
+          '<id>': 'Full session id, or a unique prefix',
+          '--limit <n>': 'Number of messages (default: 10, max: 50)',
+          '--json': 'Output JSON instead of formatted lines',
+        },
+        run: runSessionPeekCli,
+      },
+    },
+  },
+};
+
+function runCli(argv) {
+  if (argv.includes('--version') || argv.includes('-v')) {
+    console.log(require('./package.json').version);
+    process.exit(0);
+  }
+  const cli = resolveCliCommand(argv);
+  if (cli.kind === 'server') return false;
+  if (cli.kind === 'help') {
+    if (cli.target && Object.hasOwn(COMMANDS, cli.target)) printNounHelp(cli.target);
+    else printTopHelp();
+    process.exit(0);
+  }
+  if (cli.kind === 'unknown-noun') {
+    console.error(`Unknown command: ${cli.noun}\n`);
+    printTopHelp();
+    process.exit(1);
+  }
+  if (cli.kind === 'unknown-verb') {
+    console.error(`Unknown subcommand: ${cli.noun} ${cli.verb}\n`);
+    printNounHelp(cli.noun);
+    process.exit(1);
+  }
+  if (cli.kind === 'noun') {
+    printNounHelp(cli.noun);
+    process.exit(0);
+  }
+  if (cli.kind === 'leaf') {
+    if (cli.args.includes('--help') || cli.args.includes('-h')) {
+      printLeafHelp(cli.name, cli.entry);
+      process.exit(0);
+    }
+    cli.entry.run(cli.args)
+      .then(code => { process.exitCode = code; })
+      .catch(e => { console.error(e.message); process.exitCode = 1; });
+    return true;
+  }
+  return true;
+}
+
+function resolveCliCommand(argv) {
+  const noun = argv[2] && !argv[2].startsWith('-') ? argv[2] : null;
+  const hasHelp = (a) => a.includes('--help') || a.includes('-h');
+  if (!noun) return hasHelp(argv) ? { kind: 'help' } : { kind: 'server' };
+  if (noun === 'help') return { kind: 'help', target: argv[3] };
+  if (!Object.hasOwn(COMMANDS, noun)) return { kind: 'unknown-noun', noun };
+  const entry = COMMANDS[noun];
+  if (!entry.verbs) return { kind: 'leaf', name: noun, entry, args: argv.slice(3) };
+  const verb = argv[3] && !argv[3].startsWith('-') ? argv[3] : null;
+  if (!verb) return { kind: 'noun', noun };
+  if (!Object.hasOwn(entry.verbs, verb)) return { kind: 'unknown-verb', noun, verb };
+  return { kind: 'leaf', name: `${noun} ${verb}`, entry: entry.verbs[verb], args: argv.slice(4) };
+}
+
+function printTopHelp() {
+  console.log('Usage: claude-code-kanban <command> [args] [--flags]\n');
+  console.log('Commands:');
+  for (const [name, cmd] of Object.entries(COMMANDS)) {
+    console.log(`  ${name.padEnd(20)}${cmd.summary}`);
+    if (cmd.verbs) {
+      for (const [vName, v] of Object.entries(cmd.verbs)) {
+        console.log(`    ${`${name} ${vName}`.padEnd(18)}${v.summary}`);
+      }
+    }
+  }
+  console.log(`  ${'help'.padEnd(20)}Show help for a command (claude-code-kanban help <command>)`);
+  console.log('\nFlags:');
+  console.log('  --help, -h            Show help (top-level, noun-level, or leaf-level)');
+  console.log('  --version, -v         Print version and exit');
+  console.log('\nServer mode (no subcommand):');
+  console.log('  --port <n>            Port to listen on (default 3456)');
+  console.log('  --dir <path>          Override Claude config dir (default ~/.claude)');
+  console.log('  --open                Open browser on start');
+  console.log('  --install, --uninstall    Install or remove the agent-spy hook');
+}
+
+function printNounHelp(noun) {
+  const entry = COMMANDS[noun];
+  console.log(`${entry.summary}\n`);
+  if (entry.verbs) {
+    console.log(`Usage: claude-code-kanban ${noun} <subcommand> [args] [--flags]\n`);
+    console.log('Subcommands:');
+    for (const [vName, v] of Object.entries(entry.verbs)) {
+      console.log(`  ${vName.padEnd(12)}${v.summary}`);
+    }
+    console.log(`\nRun \`claude-code-kanban ${noun} <subcommand> --help\` for details.`);
+  } else {
+    printLeafHelp(noun, entry);
+  }
+}
+
+function printLeafHelp(name, entry) {
+  console.log(`${entry.summary}\n`);
+  console.log(`Usage: ${entry.usage}`);
+  if (entry.flags && Object.keys(entry.flags).length) {
+    const pad = Math.max(...Object.keys(entry.flags).map(f => f.length));
+    console.log('\nFlags:');
+    for (const [flag, desc] of Object.entries(entry.flags)) {
+      console.log(`  ${flag.padEnd(pad + 2)}${desc}`);
+    }
+  }
+  console.log('\n  --help, -h            Show this help');
+}
+
+function getArgValue(args, name) {
+  const idx = args.findIndex(a => a === `--${name}` || a.startsWith(`--${name}=`));
+  if (idx === -1) return null;
+  const arg = args[idx];
+  if (arg.includes('=')) return arg.split('=').slice(1).join('=');
+  return args[idx + 1] && !args[idx + 1].startsWith('--') ? args[idx + 1] : null;
+}
+
+function cliPort() { return process.env.PORT || 3456; }
+function unreachable() { return `Cannot reach cck server on port ${cliPort()}. Start it first with "claude-code-kanban".`; }
+
+class CliUnreachable extends Error { constructor() { super(unreachable()); this.code = 'unreachable'; } }
+
+async function cliFetch(urlPath, init) {
+  try {
+    return await fetch(`http://127.0.0.1:${cliPort()}${urlPath}`, init);
+  } catch (e) {
+    if (e.cause?.code === 'ECONNREFUSED' || /fetch failed/i.test(e.message)) throw new CliUnreachable();
+    throw e;
+  }
+}
+
+function reportCliError(e) {
+  console.error(e.code === 'unreachable' ? e.message : (e.message || String(e)));
+}
+
+async function runPreviewCli(args) {
+  const filePathArg = args.find(a => !a.startsWith('--'));
+  if (!filePathArg) {
+    printLeafHelp('preview', COMMANDS.preview);
+    return 1;
+  }
+  const sessionId = getArgValue(args, 'session') || process.env.PREVIEW_SESSION || null;
+  const abs = path.resolve(filePathArg);
+  try {
+    const res = await cliFetch('/api/preview', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path: abs, sessionId })
+    });
+    if (!res.ok) {
+      console.error(`Preview failed (${res.status}): ${await res.text()}`);
+      return 1;
+    }
+    console.log(`Preview opened: ${abs}${sessionId ? ` (session ${sessionId})` : ''}`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+// Mirror of `isSessionActive` in public/app.js — keep in sync (different runtimes, no shared module).
+function isSessionActive(s) {
+  return s.hasRecentLog || s.inProgress > 0 || s.hasActiveAgents || s.hasWaitingForUser;
+}
+
+function sessionStatus(s) {
+  if (!isSessionActive(s)) return 'idle';
+  if (s.hasWaitingForUser) return 'wait';
+  if (s.inProgress > 0) return 'busy';
+  return 'active';
+}
+
+function parseLimit(args, { fallback, allowAll = false }) {
+  const raw = getArgValue(args, 'limit');
+  if (raw === null) return { ok: true, limit: fallback };
+  if (allowAll && raw === 'all') return { ok: true, limit: null };
+  const n = parseInt(raw, 10);
+  if (Number.isNaN(n) || n <= 0) return { ok: false, error: `Invalid --limit value: ${raw}` };
+  return { ok: true, limit: n };
+}
+
+async function fetchSessionsList(limit) {
+  const q = limit === null ? 'all' : String(limit);
+  const res = await cliFetch(`/api/sessions?limit=${q}`);
+  if (!res.ok) throw new Error(`Failed to fetch sessions (${res.status})`);
+  return res.json();
+}
+
+async function resolveSessionByIdOrPrefix(idArg) {
+  let res;
+  try {
+    res = await cliFetch(`/api/session/resolve?id=${encodeURIComponent(idArg)}`);
+  } catch (e) {
+    reportCliError(e);
+    return null;
+  }
+  if (res.status === 404) {
+    console.error(`No session matches: ${idArg}`);
+    return null;
+  }
+  if (res.status === 409) {
+    const { matches = [] } = await res.json().catch(() => ({}));
+    console.error(`Ambiguous prefix "${idArg}" matches ${matches.length} sessions:`);
+    for (const m of matches.slice(0, 10)) console.error(`  ${m.id}  ${m.customTitle || ''}`);
+    return null;
+  }
+  if (!res.ok) {
+    console.error(`Resolve failed (${res.status}): ${await res.text()}`);
+    return null;
+  }
+  return res.json();
+}
+
+async function runSessionListCli(args) {
+  const activeOnly = args.includes('--active');
+  const projectFilter = getArgValue(args, 'project');
+  const daysArg = getArgValue(args, 'days');
+  const days = daysArg !== null ? parseFloat(daysArg) : null;
+  if (daysArg !== null && (Number.isNaN(days) || days <= 0)) {
+    console.error(`Invalid --days value: ${daysArg}`);
+    return 1;
+  }
+  const parsed = parseLimit(args, { fallback: 10, allowAll: true });
+  if (!parsed.ok) { console.error(parsed.error); return 1; }
+  const limit = parsed.limit;
+  const asJson = args.includes('--json');
+  const hasClientFilter = activeOnly || days !== null || projectFilter;
+  let list;
+  try {
+    list = await fetchSessionsList(hasClientFilter ? null : limit);
+  } catch (e) {
+    reportCliError(e);
+    return 1;
+  }
+  if (activeOnly) list = list.filter(isSessionActive);
+  if (days !== null) {
+    const cutoff = Date.now() - days * 86_400_000;
+    list = list.filter(s => s.modifiedAt && new Date(s.modifiedAt).getTime() >= cutoff);
+  }
+  if (projectFilter) {
+    const needle = projectFilter.toLowerCase();
+    list = list.filter(s => (s.project || '').toLowerCase().includes(needle));
+  }
+  const totalMatched = list.length;
+  if (limit !== null && list.length > limit) list = list.slice(0, limit);
+  if (asJson) {
+    console.log(JSON.stringify(list, null, 2));
+    return 0;
+  }
+  if (!list.length) {
+    console.log('No sessions match.');
+    return 0;
+  }
+  const rows = list.map(s => ({
+    id: s.id.slice(0, 8),
+    status: sessionStatus(s),
+    age: s.modifiedAt ? formatAge(Date.now() - new Date(s.modifiedAt).getTime()) : '-',
+    tasks: `${s.completed}/${s.taskCount}`,
+    project: path.basename(s.project || ''),
+    title: s.customTitle || s.name || s.slug || '',
+  }));
+  const w = {
+    id: 8,
+    status: Math.max(6, ...rows.map(r => r.status.length)),
+    age: Math.max(3, ...rows.map(r => r.age.length)),
+    tasks: Math.max(5, ...rows.map(r => r.tasks.length)),
+    project: Math.max(7, ...rows.map(r => r.project.length)),
+  };
+  console.log(`${'ID'.padEnd(w.id)}  ${'STATUS'.padEnd(w.status)}  ${'AGE'.padEnd(w.age)}  ${'TASKS'.padEnd(w.tasks)}  ${'PROJECT'.padEnd(w.project)}  TITLE`);
+  for (const r of rows) {
+    console.log(`${r.id.padEnd(w.id)}  ${r.status.padEnd(w.status)}  ${r.age.padEnd(w.age)}  ${r.tasks.padEnd(w.tasks)}  ${r.project.padEnd(w.project)}  ${r.title}`);
+  }
+  if (limit !== null && totalMatched > limit) {
+    console.log(`\n... ${totalMatched - limit} more. Use --limit <n> or --limit all to see them.`);
+  }
+  return 0;
+}
+
+function formatAge(ms) {
+  if (ms < 0) return '0s';
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  const d = Math.floor(h / 24);
+  return `${d}d`;
+}
+
+async function runSessionOpenCli(args) {
+  const idArg = args.find(a => !a.startsWith('--'));
+  if (!idArg) {
+    printLeafHelp('session open', COMMANDS.session.verbs.open);
+    return 1;
+  }
+  const resolved = await resolveSessionByIdOrPrefix(idArg);
+  if (!resolved) return 1;
+  try {
+    const res = await cliFetch('/api/session/open', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id: resolved.id })
+    });
+    if (!res.ok) {
+      console.error(`Open failed (${res.status}): ${await res.text()}`);
+      return 1;
+    }
+    console.log(`Session opened: ${resolved.id}${resolved.customTitle ? ` (${resolved.customTitle})` : ''}`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runSessionViewCli(args) {
+  const idArg = args.find(a => !a.startsWith('--'));
+  if (!idArg) {
+    printLeafHelp('session view', COMMANDS.session.verbs.view);
+    return 1;
+  }
+  const asJson = args.includes('--json');
+  const resolved = await resolveSessionByIdOrPrefix(idArg);
+  if (!resolved) return 1;
+  let list;
+  try {
+    list = await fetchSessionsList(null);
+  } catch (e) { reportCliError(e); return 1; }
+  const s = list.find(x => x.id === resolved.id);
+  if (!s) {
+    console.error(`Session ${resolved.id} not found in /api/sessions response.`);
+    return 1;
+  }
+  if (asJson) {
+    console.log(JSON.stringify(s, null, 2));
+    return 0;
+  }
+  const status = sessionStatus(s);
+  const title = s.customTitle || s.name || s.slug || '';
+  const age = s.modifiedAt ? formatAge(Date.now() - new Date(s.modifiedAt).getTime()) : '-';
+  const fmtTok = (n) => typeof n === 'number' ? (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n)) : '-';
+  const fmtCost = (n) => typeof n === 'number' ? `$${n.toFixed(2)}` : '-';
+  const lines = [];
+  lines.push(`${s.id.slice(0, 8)} — ${title} [${status}]`);
+  if (s.project) lines.push(`  ${path.basename(s.project)}${s.gitBranch ? ` · ${s.gitBranch}` : ''} · modified ${age} ago`);
+  lines.push(`  Tasks: ${s.completed}/${s.taskCount}${s.inProgress ? ` (${s.inProgress} in progress)` : ''}${s.pending ? ` · ${s.pending} pending` : ''}`);
+  const ctx = s.contextStatus;
+  if (ctx) {
+    const cw = ctx.context_window || {};
+    const cost = ctx.cost || {};
+    const rl = ctx.rate_limits || {};
+    const modelName = ctx.model?.display_name || ctx.model?.id || '-';
+    const modelExtras = [
+      ctx.effort?.level,
+      ctx.thinking?.enabled ? 'thinking' : null,
+      ctx.fast_mode ? 'fast' : null,
+    ].filter(Boolean).join(' · ');
+    lines.push(`  Model: ${modelName}${modelExtras ? ` (${modelExtras})` : ''}`);
+    if (cw.used_percentage != null) {
+      lines.push(`  Context: ${cw.used_percentage}% used · ${fmtTok(cw.total_input_tokens)} in / ${fmtTok(cw.total_output_tokens)} out · cache ${fmtTok(cw.current_usage?.cache_read_input_tokens)} read`);
+    }
+    lines.push(`  Cost: ${fmtCost(cost.total_cost_usd)} · ${cost.total_api_duration_ms != null ? formatAge(cost.total_api_duration_ms) : '-'} api / ${cost.total_duration_ms != null ? formatAge(cost.total_duration_ms) : '-'} total · +${cost.total_lines_added || 0}/-${cost.total_lines_removed || 0}`);
+    if (rl.five_hour || rl.seven_day) {
+      lines.push(`  Limits: 5h ${rl.five_hour?.used_percentage ?? '-'}% · 7d ${rl.seven_day?.used_percentage ?? '-'}%`);
+    }
+  }
+  console.log(lines.join('\n'));
+  return 0;
+}
+
+async function runSessionPeekCli(args) {
+  const idArg = args.find(a => !a.startsWith('--'));
+  if (!idArg) {
+    printLeafHelp('session peek', COMMANDS.session.verbs.peek);
+    return 1;
+  }
+  const parsed = parseLimit(args, { fallback: 10 });
+  if (!parsed.ok) { console.error(parsed.error); return 1; }
+  const limit = parsed.limit;
+  const asJson = args.includes('--json');
+  const resolved = await resolveSessionByIdOrPrefix(idArg);
+  if (!resolved) return 1;
+  try {
+    const res = await cliFetch(`/api/sessions/${resolved.id}/messages?limit=${Math.min(limit, 50)}`);
+    if (!res.ok) {
+      console.error(`Peek failed (${res.status}): ${await res.text()}`);
+      return 1;
+    }
+    const { messages } = await res.json();
+    const ordered = [...messages].reverse();
+    if (asJson) {
+      console.log(JSON.stringify(ordered, null, 2));
+      return 0;
+    }
+    if (!ordered.length) {
+      console.log(`No messages for session ${resolved.id.slice(0, 8)}.`);
+      return 0;
+    }
+    console.log(`Session ${resolved.id.slice(0, 8)}${resolved.customTitle ? ` — ${resolved.customTitle}` : ''}`);
+    for (const m of ordered) {
+      const ts = m.timestamp ? new Date(m.timestamp).toLocaleTimeString('en-GB', { hour12: false }) : '--:--:--';
+      const label = (m.type === 'tool_use' ? (m.tool || 'tool') : m.type).padEnd(10);
+      const body = (m.text || m.detail || m.description || '').replace(/\s+/g, ' ').trim();
+      console.log(`[${ts}] ${label} ${body.slice(0, 120)}${body.length > 120 ? '…' : ''}`);
+    }
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+module.exports = { runCli };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "3.2.3",
+  "version": "3.3.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
   "bin": {
@@ -44,6 +44,7 @@
   },
   "files": [
     "server.js",
+    "cli.js",
     "install.js",
     "plugin/**/*",
     "lib/**/*",

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

@@ -1,5 +1,5 @@
 {
   "name": "claude-code-kanban",
-  "version": "1.0.1",
+  "version": "1.1.3",
   "description": "Agent activity tracking for claude-code-kanban dashboard"
 }

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

@@ -0,0 +1,52 @@
+---
+name: kanban
+description: Drive the claude-code-kanban browser dashboard from this Claude session. Use this skill when the user mentions "kanban" together with "session" — e.g. "open this session in kanban", "show kanban", "focus current session in kanban", "preview this file in kanban", or asks to peek/view a kanban session.
+compatibility: Requires the `claude-code-kanban` CLI on PATH and the server running locally (default port 3456).
+---
+
+# Kanban Skill
+
+Drive the kanban from this Claude session. Every command corresponds to something the user could do in the kanban dashboard.
+
+The current Claude session id is available as `${CLAUDE_SESSION_ID}` (substituted when this skill loads), so the user never needs to look it up.
+
+NOTE, sometimes user prefers `npx claude-code-kanban` to `claude-code-kanban` — both work, as long as the CLI is available. Use npx as fallback or when user instructed explicitly.
+
+## Open the current session in kanban
+
+Primary use case. Pins the active Claude session in the kanban sidebar and switches to the Active tab.
+
+```bash
+claude-code-kanban session open ${CLAUDE_SESSION_ID}
+```
+
+Trigger phrases: "show this session in kanban", "focus current session", "open in kanban".
+
+## Preview a file in kanban
+
+Opens a markdown file in the preview modal:
+
+```bash
+claude-code-kanban preview <path-to-file.md> --session ${CLAUDE_SESSION_ID}   # prefer this one
+```
+
+Relative paths are fine — the server resolves to absolute.
+
+## Inspect sessions (read-only)
+
+When the user asks "what's going on in kanban?" or wants stats:
+
+```bash
+claude-code-kanban session list --active                            # recent active sessions
+claude-code-kanban session list --project <name>                    # filter by project
+claude-code-kanban session view ${CLAUDE_SESSION_ID}                # full stats for current session
+claude-code-kanban session peek ${CLAUDE_SESSION_ID} --limit 20     # last 20 messages
+```
+
+Add `--json` to any list-style verb for machine-readable output.
+
+## Troubleshooting
+
+- **"Cannot reach cck server on port 3456"** → ask the user to start it: `claude-code-kanban` (or `npm start` in the cck repo).
+- **Different port** → set `PORT=<n>` env var when invoking the CLI.
+- **Ambiguous session prefix (HTTP 409)** → use the full id. With `${CLAUDE_SESSION_ID}` this won't happen.

package/public/app.js

@@ -135,7 +135,11 @@ async function fetchSessions(includeTasks = true) {
     if (revealedPlanSessionId) allPinnedIds.add(revealedPlanSessionId);
     if (revealedStorageSessionId) allPinnedIds.add(revealedStorageSessionId);
     const pinnedParam = allPinnedIds.size > 0 ? `&pinned=${[...allPinnedIds].join(',')}` : '';
-    const sessionsPromise = fetch(`/api/sessions?limit=${sessionLimit}${pinnedParam}`).then((r) => r.json());
+    const projectParam =
+      filterProject && filterProject !== '__recent__' ? `&project=${encodeURIComponent(filterProject)}` : '';
+    const sessionsPromise = fetch(`/api/sessions?limit=${sessionLimit}${pinnedParam}${projectParam}`).then((r) =>
+      r.json(),
+    );
 
     let newSessions, newTasks;
     if (includeTasks) {
@@ -4036,6 +4040,219 @@ document.addEventListener('keydown', (e) => {
 
 //#endregion
 
+//#region MARKDOWN_PREVIEW
+const PREVIEW_STORAGE_PREFIX = 'preview-paths-';
+let currentPreviewPath = null;
+
+function getSessionPreviewPaths(sessionId) {
+  if (!sessionId) return [];
+  try {
+    const raw = localStorage.getItem(PREVIEW_STORAGE_PREFIX + sessionId);
+    const arr = raw ? JSON.parse(raw) : [];
+    return Array.isArray(arr) ? arr : [];
+  } catch {
+    return [];
+  }
+}
+
+function addSessionPreviewPath(sessionId, filePath) {
+  if (!sessionId || !filePath) return;
+  const paths = getSessionPreviewPaths(sessionId).filter((p) => p !== filePath);
+  paths.unshift(filePath);
+  localStorage.setItem(PREVIEW_STORAGE_PREFIX + sessionId, JSON.stringify(paths.slice(0, 20)));
+}
+
+function removeSessionPreviewPath(sessionId, filePath) {
+  if (!sessionId) return;
+  const paths = getSessionPreviewPaths(sessionId).filter((p) => p !== filePath);
+  if (paths.length) localStorage.setItem(PREVIEW_STORAGE_PREFIX + sessionId, JSON.stringify(paths));
+  else localStorage.removeItem(PREVIEW_STORAGE_PREFIX + sessionId);
+}
+
+function splitFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return { fm: null, body: text };
+  const fm = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z0-9_.-]+)\s*:\s*(.*)$/);
+    if (kv) fm[kv[1]] = kv[2].replace(/^['"]|['"]$/g, '');
+  }
+  return { fm, body: m[2] };
+}
+
+function renderFrontmatterBlock(fm) {
+  const rows = Object.entries(fm)
+    .map(
+      ([k, v]) =>
+        `<div class="fm-row"><span class="fm-k">${escapeHtml(k)}</span><span class="fm-v">${escapeHtml(String(v))}</span></div>`,
+    )
+    .join('');
+  return `<details class="preview-fm" open><summary>frontmatter</summary><div class="fm-grid">${rows}</div></details>`;
+}
+
+function openPreviewModal(filePath, content) {
+  currentPreviewPath = filePath;
+  document.getElementById('preview-modal-title').textContent = filePath.split(/[\\/]/).pop();
+  const { fm, body } = /\.(md|markdown)$/i.test(filePath) ? splitFrontmatter(content) : { fm: null, body: content };
+  document.getElementById('preview-modal-body').innerHTML =
+    (fm ? renderFrontmatterBlock(fm) : '') + renderMarkdown(body);
+  document.getElementById('preview-modal-meta').textContent = filePath;
+  document.getElementById('preview-modal').classList.add('visible');
+  updatePreviewLinkBtn();
+}
+
+function isPreviewLinkedToCurrentSession() {
+  if (!currentPreviewPath || !currentSessionId) return false;
+  return getSessionPreviewPaths(currentSessionId).includes(currentPreviewPath);
+}
+
+function updatePreviewLinkBtn() {
+  const btn = document.getElementById('preview-link-btn');
+  if (!btn) return;
+  if (!currentSessionId) {
+    btn.style.display = 'none';
+    return;
+  }
+  btn.style.display = '';
+  const linked = isPreviewLinkedToCurrentSession();
+  btn.title = linked ? 'Unlink from current session' : 'Link to current session';
+  btn.style.color = linked ? 'var(--accent, #5b9a6b)' : '';
+}
+
+// biome-ignore lint/correctness/noUnusedVariables: used in HTML
+function togglePreviewSessionLink() {
+  if (!currentPreviewPath || !currentSessionId) {
+    showToast('Select a session first');
+    return;
+  }
+  if (isPreviewLinkedToCurrentSession()) {
+    removeSessionPreviewPath(currentSessionId, currentPreviewPath);
+    showToast('Unlinked from session');
+  } else {
+    addSessionPreviewPath(currentSessionId, currentPreviewPath);
+    showToast('Linked to session');
+  }
+  updatePreviewLinkBtn();
+  if (_infoModalSessionId === currentSessionId) {
+    refreshInfoModalLinkedDocs();
+  }
+}
+
+function refreshInfoModalLinkedDocs() {
+  const bodyEl = document.getElementById('team-modal-body');
+  if (!bodyEl) return;
+  const existing = bodyEl.querySelector('.linked-docs-section');
+  const html = renderLinkedDocsHtml(_infoModalSessionId);
+  if (!existing) {
+    if (!html) return;
+    const planCard = bodyEl.querySelector('[data-plan-card]');
+    const wrap = document.createElement('div');
+    wrap.innerHTML = html;
+    const node = wrap.firstElementChild;
+    if (planCard?.nextSibling) planCard.parentNode.insertBefore(node, planCard.nextSibling);
+    else bodyEl.appendChild(node);
+    bindLinkedDocsHandlers(node, _infoModalSessionId);
+    return;
+  }
+  if (!html) {
+    existing.remove();
+    return;
+  }
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  const node = wrap.firstElementChild;
+  existing.replaceWith(node);
+  bindLinkedDocsHandlers(node, _infoModalSessionId);
+}
+
+// biome-ignore lint/correctness/noUnusedVariables: used in HTML
+function closePreviewModal() {
+  resetModalFullscreen('preview-modal');
+  currentPreviewPath = null;
+}
+
+// biome-ignore lint/correctness/noUnusedVariables: used in HTML
+function openPreviewInEditor() {
+  if (!currentPreviewPath) return;
+  postAndToast('/api/open-in-editor', { file: currentPreviewPath }, 'in editor');
+}
+
+async function openPreviewByPath(filePath) {
+  if (!filePath) return;
+  try {
+    const r = await fetch(`/api/preview?path=${encodeURIComponent(filePath)}`);
+    if (!r.ok) {
+      showToast('Preview file unavailable');
+      return;
+    }
+    const data = await r.json();
+    openPreviewModal(data.path, data.content);
+  } catch {
+    showToast('Failed to load preview');
+  }
+}
+
+function handleSessionOpenEvent(data) {
+  const { id } = data;
+  if (!id) return;
+  const target = sessions.find((s) => s.id === id);
+  if (!target) {
+    showToast(`Session not found: ${id.slice(0, 8)}`);
+    return;
+  }
+  if (sessionFilter !== 'active') {
+    sessionFilter = 'active';
+    const sel = document.getElementById('session-filter');
+    if (sel) sel.value = 'active';
+    updateUrl();
+  }
+  if (!isSessionActive(target)) {
+    stickySessionIds.add(id);
+  }
+  fetchTasks(id);
+}
+
+function handlePreviewOpenEvent(data) {
+  const { path: filePath, content, sessionId } = data;
+  if (sessionId && sessionId !== currentSessionId) {
+    if (sessions.find((s) => s.id === sessionId)) {
+      fetchTasks(sessionId);
+    } else {
+      showToast(`Preview received for unknown session ${sessionId.slice(0, 8)}`);
+    }
+  }
+  openPreviewModal(filePath, content);
+}
+
+function renderLinkedDocsHtml(sessionId) {
+  const paths = getSessionPreviewPaths(sessionId);
+  if (!paths.length) return '';
+  const items = paths
+    .map((p, i) => {
+      const name = p.split(/[\\/]/).pop();
+      return `<a href="#" class="linked-doc-link" data-idx="${i}" title="${escapeHtml(p)}" style="color:var(--accent-text);text-decoration:underline;text-decoration-style:dotted;text-underline-offset:3px;">${escapeHtml(name)}</a>`;
+    })
+    .join(', ');
+  return `<div class="linked-docs-section" style="margin-bottom:16px;font-size:12px;">
+    <div style="font-size:11px;font-weight:500;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.5px;margin-bottom:6px;">Linked documents</div>
+    <div>${items}</div>
+  </div>`;
+}
+
+function bindLinkedDocsHandlers(container, sessionId) {
+  if (!container) return;
+  const links = container.querySelectorAll('.linked-doc-link');
+  if (!links.length) return;
+  const paths = getSessionPreviewPaths(sessionId);
+  for (const link of links) {
+    link.addEventListener('click', (e) => {
+      e.preventDefault();
+      openPreviewByPath(paths[+link.dataset.idx]);
+    });
+  }
+}
+//#endregion
+
 //#region SSE
 function setupEventSource() {
   let retryDelay = 1000;
@@ -4149,6 +4366,15 @@ function setupEventSource() {
 
       if (data.type === 'context-update') {
         debouncedRefresh(data.sessionId, true);
+        refreshRateLimits();
+      }
+
+      if (data.type === 'preview:open') {
+        handlePreviewOpenEvent(data);
+      }
+
+      if (data.type === 'session:open') {
+        handleSessionOpenEvent(data);
       }
 
       if (data.type === 'team-update') {
@@ -4590,7 +4816,7 @@ document.addEventListener('click', (e) => {
 function filterByProject(project) {
   filterProject = project || null;
   updateUrl();
-  renderSessions();
+  fetchSessions(false);
   showAllTasks();
 }
 
@@ -4936,7 +5162,7 @@ function showInfoModal(session, teamConfig, tasks, planContent) {
     _pendingPlanContent = planContent;
     const titleMatch = planContent.match(/^#\s+(.+)$/m);
     const planTitle = titleMatch ? titleMatch[1].trim() : null;
-    html += `<div onclick="openPlanModal()" style="margin-bottom: 16px; padding: 10px 14px; background: var(--bg-elevated); border: 1px solid var(--border); border-radius: 8px; cursor: pointer; display: flex; align-items: center; gap: 10px; transition: all 0.15s ease;" onmouseover="this.style.borderColor='var(--accent)';this.style.background='var(--bg-hover)'" onmouseout="this.style.borderColor='var(--border)';this.style.background='var(--bg-elevated)'">
+    html += `<div data-plan-card="1" onclick="openPlanModal()" style="margin-bottom: 16px; padding: 10px 14px; background: var(--bg-elevated); border: 1px solid var(--border); border-radius: 8px; cursor: pointer; display: flex; align-items: center; gap: 10px; transition: all 0.15s ease;" onmouseover="this.style.borderColor='var(--accent)';this.style.background='var(--bg-hover)'" onmouseout="this.style.borderColor='var(--border)';this.style.background='var(--bg-elevated)'">
           <span style="font-size: 14px;">📋</span>
           <div style="flex: 1; min-width: 0;">
             <div style="font-size: 11px; font-weight: 500; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.5px;">Plan</div>
@@ -4946,6 +5172,8 @@ function showInfoModal(session, teamConfig, tasks, planContent) {
         </div>`;
   }
 
+  html += renderLinkedDocsHtml(session.id);
+
   // Team info section
   if (teamConfig) {
     const ownerCounts = {};
@@ -5000,6 +5228,7 @@ function showInfoModal(session, teamConfig, tasks, planContent) {
   }
 
   bodyEl.innerHTML = html;
+  bindLinkedDocsHandlers(bodyEl, session.id);
   const alreadyVisible = modal.classList.contains('visible');
   _infoModalSessionId = session.id;
   updateStickyBtnState();
@@ -5298,10 +5527,76 @@ msgContentEl.addEventListener('wheel', function (e) {
   }
 });
 
+const footerState = { version: null, limitsKey: null, timer: null };
+function formatResetIn(epochSec) {
+  if (!epochSec) return null;
+  const ms = epochSec * 1000 - Date.now();
+  if (ms <= 0) return 'now';
+  const m = Math.round(ms / 60000);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  if (h < 24) return rm ? `${h}h ${rm}m` : `${h}h`;
+  const d = Math.floor(h / 24);
+  const rh = h % 24;
+  return rh ? `${d}d ${rh}h` : `${d}d`;
+}
+function makeLimitCell(label, bucket) {
+  const pct = bucket?.used_percentage;
+  const cell = document.createElement('span');
+  cell.className = 'footer-limit-cell';
+  const reset = formatResetIn(bucket?.resets_at);
+  if (reset) cell.title = `${label}: resets in ${reset}`;
+  cell.append(document.createTextNode(`${label} `));
+  const strong = document.createElement('strong');
+  strong.textContent = pct == null ? '-%' : `${Math.ceil(pct)}%`;
+  cell.appendChild(strong);
+  return cell;
+}
+function makeLimitSpan(rl) {
+  const span = document.createElement('span');
+  span.className = 'footer-limits';
+  span.append(makeLimitCell('5h', rl?.five_hour), document.createTextNode(' · '), makeLimitCell('7d', rl?.seven_day));
+  return span;
+}
+function renderSidebarFooter(rateLimits) {
+  const el = document.getElementById('sidebar-footer');
+  if (!el) return;
+  const fh = rateLimits?.five_hour?.used_percentage ?? null;
+  const sd = rateLimits?.seven_day?.used_percentage ?? null;
+  const children = [];
+  if (footerState.version) {
+    const v = document.createElement('span');
+    v.textContent = `v${footerState.version}`;
+    children.push(v);
+  }
+  if (fh != null || sd != null) children.push(makeLimitSpan(rateLimits));
+  el.replaceChildren(...children);
+}
+function refreshRateLimits() {
+  if (footerState.timer) return;
+  footerState.timer = setTimeout(() => {
+    footerState.timer = null;
+    fetch('/api/context-status')
+      .then((r) => r.json())
+      .then((all) => {
+        const rl = Object.values(all || {}).find((e) => e?.rate_limits)?.rate_limits || null;
+        const fh = rl?.five_hour?.used_percentage ?? null;
+        const sd = rl?.seven_day?.used_percentage ?? null;
+        const key = `${fh}|${sd}`;
+        if (key === footerState.limitsKey) return;
+        footerState.limitsKey = key;
+        renderSidebarFooter(rl);
+      })
+      .catch(() => {});
+  }, 1500);
+}
 fetch('/api/version')
   .then((r) => r.json())
   .then((d) => {
-    document.getElementById('sidebar-footer').textContent = `v${d.version}`;
+    footerState.version = d.version;
+    renderSidebarFooter(null);
+    refreshRateLimits();
   })
   .catch(() => {});
 

package/public/index.html

@@ -310,6 +310,33 @@
     </div>
   </div>
 
+  <!-- Markdown Preview Modal -->
+  <div id="preview-modal" class="modal-overlay" style="z-index:10002;" onclick="closePreviewModal()">
+    <div class="modal preview-modal-dialog" onclick="event.stopPropagation()">
+      <div class="modal-header">
+        <h3 class="modal-title" id="preview-modal-title">Preview</h3>
+        <div style="display:flex;gap:4px;align-items:center;">
+          <button id="preview-link-btn" class="icon-btn" aria-label="Link to current session" title="Link to current session" onclick="togglePreviewSessionLink()">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="16" height="16"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>
+          </button>
+          <button class="icon-btn" aria-label="Open in editor" title="Open in editor" onclick="openPreviewInEditor()">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="16" height="16"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
+          </button>
+          <button id="preview-modal-fullscreen-btn" class="icon-btn" aria-label="Toggle fullscreen" title="Toggle fullscreen" onclick="toggleModalFullscreen('preview-modal')">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="16" height="16"><polyline points="15 3 21 3 21 9"/><polyline points="9 21 3 21 3 15"/><line x1="21" y1="3" x2="14" y2="10"/><line x1="3" y1="21" x2="10" y2="14"/></svg>
+          </button>
+          <button class="modal-close" aria-label="Close" onclick="closePreviewModal()">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M18 6L6 18M6 6l12 12"/></svg>
+          </button>
+        </div>
+      </div>
+      <div class="modal-body" style="flex: 0 1 auto; min-height: 0; display: flex; flex-direction: column; overflow: hidden;">
+        <div id="preview-modal-body" class="rendered-md" style="word-break: break-word; font-size: 13px; line-height: 1.6; overflow-y: auto; flex: 0 1 auto; min-height: 0; padding-right: 8px;"></div>
+        <div id="preview-modal-meta" style="margin-top: 12px; font-size: 11px; color: var(--text-muted); flex-shrink: 0;"></div>
+      </div>
+    </div>
+  </div>
+
   <!-- Help Modal -->
   <div id="help-modal" class="modal-overlay" onclick="closeHelpModal()">
     <div class="modal" onclick="event.stopPropagation()">

package/public/style.css

@@ -739,6 +739,10 @@ body::before {
   background-position: top;
   font-size: 10px;
   color: var(--text-muted);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
 }
 
 .sidebar-footer a {
@@ -747,6 +751,11 @@ body::before {
   transition: color 0.15s;
 }
 
+.sidebar-footer .footer-limits strong {
+  color: var(--text-secondary);
+  font-weight: 600;
+}
+
 .sidebar-footer a:hover {
   color: var(--text-secondary);
 }
@@ -2689,6 +2698,68 @@ body.light .msg-assistant .msg-text {
   max-height: 92vh;
 }
 
+.modal.preview-modal-dialog {
+  width: 90vw;
+  max-width: 1200px;
+  max-height: 90vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.modal.preview-modal-dialog.fullscreen {
+  width: 90vw;
+  max-width: 90vw;
+  height: 90vh;
+  max-height: 90vh;
+}
+
+.preview-fm {
+  margin: 0 0 14px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--bg-elevated, rgba(127, 127, 127, 0.06));
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+  font-size: 11px;
+}
+
+.preview-fm > summary {
+  cursor: pointer;
+  padding: 6px 10px;
+  color: var(--text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-size: 10px;
+  user-select: none;
+}
+
+.preview-fm[open] > summary {
+  border-bottom: 1px solid var(--border);
+}
+
+.preview-fm .fm-grid {
+  padding: 8px 10px;
+  display: grid;
+  gap: 4px 12px;
+}
+
+.preview-fm .fm-row {
+  display: grid;
+  grid-template-columns: minmax(80px, 140px) 1fr;
+  gap: 12px;
+  align-items: baseline;
+}
+
+.preview-fm .fm-k {
+  color: var(--accent, #7aa2f7);
+  font-weight: 600;
+}
+
+.preview-fm .fm-v {
+  color: var(--text, inherit);
+  word-break: break-word;
+  white-space: pre-wrap;
+}
+
 .modal-sm {
   max-width: 440px;
 }

package/server.js

@@ -20,14 +20,15 @@ const {
   extractPromptFromTranscript
 } = require('./lib/parsers');
 
-const isSetupCommand = process.argv.includes('--install') || process.argv.includes('--uninstall');
-
-if (isSetupCommand) {
-  const { runInstall, runUninstall } = require('./install');
-  (process.argv.includes('--install') ? runInstall() : runUninstall())
+if (process.argv.includes("--install") || process.argv.includes("--uninstall")) {
+  const { runInstall, runUninstall } = require("./install");
+  (process.argv.includes("--install") ? runInstall() : runUninstall())
     .then(() => process.exit(0))
     .catch(e => { console.error(e.message); process.exit(1); });
+  return;
 }
+if (require("./cli").runCli(process.argv)) return;
+
 
 const app = express();
 const PORT = process.env.PORT || 3456;
@@ -387,9 +388,23 @@ function loadSessionMetadata() {
           resolvedProjectPath = sessionInfo.projectPath;
         }
 
+        const candidateProject = indexProjectPath || sessionInfo.projectPath || null;
+        const existing = metadata[sessionId];
+        // Same sessionId can appear in multiple project dirs (e.g. "shadow"
+        // JSONLs that only hold custom-title/agent-name records when a session
+        // is continued from a worktree). Don't let a weaker entry (no cwd, no
+        // project) overwrite a previously resolved one — just merge scalars.
+        if (existing && existing.project && !candidateProject) {
+          if (!existing.slug && sessionInfo.slug) existing.slug = sessionInfo.slug;
+          if (!existing.customTitle && sessionInfo.customTitle) existing.customTitle = sessionInfo.customTitle;
+          if (!existing.gitBranch && sessionInfo.gitBranch) existing.gitBranch = sessionInfo.gitBranch;
+          sessionIds.push(sessionId);
+          continue;
+        }
+
         metadata[sessionId] = {
           slug: sessionInfo.slug,
-          project: indexProjectPath || sessionInfo.projectPath || null,
+          project: candidateProject,
           cwd: sessionInfo.cwd || null,
           gitBranch: sessionInfo.gitBranch || null,
           customTitle: sessionInfo.customTitle || null,
@@ -777,6 +792,12 @@ app.get('/api/sessions', async (req, res) => {
     let sessions = Array.from(sessionsMap.values());
     sessions.sort((a, b) => new Date(b.modifiedAt) - new Date(a.modifiedAt));
 
+    // Apply project filter before limit so the limit is per-project
+    const projectFilter = req.query.project;
+    if (projectFilter) {
+      sessions = sessions.filter(s => s.project === projectFilter);
+    }
+
     // Apply limit if specified, but always include pinned sessions
     if (limit !== null && limit > 0) {
       const top = sessions.slice(0, limit);
@@ -1289,6 +1310,7 @@ app.get('/api/tasks/all', async (req, res) => {
     }
 
     const metadata = loadSessionMetadata();
+    const { listToSessions } = loadAllTaskMaps();
     const sessionDirs = readdirSync(TASKS_DIR, { withFileTypes: true })
       .filter(d => d.isDirectory());
 
@@ -1299,6 +1321,19 @@ app.get('/api/tasks/all', async (req, res) => {
       const taskFiles = readdirSync(sessionPath).filter(f => f.endsWith('.json'));
       const meta = metadata[sessionDir.name] || {};
 
+      // For custom task list directories (non-UUID dirs), resolve project from the
+      // mapped sessions since those dirs don't have their own metadata entry.
+      let project = meta.project || null;
+      if (!project) {
+        const mappedSessions = listToSessions[sessionDir.name];
+        if (mappedSessions) {
+          for (const [sid, info] of Object.entries(mappedSessions)) {
+            project = metadata[sid]?.project || info.project || null;
+            if (project) break;
+          }
+        }
+      }
+
       for (const file of taskFiles) {
         try {
           const task = JSON.parse(readFileSync(path.join(sessionPath, file), 'utf8'));
@@ -1306,7 +1341,7 @@ app.get('/api/tasks/all', async (req, res) => {
             ...task,
             sessionId: sessionDir.name,
             sessionName: getSessionDisplayName(sessionDir.name, meta),
-            project: meta.project || null
+            project
           });
         } catch (e) {
           // Skip invalid files
@@ -1417,6 +1452,91 @@ 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;
+  }
+  try {
+    return await fs.readFile(absPath, 'utf8');
+  } 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; }
+    throw e;
+  }
+}
+
+function resolvePreviewPath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return null;
+  return path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+}
+
+app.post('/api/preview', async (req, res) => {
+  try {
+    const { path: filePath, sessionId } = req.body || {};
+    const abs = resolvePreviewPath(filePath);
+    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 });
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error in /api/preview:', error);
+    res.status(error.status || 500).json({ error: error.message || 'Preview failed' });
+  }
+});
+
+app.get('/api/session/resolve', (req, res) => {
+  try {
+    const idArg = (req.query.id || '').toString();
+    if (!idArg) return res.status(400).json({ error: 'id is required' });
+    const metadata = loadSessionMetadata();
+    const ids = Object.keys(metadata);
+    if (Object.hasOwn(metadata, idArg)) {
+      const m = metadata[idArg];
+      return res.json({ id: idArg, customTitle: m?.customTitle || null });
+    }
+    const matches = ids.filter(id => id.startsWith(idArg));
+    if (matches.length === 0) return res.status(404).json({ matches: [] });
+    if (matches.length > 1) {
+      return res.status(409).json({
+        matches: matches.slice(0, 50).map(id => ({ id, customTitle: metadata[id]?.customTitle || null }))
+      });
+    }
+    const id = matches[0];
+    res.json({ id, customTitle: metadata[id]?.customTitle || null });
+  } catch (error) {
+    console.error('Error in /api/session/resolve:', error);
+    res.status(500).json({ error: error.message || 'Failed' });
+  }
+});
+
+app.post('/api/session/open', async (req, res) => {
+  try {
+    const { id } = req.body || {};
+    if (!id || typeof id !== 'string') return res.status(400).json({ error: 'id is required' });
+    broadcast({ type: 'session:open', id });
+    res.json({ success: true, id });
+  } catch (error) {
+    console.error('Error in /api/session/open:', error);
+    res.status(500).json({ error: error.message || 'Failed' });
+  }
+});
+
+app.get('/api/preview', async (req, res) => {
+  try {
+    const abs = resolvePreviewPath(req.query.path);
+    if (!abs) return res.status(400).json({ error: 'path is required' });
+    const content = await readMarkdownFile(abs);
+    res.json({ path: abs, content });
+  } catch (error) {
+    console.error('Error in GET /api/preview:', error);
+    res.status(error.status || 500).json({ error: error.message || 'Preview failed' });
+  }
+});
+
 // SSE endpoint for live updates
 app.get('/api/events', (req, res) => {
   res.setHeader('Content-Type', 'text/event-stream');
@@ -1454,9 +1574,6 @@ app.use('/api', (req, res) => {
   res.status(404).json({ error: 'Not found' });
 });
 
-// File watchers and server startup (skip for --install/--uninstall)
-if (!isSetupCommand) {
-
 // Watch for file changes (chokidar handles non-existent paths)
 const watcher = chokidar.watch(TASKS_DIR, {
   persistent: true,
@@ -1705,4 +1822,3 @@ const server = app.listen(PORT, () => {
     }
   });
 
-} // end if (!isSetupCommand)