wavework 0.0.0-stage → 0.1.1

package/templates/dashboard/public/default-theme.css

@@ -0,0 +1,86 @@
+/* Neutral default theme: the design tokens app.css uses, light and dark. A project can override any of them
+   with its own tokens CSS (config dashboard.tokensFile), which is loaded after this file as /tokens.css. */
+:root {
+  color-scheme: light dark;
+  --font-sans: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+
+  --text-caption-size: 0.75rem;  --text-caption-leading: 1.3;  --text-caption-tracking: 0.01em;
+  --text-small-size: 0.8125rem;  --text-small-leading: 1.4;
+  --text-body-size: 0.9375rem;   --text-body-leading: 1.5;     --text-body-tracking: 0;
+  --text-title-size: 1.0625rem;  --text-title-leading: 1.3;    --text-title-tracking: -0.01em;
+  --text-heading-size: 1.5rem;   --text-heading-leading: 1.2;  --text-heading-tracking: -0.02em;
+  --weight-medium: 500;
+  --weight-semibold: 600;
+
+  --space-1: 0.25rem; --space-2: 0.5rem; --space-3: 0.75rem; --space-4: 1rem;
+  --space-5: 1.25rem; --space-6: 1.5rem; --space-7: 2rem; --space-8: 3rem;
+  --radius-sm: 0.375rem; --radius-md: 0.625rem; --radius-pill: 999px;
+  --border-width: 1px; --border-width-thick: 2px;
+  --size-dot: 0.5rem;
+  --size-file-col-date: 9rem;
+  --control-height: 2.25rem;
+  --shell-bar-height: 3.25rem;
+  --page-width-wide: 72rem;
+  --content-narrow: 40rem;
+  --focus-offset: 2px;
+  --z-sticky: 10;
+  --safe-left: env(safe-area-inset-left, 0px);
+  --safe-right: env(safe-area-inset-right, 0px);
+  --safe-bottom: env(safe-area-inset-bottom, 0px);
+
+  --duration-press: 80ms;
+  --duration-fast: 160ms;
+  --duration-pulse: 1.6s;
+  --duration-spin-calm: 1.2s;
+  --ease-out: cubic-bezier(0.2, 0.8, 0.2, 1);
+  --press-scale: 0.97;
+  --opacity-ghost: 0.45;
+  --blur-material: blur(16px) saturate(1.4);
+  --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.08);
+
+  --color-bg: #f7f7f8;
+  --color-surface: #ffffff;
+  --color-surface-sunken: #efeff1;
+  --color-surface-hover: #f1f1f3;
+  --color-material: rgb(247 247 248 / 0.8);
+  --color-border: #dcdce0;
+  --color-text: #1b1b1f;
+  --color-text-muted: #5a5a63;
+  --color-text-subtle: #8a8a94;
+  --color-accent: #3b5bdb;
+  --color-accent-hover: #3050c4;
+  --color-accent-soft: #e4e9fb;
+  --color-accent-text: #2f4ac2;
+  --color-on-accent: #ffffff;
+  --color-focus: #3b5bdb;
+  --color-ok: #1f7a3d;   --color-ok-soft: #e1f3e6;   --color-ok-solid: #2e9e55;
+  --color-warn: #8a5a00; --color-warn-soft: #fbefd5; --color-warn-solid: #d9930d;
+  --color-bad: #b3261e;  --color-bad-soft: #fbe4e2;  --color-bad-solid: #d64034;
+  --color-info: #1f5f99; --color-info-soft: #deedfa; --color-info-solid: #2f84cf;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.4);
+    --color-bg: #121214;
+    --color-surface: #1b1b1f;
+    --color-surface-sunken: #161619;
+    --color-surface-hover: #232328;
+    --color-material: rgb(18 18 20 / 0.8);
+    --color-border: #2f2f36;
+    --color-text: #ececf0;
+    --color-text-muted: #a4a4ae;
+    --color-text-subtle: #70707a;
+    --color-accent: #7b93f0;
+    --color-accent-hover: #93a7f5;
+    --color-accent-soft: #232a4a;
+    --color-accent-text: #9db0f6;
+    --color-on-accent: #101018;
+    --color-focus: #7b93f0;
+    --color-ok: #6fcf8f;   --color-ok-soft: #16301f;   --color-ok-solid: #3fb866;
+    --color-warn: #f0bd5a; --color-warn-soft: #3a2c0f; --color-warn-solid: #e0a52c;
+    --color-bad: #f2877f;  --color-bad-soft: #3c1a18;  --color-bad-solid: #e5574b;
+    --color-info: #7ab8ee; --color-info-soft: #162b3e; --color-info-solid: #4a9be0;
+  }
+}

package/templates/dashboard/public/format.mjs

@@ -0,0 +1,138 @@
+// Pure helpers for the dashboard UI (no DOM), unit-tested in test/ui.test.mjs.
+const DASH = '—';
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+
+export function formatDuration(ms) {
+  if (!isNum(ms) || ms < 0) return DASH;
+  if (ms < 1000) return '<1s';
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  return `${Math.floor(m / 60)}h ${m % 60}m`;
+}
+
+/** Cost is an estimate (prefix "~"). Unknown (null) is a dash, never $0.00. */
+export function formatCost(cost) {
+  if (!isNum(cost)) return DASH;
+  if (cost > 0 && cost < 0.005) return '<$0.01';
+  return `~$${cost.toFixed(2)}`;
+}
+
+export function formatTokens(n) {
+  if (!isNum(n)) return DASH;
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1).replace(/\.0$/, '')}k`;
+  return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
+}
+
+/** Sum of all token kinds of an agents/totals object. */
+export function totalTokens(t) {
+  if (!t) return null;
+  return ['tokensIn', 'tokensOut', 'tokensCacheRead', 'tokensCacheWrite'].reduce((s, k) => s + (isNum(t[k]) ? t[k] : 0), 0);
+}
+
+const STATUS = {
+  running: { label: 'Running', tone: 'info' },
+  done: { label: 'Done', tone: 'ok' },
+  blocked: { label: 'Blocked', tone: 'warn' },
+  failed: { label: 'Failed', tone: 'bad' },
+};
+export function statusBadge(status) {
+  return STATUS[status] ?? { label: String(status ?? DASH), tone: 'neutral' };
+}
+
+const CI = {
+  success: { label: 'CI passed', tone: 'ok' },
+  failure: { label: 'CI failed', tone: 'bad' },
+  pending: { label: 'CI running', tone: 'info' },
+  none: { label: 'No CI', tone: 'neutral' },
+  unknown: { label: 'CI unknown', tone: 'neutral' },
+};
+export function ciBadge(ci) {
+  if (!ci) return null;
+  return CI[ci.state] ?? CI.unknown;
+}
+
+/** Returns the url only when it is http(s); anything else (javascript:, data:, relative) is null. */
+export function safeHref(url) {
+  if (typeof url !== 'string') return null;
+  try {
+    const u = new URL(url);
+    return u.protocol === 'http:' || u.protocol === 'https:' ? url : null;
+  } catch { return null; }
+}
+
+/** Running runs first, then newest started first. Returns a new array. */
+export function sortRuns(runs) {
+  const rank = (r) => (r.status === 'running' ? 0 : 1);
+  return [...runs].sort((a, b) => rank(a) - rank(b) || (b.started ?? '').localeCompare(a.started ?? ''));
+}
+
+export function parseRoute(hash) {
+  const m = /^#\/runs\/(.+)$/.exec(hash ?? '');
+  if (!m) return { view: 'list' };
+  try { return { view: 'run', id: decodeURIComponent(m[1]) }; } catch { return { view: 'list' }; }
+}
+
+export function relativeTime(iso, now = Date.now()) {
+  const t = Date.parse(iso ?? '');
+  if (!Number.isFinite(t)) return DASH;
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 30) return 'just now';
+  if (s < 3600) return `${Math.max(1, Math.round(s / 60))}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+/** Latest verdict and highest round per bead, from raw review events that carry a bead (the skill may record only the final round). */
+export function reviewsByBead(events) {
+  const map = new Map();
+  for (const e of events ?? []) {
+    if (e.type !== 'review' || !e.bead) continue;
+    const prev = map.get(e.bead);
+    const round = isNum(e.round) ? e.round : 0;
+    if (!prev || round >= prev.round) map.set(e.bead, { verdict: e.verdict ?? null, round });
+  }
+  return map;
+}
+
+/** Review events (newest first) with their bead, for the reviews table. */
+export function reviewRows(events) {
+  return (events ?? []).filter((e) => e.type === 'review')
+    .map((e) => ({ ts: e.ts, bead: e.bead ?? null, round: e.round ?? null, verdict: e.verdict ?? null, mustFix: e.mustFix ?? 0 }))
+    .reverse();
+}
+
+const RESULT = { committed: 'ok', ok: 'ok', done: 'ok', blocked: 'warn', failed: 'bad', running: 'info' };
+export function resultBadge(result) {
+  if (!result) return null;
+  return { label: String(result), tone: RESULT[result] ?? 'neutral' };
+}
+
+/** Total tokens, or null when no agent was recorded (unknown, not 0). */
+export function tokensOf(totals) {
+  if (!totals || !totals.agents) return null;
+  return totalTokens(totals);
+}
+
+/** Compact start time like "13 Nov, 10:44". */
+export function formatStarted(iso, locale = undefined, timeZone = undefined) {
+  const t = Date.parse(iso ?? '');
+  if (!Number.isFinite(t)) return DASH;
+  const d = new Date(t);
+  const opts = { timeZone };
+  const day = new Intl.DateTimeFormat(locale, { ...opts, day: 'numeric', month: 'short' }).format(d);
+  const time = new Intl.DateTimeFormat(locale, { ...opts, hour: '2-digit', minute: '2-digit', hour12: false }).format(d);
+  return `${day}, ${time}`;
+}
+
+export function stepLabel({ step, wave }) {
+  const name = String(step ?? DASH).replace(/^./, (c) => c.toUpperCase());
+  if (step === 'wave') return wave != null ? `${name} ${wave}` : name;
+  return wave != null ? `${name} · wave ${wave}` : name;
+}
+
+export function findingsOf(events) {
+  return (events ?? []).filter((e) => e.type === 'finding' && e.bead).map((e) => e.bead);
+}

package/templates/dashboard/public/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+  <meta name="color-scheme" content="light dark">
+  <title>Pipeline dashboard</title>
+  <link rel="stylesheet" href="/default-theme.css">
+  <link rel="stylesheet" href="/tokens.css">
+  <link rel="stylesheet" href="/app.css">
+</head>
+<body>
+  <header class="topbar">
+    <a class="brand" href="#/">Pipeline</a>
+    <span class="live" id="live" data-state="connecting" role="status">Connecting</span>
+  </header>
+  <main id="app" class="page"></main>
+  <script type="module" src="/app.js"></script>
+</body>
+</html>

package/templates/dashboard/record.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// Pipeline run recorder: appends events of /next-task* runs to a store shared by all worktrees.
+// CLI: record.mjs <event> [--run <id>] [--key value ...]. Never fails loudly (exit 0 always).
+// Importable: resolveStoreDir, findRunByCwd, recordEvent, readRun, listRuns, EVENT_TYPES.
+import { execFileSync } from 'node:child_process';
+import {
+  appendFileSync, closeSync, mkdirSync, openSync, readdirSync, readFileSync,
+  realpathSync, renameSync, writeFileSync, constants,
+} from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const STORE_ENV = 'WAVEWORK_PIPELINE_STORE';
+export const EVENT_TYPES = [
+  'run-start', 'run-end', 'step-start', 'step-end', 'child-start', 'child-end',
+  'review', 'tests', 'finding', 'agent',
+];
+const RUN_KINDS = ['next-task', 'beads', 'batch'];
+const RUN_STATUSES = ['running', 'done', 'blocked', 'failed'];
+const NUMERIC = new Set([
+  'wave', 'round', 'mustFix', 'passed', 'failed', 'duration', 'durationMs',
+  'tokensIn', 'tokensOut', 'tokensCacheRead', 'tokensCacheWrite', 'cost',
+]);
+const LIST = new Set(['units']);
+export const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** Store directory: $WAVEWORK_PIPELINE_STORE, else <git common dir>/pipeline-runs. Throws if neither works. */
+export function resolveStoreDir({ cwd = process.cwd(), env = process.env } = {}) {
+  if (env[STORE_ENV]) return path.resolve(env[STORE_ENV]);
+  const out = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+    cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+  return path.join(path.resolve(cwd, out), 'pipeline-runs');
+}
+
+function real(p) {
+  try { return realpathSync(p); } catch { return path.resolve(p); }
+}
+
+function within(dir, cwd) {
+  const rel = path.relative(dir, cwd);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+export function readRun(storeDir, id) {
+  if (typeof id !== 'string' || !RUN_ID.test(id)) return null;
+  try { return JSON.parse(readFileSync(path.join(storeDir, id, 'run.json'), 'utf8')); } catch { return null; }
+}
+
+export function listRuns(storeDir) {
+  let names;
+  try { names = readdirSync(storeDir); } catch { return []; }
+  return names.map((n) => readRun(storeDir, n)).filter(Boolean);
+}
+
+/** The running run whose worktree contains cwd (deepest worktree wins), or null. */
+export function findRunByCwd(cwd, { storeDir = resolveStoreDir({ cwd }) } = {}) {
+  const target = real(cwd);
+  let best = null;
+  let bestLen = -1;
+  for (const run of listRuns(storeDir)) {
+    if (run.status !== 'running' || !run.worktree) continue;
+    const wt = real(run.worktree);
+    if (within(wt, target) && wt.length > bestLen) { best = run; bestLen = wt.length; }
+  }
+  return best;
+}
+
+function writeRunJson(storeDir, id, run) {
+  const dir = path.join(storeDir, id);
+  const tmp = path.join(dir, `.run.json.${process.pid}.${Date.now()}.tmp`);
+  writeFileSync(tmp, JSON.stringify(run, null, 2) + '\n');
+  renameSync(tmp, path.join(dir, 'run.json'));
+}
+
+function appendLine(file, obj) {
+  // One write call with O_APPEND: lines from parallel processes do not interleave.
+  const fd = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT, 0o644);
+  try { appendFileSync(fd, JSON.stringify(obj) + '\n'); } finally { closeSync(fd); }
+}
+
+/** Records one event. `fields` are the event's data (without ts/type). Returns the written event. */
+export function recordEvent(storeDir, runId, type, fields = {}, now = new Date()) {
+  if (!EVENT_TYPES.includes(type)) throw new Error(`unknown event type: ${type}`);
+  if (!RUN_ID.test(runId || '')) throw new Error(`invalid run id: ${runId}`);
+  const ts = now.toISOString();
+  mkdirSync(path.join(storeDir, runId), { recursive: true });
+  const event = { ...fields, ts, type, run: runId };
+  appendLine(path.join(storeDir, runId, 'events.jsonl'), event);
+
+  if (type === 'run-start') {
+    const kind = RUN_KINDS.includes(fields.kind) ? fields.kind : 'next-task';
+    writeRunJson(storeDir, runId, {
+      id: runId, kind, units: fields.units ?? [], parent: fields.parent ?? null,
+      branch: fields.branch ?? null, worktree: fields.worktree ?? null,
+      status: 'running', started: ts, ended: null,
+    });
+  } else if (type === 'run-end') {
+    const run = readRun(storeDir, runId) ?? { id: runId, started: null };
+    const status = RUN_STATUSES.includes(fields.status) && fields.status !== 'running' ? fields.status : 'done';
+    writeRunJson(storeDir, runId, { ...run, status, ended: ts });
+  }
+  return event;
+}
+
+/** Parses `--key value` pairs; numeric and list fields are coerced, bare flags become true. */
+export function parseArgs(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const next = args[i + 1];
+    let value = true;
+    if (next !== undefined && !next.startsWith('--')) { value = next; i++; }
+    if (typeof value === 'string') {
+      if (LIST.has(key)) value = value.split(',').map((s) => s.trim()).filter(Boolean);
+      else if (NUMERIC.has(key) && value.trim() !== '' && Number.isFinite(Number(value))) value = Number(value);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/** CLI entry. Returns the exit code, which is always 0. */
+export function main(argv, { cwd = process.cwd(), env = process.env, stderr = console.error } = {}) {
+  try {
+    const [type, ...rest] = argv;
+    if (!type) throw new Error(`usage: record.mjs <${EVENT_TYPES.join('|')}> --run <id> [--key value ...]`);
+    const { run, ...fields } = parseArgs(rest);
+    const storeDir = resolveStoreDir({ cwd, env });
+    let runId = typeof run === 'string' ? run : undefined;
+    if (!runId) runId = findRunByCwd(cwd, { storeDir })?.id;
+    if (!runId) throw new Error('no --run given and no running run for this directory');
+    recordEvent(storeDir, runId, type, fields);
+  } catch (e) {
+    stderr(`pipeline-record: ${e?.message ?? String(e)}`);
+  }
+  return 0;
+}
+
+if (process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.url))) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/templates/dashboard/server.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+// Pipeline dashboard server: JSON API over the run store, SSE live updates, CI status, static UI.
+// Node built-ins only. Binds 127.0.0.1. See README "Server/API".
+import { readFileSync, readdirSync, realpathSync, statSync, watch as fsWatch } from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createCiLookup } from './lib/ci.mjs';
+import { deriveTimeline } from './lib/derive.mjs';
+import { projectName, readSettings, resolvePort } from './lib/settings.mjs';
+import { resolveTokensFile } from './lib/tokens.mjs';
+import { RUN_ID, listRuns, readRun, resolveStoreDir } from './record.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// This folder is <repo>/.claude/wavework/dashboard, so the checkout root is three levels up.
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json; charset=utf-8', '.svg': 'image/svg+xml',
+  '.png': 'image/png', '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.map': 'application/json; charset=utf-8',
+};
+
+function readEvents(storeDir, id) {
+  if (!RUN_ID.test(id)) return [];
+  let text;
+  try { text = readFileSync(path.join(storeDir, id, 'events.jsonl'), 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* partial or corrupt line: skip */ }
+  }
+  return out;
+}
+
+function sendJson(res, status, body) {
+  const data = JSON.stringify(body);
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(data);
+}
+
+function sendText(res, status, type, text) {
+  res.writeHead(status, { 'content-type': type, 'cache-control': 'no-cache' });
+  res.end(text);
+}
+
+function sendFile(res, file) {
+  let data;
+  try { data = readFileSync(file); } catch { return sendJson(res, 404, { error: 'not found' }); }
+  res.writeHead(200, { 'content-type': MIME[path.extname(file).toLowerCase()] ?? 'application/octet-stream', 'cache-control': 'no-cache' });
+  res.end(data);
+}
+
+/** Maps a URL path to a file inside publicDir, or null. Rejects traversal, NULs and symlinks leaving publicDir. */
+function resolvePublic(publicDir, rawPath) {
+  let decoded;
+  try { decoded = decodeURIComponent(rawPath); } catch { return { status: 400 }; }
+  if (decoded.includes('\0') || decoded.includes('\\')) return { status: 400 };
+  const rel = decoded === '/' ? 'index.html' : decoded.replace(/^\/+/, '');
+  if (rel.split('/').includes('..')) return { status: 400 };
+  const base = path.resolve(publicDir);
+  const candidate = path.resolve(base, rel);
+  if (!candidate.startsWith(base + path.sep)) return { status: 400 };
+  try {
+    const realBase = realpathSync(base);
+    const real = realpathSync(candidate);
+    if (!real.startsWith(realBase + path.sep) || !statSync(real).isFile()) return { status: 404 };
+    return { file: real };
+  } catch { return { status: 404 }; }
+}
+
+function snapshot(storeDir) {
+  const snap = new Map();
+  let names;
+  try { names = readdirSync(storeDir); } catch { return snap; }
+  for (const n of names) {
+    if (!RUN_ID.test(n)) continue;
+    const sig = ['run.json', 'events.jsonl'].map((f) => {
+      try { const s = statSync(path.join(storeDir, n, f)); return `${s.mtimeMs}:${s.size}`; } catch { return '-'; }
+    }).join('|');
+    snap.set(n, sig);
+  }
+  return snap;
+}
+
+/**
+ * Calls onChange(runId) when a store file changes. fs.watch (recursive) is only the trigger; the run id comes
+ * from diffing store snapshots, because filename reporting differs per platform. Falls back to polling.
+ */
+function watchStore(storeDir, onChange, { mode = 'auto', pollMs = 1000 } = {}) {
+  let watcher = null;
+  let timer = null;
+  let debounce = null;
+  let closed = false;
+  let prev = snapshot(storeDir);
+  const diff = () => {
+    const next = snapshot(storeDir);
+    for (const [id, sig] of next) if (prev.get(id) !== sig) onChange(id);
+    prev = next;
+  };
+  if (mode !== 'poll') {
+    try {
+      watcher = fsWatch(storeDir, { recursive: true }, () => {
+        clearTimeout(debounce);
+        debounce = setTimeout(diff, 20);
+      });
+      watcher.on('error', () => { watcher?.close(); watcher = null; if (!closed) startPolling(); });
+    } catch { watcher = null; }
+  }
+  function startPolling() {
+    if (timer || closed) return;
+    timer = setInterval(diff, pollMs);
+    timer.unref?.();
+  }
+  if (!watcher) startPolling();
+  return () => {
+    closed = true;
+    watcher?.close();
+    clearTimeout(debounce);
+    if (timer) clearInterval(timer);
+  };
+}
+
+export function createServer({
+  storeDir = resolveStoreDir(), port = resolvePort(HERE),
+  publicDir = path.join(HERE, 'public'),
+  // The project's own tokens CSS: a fixed absolute path, or a function returning it (or null) per request.
+  tokensPath = () => resolveTokensFile(REPO_ROOT, readSettings(HERE).tokensFile),
+  project = projectName(REPO_ROOT),
+  ghRunner, ciRefreshMs = 15_000, watch = 'auto', pollMs = 1000,
+} = {}) {
+  const ci = createCiLookup({ ghRunner, refreshMs: ciRefreshMs });
+  const sse = new Set();
+
+  /** A batch still `running` whose members have all ended is reported as ended (blocked if any member is blocked/failed). */
+  const withBatchStatus = (run, all) => {
+    if (run.status !== 'running') return run;
+    const members = all.filter((r) => r.parent === run.id);
+    if (members.length === 0 || members.some((m) => m.status === 'running')) return run;
+    const bad = members.some((m) => m.status === 'blocked' || m.status === 'failed');
+    const ended = members.map((m) => m.ended).filter(Boolean).sort().pop() ?? null;
+    return { ...run, status: bad ? 'blocked' : 'done', ended };
+  };
+
+  const summary = (run) => {
+    const timeline = deriveTimeline(run, readEvents(storeDir, run.id));
+    return { ...run, totals: timeline.totals };
+  };
+
+  function listSummaries() {
+    const raw = listRuns(storeDir);
+    const all = raw.map((r) => summary(withBatchStatus(r, raw)));
+    const newest = (a, b) => (b.started ?? '').localeCompare(a.started ?? '');
+    const ids = new Set(all.map((r) => r.id));
+    const kids = new Map();
+    const top = [];
+    for (const r of all) {
+      if (r.parent && ids.has(r.parent)) {
+        if (!kids.has(r.parent)) kids.set(r.parent, []);
+        kids.get(r.parent).push(r);
+      } else top.push(r);
+    }
+    return top.sort(newest).map((r) => ({ ...r, children: (kids.get(r.id) ?? []).sort(newest) }));
+  }
+
+  async function runDetail(id) {
+    const stored = readRun(storeDir, id);
+    if (!stored) return null;
+    const run = withBatchStatus(stored, listRuns(storeDir));
+    const events = readEvents(storeDir, id);
+    const timeline = deriveTimeline(run, events);
+    return { run, events, timeline, ci: timeline.sha ? await ci.lookup(timeline.sha) : null };
+  }
+
+  async function handle(req, res) {
+    const host = req.headers.host ?? '';
+    const p = server.address()?.port;
+    if (host !== `127.0.0.1:${p}` && host !== `localhost:${p}`) return sendJson(res, 403, { error: 'forbidden host' });
+    if (req.method !== 'GET' && req.method !== 'HEAD') return sendJson(res, 405, { error: 'method not allowed' });
+    // Raw path on purpose: new URL() would normalize %2e%2e/.. segments before we can reject them.
+    const rawPath = (req.url ?? '/').split('?')[0].split('#')[0];
+
+    // root: the checkout this server runs from, so the SessionStart hook can replace a server whose worktree was deleted.
+    if (rawPath === '/api/health') return sendJson(res, 200, { ok: true, root: HERE });
+    // project: the repo directory name, shown in the UI title.
+    if (rawPath === '/api/info') return sendJson(res, 200, { project });
+    if (rawPath === '/api/runs') return sendJson(res, 200, listSummaries());
+    if (rawPath === '/api/events') {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      res.write(': connected\n\n');
+      sse.add(res);
+      res.on('close', () => sse.delete(res));
+      return undefined;
+    }
+    if (rawPath.startsWith('/api/runs/')) {
+      let id;
+      try { id = decodeURIComponent(rawPath.slice('/api/runs/'.length)); } catch { return sendJson(res, 400, { error: 'invalid run id' }); }
+      if (!RUN_ID.test(id)) return sendJson(res, 400, { error: 'invalid run id' });
+      const detail = await runDetail(id);
+      return detail ? sendJson(res, 200, detail) : sendJson(res, 404, { error: 'run not found' });
+    }
+    if (rawPath.startsWith('/api/')) return sendJson(res, 404, { error: 'not found' });
+    if (rawPath === '/tokens.css') {
+      // Optional project theme, loaded after the default theme. Nothing configured: an empty stylesheet.
+      const file = typeof tokensPath === 'function' ? tokensPath() : tokensPath;
+      if (!file) return sendText(res, 200, 'text/css; charset=utf-8', '/* no project tokens configured */\n');
+      return sendFile(res, file);
+    }
+    const r = resolvePublic(publicDir, rawPath);
+    if (r.file) return sendFile(res, r.file);
+    return sendJson(res, r.status, { error: r.status === 400 ? 'bad request' : 'not found' });
+  }
+
+  const server = http.createServer((req, res) => {
+    handle(req, res).catch(() => { if (!res.headersSent) sendJson(res, 500, { error: 'internal error' }); else res.end(); });
+  });
+  let stopWatch = null;
+  let keepAlive = null;
+
+  return {
+    get port() { return server.address()?.port; },
+    address: () => server.address(),
+    listen() {
+      return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+          server.off('error', reject);
+          stopWatch = watchStore(storeDir, (id) => {
+            for (const res of sse) res.write(`event: run-changed\ndata: ${JSON.stringify({ id })}\n\n`);
+          }, { mode: watch, pollMs });
+          keepAlive = setInterval(() => { for (const res of sse) res.write(': ping\n\n'); }, 25_000);
+          keepAlive.unref();
+          resolve(server.address());
+        });
+      });
+    },
+    close() {
+      return new Promise((resolve) => {
+        stopWatch?.();
+        clearInterval(keepAlive);
+        for (const res of sse) res.end();
+        sse.clear();
+        server.close(() => resolve());
+        server.closeAllConnections?.();
+      });
+    },
+  };
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  const s = createServer();
+  s.listen().then(() => {
+    console.log(`pipeline dashboard: http://127.0.0.1:${s.port}`);
+  }).catch((e) => { console.error(`pipeline dashboard: ${e.message}`); process.exitCode = 1; });
+}

package/templates/dashboard-config.json

@@ -0,0 +1 @@
+{{dashboardConfigJson}}