scripts-orchestrator 2.13.0 → 2.15.0

package/lib/recommend-phases.js

@@ -0,0 +1,251 @@
+/**
+ * @file recommend-phases.js
+ * @description R12 — memory-aware phase recommender (advisory).
+ *
+ * Reads a results JSON (the same payload the orchestrator writes via `metrics: ['time','memory']`)
+ * and proposes a phase layout that keeps each phase's concurrent peak memory under a per-host
+ * budget while letting long-running steps overlap. This is the "advisory" first step of R12:
+ * it only reports — it does not change how a run is scheduled.
+ *
+ * Algorithm: First-Fit-Decreasing bin-packing by step duration. Steps are sorted longest-first
+ * and each is placed into the earliest phase where adding it keeps Σ(concurrent peak memory) ≤ budget
+ * and concurrent step count ≤ core share; otherwise a new phase is opened. Long steps seed phases;
+ * short steps fill the gaps beneath them, so makespan (Σ of each phase's longest step) stays near the
+ * theoretical floor (the single longest step) without oversubscribing RAM.
+ */
+
+import os from 'os';
+import chalk from 'chalk';
+
+const KB = 1024;
+const GB = 1024 * 1024 * 1024;
+
+/**
+ * Resolve the per-host scheduling budget.
+ *
+ * budget = totalmem × memSafety ÷ fanout   (overridable wholesale via budgetMb)
+ * coreShare = (cores − 2) ÷ fanout         (≥ 1)
+ *
+ * `fanout` models the workspace-level parallelism (R1's `--parallel=N`): when N workspaces gate
+ * concurrently they share the host, so each gets 1/N of RAM and cores.
+ */
+export function computeBudget(opts = {}) {
+  const totalMemBytes = opts.totalMemBytes != null ? Number(opts.totalMemBytes) : os.totalmem();
+  const cores = opts.cores != null ? Number(opts.cores) : os.cpus().length;
+  const fanout = Math.max(1, Number(opts.fanout) || 1);
+  const memSafety = opts.memSafety != null ? Number(opts.memSafety) : 0.8;
+  const budgetBytes =
+    opts.budgetMb != null
+      ? Number(opts.budgetMb) * 1024 * 1024
+      : (totalMemBytes * memSafety) / fanout;
+  const coreShare = Math.max(1, Math.floor((cores - 2) / fanout));
+  return { totalMemBytes, cores, fanout, memSafety, budgetBytes, coreShare };
+}
+
+/**
+ * Extract the steps that actually ran and were timed. Skipped/disabled commands and untimed
+ * entries are excluded — they tell us nothing about contention. `memoryKb` defaults to 0 when the
+ * memory metric wasn't collected (the report then warns and packs by core share alone).
+ */
+export function usableSteps(payload) {
+  const commands = Array.isArray(payload?.commands) ? payload.commands : [];
+  return commands
+    .filter((c) => c && typeof c.durationMs === 'number' && c.durationMs > 0 && !c.skipReason)
+    .map((c) => ({
+      command: c.command,
+      phase: c.phase != null ? c.phase : '(no phase)',
+      durationMs: c.durationMs,
+      memoryKb: typeof c.memoryKb === 'number' && c.memoryKb > 0 ? c.memoryKb : 0,
+    }));
+}
+
+/**
+ * Group steps by their original phase (first-seen order) and, for each phase, report the
+ * concurrent peak memory (Σ of member peaks — conservative, since peaks rarely coincide exactly)
+ * and the phase wall-clock (max member duration, because the phase runs them in parallel).
+ */
+export function observedTimeline(steps, budgetBytes) {
+  const order = [];
+  const byPhase = new Map();
+  for (const s of steps) {
+    if (!byPhase.has(s.phase)) {
+      byPhase.set(s.phase, []);
+      order.push(s.phase);
+    }
+    byPhase.get(s.phase).push(s);
+  }
+  return order.map((name) => {
+    const members = byPhase.get(name);
+    const concurrentMemBytes = members.reduce((sum, s) => sum + s.memoryKb * KB, 0);
+    const wallclockMs = Math.max(...members.map((s) => s.durationMs));
+    return {
+      name,
+      steps: members,
+      concurrentMemBytes,
+      wallclockMs,
+      overBudget: concurrentMemBytes > budgetBytes,
+    };
+  });
+}
+
+/**
+ * First-Fit-Decreasing bin-packing by duration. A step too large to fit any existing bin under the
+ * budget opens a new bin; a single step whose own peak exceeds the budget still gets its own bin
+ * (it can't be split) and is flagged.
+ */
+export function packPhases(steps, budgetBytes, coreShare) {
+  const sorted = [...steps].sort((a, b) => b.durationMs - a.durationMs);
+  const bins = [];
+  for (const step of sorted) {
+    const stepBytes = step.memoryKb * KB;
+    let placed = false;
+    for (const bin of bins) {
+      if (bin.memBytes + stepBytes <= budgetBytes && bin.steps.length < coreShare) {
+        bin.steps.push(step);
+        bin.memBytes += stepBytes;
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) {
+      bins.push({ steps: [step], memBytes: stepBytes });
+    }
+  }
+  for (const bin of bins) {
+    bin.wallclockMs = Math.max(...bin.steps.map((s) => s.durationMs));
+    bin.exceedsBudget = bin.memBytes > budgetBytes; // only possible for a lone oversized step
+  }
+  return bins;
+}
+
+/**
+ * Produce a full recommendation object from a results payload. Pure — all host inputs are taken from
+ * `opts` or `os`, so it's testable without a real machine.
+ */
+export function recommendPhases(payload, opts = {}) {
+  const budget = computeBudget(opts);
+  const steps = usableSteps(payload);
+  const warnings = [];
+
+  if (steps.length === 0) {
+    warnings.push('No completed, timed commands found in the results — nothing to recommend.');
+  }
+  const hasMemory = steps.some((s) => s.memoryKb > 0);
+  if (steps.length > 0 && !hasMemory) {
+    warnings.push(
+      'No memory metrics in the results — re-run with metrics including "memory" for a meaningful budget. Packing falls back to the core-share limit only.',
+    );
+  }
+
+  const observed = observedTimeline(steps, budget.budgetBytes);
+  const bins = packPhases(steps, budget.budgetBytes, budget.coreShare);
+
+  const observedMakespanMs = observed.reduce((sum, p) => sum + p.wallclockMs, 0);
+  const recommendedMakespanMs = bins.reduce((sum, b) => sum + b.wallclockMs, 0);
+  const optimalMakespanMs = steps.length ? Math.max(...steps.map((s) => s.durationMs)) : 0;
+
+  return {
+    ...budget,
+    steps,
+    observed,
+    observedMakespanMs,
+    recommended: { bins, makespanMs: recommendedMakespanMs },
+    optimalMakespanMs,
+    warnings,
+  };
+}
+
+// ---- formatting helpers ---------------------------------------------------
+
+export function fmtDuration(ms) {
+  if (ms == null) return '—';
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rem = Math.round(seconds % 60);
+  return `${minutes}m ${rem}s`;
+}
+
+export function fmtMemKb(kb) {
+  if (!kb) return '0';
+  const bytes = kb * KB;
+  if (bytes >= GB) return `${(bytes / GB).toFixed(2)} GB`;
+  return `${Math.round(bytes / (1024 * 1024))} MB`;
+}
+
+function stepLine(s) {
+  return `      ${fmtDuration(s.durationMs).padStart(8)}  ${fmtMemKb(s.memoryKb).padStart(9)}  ${s.command}`;
+}
+
+/**
+ * Render a recommendation as a human-readable, optionally-colored report.
+ */
+export function formatRecommendationReport(rec, { sourcePath = null } = {}) {
+  const c = chalk;
+  const L = [];
+
+  L.push(c.bold('🧮 Scripts-Orchestrator — memory-aware phase recommendation (R12, advisory)'));
+  if (sourcePath) L.push(c.dim(`   Source: ${sourcePath}`));
+  L.push(
+    `   Budget: ${c.yellow(fmtMemKb(rec.budgetBytes / KB))} ` +
+      `(RAM ${fmtMemKb(rec.totalMemBytes / KB)} × ${rec.memSafety} ÷ fan-out ${rec.fanout}) · ` +
+      `core share: ${c.yellow(String(rec.coreShare))} (${rec.cores} cores − 2 ÷ ${rec.fanout})`,
+  );
+
+  for (const w of rec.warnings) L.push(c.yellow(`   ⚠ ${w}`));
+  if (rec.steps.length === 0) return L.join('\n');
+
+  // Observed timeline
+  L.push('');
+  L.push(
+    c.bold(
+      `Observed timeline — ${rec.steps.length} steps · ${rec.observed.length} phase(s) · makespan ${fmtDuration(rec.observedMakespanMs)}`,
+    ),
+  );
+  for (const ph of rec.observed) {
+    const flag = ph.overBudget ? c.red('  ⚠ concurrent peak over budget') : '';
+    L.push(
+      `  ${c.cyan(ph.name)}  ${fmtDuration(ph.wallclockMs)} · ${ph.steps.length} step(s) · Σ peak ${fmtMemKb(ph.concurrentMemBytes / KB)}${flag}`,
+    );
+    for (const s of [...ph.steps].sort((a, b) => b.durationMs - a.durationMs)) L.push(stepLine(s));
+  }
+
+  // Recommended layout
+  L.push('');
+  L.push(
+    c.bold(
+      `Recommended layout — First-Fit-Decreasing by duration (≤ ${fmtMemKb(rec.budgetBytes / KB)} mem, ≤ ${rec.coreShare} concurrent)`,
+    ),
+  );
+  rec.recommended.bins.forEach((bin, i) => {
+    const flag = bin.exceedsBudget ? c.red('  ⚠ lone step exceeds budget (cannot split)') : '';
+    L.push(
+      `  ${c.green('phase ' + (i + 1))}  ${fmtDuration(bin.wallclockMs)} · ${bin.steps.length} step(s) · Σ peak ${fmtMemKb(bin.memBytes / KB)}${flag}`,
+    );
+    for (const s of [...bin.steps].sort((a, b) => b.durationMs - a.durationMs)) L.push(stepLine(s));
+  });
+
+  // Summary
+  const saved = rec.observedMakespanMs - rec.recommended.makespanMs;
+  L.push('');
+  L.push(c.bold('Estimated makespan'));
+  L.push(`  observed (sequential phases): ${fmtDuration(rec.observedMakespanMs)}`);
+  const delta =
+    saved > 0
+      ? c.green(`(−${fmtDuration(saved)})`)
+      : saved < 0
+        ? c.red(`(+${fmtDuration(-saved)})`)
+        : c.dim('(no change)');
+  L.push(`  recommended (packed):         ${fmtDuration(rec.recommended.makespanMs)}  ${delta}`);
+  L.push(`  theoretical floor (∞ RAM):    ${fmtDuration(rec.optimalMakespanMs)}`);
+  L.push('');
+  L.push(
+    c.dim(
+      '  Note: advisory only — peaks are per-process maxima summed conservatively, and packing ignores\n' +
+        '  inter-phase data dependencies (e.g. build → post-build checks). Validate against a real run.',
+    ),
+  );
+
+  return L.join('\n');
+}

package/lib/recommend-phases.test.js

@@ -0,0 +1,107 @@
+import {
+  computeBudget,
+  usableSteps,
+  observedTimeline,
+  packPhases,
+  recommendPhases,
+  formatRecommendationReport,
+} from './recommend-phases.js';
+
+const GB_KB = 1024 * 1024; // 1 GB expressed in KB
+
+// A small synthetic run loosely modelled on the finalyzerui worktree profile.
+const payload = {
+  success: true,
+  commands: [
+    { command: 'build', phase: 'build', success: true, durationMs: 123000, memoryKb: 3.5 * GB_KB },
+    { command: 'type-check', phase: 'build', success: true, durationMs: 28000, memoryKb: 1.9 * GB_KB },
+    { command: 'test-ci', phase: 'tests', success: true, durationMs: 92000, memoryKb: 1.3 * GB_KB },
+    { command: 'build-storybook', phase: 'storybook', success: true, durationMs: 97000, memoryKb: 6.8 * GB_KB },
+    { command: 'lint-ci', phase: 'lint', success: true, durationMs: 6500, memoryKb: 0.3 * GB_KB },
+    { command: 'disabled-thing', phase: 'lint', success: true, durationMs: 0, skipReason: 'disabled' },
+  ],
+};
+
+describe('computeBudget', () => {
+  test('derives budget and core share from host inputs and fan-out', () => {
+    const b = computeBudget({ totalMemBytes: 16 * 1024 ** 3, cores: 10, fanout: 1, memSafety: 0.8 });
+    expect(b.budgetBytes).toBeCloseTo(16 * 1024 ** 3 * 0.8);
+    expect(b.coreShare).toBe(8); // (10 - 2) / 1
+  });
+
+  test('fan-out divides both memory and core budgets', () => {
+    const b = computeBudget({ totalMemBytes: 32 * 1024 ** 3, cores: 12, fanout: 2, memSafety: 0.8 });
+    expect(b.budgetBytes).toBeCloseTo((32 * 1024 ** 3 * 0.8) / 2);
+    expect(b.coreShare).toBe(5); // floor((12 - 2) / 2)
+  });
+
+  test('budgetMb overrides the computed budget; core share never drops below 1', () => {
+    const b = computeBudget({ totalMemBytes: 8 * 1024 ** 3, cores: 2, budgetMb: 4096 });
+    expect(b.budgetBytes).toBe(4096 * 1024 * 1024);
+    expect(b.coreShare).toBe(1);
+  });
+});
+
+describe('usableSteps', () => {
+  test('drops skipped/untimed commands and normalises fields', () => {
+    const steps = usableSteps(payload);
+    expect(steps.map((s) => s.command)).not.toContain('disabled-thing');
+    expect(steps).toHaveLength(5);
+    expect(steps.every((s) => s.durationMs > 0)).toBe(true);
+  });
+});
+
+describe('observedTimeline', () => {
+  test('groups by phase, sums concurrent peaks, flags over-budget phases', () => {
+    const steps = usableSteps(payload);
+    const budgetBytes = 4 * 1024 ** 3; // 4 GB
+    const tl = observedTimeline(steps, budgetBytes);
+    const build = tl.find((p) => p.name === 'build');
+    // build (3.5) + type-check (1.9) = 5.4 GB > 4 GB budget
+    expect(build.overBudget).toBe(true);
+    expect(build.wallclockMs).toBe(123000); // max of its members
+  });
+});
+
+describe('packPhases (First-Fit-Decreasing)', () => {
+  test('keeps each bin under the memory budget and respects core share', () => {
+    const steps = usableSteps(payload);
+    const budgetBytes = 12.8 * 1024 ** 3; // 16 GB laptop @ 0.8
+    const bins = packPhases(steps, budgetBytes, 8);
+    for (const bin of bins) {
+      expect(bin.memBytes).toBeLessThanOrEqual(budgetBytes);
+      expect(bin.steps.length).toBeLessThanOrEqual(8);
+    }
+    // longest step seeds the first bin
+    expect(bins[0].steps[0].command).toBe('build');
+  });
+
+  test('a lone oversized step gets its own bin and is flagged', () => {
+    const big = [{ command: 'huge', phase: 'p', durationMs: 1000, memoryKb: 10 * GB_KB }];
+    const bins = packPhases(big, 4 * 1024 ** 3, 8);
+    expect(bins).toHaveLength(1);
+    expect(bins[0].exceedsBudget).toBe(true);
+  });
+});
+
+describe('recommendPhases', () => {
+  test('packed makespan beats the sequential-phase makespan on a constrained host', () => {
+    const rec = recommendPhases(payload, { totalMemBytes: 16 * 1024 ** 3, cores: 10, fanout: 1 });
+    expect(rec.recommended.makespanMs).toBeLessThan(rec.observedMakespanMs);
+    expect(rec.optimalMakespanMs).toBe(123000); // single longest step
+  });
+
+  test('warns when no memory metrics are present', () => {
+    const rec = recommendPhases({
+      commands: [{ command: 'a', phase: 'p', success: true, durationMs: 1000 }],
+    });
+    expect(rec.warnings.join(' ')).toMatch(/memory/i);
+  });
+
+  test('empty results produce a graceful warning, no throw', () => {
+    const rec = recommendPhases({ commands: [] });
+    expect(rec.steps).toHaveLength(0);
+    expect(rec.warnings.join(' ')).toMatch(/nothing to recommend/i);
+    expect(() => formatRecommendationReport(rec)).not.toThrow();
+  });
+});

package/lib/report-html.js

@@ -0,0 +1,308 @@
+import path from 'path';
+
+// Generic, domain-agnostic HTML renderer for orchestrator-shaped result payloads.
+//
+// The renderer knows ONLY about generic orchestrator concepts: a document has optional
+// `commands` and optional nested `sections` (recursive). It has no notion of workspaces,
+// monorepos, nx, etc. — any such labels arrive purely as data (section.title, section.meta,
+// section.statusLabel) and are rendered opaquely.
+//
+// Columns are discovered as the union of keys across all command entries, so new JSON fields
+// appear automatically. Known keys get rich formatting (badges, bars, links); unknown keys
+// render as plain text.
+
+export function escapeHtml(s) {
+  if (s == null) return '';
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+export function formatMs(ms) {
+  if (ms == null || ms === 0) return '—';
+  if (ms < 1000) return `${ms}ms`;
+  const s = (ms / 1000).toFixed(1);
+  return `${s}s`;
+}
+
+// Keys that are folded into the synthetic Status column or the Gantt rather than shown raw.
+const HANDLED_KEYS = new Set(['success', 'startedAt', 'skipReason']);
+
+// Preferred left-to-right order for known columns (others appended alphabetically).
+const KNOWN_ORDER = ['command', 'phase', 'durationMs', 'memoryKb', 'logFile'];
+
+const COLUMN_LABELS = {
+  command: 'Command',
+  phase: 'Phase',
+  durationMs: 'Duration',
+  memoryKb: 'Memory',
+  logFile: 'Log',
+};
+
+function humanizeKey(key) {
+  if (COLUMN_LABELS[key]) return COLUMN_LABELS[key];
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .replace(/^./, (c) => c.toUpperCase());
+}
+
+// Map a command/section to a generic status kind + label.
+function statusOf(entry) {
+  if (entry.statusKind) {
+    return { kind: entry.statusKind, label: entry.statusLabel ?? entry.statusKind };
+  }
+  if (entry.success === null || entry.success === undefined) {
+    // For commands: started-but-not-finished is "running"; otherwise unknown → muted.
+    if (entry.startedAt && entry.durationMs == null) return { kind: 'running', label: 'Running' };
+    if (entry.success === null) return { kind: 'running', label: 'Running' };
+    return { kind: 'muted', label: '—' };
+  }
+  if (entry.success) return { kind: 'ok', label: 'OK' };
+  return { kind: 'fail', label: entry.skipReason || 'Failed' };
+}
+
+// Collect every command entry in the document (top-level + all nested sections).
+function collectCommands(payload) {
+  const all = [];
+  const visit = (node) => {
+    for (const c of node.commands || []) all.push(c);
+    for (const s of node.sections || []) visit(s);
+  };
+  visit(payload);
+  return all;
+}
+
+function pct(value, max) {
+  return max > 0 && value != null ? (value / max) * 100 : 0;
+}
+
+function barCellWrap(text, percent, kind) {
+  return `<div class="cellbar"><span>${text}</span><div class="bar ${kind}" style="width:${percent.toFixed(1)}%"></div></div>`;
+}
+
+// Render a single command cell for a given column key.
+function renderCell(key, c, ctx) {
+  const v = c[key];
+  switch (key) {
+  case 'command':
+    return `<code>${escapeHtml(v)}</code>`;
+  case 'phase':
+    return v != null ? escapeHtml(v) : '—';
+  case 'durationMs':
+    return v != null ? barCellWrap(formatMs(v), pct(v, ctx.maxDuration), 'dur') : '—';
+  case 'memoryKb':
+    return v != null ? barCellWrap(`${(v / 1024).toFixed(1)} MB`, pct(v, ctx.maxMemory), 'mem') : '—';
+  case 'logFile':
+    return v
+      ? `<a class="logref" href="file://${escapeHtml(path.resolve(process.cwd(), v))}" title="${escapeHtml(v)}"><code>${escapeHtml(v)}</code></a>`
+      : '—';
+  default:
+    if (v == null) return '—';
+    return escapeHtml(typeof v === 'object' ? JSON.stringify(v) : v);
+  }
+}
+
+function renderCommandsTable(commands, columns, ctx) {
+  if (!commands || commands.length === 0) return '';
+  const headerCells = ['<th>Status</th>', ...columns.map((k) => `<th>${escapeHtml(humanizeKey(k))}</th>`)];
+  const rows = commands
+    .map((c) => {
+      const st = statusOf(c);
+      const cells = columns.map((k) => `<td>${renderCell(k, c, ctx)}</td>`).join('');
+      return `<tr class="${st.kind}"><td><span class="badge ${st.kind}">${escapeHtml(st.label)}</span></td>${cells}</tr>`;
+    })
+    .join('');
+  return `<table><thead><tr>${headerCells.join('')}</tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function renderPhasesTable(phases, ctx) {
+  if (!phases || phases.length === 0) return '';
+  const rows = phases
+    .map((p) => {
+      const st = statusOf(p);
+      return `<tr class="${st.kind}"><td>${escapeHtml(p.name)}</td><td><span class="badge ${st.kind}">${escapeHtml(st.label)}</span></td><td>${barCellWrap(formatMs(p.durationMs), pct(p.durationMs, ctx.maxDuration), 'dur')}</td></tr>`;
+    })
+    .join('');
+  return `<section><h3>Phases</h3><table><thead><tr><th>Phase</th><th>Status</th><th>Duration</th></tr></thead><tbody>${rows}</tbody></table></section>`;
+}
+
+// Critical-path Gantt for one command list (uses observed startedAt + durationMs).
+function renderGantt(commands, overallDurationMs, hasPhases) {
+  const timed = (commands || [])
+    .filter((c) => c.startedAt && c.durationMs != null)
+    .map((c) => ({ ...c, _start: Date.parse(c.startedAt) }))
+    .filter((c) => Number.isFinite(c._start))
+    .sort((a, b) => a._start - b._start);
+  if (timed.length === 0) return '';
+
+  const runStart = Math.min(...timed.map((c) => c._start));
+  const maxEnd = Math.max(...timed.map((c) => c._start + c.durationMs));
+  const spanMs = overallDurationMs != null && overallDurationMs > 0 ? overallDurationMs : Math.max(1, maxEnd - runStart);
+
+  // Critical chain: longest command per phase (phases run sequentially, commands within run parallel).
+  const criticalKeys = new Set();
+  if (hasPhases) {
+    const byPhase = new Map();
+    for (const c of timed) {
+      const arr = byPhase.get(c.phase) || [];
+      arr.push(c);
+      byPhase.set(c.phase, arr);
+    }
+    for (const arr of byPhase.values()) {
+      const top = arr.reduce((a, b) => (b.durationMs > a.durationMs ? b : a));
+      criticalKeys.add(top.command);
+    }
+  } else {
+    timed.forEach((c) => criticalKeys.add(c.command));
+  }
+  const criticalTotal = timed.filter((c) => criticalKeys.has(c.command)).reduce((sum, c) => sum + c.durationMs, 0);
+
+  const ganttRow = (c) => {
+    const offsetPct = ((c._start - runStart) / spanMs) * 100;
+    const widthPct = Math.max((c.durationMs / spanMs) * 100, 0.5);
+    const crit = criticalKeys.has(c.command);
+    const cls = c.success === false ? 'failed' : crit ? 'crit' : '';
+    return `<div class="gantt-row"><div class="gantt-label" title="${escapeHtml(c.command)}${c.phase ? ` — ${escapeHtml(c.phase)}` : ''}">${crit ? '★ ' : ''}${escapeHtml(c.command)}</div><div class="gantt-track"><div class="gantt-bar ${cls}" style="left:${offsetPct.toFixed(2)}%;width:${widthPct.toFixed(2)}%" title="${escapeHtml(c.command)} — ${formatMs(c.durationMs)}"><span class="gantt-dur">${formatMs(c.durationMs)}</span></div></div></div>`;
+  };
+
+  return `<section><h3>Actual Critical Path</h3><p class="muted">★ marks each phase's bottleneck — the chain that drives wall-clock time. Critical path ≈ <strong>${formatMs(criticalTotal)}</strong>${overallDurationMs != null ? ` of ${formatMs(overallDurationMs)} total` : ''}.</p><div class="gantt">${timed.map(ganttRow).join('')}</div></section>`;
+}
+
+function renderMeta(meta) {
+  if (!meta || typeof meta !== 'object') return '';
+  const items = Object.entries(meta)
+    .filter(([, v]) => v != null && v !== '')
+    .map(([k, v]) => `<span class="meta-item"><span class="meta-k">${escapeHtml(humanizeKey(k))}</span> ${escapeHtml(typeof v === 'object' ? JSON.stringify(v) : v)}</span>`)
+    .join('');
+  return items ? `<div class="meta">${items}</div>` : '';
+}
+
+// Render one section as a collapsible block.
+function renderSection(section, columns, ctx) {
+  const st = statusOf(section);
+  const hasPhases = (section.phases || []).length > 0;
+  const dur = section.overallDurationMs != null ? ` · ${formatMs(section.overallDurationMs)}` : '';
+  const inner =
+    renderMeta(section.meta) +
+    renderPhasesTable(section.phases, ctx) +
+    renderGantt(section.commands, section.overallDurationMs, hasPhases) +
+    renderCommandsTable(section.commands, columns, ctx) +
+    (section.sections || []).map((s) => renderSection(s, columns, ctx)).join('');
+  return `<details class="section" open><summary><span class="badge ${st.kind}">${escapeHtml(st.label)}</span> <span class="section-title">${escapeHtml(section.title || 'Section')}</span><span class="section-dur">${dur}</span></summary><div class="section-body">${inner}</div></details>`;
+}
+
+const STYLES = `
+* { box-sizing: border-box; }
+body { font-family: system-ui, sans-serif; margin: 1rem 2rem; background: #1a1a1a; color: #e0e0e0; }
+h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
+h3 { font-size: 1rem; color: #a0a0a0; margin: 0.75rem 0 0.4rem; }
+.summary { display: flex; gap: 1.5rem; flex-wrap: wrap; margin-bottom: 1.5rem; }
+.summary .card { background: #2a2a2a; padding: 1rem 1.25rem; border-radius: 8px; min-width: 140px; }
+.summary .card.ok { border-left: 4px solid #22c55e; }
+.summary .card.fail { border-left: 4px solid #ef4444; }
+.summary .card.running { border-left: 4px solid #3b82f6; }
+.summary .card.warn { border-left: 4px solid #f59e0b; }
+.summary .card.muted { border-left: 4px solid #666; }
+.summary .label { font-size: 0.75rem; text-transform: uppercase; color: #888; }
+.summary .value { font-size: 1.25rem; font-weight: 600; }
+section { margin-bottom: 1rem; }
+table { width: 100%; border-collapse: collapse; background: #2a2a2a; border-radius: 8px; overflow: hidden; margin-bottom: 0.5rem; }
+th, td { padding: 0.5rem 0.75rem; text-align: left; vertical-align: top; }
+th { background: #333; color: #888; font-weight: 600; font-size: 0.8rem; }
+tr.fail { background: rgba(239,68,68,0.08); }
+tr.running { background: rgba(59,130,246,0.08); }
+.badge { padding: 0.2rem 0.5rem; border-radius: 4px; font-size: 0.8rem; white-space: nowrap; }
+.badge.ok { background: #22c55e; color: #0f0f0f; }
+.badge.fail { background: #ef4444; color: #fff; }
+.badge.running { background: #3b82f6; color: #fff; }
+.badge.warn { background: #f59e0b; color: #0f0f0f; }
+.badge.muted { background: #555; color: #ddd; }
+.cellbar { min-width: 90px; }
+.cellbar span { font-size: 0.85em; }
+.bar { height: 6px; background: #3b82f6; border-radius: 4px; min-width: 2px; margin-top: 2px; }
+.bar.mem { background: #8b5cf6; }
+code { font-size: 0.9em; background: #333; padding: 0.1rem 0.3rem; border-radius: 4px; }
+a.logref { color: #60a5fa; text-decoration: none; }
+a.logref:hover { text-decoration: underline; }
+.muted { color: #888; font-size: 0.85rem; margin: 0 0 0.6rem; }
+.gantt { background: #2a2a2a; border-radius: 8px; padding: 0.6rem 0.75rem; }
+.gantt-row { display: flex; align-items: center; gap: 0.5rem; padding: 2px 0; }
+.gantt-label { width: 280px; flex: 0 0 280px; font-family: ui-monospace, monospace; font-size: 0.78rem; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; color: #bbb; }
+.gantt-track { position: relative; flex: 1; height: 16px; background: #1f1f1f; border-radius: 4px; }
+.gantt-bar { position: absolute; top: 0; height: 16px; background: #3b82f6; border-radius: 4px; min-width: 2px; display: flex; align-items: center; overflow: hidden; }
+.gantt-bar.crit { background: #f59e0b; }
+.gantt-bar.failed { background: #ef4444; }
+.gantt-dur { font-size: 0.65rem; color: #0f0f0f; padding: 0 4px; white-space: nowrap; }
+details.section { background: #232323; border-radius: 8px; margin-bottom: 0.6rem; padding: 0.25rem 0.75rem; }
+details.section > summary { cursor: pointer; padding: 0.5rem 0; display: flex; align-items: center; gap: 0.6rem; }
+.section-title { font-weight: 600; }
+.section-dur { color: #888; font-size: 0.85rem; }
+.section-body { padding: 0.25rem 0 0.5rem; }
+.meta { display: flex; flex-wrap: wrap; gap: 0.75rem; margin-bottom: 0.5rem; }
+.meta-item { font-size: 0.8rem; color: #bbb; }
+.meta-k { color: #777; text-transform: uppercase; font-size: 0.7rem; }
+`;
+
+export function renderReportHtml(payload) {
+  const { success, timestamp, overallDurationMs, title } = payload;
+  const topCommands = payload.commands || [];
+  const sections = payload.sections || [];
+  const hasTopPhases = (payload.phases || []).length > 0;
+
+  // Global column set + bar scaling across every command in the document.
+  const allCommands = collectCommands(payload);
+  const present = new Set();
+  for (const c of allCommands) for (const k of Object.keys(c)) if (!HANDLED_KEYS.has(k)) present.add(k);
+  const ordered = KNOWN_ORDER.filter((k) => present.has(k));
+  const extras = [...present].filter((k) => !KNOWN_ORDER.includes(k)).sort();
+  const columns = [...ordered, ...extras];
+
+  const ctx = {
+    maxDuration: Math.max(0, ...allCommands.map((c) => c.durationMs || 0)),
+    maxMemory: Math.max(0, ...allCommands.map((c) => c.memoryKb || 0)),
+  };
+
+  const top = statusOf({ success });
+  const statusLabel = success === null ? 'Running…' : success ? 'Success' : 'Failed';
+
+  const topBlocks =
+    renderPhasesTable(payload.phases, ctx) +
+    renderGantt(topCommands, overallDurationMs, hasTopPhases) +
+    (topCommands.length > 0
+      ? `<section><h3>Commands</h3>${renderCommandsTable(topCommands, columns, ctx)}</section>`
+      : '');
+
+  const sectionBlocks = sections.map((s) => renderSection(s, columns, ctx)).join('');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>${escapeHtml(title || 'Scripts Orchestrator Report')}</title>
+  <style>${STYLES}</style>
+</head>
+<body>
+  <h1>${escapeHtml(title || 'Scripts Orchestrator Report')}</h1>
+  <div class="summary">
+    <div class="card ${top.kind}">
+      <div class="label">Status</div>
+      <div class="value">${statusLabel}</div>
+    </div>
+    <div class="card">
+      <div class="label">Timestamp</div>
+      <div class="value" style="font-size:0.9rem">${escapeHtml(timestamp)}</div>
+    </div>
+    ${overallDurationMs != null ? `
+    <div class="card">
+      <div class="label">${success === null ? 'Elapsed' : 'Total time'}</div>
+      <div class="value">${formatMs(overallDurationMs)}</div>
+    </div>` : ''}
+  </div>
+  ${topBlocks}
+  ${sectionBlocks}
+</body>
+</html>`;
+}