wavework 0.0.0-stage → 0.1.0

package/templates/dashboard/hooks/session-start.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// SessionStart hook: makes sure the pipeline dashboard server runs and tells the user its URL.
+// Health answers from a live checkout -> silent. Port free -> start server.mjs detached (log in <store>/server.log)
+// and print the URL. Port held by something else, or by a server whose checkout was deleted and is not the
+// recorded one -> one warning. Always exits 0.
+// Time budget (hard kill is the 5 s `timeout` in settings.json), worst case = stale-server replace path:
+//   probe 300 ms + lsof 800 + ps 800 + stop wait 250 + start wait 2000 + probes 150 + node start-up ~100  =  about 4.4 s.
+// Keep the sum under 5 s when changing any of these.
+// Output format: https://code.claude.com/docs/en/hooks.md (systemMessage on stdout JSON; exit 0).
+import { execFile, execFileSync, spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveStoreDir } from '../record.mjs';
+import { resolvePort } from '../lib/settings.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const OWN_SERVER = path.join(HERE, '..', 'server.mjs');
+// Where the dashboard lives in a checkout (wavework init puts it there).
+const DASHBOARD_REL = ['.claude', 'wavework', 'dashboard'];
+const PROBE_MS = 300;        // first health probe
+const LOOP_PROBE_MS = 150;   // probes while waiting for a started server
+// How long a started server gets to answer. The env override is for tests (a near-zero wait forces "gave up waiting").
+const WAIT_MS = Number(process.env.PIPELINE_DASHBOARD_START_WAIT_MS) > 0 ? Number(process.env.PIPELINE_DASHBOARD_START_WAIT_MS) : 2000;
+const EXEC_MS = 800;         // lsof / ps each (a loaded machine can be slow; see the budget above)
+const STOP_WAIT_MS = 250;    // how long a stopped stale server gets to release the port
+const STALE_LOCK_MS = 5000;  // a start lock this old belongs to a crashed hook
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function emit(systemMessage) {
+  process.stdout.write(JSON.stringify({ systemMessage }) + '\n');
+}
+
+const inUse = (port) => `Pipeline dashboard: port ${port} is in use by another process (set dashboard.port in .claude/wavework.json and run wavework update to change it)`;
+const staleInUse = (port) => `Pipeline dashboard: port ${port} is in use by a server from a missing checkout that is not the recorded one; stop it to start the dashboard`;
+const couldNotStart = (logFile) => `Pipeline dashboard: could not start, see ${logFile}`;
+
+/**
+ * Health probe. state: 'ok' (our health answers {"ok":true}), 'free' (connection refused),
+ * 'foreign' (something else answers, or accepts the connection but does not answer in time).
+ * root: the checkout directory the server reports, when it reports one.
+ */
+function probe(port, timeout) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/api/health', timeout, agent: false }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (d) => { body += d; });
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(body);
+          if (res.statusCode === 200 && json.ok === true) {
+            resolve({ state: 'ok', root: typeof json.root === 'string' ? json.root : null });
+            return;
+          }
+        } catch { /* not our health answer */ }
+        resolve({ state: 'foreign', root: null });
+      });
+      res.on('error', () => resolve({ state: 'foreign', root: null }));
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ state: 'foreign', root: null }); });
+    req.on('error', (e) => resolve({ state: e.code === 'ECONNREFUSED' ? 'free' : 'foreign', root: null }));
+  });
+}
+
+const isMissingCheckout = (root) => typeof root === 'string' && !existsSync(root);
+
+
+/** Runs a fixed program with an argument list (no shell). Resolves to stdout, or null when it cannot run or fails. */
+function run(file, args) {
+  return new Promise((resolve) => {
+    execFile(file, args, { encoding: 'utf8', timeout: EXEC_MS }, (err, stdout) => resolve(err ? null : stdout));
+  });
+}
+
+/**
+ * True only when `pid` is the single listener on `port` and its command line is the dashboard server. A pid that is
+ * merely recorded (pids get reused) is not enough. Anything that cannot be checked (no lsof or ps, no listener) counts
+ * as not proven, so nothing is killed.
+ */
+/** True when `command` names `serverFile` as a whole argument (not merely as the tail of a longer path). */
+export function commandNamesServer(command, serverFile) {
+  const escaped = serverFile.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(^|\\s)${escaped}(\\s|$)`).test(command.trim());
+}
+
+async function isDashboardListener(pid, port, serverFile) {
+  const listing = await run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']);
+  if (listing === null) return false;
+  const pids = listing.split('\n').filter(Boolean).map(Number);
+  if (pids.length !== 1 || pids[0] !== pid) return false;
+  const command = await run('ps', ['-p', String(pid), '-o', 'command=']);
+  return command !== null && commandNamesServer(command, serverFile);
+}
+
+/** The main checkout's directory (the common git dir's parent), or null outside git. */
+function mainCheckout() {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      cwd: process.cwd(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return path.dirname(common);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Which server.mjs to run: the main checkout's when it has one, so the long-lived server does not depend on a
+ * worktree that a later /next-task-finish deletes; otherwise the copy this hook belongs to.
+ */
+function serverLocation() {
+  const main = mainCheckout();
+  const mainServer = main ? path.join(main, ...DASHBOARD_REL, 'server.mjs') : null;
+  if (mainServer && existsSync(mainServer)) return { server: mainServer, cwd: main, root: path.dirname(mainServer) };
+  return { server: OWN_SERVER, cwd: process.cwd(), root: path.dirname(OWN_SERVER) };
+}
+
+/** Exclusive create of the start lock. A lock older than STALE_LOCK_MS (crashed hook) is taken over. */
+function acquireLock(lockFile) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      return openSync(lockFile, 'wx');
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      if (!takeOverStaleLock(lockFile)) return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Removes a stale lock without racing other hooks: rename is atomic, so the lock file is moved to a unique name
+ * and only the hook that moved it inspects it. A fresh lock that was moved by mistake is linked back (link does
+ * not overwrite, so a lock someone else created meanwhile is never replaced). Returns true if a stale lock was removed.
+ */
+function takeOverStaleLock(lockFile) {
+  const parked = `${lockFile}.${process.pid}.${randomUUID()}`;
+  try {
+    renameSync(lockFile, parked);
+  } catch {
+    return false; // gone, or moved by another hook
+  }
+  let stale = false;
+  try {
+    stale = Date.now() - statSync(parked).mtimeMs >= STALE_LOCK_MS;
+  } catch { /* unreadable: treat as not ours */ }
+  if (!stale) {
+    try { linkSync(parked, lockFile); } catch { /* someone else created a lock meanwhile */ }
+  }
+  rmSync(parked, { force: true });
+  return stale;
+}
+
+const readRecord = (pidFile) => {
+  try {
+    return JSON.parse(readFileSync(pidFile, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+const isAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+};
+
+/**
+ * Records the pid of a freshly spawned server, unless <store>/server.pid already names a live server on the same
+ * port (then that server stays recorded). Returns true when the record was written.
+ */
+export async function recordSpawnedPid(pidFile, record) {
+  const current = readRecord(pidFile);
+  if (current && current.port === record.port && Number.isInteger(current.pid) && isAlive(current.pid)
+      && (await probe(record.port, LOOP_PROBE_MS)).state === 'ok') {
+    return false;
+  }
+  writeFileSync(pidFile, JSON.stringify(record));
+  return true;
+}
+
+/**
+ * Spawns the detached server and records its pid at once, before any health wait: a server that is still starting
+ * when the hook stops waiting must stay stoppable (the next session or a test cleanup reads this record).
+ */
+async function startServer({ server, cwd, root }, { logFile, pidFile, port }) {
+  const logFd = openSync(logFile, 'a');
+  let child;
+  try {
+    child = spawn(process.execPath, [server], { cwd, env: { ...process.env, PIPELINE_DASHBOARD_PORT: String(port) }, detached: true, stdio: ['ignore', logFd, logFd] });
+  } finally {
+    closeSync(logFd);
+  }
+  const spawned = { child, exited: false, answered: false };
+  if (child.pid) await recordSpawnedPid(pidFile, { pid: child.pid, port, root });
+  // A child that exits clears only its own record, and only if it never answered health: a process that served
+  // is a real server, and its record is not this hook's to drop.
+  const forget = () => {
+    spawned.exited = true;
+    if (spawned.answered) return;
+    if (readRecord(pidFile)?.pid === child.pid) rmSync(pidFile, { force: true });
+  };
+  child.once('exit', forget);
+  child.once('error', forget);
+  child.unref();
+  return spawned;
+}
+
+/** Probes until the server answers ok, the spawned child exits, or WAIT_MS passes. Returns the last probe. */
+async function waitForServer(port, spawned) {
+  const deadline = Date.now() + WAIT_MS;
+  for (;;) {
+    const last = await probe(port, LOOP_PROBE_MS);
+    if (last.state === 'ok') {
+      if (spawned) spawned.answered = true;
+      return { state: 'ok', last };
+    }
+    if (spawned?.exited || Date.now() >= deadline) return { state: 'failed', last };
+    await sleep(100);
+  }
+}
+
+/**
+ * Stops the server recorded in <store>/server.pid, but only when the record matches the answering server exactly
+ * (same port and same checkout root). Returns true once the port is free.
+ */
+async function stopRecordedServer(pidFile, port, root) {
+  const record = readRecord(pidFile);
+  if (!record || record.port !== port || record.root !== root || !Number.isInteger(record.pid) || record.pid < 1) return false;
+  // The command line must name this record's own server file (<root>/server.mjs): another repo's dashboard, or
+  // a developer's own, never matches, so one repo's hook can only ever stop the server it started itself.
+  if (!(await isDashboardListener(record.pid, port, path.join(String(record.root), 'server.mjs')))) return false;
+  try {
+    process.kill(record.pid, 'SIGTERM');
+  } catch {
+    return false;
+  }
+  const deadline = Date.now() + STOP_WAIT_MS;
+  while (Date.now() < deadline) {
+    if ((await probe(port, LOOP_PROBE_MS)).state === 'free') {
+      rmSync(pidFile, { force: true });
+      return true;
+    }
+    await sleep(50);
+  }
+  return false;
+}
+
+async function main() {
+  const port = resolvePort(path.join(HERE, '..'));
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return;
+  const url = `http://127.0.0.1:${port}`;
+
+  const first = await probe(port, PROBE_MS);
+  if (first.state === 'foreign') return emit(inUse(port));
+  if (first.state === 'ok' && !isMissingCheckout(first.root)) return;
+
+  const storeDir = resolveStoreDir({ cwd: process.cwd() });
+  mkdirSync(storeDir, { recursive: true });
+  const pidFile = path.join(storeDir, 'server.pid');
+  const logFile = path.join(storeDir, 'server.log');
+  if (first.state === 'ok') {
+    // Healthy server whose checkout was deleted: replace it, but only the process we recorded for this port and root.
+    if (!(await stopRecordedServer(pidFile, port, first.root))) return emit(staleInUse(port));
+  }
+
+  // Only the session holding the lock spawns; a concurrent session waits for that server instead.
+  const lockFile = path.join(storeDir, 'server.starting');
+  const lock = acquireLock(lockFile);
+  if (lock === null) {
+    const r = await waitForServer(port, null);
+    if (r.state === 'ok') return emit(`Pipeline dashboard: ${url}`);
+    return emit(r.last.state === 'foreign' ? inUse(port) : couldNotStart(logFile));
+  }
+  let r;
+  try {
+    const spawned = await startServer(serverLocation(), { logFile, pidFile, port });
+    r = await waitForServer(port, spawned);
+    if (r.state === 'ok') return emit(`Pipeline dashboard: ${url}`);
+  } finally {
+    closeSync(lock);
+    rmSync(lockFile, { force: true });
+  }
+  emit(r.last.state === 'foreign' ? inUse(port) : couldNotStart(logFile));
+}
+
+// Runs only as the CLI entry (tests import the helpers). Let the process end on its own (no process.exit, so stdout
+// is never cut short); nothing here keeps the loop alive.
+const isEntry = (() => {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isEntry) {
+  main().catch(() => { /* never fail the session */ }).finally(() => { process.exitCode = 0; });
+}

package/templates/dashboard/hooks/subagent-stop.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// SubagentStop hook: appends one `agent` event (duration, tokens, estimated cost) to the active pipeline run.
+// Input (stdin JSON, Claude Code hooks docs): cwd, agent_id, agent_type, agent_transcript_path.
+// Never blocks or fails the session: exit 0 always, nothing on stdout.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findRunByCwd, recordEvent, resolveStoreDir } from '../record.mjs';
+
+const PRICING_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'pricing.json');
+const TOKEN_FIELDS = {
+  input: 'input_tokens', output: 'output_tokens',
+  cacheRead: 'cache_read_input_tokens', cacheWrite: 'cache_creation_input_tokens',
+};
+
+export function loadPricing(file = PRICING_FILE) {
+  try { return JSON.parse(readFileSync(file, 'utf8')).models ?? {}; } catch { return {}; }
+}
+
+const BEAD = /\bbead\b\s*:?\s*([a-z][a-z0-9]*-[a-z0-9]+(?:\.[0-9]+)*)\b/i;
+
+function promptText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map((c) => (typeof c?.text === 'string' ? c.text : '')).join('\n');
+  return '';
+}
+
+const num = (v) => (Number.isFinite(v) && v >= 0 ? v : 0);
+
+/** Parses a sub-agent transcript (JSONL). Bad lines are skipped. Returns the event fields and the transcript cwd. */
+export function summarizeTranscript(text, pricing = loadPricing()) {
+  const messages = new Map(); // message id -> { model, usage } (streamed lines repeat the id: keep the max per field)
+  let first = null;
+  let last = null;
+  let cwd = null;
+  let anon = 0;
+  let bead = null;
+  let seenPrompt = false;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    if (!o || typeof o !== 'object') continue;
+    const t = Date.parse(o.timestamp);
+    if (Number.isFinite(t)) {
+      if (first === null || t < first) first = t;
+      if (last === null || t > last) last = t;
+    }
+    if (!cwd && typeof o.cwd === 'string') cwd = o.cwd;
+    const m = o.message;
+    if (o.type === 'user' && !seenPrompt && m) {
+      seenPrompt = true; // only the first user prompt names the bead
+      bead = BEAD.exec(promptText(m.content))?.[1] ?? null;
+    }
+    if (o.type !== 'assistant' || !m || typeof m.usage !== 'object' || m.usage === null) continue;
+    const id = typeof m.id === 'string' ? m.id : `anon-${anon++}`;
+    const cur = messages.get(id) ?? { model: null, usage: {} };
+    if (typeof m.model === 'string' && m.model && m.model !== '<synthetic>') cur.model = m.model;
+    for (const f of Object.values(TOKEN_FIELDS)) cur.usage[f] = Math.max(num(cur.usage[f]), num(m.usage[f]));
+    messages.set(id, cur);
+  }
+
+  const fields = {};
+  if (first !== null) fields.durationMs = last - first;
+  if (bead) fields.bead = bead;
+  if (messages.size === 0) return { fields, cwd };
+
+  const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  let cost = 0;
+  let priced = true;
+  let model = null;
+  for (const msg of messages.values()) {
+    for (const [k, f] of Object.entries(TOKEN_FIELDS)) totals[k] += msg.usage[f] ?? 0;
+    if (msg.model) model = msg.model;
+    if (Object.values(msg.usage).every((v) => v === 0)) continue; // zero usage costs nothing, whatever its model
+    const p = msg.model ? pricing[msg.model] : null;
+    if (!p) { priced = false; continue; }
+    for (const k of Object.keys(totals)) cost += ((msg.usage[TOKEN_FIELDS[k]] ?? 0) * num(p[k])) / 1e6;
+  }
+  if (model) fields.model = model;
+  Object.assign(fields, {
+    tokensIn: totals.input, tokensOut: totals.output,
+    tokensCacheRead: totals.cacheRead, tokensCacheWrite: totals.cacheWrite,
+  });
+  if (priced) fields.cost = Number(cost.toFixed(6)); // unknown model: no cost field, never 0
+  return { fields, cwd };
+}
+
+/** Handles one hook input. Returns the recorded event or null (no-op). May throw; main() swallows. */
+export function handle(input, { env = process.env, pricing = loadPricing() } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const file = input.agent_transcript_path;
+  if (typeof file !== 'string' || !file) return null;
+  const { fields, cwd: transcriptCwd } = summarizeTranscript(readFileSync(file, 'utf8'), pricing);
+
+  let run = null;
+  let storeDir = null;
+  for (const cwd of [input.cwd, transcriptCwd]) {
+    if (typeof cwd !== 'string' || !cwd) continue;
+    try {
+      storeDir = resolveStoreDir({ cwd, env });
+      run = findRunByCwd(cwd, { storeDir });
+    } catch { run = null; }
+    if (run) break;
+  }
+  if (!run) return null;
+
+  const event = {};
+  if (typeof input.agent_id === 'string' && input.agent_id) event.agentId = input.agent_id;
+  if (typeof input.agent_type === 'string' && input.agent_type) event.agentType = input.agent_type;
+  return recordEvent(storeDir, run.id, 'agent', { ...event, ...fields });
+}
+
+function readStdin() {
+  try { return readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+export function main() {
+  try {
+    handle(JSON.parse(readStdin()));
+  } catch (err) {
+    console.error(`pipeline-subagent-stop: ${err?.message ?? err}`);
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+  process.exitCode = 0;
+}

package/templates/dashboard/lib/ci.mjs

@@ -0,0 +1,52 @@
+// CI status for a pushed SHA via `gh run list --commit <sha>`, cached per SHA (only success is final: failed runs get re-run).
+import { execFile } from 'node:child_process';
+
+const SHA = /^[0-9a-f]{7,40}$/i;
+const BAD = new Set(['failure', 'cancelled', 'timed_out', 'startup_failure', 'action_required', 'stale']);
+
+export function isSha(v) { return typeof v === 'string' && SHA.test(v); }
+
+/** Default gh runner: execFile with an argument list, no shell. Rejects when gh is missing or fails. */
+export function defaultGhRunner(args) {
+  return new Promise((resolve, reject) => {
+    execFile('gh', args, { timeout: 10_000, maxBuffer: 1024 * 1024 }, (err, stdout) => (err ? reject(err) : resolve(stdout)));
+  });
+}
+
+export function summarize(runs) {
+  if (runs.length === 0) return 'none';
+  if (runs.some((r) => r.status !== 'completed')) return 'pending';
+  if (runs.some((r) => BAD.has(r.conclusion))) return 'failure';
+  return 'success';
+}
+
+export function createCiLookup({ ghRunner = defaultGhRunner, refreshMs = 15_000, now = Date.now } = {}) {
+  const cache = new Map(); // sha -> { at, value, inflight }
+
+  async function fetchSha(sha) {
+    try {
+      const out = await ghRunner(['run', 'list', '--commit', sha, '--json', 'status,conclusion,url,name']);
+      const parsed = JSON.parse(out);
+      if (!Array.isArray(parsed)) throw new Error('unexpected gh output');
+      const runs = parsed.map((r) => ({
+        name: String(r.name ?? ''), status: String(r.status ?? ''), conclusion: r.conclusion ? String(r.conclusion) : null, url: String(r.url ?? ''),
+      }));
+      return { sha, state: summarize(runs), runs };
+    } catch {
+      return { sha, state: 'unknown', runs: [] };
+    }
+  }
+
+  /** Returns { sha, state, runs }; state is unknown when gh is missing/fails or the sha is not a plain hex string. */
+  async function lookup(sha) {
+    if (!isSha(sha)) return { sha: sha ?? null, state: 'unknown', runs: [] };
+    const hit = cache.get(sha);
+    const final = hit?.value && (hit.value.state === 'success');
+    if (hit?.inflight) return hit.inflight;
+    if (hit && (final || now() - hit.at < refreshMs)) return hit.value;
+    const inflight = fetchSha(sha).then((value) => { cache.set(sha, { at: now(), value }); return value; });
+    cache.set(sha, { ...(hit ?? { at: 0 }), inflight });
+    return inflight;
+  }
+  return { lookup };
+}

package/templates/dashboard/lib/derive.mjs

@@ -0,0 +1,105 @@
+// Derives the run timeline (steps, children, reviews, tests, totals) from a run's events.
+const AGENT_SUMS = ['durationMs', 'tokensIn', 'tokensOut', 'tokensCacheRead', 'tokensCacheWrite', 'cost'];
+
+const ms = (a, b) => {
+  const d = Date.parse(b) - Date.parse(a);
+  return Number.isFinite(d) ? d : null;
+};
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+
+/**
+ * Sums agent stats. `cost` is null (never 0 or a partial sum) when there are no agents or any agent
+ * lacks a numeric cost (unknown model): an unknown cost must not look like a cheap one.
+ */
+function sumAgents(agents) {
+  const out = { count: agents.length };
+  for (const k of AGENT_SUMS) out[k] = agents.reduce((s, a) => s + num(a[k]), 0);
+  const known = agents.length > 0 && agents.every((a) => typeof a.cost === 'number' && Number.isFinite(a.cost));
+  // Round away binary float noise (0.1 + 0.2).
+  out.cost = known ? Math.round(out.cost * 1e6) / 1e6 : null;
+  return out;
+}
+
+export function deriveTimeline(run, events, now = Date.now()) {
+  const steps = [];
+  const open = new Map(); // step + wave -> stack of open step entries
+  const key = (step, wave) => `${step}\0${wave ?? ''}`;
+  const sha = (e) => (e.sha ? { sha: e.sha } : {});
+  for (const e of events) {
+    if (e.type === 'step-start') {
+      const entry = { step: e.step, wave: e.wave ?? null, start: e.ts, end: null, durationMs: null };
+      steps.push(entry);
+      const k = key(e.step, e.wave);
+      if (!open.has(k)) open.set(k, []);
+      open.get(k).push(entry);
+    } else if (e.type === 'step-end') {
+      let entry = open.get(key(e.step, e.wave))?.pop();
+      if (!entry && e.wave == null) {
+        // End without a wave: close the latest open entry of that step.
+        const stacks = [...open.entries()].filter(([k, v]) => k.startsWith(`${e.step}\0`) && v.length);
+        entry = stacks.length ? stacks[stacks.length - 1][1].pop() : undefined;
+      }
+      if (entry) {
+        entry.end = e.ts;
+        entry.durationMs = ms(entry.start, e.ts);
+        Object.assign(entry, sha(e));
+      } else {
+        steps.push({ step: e.step, wave: e.wave ?? null, start: null, end: e.ts, durationMs: null, ...sha(e) });
+      }
+    }
+  }
+
+  const children = [];
+  const byBead = new Map();
+  for (const e of events) {
+    if (e.type === 'child-start') {
+      const c = {
+        bead: e.bead, model: e.model ?? null, wave: e.wave ?? null, start: e.ts, end: null,
+        durationMs: null, result: null, redBeforeGreen: null,
+      };
+      children.push(c);
+      byBead.set(e.bead, c);
+    } else if (e.type === 'child-end') {
+      let c = byBead.get(e.bead);
+      if (!c) {
+        c = { bead: e.bead, model: e.model ?? null, wave: e.wave ?? null, start: null, end: null, durationMs: null, result: null, redBeforeGreen: null };
+        children.push(c);
+        byBead.set(e.bead, c);
+      }
+      c.end = e.ts;
+      c.durationMs = c.start ? ms(c.start, e.ts) : null;
+      c.result = e.result ?? null;
+      c.redBeforeGreen = e.redBeforeGreen ?? null;
+      if (!c.model && e.model) c.model = e.model;
+    }
+  }
+
+  const agentEvents = events.filter((e) => e.type === 'agent');
+  const perChild = new Map(children.map((c) => [c, []]));
+  for (const a of agentEvents) {
+    let owner = a.bead ? byBead.get(a.bead) : undefined;
+    if (!owner) {
+      // No bead on the event: attribute to the child whose window contains it.
+      owner = children.find((c) => c.start && a.ts >= c.start && (!c.end || a.ts <= c.end));
+    }
+    if (owner) perChild.get(owner).push(a);
+  }
+  for (const c of children) c.agents = sumAgents(perChild.get(c));
+
+  const reviews = events.filter((e) => e.type === 'review')
+    .map((e) => ({ ts: e.ts, round: e.round ?? null, verdict: e.verdict ?? null, mustFix: e.mustFix ?? 0 }));
+  const tests = events.filter((e) => e.type === 'tests')
+    .map((e) => ({ ts: e.ts, scope: e.scope ?? null, passed: e.passed ?? 0, failed: e.failed ?? 0, duration: e.duration ?? null }));
+
+  const all = sumAgents(agentEvents);
+  const end = run?.ended ? Date.parse(run.ended) : now;
+  const start = run?.started ? Date.parse(run.started) : NaN;
+  const totals = {
+    agents: all.count, tokensIn: all.tokensIn, tokensOut: all.tokensOut,
+    tokensCacheRead: all.tokensCacheRead, tokensCacheWrite: all.tokensCacheWrite, cost: all.cost,
+    durationMs: Number.isFinite(start) && Number.isFinite(end) ? end - start : null,
+  };
+
+  const pushed = [...steps].reverse().find((s) => s.step === 'push' && s.sha)?.sha ?? null;
+  return { steps, children, reviews, tests, totals, sha: pushed };
+}

package/templates/dashboard/lib/settings.mjs

@@ -0,0 +1,34 @@
+// Dashboard settings written by `wavework init/update` into ../config.json: { port, tokensFile }.
+// The runtime never reads .claude/wavework.json, so it works in any checkout that has this folder.
+// Without config.json (or with an unreadable one) the defaults apply.
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+
+export const DEFAULT_PORT = 4690;
+
+/** `{ port, tokensFile }` from `<dashboardDir>/config.json`; defaults for anything missing or invalid. */
+export function readSettings(dashboardDir) {
+  let raw = {};
+  try { raw = JSON.parse(readFileSync(path.join(dashboardDir, 'config.json'), 'utf8')); } catch { /* defaults */ }
+  const port = Number.isInteger(raw?.port) && raw.port >= 1024 && raw.port <= 65535 ? raw.port : DEFAULT_PORT;
+  const tokensFile = typeof raw?.tokensFile === 'string' && raw.tokensFile !== '' ? raw.tokensFile : null;
+  return { port, tokensFile };
+}
+
+/** PIPELINE_DASHBOARD_PORT wins over config.json. Port 0 (ephemeral) is only meant for tests. */
+export function resolvePort(dashboardDir, env = process.env) {
+  if (env.PIPELINE_DASHBOARD_PORT !== undefined) return Number(env.PIPELINE_DASHBOARD_PORT);
+  return readSettings(dashboardDir).port;
+}
+
+/** Repo directory name for the UI title: the main checkout (parent of the git common dir), else the checkout root. */
+export function projectName(root) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (common) return path.basename(path.dirname(common));
+  } catch { /* not a git checkout */ }
+  return path.basename(path.resolve(root));
+}

package/templates/dashboard/lib/tokens.mjs

@@ -0,0 +1,21 @@
+// Safe lookup of the project's own tokens CSS (config `dashboard.tokensFile`).
+import { realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Absolute real path of `rel` inside `root`, or null. Refuses anything that is not a plain repo-relative
+ * path (absolute, `..`, `.` or empty segments, backslash, NUL) and anything whose real path (symlinks
+ * resolved, also in parent directories) leaves the real repo root or is not a regular file.
+ */
+export function resolveTokensFile(root, rel) {
+  if (typeof rel !== 'string' || rel === '' || rel.includes('\0') || rel.includes('\\')) return null;
+  if (!rel.endsWith('.css')) return null; // config.json can be edited by hand: the suffix is enforced here too
+  if (rel.startsWith('/') || /^[A-Za-z]:/.test(rel)) return null;
+  if (rel.split('/').some((s) => s === '' || s === '.' || s === '..')) return null;
+  try {
+    const realRoot = realpathSync(root);
+    const real = realpathSync(path.join(realRoot, ...rel.split('/')));
+    if (!real.startsWith(realRoot + path.sep) || !statSync(real).isFile()) return null;
+    return real;
+  } catch { return null; }
+}

package/templates/dashboard/pricing.json

@@ -0,0 +1,11 @@
+{
+  "unit": "USD per million tokens",
+  "source": "claude-api skill model table (cached 2026-10-06) and prompt-caching rules: cache read as listed (Haiku 5.5: 0.1x input), 5-minute cache write 1.25x input",
+  "note": "claude-haiku-5-5 uses the rate card for prompts up to 100K tokens. A model missing here gets no cost.",
+  "models": {
+    "claude-opus-5-5": { "input": 4, "output": 20, "cacheRead": 0.2, "cacheWrite": 5 },
+    "claude-sonnet-5-5": { "input": 2, "output": 10, "cacheRead": 0.2, "cacheWrite": 2.5 },
+    "claude-haiku-5-5": { "input": 0.1, "output": 0.5, "cacheRead": 0.01, "cacheWrite": 0.125 },
+    "claude-fable-5-1": { "input": 10, "output": 50, "cacheRead": 0.25, "cacheWrite": 12.5 }
+  }
+}