faberun 0.30.0 → 0.32.0

package/src/report/progress.mjs

@@ -21,6 +21,11 @@
  * authored file is gone is left out rather than allowed to abort the render:
  * one missing file must not cost the page all four answers.
  *
+ * The same roll-up is the one projection for where the campaign stands now:
+ * current phase, node in flight, time since useful progress, wait reason,
+ * unpriced invocations, and the next action's state -- applied, pending or
+ * none -- with the owner of a human decision, all from persisted state.
+ *
  * Every number here comes from a reader that already owns it -- the status
  * payload (`renderStatusJson`, which already carries per-node phase, spans,
  * cost and per-role usage with provenance), the raw node snapshot (for the
@@ -37,6 +42,7 @@ import { finite } from "../util.mjs";
 import { SETTLED, SUCCESS } from "../engine/prompts.mjs";
 import { campaignDir } from "../campaign/layout.mjs";
 import { readCampaign } from "../campaign/record.mjs";
+import { readJournal } from "../campaign/journal.mjs";
 import { computeNextItems } from "./next.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -154,7 +160,12 @@ function campaignCumulativeCostUsd(runsDir, campaignId) {
  */
 /** @typedef {{contractId: string|null, runId: string|null, phase: string|null, name: string|null, goal: string|null, declaredRequirementIds: string[], nodes: RollupNode[], counts: {done: number, settled: number, total: number}, newestSettledNode: RollupNewestNode|null, recordGone?: boolean}} RollupPhase */
 /** @typedef {{contractId: string, nodeId: string, summary: string}} RollupNewestNode */
-/** @typedef {{reason: string, command: string, runnable: boolean}} RollupNextAction */
+/**
+ * @typedef {{state: "applied"|"pending"|"none", reason: string|null, command: string|null, runnable: boolean, decisionOwner: "operator"|null}} RollupNextAction
+ * `applied` means the journal records an operator command for the action
+ * written after the state that demanded it; `decisionOwner` names the
+ * owner of the campaign's human decision, always the operator, else null.
+ */
 
 /**
  * The campaign roll-up: `renderRunProgress`'s campaign-wide sibling. Every
@@ -204,6 +215,15 @@ export function buildCampaignProgress(runsDir, campaignId, now) {
   const done = phases.reduce((total, phase) => total + phase.counts.done, 0);
   const settled = phases.reduce((total, phase) => total + phase.counts.settled, 0);
   const total = phases.reduce((total2, phase) => total2 + phase.counts.total, 0);
+  // The waiting clocks read against the record's own `closedAt` once
+  // closed -- `campaignTime`'s elapsed rule -- else the render's now.
+  const closedAt = typeof campaign.closedAt === "string" && Number.isFinite(Date.parse(campaign.closedAt)) ? campaign.closedAt : null;
+  const end = closedAt === null ? now : Date.parse(closedAt);
+  const progressAt = lastProgressAtOf(settledNodes);
+  const activity = currentActivityOf(phases, settledNodes);
+  const current = currentPhaseOf(phases);
+  const decisionNeeded = phases.some((phase) => phase.nodes.some((node) => node.status === "blocked" || node.status === "exhausted"));
+  const costByRole = campaignRoleUsage(runsDir, campaign.linkedRunIds);
   return {
     schemaVersion: 1,
     campaignId: campaign.id,
@@ -220,18 +240,29 @@ export function buildCampaignProgress(runsDir, campaignId, now) {
     // not done either, but only `settled` also folds in blocked, failed and
     // exhausted, which would read as progress.
     percentDone: total ? Math.round((done / total) * 100) : 0,
-    costByRole: campaignRoleUsage(runsDir, campaign.linkedRunIds),
+    // Where the campaign stands: the first phase, in the record's own order,
+    // with a node that has not settled, and the node in flight, if any.
+    currentPhase: current === null ? null : { contractId: current.contractId, runId: current.runId, phase: current.phase, name: current.name },
+    activity,
+    requirements: campaignRequirements(phases),
+    costByRole,
     // The same sum the single-run message prints as "campaign total", from
     // the same ledgers -- the roll-up and the message cannot disagree about
     // what the campaign spent.
     costTotalUsd: campaignCumulativeCostUsd(runsDir, campaignId),
+    unpricedInvocations: costByRole.worker.unpricedInvocations + costByRole.judge.unpricedInvocations,
     newestSettledNode: newestSettledNode(settledNodes),
-    time: campaignTime(campaign, phases, settledNodes, now),
+    time: {
+      ...campaignTime(campaign, phases, settledNodes, now),
+      lastProgressAt: progressAt,
+      sinceProgress: progressAt === null ? null : formatDuration(Math.max(0, end - Date.parse(progressAt))),
+    },
+    waitReason: campaignWaitReason(phases, activity, closedAt, total),
     // The chain calls this contract's own run directory the campaign's
     // repo root three levels above `campaignPath` (`record.mjs`'s
     // `preserveCampaignLedger` derives it the same way); reused here so the
     // next action's command matches what `next` itself would print.
-    nextAction: campaignNextAction(runsDir, campaignId, resolve(campaignPath, "..", "..", "..")),
+    nextAction: campaignNextAction(runsDir, campaignId, resolve(campaignPath, "..", "..", ".."), campaignPath, progressAt, closedAt, decisionNeeded),
   };
 }
 
@@ -596,20 +627,173 @@ function campaignTime(campaign, phases, settledCandidates, now) {
   };
 }
 
+/**
+ * When the campaign last usefully moved: the newest `updatedAt` among its
+ * settled nodes, read from the same snapshots `newestSettledNode` reads. A
+ * running node's own timestamp climbs while it works, so it is never
+ * progress -- only a node that has stopped moving (done, blocked, failed,
+ * exhausted) is. `null` when nothing has settled: no progress is on record,
+ * and none is invented.
+ *
+ * @param {{contractId: string, nodeId: string, snapshot: Record<string, unknown>}[]} candidates
+ * @returns {string|null}
+ */
+function lastProgressAtOf(candidates) {
+  let latest = null;
+  for (const candidate of candidates) {
+    if (!SETTLED.has(/** @type {import("../contract/index.mjs").NodeStatus} */ (String(candidate.snapshot.status)))) continue;
+    const at = candidate.snapshot.updatedAt;
+    if (typeof at === "string" && (latest === null || at > latest)) latest = at;
+  }
+  return latest;
+}
+
+/**
+ * What the campaign is doing right now: the not-yet-settled node that
+ * started most recently, from persisted snapshots -- never a live probe.
+ * `null` when nothing is in flight.
+ *
+ * @param {RollupPhase[]} phases
+ * @param {{contractId: string, nodeId: string, snapshot: Record<string, unknown>}[]} candidates
+ * @returns {{runId: string|null, phase: string|null, nodeId: string, startedAt: string}|null}
+ */
+function currentActivityOf(phases, candidates) {
+  /** @type {{runId: string|null, phase: string|null, nodeId: string, startedAt: string}|null} */
+  let latest = null;
+  for (const candidate of candidates) {
+    if (SETTLED.has(/** @type {import("../contract/index.mjs").NodeStatus} */ (String(candidate.snapshot.status)))) continue;
+    const startedAt = typeof candidate.snapshot.startedAt === "string" ? candidate.snapshot.startedAt : null;
+    if (startedAt === null || (latest !== null && startedAt <= latest.startedAt)) continue;
+    const phase = phases.find((entry) => entry.contractId === candidate.contractId && entry.nodes.some((node) => node.id === candidate.nodeId));
+    latest = { runId: phase?.runId ?? null, phase: phase?.phase ?? null, nodeId: candidate.nodeId, startedAt };
+  }
+  return latest;
+}
+
+/**
+ * Where the campaign stands: the first phase, in the record's own order,
+ * with a node that has not settled -- the one a running node belongs to, or
+ * the blocked one, or the next queued one. `null` when every declared node
+ * has settled.
+ *
+ * @param {RollupPhase[]} phases
+ * @returns {RollupPhase|null}
+ */
+function currentPhaseOf(phases) {
+  return phases.find((phase) => phase.counts.settled < phase.counts.total) ?? null;
+}
+
+/**
+ * Why nothing is moving, from the same nodes the counts come from: a
+ * blocked or exhausted node waits on a human decision, a never-launched
+ * phase waits on its launch, a run stopped mid-phase waits on supervision,
+ * everything settled with nothing queued waits on closure. A campaign with
+ * a node in flight is not waiting; a closed one waits for nothing.
+ *
+ * @param {RollupPhase[]} phases
+ * @param {{runId: string|null, phase: string|null, nodeId: string, startedAt: string}|null} activity
+ * @param {string|null} closedAt
+ * @param {number} total
+ * @returns {{code: "decision"|"launch"|"supervise"|"complete", detail: string|null}|null}
+ */
+function campaignWaitReason(phases, activity, closedAt, total) {
+  if (closedAt !== null || activity !== null) return null;
+  for (const phase of phases) {
+    const node = phase.nodes.find((entry) => entry.status === "blocked" || entry.status === "exhausted");
+    if (node) return { code: "decision", detail: node.id };
+  }
+  const current = currentPhaseOf(phases);
+  if (current === null) return total > 0 ? { code: "complete", detail: null } : { code: "launch", detail: null };
+  if (current.runId === null) return { code: "launch", detail: current.name };
+  return { code: "supervise", detail: current.name };
+}
+
+/**
+ * Requirements proven over total, from the requirement ids the phases
+ * declare: a phase's ids are proven when every node it declared finished.
+ * No phase carries declared ids yet (the journal scrape was removed --
+ * journal prose is not a traceability source), so both are `null`: absent,
+ * never zero, the page's standing refusal on requirement coverage.
+ *
+ * @param {RollupPhase[]} phases
+ * @returns {{proven: number|null, total: number|null}}
+ */
+function campaignRequirements(phases) {
+  const total = new Set();
+  const proven = new Set();
+  for (const phase of phases) {
+    for (const id of phase.declaredRequirementIds) {
+      total.add(id);
+      if (phase.counts.total > 0 && phase.counts.done === phase.counts.total) proven.add(id);
+    }
+  }
+  return total.size > 0 ? { proven: proven.size, total: total.size } : { proven: null, total: null };
+}
+
 /**
  * The operator's next action for this one campaign, reusing `next`'s own
  * ranked predicates rather than re-deriving them: a second implementation of
  * "what needs the operator" is exactly how a page and `faberun next` could
- * disagree. `null` when `next` has nothing runnable or worth naming for this
- * campaign (an empty command, e.g. "run live; nothing to do").
+ * disagree. The action carries its state -- `pending` while it stands,
+ * `applied` once the journal records an operator command for it, `none`
+ * when nothing needs doing: a campaign the record shows closed, or one
+ * `next` ranks with nothing to run. `decisionOwner` names who owns the
+ * human decision when the campaign holds a blocked or exhausted node --
+ * that answer is the operator's, never the projection's.
  *
  * @param {string} runsDir
  * @param {string} campaignId
  * @param {string} cwd
- * @returns {RollupNextAction|null}
+ * @param {string} campaignPath
+ * @param {string|null} progressAt the timestamp of the state the action answers
+ * @param {string|null} closedAt
+ * @param {boolean} decisionNeeded
+ * @returns {RollupNextAction}
  */
-function campaignNextAction(runsDir, campaignId, cwd) {
+function campaignNextAction(runsDir, campaignId, cwd, campaignPath, progressAt, closedAt, decisionNeeded) {
+  /** @type {RollupNextAction} */
+  const none = { state: "none", reason: null, command: null, runnable: false, decisionOwner: null };
+  if (closedAt !== null) return none;
   const item = computeNextItems(runsDir, cwd).find((candidate) => candidate.campaign === campaignId);
-  if (!item || !item.command) return null;
-  return { reason: item.reason, command: item.command, runnable: item.runnable };
+  if (!item || !item.command) {
+    return decisionNeeded ? { ...none, decisionOwner: "operator" } : none;
+  }
+  return {
+    state: actionAppliedInJournal(campaignPath, item, progressAt) ? "applied" : "pending",
+    reason: item.reason,
+    command: item.command,
+    runnable: item.runnable,
+    decisionOwner: decisionNeeded ? "operator" : null,
+  };
+}
+
+/**
+ * Whether the journal records the operator applying this action: an
+ * `operator.command` entry with the action's verb naming its target (the
+ * first argument), written no earlier than the state that demanded it --
+ * never the whole line, since the operator's real answer file is not the
+ * placeholder the projection prints. An unreadable journal leaves it pending.
+ *
+ * @param {string} campaignPath
+ * @param {{command: string}} item
+ * @param {string|null} progressAt
+ * @returns {boolean}
+ */
+function actionAppliedInJournal(campaignPath, item, progressAt) {
+  const tokens = item.command.trim().split(/\s+/u);
+  /** @type {import("../campaign/index.mjs").JournalEntry[]} */
+  let entries;
+  try {
+    entries = readJournal(campaignPath);
+  } catch {
+    return false;
+  }
+  return entries.some((entry) => {
+    const command = entry.type === "operator.command" ? /** @type {Record<string, unknown>} */ (entry).command : null;
+    if (typeof command !== "string") return false;
+    const applied = command.trim().split(/\s+/u);
+    return applied[0] === tokens[0]
+      && (tokens[1] === undefined || command.includes(tokens[1]))
+      && (progressAt === null || entry.at >= progressAt);
+  });
 }

package/src/report/render.mjs

@@ -448,7 +448,7 @@ export function renderReport(runDir) {
   const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, costUsd: null };
   const costs = nodes.map(costProjection);
   const aggregateCost = aggregateCostProjection(costs);
-  const lines = [`# run ${basename(runDir)}`, "", `${nodes.length} nodes · ${summary} · in ${compactTokens(usage.inputTokens)} · out ${compactTokens(usage.outputTokens)} · cache ${compactTokens(usage.cacheReadInputTokens)} · cost ${compactCost(usage.costUsd)}`, "", "```", row(["", "NODE", "STATE", "TRY", "REV", "RUNTIME", "IN", "OUT", "CACHE", "COST", "NOTE"]), row(widths.map((width) => "-".repeat(width)))];
+  const lines = [`# run ${basename(runDir)}`, "", `${nodes.length} nodes · ${summary} · in ${compactTokens(usage.inputTokens)} · out ${compactTokens(usage.outputTokens)} · cache ${compactTokens(usage.cacheReadInputTokens)} · cost ${compactCost(usage.costUsd)}`, "", "```", row(["", "NODE", "STATE", "TRY", "REV", "RUNTIME", "IN", "OUT", "CACHE", "USD", "NOTE"]), row(widths.map((width) => "-".repeat(width)))];
   for (const [index, node] of nodes.entries()) {
     const usage = node.usage ?? { inputTokens: null, outputTokens: null, cacheReadInputTokens: null };
     for (const key of /** @type {("inputTokens"|"outputTokens"|"cacheReadInputTokens")[]} */ (Object.keys(totals).filter((key) => key !== "costUsd"))) totals[key] = (totals[key] ?? 0) + (usage[key] ?? 0);

package/src/report/report-html.mjs

@@ -0,0 +1,235 @@
+/**
+ * The run report's HTML boundary: the same contract `campaign-brief-html.mjs`
+ * owns for the campaign brief — Markdown is the durable source, the portable
+ * `.md.html` is a copy that only survives a build, check and round-trip — but
+ * for `report`, the surface the operator reads a run's attempts, tokens and
+ * cost from. It renders the ASCII table as a Markdown table and, when the
+ * phase has a dependency topology, an inline SVG of the work graph instead of
+ * a list, then hands the Markdown to that one renderer rather than opening a
+ * second markdown→HTML path.
+ *
+ * It is a module apart from `render.mjs` because that file owns the terminal
+ * and JSON surfaces and is already near the 800-line ceiling; the HTML copy is
+ * a different audience (a browser, not a terminal) and a different lifetime
+ * (a file beside the Markdown, not stdout).
+ */
+import { readFileSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import { renderReportJson } from "./render.mjs";
+import { cell } from "./campaign-brief.mjs";
+import { CampaignBriefRenderError, renderCampaignBriefHtml } from "./campaign-brief-html.mjs";
+import { formatCost, formatRole } from "./role-usage.mjs";
+import { compactTokens } from "../util.mjs";
+import { writeTextAtomic } from "../run/store.mjs";
+
+/** The durable source and its portable copy, beside `STATUS.md` in the run directory. */
+const REPORT_MD_FILE = "report.md";
+const REPORT_HTML_FILE = "report.md.html";
+
+/** @typedef {{id: string, status: string, dependsOn: string[]}} GraphNode */
+/** @typedef {import("./role-usage.mjs").RoleUsage} RoleUsage */
+/** @typedef {import("./role-usage.mjs").CostProjection} CostProjection */
+/** @typedef {{id: string, status: string, attempt: number, revisions: number, runtime: string|null, usage: {inputTokens: number|null, outputTokens: number|null, cacheReadInputTokens: number|null}|null, costUsd: number|null, costStatus: CostProjection["status"], note: string|null}} ReportNode */
+/** @typedef {{run: string, summary: string, totals: {inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null, costStatus: CostProjection["status"]}, roles: {worker: RoleUsage, judge: RoleUsage}, nodes: ReportNode[]}} ReportPayload */
+
+/**
+ * The work graph as inline SVG, or null when every node is
+ * dependency-independent and a list reads better than a diagram. The layout is
+ * the same depth/row scheme the dashboard uses (`src/web/app.mjs`): a node's
+ * column is its dependency depth, its row is its position among the siblings
+ * at that depth. Self-contained: inline colours, no stylesheet, no external
+ * reference, so the rendered copy stays offline.
+ *
+ * @param {GraphNode[]} nodes
+ * @returns {string|null}
+ */
+export function renderReportGraphSvg(nodes) {
+  const hasEdges = nodes.some((node) => (node.dependsOn ?? []).length > 0);
+  if (!hasEdges) return null;
+  const laidOut = layoutGraphNodes(nodes);
+  const byId = new Map(laidOut.map((node) => [node.id, node]));
+  const maxDepth = laidOut.reduce((max, node) => Math.max(max, node.depth), 0);
+  const maxRow = laidOut.reduce((max, node) => Math.max(max, node.row), 0);
+  const width = NODE_MARGIN * 2 + (maxDepth + 1) * NODE_COL_WIDTH;
+  const height = NODE_MARGIN * 2 + (maxRow + 1) * NODE_ROW_HEIGHT;
+  const posOf = (/** @type {{depth: number, row: number}} */ node) => ({ x: NODE_MARGIN + node.depth * NODE_COL_WIDTH, y: NODE_MARGIN + node.row * NODE_ROW_HEIGHT });
+  const edges = laidOut.flatMap((node) => (node.dependsOn ?? [])
+    .filter((/** @type {string} */ dep) => byId.has(dep))
+    .map((/** @type {string} */ dep) => {
+      const from = posOf(/** @type {{depth: number, row: number}} */ (byId.get(dep)));
+      const to = posOf(node);
+      const x1 = from.x + NODE_BOX_W;
+      const y1 = from.y + NODE_BOX_H / 2;
+      const x2 = to.x;
+      const y2 = to.y + NODE_BOX_H / 2;
+      const midX = (x1 + x2) / 2;
+      return `<path d="M ${x1} ${y1} C ${midX} ${y1}, ${midX} ${y2}, ${x2} ${y2}" fill="none" stroke="#D97B4F" stroke-width="2"/>`;
+    })).join("");
+  const boxes = laidOut.map((node, index) => {
+    const { x, y } = posOf(node);
+    const clipId = `nodeclip${index}`;
+    const colour = STATUS_COLOURS[node.status] ?? "#1F1F1F";
+    return `<g><rect x="${x}" y="${y}" width="${NODE_BOX_W}" height="${NODE_BOX_H}" rx="8" fill="#F4E9D8" stroke="${colour}" stroke-width="2"/><clipPath id="${clipId}"><rect x="${x}" y="${y}" width="${NODE_BOX_W}" height="${NODE_BOX_H}"/></clipPath><g clip-path="url(#${clipId})"><text x="${x + 10}" y="${y + 22}" font-family="ui-monospace, monospace" font-size="12" fill="#1F1F1F">${escapeSvgText(truncateOneLine(node.id, NODE_ID_MAX_CHARS))}</text><text x="${x + 10}" y="${y + 40}" font-family="ui-sans-serif, sans-serif" font-size="12" fill="${colour}">${escapeSvgText(node.status)}</text></g></g>`;
+  }).join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img" aria-label="work graph">${edges}${boxes}</svg>`;
+}
+
+/**
+ * `report`'s Markdown: the same facts `report --json` carries, laid out for a
+ * browser. The node table mirrors the ASCII table's columns (with `USD`, the
+ * one term both surfaces now share) and the work graph renders as a diagram
+ * when there are dependencies, else as a list.
+ *
+ * @param {string} runDir
+ * @returns {string}
+ */
+export function renderReportMarkdown(runDir) {
+  const payload = /** @type {ReportPayload} */ (JSON.parse(renderReportJson(runDir)));
+  const dependsOn = readContractDependsOn(runDir);
+  const graph = renderReportGraphSvg(payload.nodes.map((node) => ({ id: node.id, status: node.status, dependsOn: dependsOn.get(node.id) ?? [] })));
+  const totals = payload.totals;
+  const summary = `${payload.summary} · in ${compactTokens(totals.inputTokens)} · out ${compactTokens(totals.outputTokens)} · cache ${compactTokens(totals.cacheReadInputTokens)} · cost ${formatCost({ costUsd: totals.costUsd, status: totals.costStatus })}`;
+
+  const header = "| NODE | STATE | TRY | REV | RUNTIME | IN | OUT | CACHE | USD | NOTE |";
+  const separator = "| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |";
+  const rows = payload.nodes.map((node) => {
+    const usage = node.usage ?? { inputTokens: null, outputTokens: null, cacheReadInputTokens: null };
+    return `| \`${cell(node.id)}\` | ${cell(node.status)} | ${node.attempt} | ${node.revisions} | ${cell(node.runtime ?? "-")} | ${compactTokens(usage.inputTokens)} | ${compactTokens(usage.outputTokens)} | ${compactTokens(usage.cacheReadInputTokens)} | ${cell(formatCost({ costUsd: node.costUsd, status: node.costStatus }))} | ${cell(node.note ?? "-")} |`;
+  });
+
+  const graphSection = graph
+    ? `## Work graph\n\n${graph}`
+    : `## Work graph\n\nDependency-independent nodes: ${payload.nodes.map((node) => `\`${node.id}\``).join(", ")}.`;
+
+  const totalsLine = `totals · in ${compactTokens(totals.inputTokens)} · out ${compactTokens(totals.outputTokens)} · cache ${compactTokens(totals.cacheReadInputTokens)} · worker ${formatRole(payload.roles.worker)} · judge ${formatRole(payload.roles.judge)} · cost ${formatCost({ costUsd: totals.costUsd, status: totals.costStatus })}`;
+
+  return [
+    `# Report — ${payload.run}`,
+    "",
+    summary,
+    "",
+    graphSection,
+    "",
+    "## Nodes",
+    "",
+    header,
+    separator,
+    ...rows,
+    "",
+    "## Totals",
+    "",
+    totalsLine,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Write `report.md` (the durable source) and render its portable copy, exactly
+ * as the campaign brief does: the Markdown is always written first, the HTML
+ * only survives a successful build, check and round-trip, and a renderer
+ * failure removes any prior HTML and reports the renderer's named code. The
+ * text path — `renderReport` — is untouched and works without mdhtml.
+ *
+ * @param {string} runDir
+ * @param {{mdhtmlBin?: string, cwd?: string, renderHtml?: (markdown: string, options: import("./campaign-brief-html.mjs").RenderCampaignBriefHtmlOptions) => import("./campaign-brief-html.mjs").RenderCampaignBriefHtmlResult}} [options]
+ * @returns {{markdownPath: string, htmlPath: string|null, code: string|null}}
+ */
+export function generateReportHtml(runDir, options = {}) {
+  const markdown = renderReportMarkdown(runDir);
+  const markdownPath = join(runDir, REPORT_MD_FILE);
+  const htmlPath = join(runDir, REPORT_HTML_FILE);
+  writeTextAtomic(markdownPath, markdown);
+  const renderHtml = options.renderHtml ?? renderCampaignBriefHtml;
+  try {
+    renderHtml(markdown, { outputPath: htmlPath, title: `Report — ${basename(runDir)}`, mdhtmlBin: options.mdhtmlBin, cwd: options.cwd });
+  } catch (error) {
+    rmSync(htmlPath, { force: true });
+    const code = error instanceof CampaignBriefRenderError ? error.code : "REPORT_HTML_FAILED";
+    return { markdownPath, htmlPath: null, code };
+  }
+  return { markdownPath, htmlPath, code: null };
+}
+
+/**
+ * The contract's per-node `dependsOn`, read tolerantly: `renderReportJson` has
+ * already validated the contract, so this fallback only guards a race where
+ * the file changes between the two reads.
+ *
+ * @param {string} runDir
+ * @returns {Map<string, string[]>}
+ */
+export function readContractDependsOn(runDir) {
+  try {
+    const contract = /** @type {{nodes?: {id?: unknown, dependsOn?: unknown}[]}} */ (JSON.parse(readFileSync(join(runDir, "contract.json"), "utf8")));
+    return new Map((contract.nodes ?? []).map((node) => [
+      String(node.id),
+      Array.isArray(node.dependsOn) ? node.dependsOn.filter((dep) => typeof dep === "string") : [],
+    ]));
+  } catch {
+    return new Map();
+  }
+}
+
+const NODE_COL_WIDTH = 260;
+const NODE_ROW_HEIGHT = 84;
+const NODE_BOX_W = 220;
+const NODE_BOX_H = 56;
+const NODE_MARGIN = 16;
+const NODE_ID_MAX_CHARS = 28;
+
+/** One fill per terminal state, the same earthy palette the brief theme declares. */
+/** @type {Record<string, string | undefined>} */
+export const STATUS_COLOURS = {
+  done: "#556B3F",
+  "no-op": "#556B3F",
+  running: "#D97B4F",
+  pending: "#1F1F1F",
+  blocked: "#B5522A",
+  failed: "#B5522A",
+  exhausted: "#B5522A",
+  stalled: "#B5522A",
+  canceled: "#B5522A",
+};
+
+/**
+ * A node's column is its dependency depth; its row is its position among the
+ * siblings at that depth (the dashboard's own scheme). Exported so the video
+ * scene (`report-video.mjs`) reuses this one layout instead of carrying a
+ * copy.
+ *
+ * @param {GraphNode[]} nodes
+ * @returns {(GraphNode & {depth: number, row: number})[]}
+ */
+export function layoutGraphNodes(nodes) {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const depthCache = new Map();
+  /** @param {string} id @param {Set<string>} seen @returns {number} */
+  const depthOf = (id, seen) => {
+    if (depthCache.has(id)) return /** @type {number} */ (depthCache.get(id));
+    if (seen.has(id)) return 0;
+    seen.add(id);
+    const node = byId.get(id);
+    const deps = (node?.dependsOn ?? []).filter((dep) => byId.has(dep));
+    const depth = deps.length === 0 ? 0 : 1 + Math.max(...deps.map((dep) => depthOf(dep, seen)));
+    depthCache.set(id, depth);
+    return depth;
+  };
+  const rowCounters = new Map();
+  return nodes.map((node) => {
+    const depth = depthOf(node.id, new Set());
+    const row = rowCounters.get(depth) ?? 0;
+    rowCounters.set(depth, row + 1);
+    return { ...node, depth, row };
+  });
+}
+
+/** @param {string} value @returns {string} */
+export function escapeSvgText(value) {
+  return value.replace(/[&<>"']/gu, (ch) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[ch] ?? ch));
+}
+
+/** @param {string} value @param {number} max @returns {string} */
+function truncateOneLine(value, max) {
+  const flat = value.replace(/\s+/gu, " ").trim();
+  return flat.length <= max ? flat : `${flat.slice(0, Math.max(0, max - 1))}…`;
+}