glassbox-trace 0.3.0 → 0.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "glassbox-trace",
-  "version": "0.3.0",
-  "description": "The flight recorder viewer for Claude Code / Agent SDK sessions: drop a session .jsonl on one HTML file and get a timeline, token and cost burn, and auto-diagnostics. Includes a CLI and a Claude Code Stop hook.",
+  "version": "0.4.1",
+  "description": "Other tools show what happened in a Claude Code session; Glassbox tells you what went wrong. Timeline, token and cost burn, auto-diagnostics with evidence and advice, session compare, live tail, a CLI and a Claude Code Stop hook that feeds the findings back to the agent.",
   "main": "src/trace-core.js",
   "scripts": {
     "test": "node --test test/*.test.mjs",
@@ -29,6 +29,9 @@
   },
   "keywords": [
     "claude-code",
+    "claude-code-log",
+    "compare",
+    "live-tail",
     "claude",
     "agent",
     "agent-sdk",

package/src/cli.mjs

@@ -4,12 +4,16 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
 const require = createRequire(import.meta.url);
 const core = require('./trace-core.js');
-const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+// fileURLToPath, not URL.pathname: on Windows the latter gives "/C:/…" which path.resolve turns into "\C:\…".
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
 export const claudeHome = (env = process.env) => env.GLASSBOX_HOME || path.join(env.HOME || env.USERPROFILE || os.homedir(), '.claude');
-export const decodeProject = (n) => n.replace(/^-/, '/').replace(/-/g, '/');
+// Claude Code encodes the project path with '-' for every separator: "/home/aldo/x" → "-home-aldo-x",
+// and on Windows "C:\Users\aldo" → "C--Users-aldo".
+export const decodeProject = (n) => { const m = n.match(/^([A-Za-z])--(.*)$/); if (m) return m[1] + ':/' + m[2].replace(/-/g, '/'); return n.replace(/^-/, '/').replace(/-/g, '/'); };
 
 export function findSessions(opts = {}) {
   const home = opts.home || claudeHome();
@@ -41,7 +45,7 @@ export function sessionTitle(file) {
 
 // Resolve a user-supplied target: a path to a .jsonl, or a session-id prefix.
 export function resolveTarget(target, opts = {}) {
-  if (!target) { const s = findSessions({ home: opts.home, last: 1 })[0]; if (!s) throw new Error('No sessions found under ' + path.join(opts.home || claudeHome(), 'projects')); return s; }
+  if (!target) { const s = findSessions({ home: opts.home, last: 1 })[0]; if (!s) throw new Error(noSessionsMessage(opts.home)); return s; }
   if (fs.existsSync(target) && fs.statSync(target).isFile()) { const file = path.resolve(target); return { id: path.basename(file).replace(/\.jsonl$/, ''), file, project: null, projectDir: path.dirname(file), size: fs.statSync(file).size, mtime: fs.statSync(file).mtimeMs }; }
   const all = findSessions({ home: opts.home });
   const hits = all.filter((s) => s.id.startsWith(target));
@@ -50,6 +54,11 @@ export function resolveTarget(target, opts = {}) {
   throw new Error(`No session or file matches "${target}"`);
 }
 
+export function noSessionsMessage(home) {
+  const dir = path.join(home || claudeHome(), 'projects');
+  return `No sessions found under ${dir}\n  Run a Claude Code session first — every session writes ${path.join(dir, '<project>', '<session-id>.jsonl')}.\n  Or point at a file:      glassbox open <file.jsonl>   (also check / compare / watch)\n  Or another home:         GLASSBOX_HOME=/path/to/.claude glassbox   (or --home)`;
+}
+
 // Session file + its subagent transcripts, as the {name, text} list the core expects.
 export function loadSessionFiles(s) {
   const files = [{ name: s.id + '.jsonl', text: fs.readFileSync(s.file, 'utf8') }];
@@ -66,7 +75,8 @@ export function embed(files, opts = {}) {
   if (!fs.existsSync(template)) throw new Error('dist/glassbox.html not found — run `npm run build` first');
   const html = fs.readFileSync(template, 'utf8');
   if (!html.includes('/*__EMBED__*/null')) throw new Error('template has no embed marker');
-  return html.replace('/*__EMBED__*/null', () => safe(JSON.stringify(files)));
+  const payload = Array.isArray(files) ? files : { files: files.files, compare: files.compare || null, labels: files.labels || null };
+  return html.replace('/*__EMBED__*/null', () => safe(JSON.stringify(payload)));
 }
 
 export function openInBrowser(file, env = process.env) {
@@ -86,8 +96,9 @@ export function checkReport({ trace, findings, cost }, opts = {}) {
   const T = trace.totals, m = trace.meta;
   const fmt = core.fmtDur, fi = core.fmtInt;
   const usd = (v) => v == null ? '—' : '$' + (v < 1 ? v.toFixed(3) : v.toFixed(2));
-  const summary = { session: m.sessionId, title: m.title || null, model: m.models, wallMs: T.wallMs, activeMs: T.activeMs, turns: T.turns, requests: T.requests, toolCalls: T.toolCalls, toolErrors: T.toolErrors, orphans: T.orphans, usage: T.usage, cacheHitRatio: T.cacheHitRatio, cost: cost.reported != null ? cost.reported : cost.total, costSource: cost.source };
-  const json = { summary, findings: findings.map((f) => ({ id: f.id, severity: f.severity, title: f.title, detail: f.detail, metric: f.metric })), failOn, failed: failing.length > 0 };
+  const redact = !!opts.redact;
+  const summary = { session: m.sessionId, title: m.title ? (redact ? '«' + m.title.length + ' chars»' : m.title) : null, model: m.models, wallMs: T.wallMs, activeMs: T.activeMs, turns: T.turns, requests: T.requests, toolCalls: T.toolCalls, toolErrors: T.toolErrors, orphans: T.orphans, usage: T.usage, cacheHitRatio: T.cacheHitRatio, cost: cost.reported != null ? cost.reported : cost.total, costSource: cost.source };
+  const json = { glassbox: core.VERSION, schema: 1, redacted: redact, summary, findings: findings.map((f) => ({ id: f.id, severity: f.severity, title: f.title, detail: redact ? core.redactDetail(f) : f.detail, metric: f.metric, evidence: f.evidence })), failOn, failed: failing.length > 0 };
   const lines = [];
   lines.push(`Glassbox · ${m.sessionId ? m.sessionId.slice(0, 8) : 'session'} · ${m.models.join(', ') || 'unknown model'}`);
   lines.push(`  wall ${fmt(T.wallMs)} (active ${fmt(T.activeMs)}) · ${T.turns} turns · ${T.requests} requests · ${T.toolCalls} tool calls (${T.toolErrors} failed${T.orphans ? ', ' + T.orphans + ' unanswered' : ''})`);
@@ -95,9 +106,10 @@ export function checkReport({ trace, findings, cost }, opts = {}) {
   lines.push('');
   if (!findings.length) lines.push('  no findings');
   for (const f of findings) lines.push(`  ${f.severity.toUpperCase().padEnd(5)} ${f.id.padEnd(16)} ${f.title}`);
+  if (redact) lines.push('', '  (redacted: prompt text, tool inputs and result text blanked)');
   lines.push('');
   lines.push(failing.length ? `  FAIL: ${failing.length} finding${failing.length > 1 ? 's' : ''} at or above "${failOn}"` : `  OK: nothing at or above "${failOn}"`);
-  const md = ['# Glassbox report', '', `- session: ${m.sessionId || '—'} · model: ${m.models.join(', ') || '—'}`, `- wall ${fmt(T.wallMs)} (active ${fmt(T.activeMs)}) · ${T.turns} turns · ${T.requests} requests · ${T.toolCalls} tool calls (${T.toolErrors} failed)`, `- context served ${fi(T.usage.input + T.usage.cacheRead + T.usage.cacheWrite)} · output ${fi(T.usage.output)} · est. cost ${usd(summary.cost)}`, '', `## Findings (${findings.length})`, '', ...(findings.length ? findings.map((f) => `- **${f.severity.toUpperCase()}** \`${f.id}\` — ${f.title}\n  ${f.detail}`) : ['Nothing flagged.']), ''].join('\n');
+  const md = core.reportMarkdown(trace, findings, cost, { redact, maxEvidence: opts.maxEvidence });
   return { text: lines.join('\n'), json, markdown: md, failed: failing.length > 0 };
 }
 
@@ -130,7 +142,7 @@ export function hookResponse(input, opts = {}) {
   // Feedback loop: only on Stop, only once (stop_hook_active guards against loops), only when something is worth saying.
   if (feedback && input.hook_event_name === 'Stop' && !input.stop_hook_active && top.length) {
     out.decision = 'block';
-    out.reason = `Glassbox read this session's flight recorder. ${head}\n\nFindings at or above "${failOn}":\n` + top.map((f) => `- ${f.severity.toUpperCase()} \`${f.id}\` — ${f.title}. ${f.detail}`).join('\n') + `\n\nIn one or two sentences, tell the user what you would do differently next session (no need to redo work), then stop.`;
+    out.reason = `Glassbox read this session's flight recorder (${head}).\n\n` + core.reportMarkdown(res.trace, top, null, { maxEvidence: 3, instruction: false, title: 'this session' }).replace(/^# [^\n]*\n\n/, '').replace(/\n## Tools[\s\S]*?(?=\n_Generated)/, '\n').replace(/\n_Generated[^\n]*\n?$/, '') + `\nIn one or two sentences, tell the user what you would do differently next session (no need to redo work), then stop.`;
   }
   return out;
 }
@@ -175,21 +187,27 @@ export function parseArgs(argv) {
   const args = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a.startsWith('--')) { const [k, v] = a.slice(2).split('='); if (v !== undefined) args.flags[k] = v; else if (i + 1 < argv.length && !argv[i + 1].startsWith('-') && ['last', 'grep', 'project', 'out', 'fail-on', 'home', 'command', 'events'].includes(k)) args.flags[k] = argv[++i]; else args.flags[k] = true; }
+    if (a.startsWith('--')) { const [k, v] = a.slice(2).split('='); if (v !== undefined) args.flags[k] = v; else if (i + 1 < argv.length && !argv[i + 1].startsWith('-') && ['last', 'grep', 'project', 'out', 'fail-on', 'home', 'command', 'events', 'format', 'label-a', 'label-b', 'port'].includes(k)) args.flags[k] = argv[++i]; else args.flags[k] = true; }
     else args._.push(a);
   }
   return args;
 }
 
-export const HELP = `glassbox — the flight recorder viewer for Claude Code sessions
+export const HELP = `glassbox — other tools show you what happened in a Claude Code session; Glassbox tells you what went wrong
 
   glassbox                       open the newest session in your browser
   glassbox list [--last N] [--grep TEXT] [--project PATH]
                                  list sessions, newest first
   glassbox open [ID|FILE] [--out FILE.html] [--no-open]
                                  build a self-contained HTML for a session (id prefix or .jsonl path)
-  glassbox check [ID|FILE] [--fail-on error|warn|info] [--json] [--markdown]
-                                 print findings; exit 1 when any finding is at/above --fail-on (default: error)
+  glassbox check [ID|FILE] [--fail-on error|warn|info] [--format text|json|md] [--redact]
+                                 print findings; exit 1 when any finding is at/above --fail-on (default: error), 2 on a usage error
+                                 --format md is written to be pasted back to the agent: evidence + advice per finding
+                                 --redact blanks prompt text, tool inputs and result text so the report can be shared
+  glassbox compare A B [--format text|json|md] [--out FILE.html] [--label-a NAME --label-b NAME]
+                                 same task, two sessions: what changed in time, tokens, cost, tools and findings
+  glassbox watch [ID|FILE] [--port N] [--no-open]
+                                 live tail: serves the viewer on 127.0.0.1 and pushes the transcript as it grows
   glassbox hook install [--feedback] [--fail-on warn]
                                  add a Claude Code Stop hook so every session ends with a Glassbox summary;
                                  --feedback also hands the findings back to the agent once, so it can learn from them
@@ -202,6 +220,29 @@ export const HELP = `glassbox — the flight recorder viewer for Claude Code ses
 
 Nothing leaves your machine. Subagent transcripts next to the session are included automatically.`;
 
+export function outputFormat(flags) {
+  const f = flags.format ? String(flags.format).toLowerCase() : (flags.json ? 'json' : flags.markdown ? 'md' : 'text');
+  if (f === 'markdown') return 'md';
+  if (!['text', 'json', 'md'].includes(f)) throw new Error(`--format must be text, json or md (got "${f}")`);
+  return f;
+}
+
+export function compareReport(A, B, opts = {}) {
+  const c = core.compare(A, B);
+  const la = opts.labelA || (A.trace.meta.sessionId || 'A').slice(0, 8), lb = opts.labelB || (B.trace.meta.sessionId || 'B').slice(0, 8);
+  const who = (x) => x === 'a' ? la : x === 'b' ? lb : 'tie';
+  const lines = [`Glassbox compare · ${la} vs ${lb}`, `  cheaper: ${who(c.verdict.cheaper)} · faster: ${who(c.verdict.faster)} · cleaner: ${who(c.verdict.cleaner)}`, ''];
+  const w = Math.max(la.length, lb.length, 10);
+  lines.push('  ' + 'metric'.padEnd(22) + la.padStart(w) + '  ' + lb.padStart(w) + '  change');
+  for (const m of c.metrics) { const ch = core.fmtChange(m); lines.push('  ' + m.label.padEnd(22) + m.aText.padStart(w) + '  ' + m.bText.padStart(w) + '  ' + ch + (m.better ? ' (' + who(m.better) + ')' : '')); }
+  lines.push('');
+  const fl = (list, label) => { if (!list.length) return; lines.push(`  only in ${label}:`); for (const f of list) lines.push(`    ${f.severity.toUpperCase().padEnd(5)} ${f.id.padEnd(16)} ${f.title}`); };
+  fl(c.findings.onlyA, la); fl(c.findings.onlyB, lb);
+  if (c.findings.both.length) lines.push(`  in both: ${c.findings.both.map((f) => f.id).join(', ')}`);
+  if (!c.findings.onlyA.length && !c.findings.onlyB.length && !c.findings.both.length) lines.push('  no findings in either session');
+  return { text: lines.join('\n'), json: c, markdown: core.compareMarkdown(c, { labelA: la, labelB: lb }), compare: c };
+}
+
 export async function main(argv, io = {}) {
   const out = io.stdout || ((s) => process.stdout.write(s + '\n'));
   const err = io.stderr || ((s) => process.stderr.write(s + '\n'));
@@ -213,16 +254,33 @@ export async function main(argv, io = {}) {
   try {
     if (cmd === 'list') {
       const list = findSessions({ home, last: args.flags.last ? +args.flags.last : 20, grep: args.flags.grep, project: args.flags.project });
-      if (!list.length) { out('No sessions found under ' + path.join(home || claudeHome(), 'projects')); return 0; }
+      if (!list.length) { out(noSessionsMessage(home)); return 0; }
       for (const s of list) out(`${s.id.slice(0, 8)}  ${new Date(s.mtime).toISOString().slice(0, 16).replace('T', ' ')}  ${String(Math.round(s.size / 1024)).padStart(6)} KB  ${s.project.padEnd(28).slice(0, 28)}  ${sessionTitle(s.file)}`);
       return 0;
     }
     if (cmd === 'check') {
       const s = resolveTarget(args._[1], { home });
-      const res = checkReport(analyse(loadSessionFiles(s)), { failOn: args.flags['fail-on'] });
-      if (args.flags.json) out(JSON.stringify(res.json, null, 2)); else if (args.flags.markdown) out(res.markdown); else out(res.text);
+      const res = checkReport(analyse(loadSessionFiles(s)), { failOn: args.flags['fail-on'], redact: !!args.flags.redact });
+      const fmtOut = outputFormat(args.flags);
+      if (fmtOut === 'json') out(JSON.stringify(res.json, null, 2)); else if (fmtOut === 'md') out(res.markdown); else out(res.text);
       return res.failed ? 1 : 0;
     }
+    if (cmd === 'compare') {
+      if (!args._[1] || !args._[2]) throw new Error('compare needs two sessions: glassbox compare A B');
+      const sa = resolveTarget(args._[1], { home }), sb = resolveTarget(args._[2], { home });
+      const fa = loadSessionFiles(sa), fb = loadSessionFiles(sb);
+      const rep = compareReport(analyse(fa), analyse(fb), { labelA: args.flags['label-a'], labelB: args.flags['label-b'] });
+      if (args.flags.out) {
+        const html = embed({ files: fa, compare: fb }, { template: io.template });
+        const outFile = path.resolve(args.flags.out); fs.writeFileSync(outFile, html);
+        out(`${outFile}  (${fa.length + fb.length} files, ${Math.round(html.length / 1024)} KB)`);
+        if (!args.flags['no-open'] && !io.noOpen) openInBrowser(outFile);
+        return 0;
+      }
+      const fmtOut = outputFormat(args.flags);
+      if (fmtOut === 'json') out(JSON.stringify(rep.json, null, 2)); else if (fmtOut === 'md') out(rep.markdown); else out(rep.text);
+      return 0;
+    }
     if (cmd === 'open') {
       const s = resolveTarget(args._[1], { home });
       const files = loadSessionFiles(s);
@@ -233,6 +291,16 @@ export async function main(argv, io = {}) {
       if (!args.flags['no-open'] && !io.noOpen) openInBrowser(outFile);
       return 0;
     }
+    if (cmd === 'watch' || (cmd === 'open' && args.flags.watch)) {
+      const { serveLive } = await import('./tail.mjs');
+      const s = resolveTarget(args._[1], { home });
+      const live = await serveLive(s, { port: args.flags.port ? +args.flags.port : 0, embed: (files) => embed(files, { template: io.template }) });
+      out(`Glassbox live · ${s.id.slice(0, 8)} · ${live.url}\n  following ${s.file}\n  Ctrl+C to stop`);
+      if (!args.flags['no-open'] && !io.noOpen) openInBrowser(live.url);
+      if (io.onLive) { io.onLive(live); return 0; }
+      await new Promise((resolve) => { const stop = () => { live.close().then(resolve); }; process.once('SIGINT', stop); process.once('SIGTERM', stop); });
+      return 0;
+    }
     if (cmd === 'hook') {
       const sub = args._[1];
       if (sub === 'install') { const r = installHook({ home, feedback: !!args.flags.feedback, failOn: args.flags['fail-on'], command: args.flags.command, events: args.flags.events ? String(args.flags.events).split(',') : undefined }); out(`Installed Stop hook in ${r.file}\n  ${r.command}\nEvery session now ends with a Glassbox summary${args.flags.feedback ? ', and findings are handed back to the agent once' : ''}. Restart Claude Code to pick it up.`); return 0; }

package/src/tail.mjs

@@ -0,0 +1,141 @@
+// Glassbox live tail — follow a session transcript (and its subagents) as it grows, and serve
+// the viewer with Server-Sent Events on 127.0.0.1. No dependencies. Nothing leaves the machine.
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+
+// Follow one session's files by byte offset. Emits:
+//   { type: 'snapshot', files: [{name, text}] }     once, at start()
+//   { type: 'append',   name, text }                 new complete lines
+//   { type: 'replace',  name, text }                 file shrank or was rewritten → whole file again
+// A trailing partial line (no newline yet) is held back until it completes.
+export class Tailer {
+  constructor(session, opts = {}) {
+    this.session = session;
+    this.pollMs = opts.pollMs || 1000;
+    this.files = new Map(); // name -> { path, offset, pending }
+    this.listeners = [];
+    this.timer = null;
+    this.watchers = [];
+  }
+  on(fn) { this.listeners.push(fn); return this; }
+  emit(ev) { for (const fn of this.listeners) fn(ev); }
+
+  // All files that belong to the session right now: main + subagents dir.
+  discover() {
+    const s = this.session; const out = [{ name: s.id + '.jsonl', path: s.file }];
+    const sub = path.join(s.projectDir, s.id, 'subagents');
+    if (fs.existsSync(sub)) for (const f of fs.readdirSync(sub).sort()) if (/\.(jsonl|json)$/.test(f)) out.push({ name: `${s.id}/subagents/${f}`, path: path.join(sub, f) });
+    return out;
+  }
+
+  // Read everything new. Returns the events it emitted (also emits them).
+  tick() {
+    const events = [];
+    for (const { name, path: p } of this.discover()) {
+      let st; try { st = fs.statSync(p); } catch (e) { continue; }
+      let f = this.files.get(name);
+      if (!f) { f = { path: p, offset: 0, pending: Buffer.alloc(0) }; this.files.set(name, f); }
+      if (st.size < f.offset) { // truncated or rewritten
+        f.offset = 0; f.pending = Buffer.alloc(0);
+        const text = this.readFrom(f, st.size, true);
+        events.push({ type: 'replace', name, text });
+        continue;
+      }
+      if (st.size === f.offset) continue;
+      const text = this.readFrom(f, st.size, false);
+      if (text) events.push({ type: 'append', name, text });
+    }
+    for (const ev of events) this.emit(ev);
+    return events;
+  }
+
+  // Read [offset, size) from the file; split at the last newline byte and keep the tail pending
+  // as bytes, so a multi-byte UTF-8 character cut across two appends is reassembled intact.
+  readFrom(f, size, whole) {
+    const len = size - f.offset; if (len <= 0) return '';
+    const fd = fs.openSync(f.path, 'r');
+    let chunk;
+    try { const buf = Buffer.alloc(len); const n = fs.readSync(fd, buf, 0, len, f.offset); chunk = buf.subarray(0, n); } finally { fs.closeSync(fd); }
+    f.offset = size;
+    const all = f.pending && f.pending.length ? Buffer.concat([f.pending, chunk]) : chunk;
+    const cut = all.lastIndexOf(0x0a);
+    if (cut < 0) { if (whole) { f.pending = Buffer.alloc(0); return all.toString('utf8'); } f.pending = Buffer.from(all); return ''; }
+    f.pending = Buffer.from(all.subarray(cut + 1));
+    return all.subarray(0, cut + 1).toString('utf8');
+  }
+
+  // Full current content of every file (complete lines only), as the viewer expects them.
+  snapshot() {
+    const files = [];
+    for (const { name, path: p } of this.discover()) {
+      let buf; try { buf = fs.readFileSync(p); } catch (e) { continue; }
+      const cut = buf.lastIndexOf(0x0a);
+      this.files.set(name, { path: p, offset: buf.length, pending: Buffer.from(cut < 0 ? buf : buf.subarray(cut + 1)) });
+      files.push({ name, text: cut < 0 ? '' : buf.subarray(0, cut + 1).toString('utf8') });
+    }
+    return files;
+  }
+
+  // Everything emitted so far, per file (complete lines only): [0, offset − pending). Drains first so
+  // a page that loads from this and then subscribes to /events cannot miss or duplicate a line.
+  current() {
+    this.tick();
+    const out = [];
+    for (const [name, f] of this.files) {
+      const len = f.offset - f.pending.length; let text = '';
+      if (len > 0) { try { const fd = fs.openSync(f.path, 'r'); try { const buf = Buffer.alloc(len); const n = fs.readSync(fd, buf, 0, len, 0); text = buf.toString('utf8', 0, n); } finally { fs.closeSync(fd); } } catch (e) { } }
+      out.push({ name, text });
+    }
+    return out;
+  }
+
+  start() {
+    const files = this.snapshot();
+    this.emit({ type: 'snapshot', files });
+    const kick = () => { try { this.tick(); } catch (e) { /* transient read errors: next tick */ } };
+    // fs.watch where it works (fast), plus a poll (fs.watch misses events on some filesystems).
+    const dirs = new Set([path.dirname(this.session.file), path.join(this.session.projectDir, this.session.id, 'subagents')]);
+    for (const d of dirs) { try { if (fs.existsSync(d)) { const w = fs.watch(d, { persistent: false }, () => setTimeout(kick, 30)); w.on('error', () => { }); this.watchers.push(w); } } catch (e) { /* fall back to polling */ } }
+    this.timer = setInterval(kick, this.pollMs); if (this.timer.unref) this.timer.unref();
+    return files;
+  }
+  stop() { if (this.timer) clearInterval(this.timer); this.timer = null; for (const w of this.watchers) { try { w.close(); } catch (e) { } } this.watchers = []; }
+}
+
+// Serve the viewer for one session on loopback and stream tail events to it.
+// opts: { port (0 = random), template (dist/glassbox.html path), embed (fn files→html), pollMs }
+export function serveLive(session, opts = {}) {
+  const tailer = new Tailer(session, { pollMs: opts.pollMs });
+  const clients = new Set();
+  const send = (res, type, data) => { try { res.write(`event: ${type}\ndata: ${JSON.stringify(data)}\n\n`); } catch (e) { clients.delete(res); } };
+  tailer.on((ev) => { if (ev.type === 'snapshot') return; for (const res of clients) send(res, ev.type, ev); });
+  const server = http.createServer((req, res) => {
+    const url = (req.url || '/').split('?')[0];
+    if (url === '/' || url === '/index.html') {
+      let html = opts.embed(tailer.current());
+      html = html.replace('/*__LIVE__*/null', () => JSON.stringify({ url: '/events', session: session.id, file: session.file }));
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+      res.end(html); return;
+    }
+    if (url === '/events') {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive', 'x-accel-buffering': 'no' });
+      res.write(': glassbox live\n\n');
+      clients.add(res);
+      send(res, 'hello', { session: session.id, file: session.file, files: tailer.current() });
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+    if (url === '/health') { res.writeHead(200, { 'content-type': 'application/json' }); res.end(JSON.stringify({ ok: true, session: session.id, clients: clients.size, files: Array.from(tailer.files.keys()) })); return; }
+    res.writeHead(404); res.end('not found');
+  });
+  const ping = setInterval(() => { for (const res of clients) send(res, 'ping', { t: Date.now() }); }, 15000); if (ping.unref) ping.unref();
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(opts.port || 0, '127.0.0.1', () => {
+      tailer.start();
+      const { port } = server.address();
+      resolve({ url: `http://127.0.0.1:${port}/`, port, tailer, server, clients, close: () => new Promise((r) => { clearInterval(ping); tailer.stop(); for (const c of clients) { try { c.end(); } catch (e) { } } clients.clear(); server.close(() => r()); }) });
+    });
+  });
+}