faberun 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {

package/src/cli/brand.mjs

@@ -184,7 +184,8 @@ export function renderUsage() {
     "<resume|cancel> <run-dir> [--detach]",
     "supervise <run-dir> [--detach] [--interval <sec>]",
     "supervise campaign <campaign-id> [--cwd <dir>] [--allow-main]",
-    "<status|report> <run-dir> [--json]",
+    "status <run-dir> [--json]",
+    "report <run-dir> [--json] [--html] [--video]",
     "findings <run-dir>",
     "doctor [<contract.json>] [--cwd <dir>] [--discover] [--json]",
     "setup [--yes] [--no-skill] [--harnesses <a,b>] [--worker <id>] [--judge <id>] [--json]",

package/src/cli.mjs

@@ -16,8 +16,11 @@ import { faberunHome } from "./host/home.mjs";
 import { reassociateProject } from "./cli/project.mjs";
 import { colorLevel, renderBanner, renderUsage, statusToken } from "./cli/brand.mjs";
 import { noTransportWarning } from "./notify/index.mjs";
+import { deliverToSessions, resolveSessionTargets } from "./notify/session.mjs";
 import { renderFindings, renderReport, renderReportJson, renderStatus, renderStatusJson } from "./report/render.mjs";
 import { renderNext, renderNextJson } from "./report/next.mjs";
+import { generateReportHtml } from "./report/report-html.mjs";
+import { generateReportVideo } from "./report/report-video.mjs";
 
 import {
   writeTextAtomic,
@@ -105,7 +108,7 @@ export const COMMAND_OPTIONS = {
   preflight: { static: { type: "boolean" }, json: { type: "boolean" }, "time-verification": { type: "boolean" } },
   validate: {},
   status: { json: { type: "boolean" } },
-  report: { json: { type: "boolean" } },
+  report: { json: { type: "boolean" }, html: { type: "boolean" }, video: { type: "boolean" } },
   findings: {},
   doctor: { cwd: { type: "string" }, json: { type: "boolean" }, discover: { type: "boolean" }, env: { type: "boolean" } },
   models: { probe: { type: "boolean" }, json: { type: "boolean" } },
@@ -278,6 +281,23 @@ function superviseIntervalOf(value) {
   return seconds;
 }
 
+/**
+ * Wake the operator's session with the report artifacts the command just
+ * wrote. Opt-in and lossy, exactly like every other notification: with no
+ * `FABERUN_NOTIFY_SESSION` target nothing is delivered and nothing blocks the
+ * command that already printed the paths.
+ *
+ * @param {{kind: "html"|"video", path: string}[]} artifacts
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {Promise<void>}
+ */
+async function notifyReportArtifacts(artifacts, env) {
+  const targets = resolveSessionTargets(env);
+  if (!targets.length || !artifacts.length) return;
+  const summary = ["🐦 faberun", ...artifacts.map((artifact) => `${artifact.kind === "video" ? "📹" : "📄"} ${artifact.path}`)].join(" · ");
+  await deliverToSessions({ type: "report", summary }, targets, { env });
+}
+
 /**
  * @param {string[]} argv
  * @returns {Promise<void>}
@@ -548,7 +568,37 @@ async function main(argv) {
     return;
   }
   if (command === "report") {
-    process.stdout.write(values.json === true ? renderReportJson(resolve(target)) : renderReport(resolve(target)));
+    const runDir = resolve(target);
+    if (values.json === true) {
+      process.stdout.write(renderReportJson(runDir));
+      return;
+    }
+    if (values.html === true) {
+      const result = generateReportHtml(runDir);
+      if (result.htmlPath === null) {
+        process.stderr.write(`[fail] ${result.code}\n`);
+        process.stdout.write(`[report] markdown · ${result.markdownPath}\n`);
+        process.exitCode = 1;
+        return;
+      }
+      process.stdout.write(`[report] markdown · ${result.markdownPath}\n`);
+      process.stdout.write(`[report] html · ${result.htmlPath}\n`);
+      await notifyReportArtifacts([{ kind: "html", path: result.htmlPath }], process.env);
+      return;
+    }
+    if (values.video === true) {
+      const result = await generateReportVideo(runDir, { env: process.env });
+      process.stdout.write(`[report] narration · ${result.narrationPath}\n`);
+      if (result.videoPath === null) {
+        process.stderr.write(`[fail] ${result.code}\n`);
+        process.exitCode = 1;
+        return;
+      }
+      process.stdout.write(`[report] video · ${result.videoPath}\n`);
+      await notifyReportArtifacts([{ kind: "video", path: result.videoPath }], process.env);
+      return;
+    }
+    process.stdout.write(renderReport(runDir));
     return;
   }
   if (command === "metrics") { process.stdout.write(renderCampaignMetrics(target, values)); return; }

package/src/engine/scheduler.mjs

@@ -38,6 +38,7 @@ import { alreadyNotified, emitNodeAdvisories, notifyQueueFor, notifyQueuesByRun,
 import { detectStalls, invocationAlive, terminateProcess } from "./process.mjs";
 import { transition, writeNode } from "./state.mjs";
 import { render, renderFinalReport, writeFindingsArtifact } from "../report/final.mjs";
+import { generateReportHtml } from "../report/report-html.mjs";
 import { operationNextState, providerReceipts, settleInvocation } from "../run/operations.mjs";
 import { appendUsageRecord, invocationCost, invocationUsage, recordInvocationUsage } from "../run/usage.mjs";
 import { captureNodeScopeBoundaries, checkWorkerScope, emptyScope } from "./scope.mjs";
@@ -203,6 +204,24 @@ function archiveCanceledRunDir(runDir) {
   renameSync(runDir, archivedPath);
 }
 
+/**
+ * The portable report copy, generated at run terminal so the operator always
+ * has a browser-readable report beside `STATUS.md`. Lossy on purpose: a
+ * missing mdhtml or an unreadable run yields no artifact and no error, because
+ * the run's own terminal work is already done and the report must not block it.
+ *
+ * @param {string} runDir
+ * @returns {{kind: "html", path: string}[]}
+ */
+function renderReportHtmlArtifacts(runDir) {
+  try {
+    const result = generateReportHtml(runDir);
+    return result.htmlPath ? [{ kind: "html", path: result.htmlPath }] : [];
+  } catch {
+    return [];
+  }
+}
+
 /**
  * @param {string} contractPath
  * @param {{detachedBootstrap?: boolean, baseRef?: string}} [options]
@@ -752,6 +771,7 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
   renderStatusIfChanged(true, null);
   renderCampaignHandoffSafely(campaign, runsDir, runDir);
   writeFindingsArtifact(runDir, contract, states);
+  const artifacts = renderReportHtmlArtifacts(runDir);
   const failed = [...states.values()].filter((state) => state.status !== "done");
   const runId = basename(runDir);
   const runDedupeKey = `run.terminal:${runId}:${failed.length ? "attention" : "done"}`;
@@ -763,6 +783,7 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
       done: states.size - failed.length,
       total: states.size,
       dedupeKey: runDedupeKey,
+      artifacts,
     });
   }
   // Delivery is lossy: there is no retry budget to wait out, so the controller

package/src/notify/index.mjs

@@ -245,7 +245,7 @@ export const NOTIFY_NO_TRANSPORT_WARNING = "no human notification transport is c
 /** @typedef {Record<string, unknown>} JsonObject */
 /** @typedef {{schemaVersion: number, eventId: string, at: string, type: string, campaignId: string|null, runId: string|null, nodeId: string|null, status: string|null, errorCode: string|null, dedupeKey: string, summary: string}} InboxEntry */
 /** @typedef {{type: string, dedupeKey: string, summary: string, at?: string, campaignId?: string|null, runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}} InboxEvent */
-/** @typedef {{type: "node.terminal"|"run.terminal"|"attention"|"advisory"|"progress", runId: string|null, campaignId?: string|null, nodeId?: string|null, status?: string|null, attempt?: number|null, errorCode?: string|null, done?: number|null, total?: number|null, dedupeKey?: string|null, runDir?: string|null, costUsd?: number|null, summary?: string|null, eventId?: string, editOfMessageId?: string|null}} NotifyEvent */
+/** @typedef {{type: "node.terminal"|"run.terminal"|"attention"|"advisory"|"progress", runId: string|null, campaignId?: string|null, nodeId?: string|null, status?: string|null, attempt?: number|null, errorCode?: string|null, done?: number|null, total?: number|null, dedupeKey?: string|null, runDir?: string|null, costUsd?: number|null, summary?: string|null, eventId?: string, editOfMessageId?: string|null, artifacts?: {kind: "html"|"video", path: string}[]}} NotifyEvent */
 /** @typedef {{id: string, ok: boolean, error?: string, messageId?: string}} TransportOutcome one transport's own outcome, named so the receipt says which took the message; `messageId` is the id a transport receipt named for the message it created or edited */
 /** @typedef {{ok: boolean, error?: string, noTransport?: boolean, messageId?: string, transports?: TransportOutcome[]}} DeliveryResult */
 

package/src/report/campaign-brief.mjs

@@ -425,12 +425,14 @@ function link(path) {
 }
 
 /**
- * Escape a table cell and collapse it to one line.
+ * Escape a table cell and collapse it to one line. Exported so the report's
+ * HTML surface (`report-html.mjs`) shares this one home instead of carrying a
+ * byte-identical copy.
  *
  * @param {string} value
  * @returns {string}
  */
-function cell(value) {
+export function cell(value) {
   return value.replace(/\|/gu, "\\|").replace(/\s+/gu, " ").trim();
 }
 

package/src/report/message.mjs

@@ -124,7 +124,7 @@ export function renderRunProgress(runDir, event) {
   const view = { runDir, runId: event.runId ?? basename(runDir), payload, objectives, snapshots, campaign, label, subject };
 
   const body = event.type === "run.terminal" ? runTerminal(view) : event.type === "attention" ? attention(view) : nodeTerminal(view);
-  const lines = [...body, RULE, footer(view, event.type), ...updateLine(label)];
+  const lines = [...body, ...artifactLines(event.artifacts), RULE, footer(view, event.type), ...updateLine(label)];
   return boundToCeiling(lines);
 }
 
@@ -614,6 +614,18 @@ function formatUsdCompact(value) {
   return formatUsd(value);
 }
 
+/**
+ * The run's readable artifacts, one line each with the glyph the report
+ * command prints beside it. The path is data, not wording, so the line needs
+ * no label and stays out of the operator's language.
+ *
+ * @param {{kind: "html"|"video", path: string}[]|undefined} artifacts
+ * @returns {string[]}
+ */
+function artifactLines(artifacts) {
+  return (artifacts ?? []).map((artifact) => `${artifact.kind === "video" ? "📹" : "📄"} ${artifact.path}`);
+}
+
 /**
  * The delivered bullets are the only block that grows with the run, so they
  * are dropped from the end first when the whole message would exceed the

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))}…`;
+}

package/src/report/report-video.mjs

@@ -0,0 +1,323 @@
+/**
+ * The run report's video boundary: the reading ladder's fourth rung, an
+ * animated explainer. It is programmatic, in the 3Blue1Brown sense — the scene
+ * is a pure function of the report's facts and a time, rendered as SVG frames,
+ * rasterised by librsvg and assembled with ffmpeg around an ElevenLabs
+ * narration — rather than manim, which no machine in the fleet has. The
+ * narration script (text) is the durable source; the mp3 and mp4 are derived
+ * copies, so a missing key, voice, rasteriser or ffmpeg is a named failure that
+ * leaves the script behind and changes nothing else.
+ *
+ * Every seam (the ElevenLabs HTTP call, the rasteriser, ffprobe and ffmpeg) is
+ * injectable, so a test proves the whole pipeline with fakes and never spends
+ * a real synthesis credit.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { NOTIFY_LANG_ENV } from "../notify/index.mjs";
+import { renderReportJson } from "./render.mjs";
+import { escapeSvgText, layoutGraphNodes, readContractDependsOn, STATUS_COLOURS } from "./report-html.mjs";
+import { compactCost } from "../util.mjs";
+import { writeTextAtomic } from "../run/store.mjs";
+
+/** The durable source and its derived copies, beside `STATUS.md` in the run directory. */
+const NARRATION_FILE = "report.narration.txt";
+const VIDEO_FILE = "report.mp4";
+
+/** Video frame rate; the animation is gradual fades, so this is plenty smooth. */
+const FPS = 15;
+const WIDTH = 1280;
+const HEIGHT = 720;
+
+/** @typedef {import("./report-html.mjs").GraphNode} GraphNode */
+/** @typedef {{run: string, summary: string, totals: {costUsd: number|null}, nodes: {id: string, status: string}[]}} VideoPayload */
+/** @typedef {{title: string, nodes: GraphNode[], done: number, total: number, cost: string|null, attention: string[]}} Scene */
+/** @typedef {{apiKey: string, voice: string, model: string}} ElevenLabsOptions */
+/** @typedef {{t: number}} Frame */
+
+/**
+ * A stable error surface for callers and CLI reporting.
+ */
+export class ReportVideoError extends Error {
+  /** @param {string} code @param {string} message @param {{cause?: unknown}} [options] */
+  constructor(code, message, options = {}) {
+    super(message, options);
+    this.name = "ReportVideoError";
+    this.code = code;
+  }
+}
+
+/**
+ * The spoken script, deterministic from the report's own facts, in the
+ * operator's language. The title is the run id; the body names the counts, the
+ * attention nodes and the spend. No model is asked to phrase it — the same
+ * discipline as the watcher's progress line, so the same run yields the same
+ * narration.
+ *
+ * @param {VideoPayload} payload
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+export function buildNarration(payload, env = process.env) {
+  const lang = (env[NOTIFY_LANG_ENV] ?? "").trim() === "en" ? "en" : "pt";
+  const attention = payload.nodes.filter((node) => !QUIET.has(node.status)).map((node) => node.id);
+  const done = doneCount(payload);
+  const cost = payload.totals.costUsd === null ? null : String(payload.totals.costUsd);
+  if (lang === "en") {
+    const attentionLine = attention.length ? `${attention.length} need${attention.length === 1 ? "s" : ""} you: ${attention.join(", ")}.` : "Nothing needs you.";
+    return `Report for run ${payload.run}. ${done} of ${payload.nodes.length} nodes done. ${attentionLine} Total cost: ${cost ?? "unknown"} dollars.`;
+  }
+  const attentionLine = attention.length ? `${attention.length} ${attention.length === 1 ? "nó precisa" : "nós precisam"} de você: ${attention.join(", ")}.` : "Nada precisa de você.";
+  return `Relatório da run ${payload.run}. ${done} de ${payload.nodes.length} nós concluídos. ${attentionLine} Custo total: ${cost ?? "desconhecido"} dólares.`;
+}
+
+/** Node states that wait on a person; everything else is quiet. */
+const QUIET = new Set(["pending", "running", "done", "no-op"]);
+
+/** @param {VideoPayload} payload @returns {number} */
+function doneCount(payload) {
+  return payload.nodes.filter((node) => node.status === "done" || node.status === "no-op").length;
+}
+
+/**
+ * One SVG frame of the scene at a normalised time `t` in [0, 1]. The work
+ * graph builds up node by node in topological order, each fading in with its
+ * status colour, while the title holds and the progress strip and spend
+ * surface near the end. Self-contained: inline colours, no external reference.
+ *
+ * @param {Scene} scene
+ * @param {Frame} frame
+ * @returns {string}
+ */
+export function renderReportSceneSvg(scene, frame) {
+  const t = clamp(frame.t, 0, 1);
+  const titleOpacity = ramp(t, 0.02, 0.08);
+  const footerOpacity = ramp(t, 0.55, 0.08);
+
+  const laidOut = layoutGraphNodes(scene.nodes);
+  const revealOf = revealSchedule(laidOut);
+  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 naturalW = GRAPH_MARGIN * 2 + (maxDepth + 1) * GRAPH_COL_WIDTH;
+  const naturalH = GRAPH_MARGIN * 2 + (maxRow + 1) * GRAPH_ROW_HEIGHT;
+  const regionW = WIDTH - 160;
+  const regionH = 400;
+  const scale = Math.min(regionW / naturalW, regionH / naturalH, 1);
+  const tx = (WIDTH - naturalW * scale) / 2;
+  const ty = 120 + (regionH - naturalH * scale) / 2;
+
+  const byId = new Map(laidOut.map((node) => [node.id, node]));
+  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 + GRAPH_BOX_W;
+      const y1 = from.y + GRAPH_BOX_H / 2;
+      const x2 = to.x;
+      const y2 = to.y + GRAPH_BOX_H / 2;
+      const midX = (x1 + x2) / 2;
+      const opacity = ramp(t, revealOf.get(node.id) ?? 0, FADE);
+      return `<path d="M ${x1} ${y1} C ${midX} ${y1}, ${midX} ${y2}, ${x2} ${y2}" fill="none" stroke="#D97B4F" stroke-width="2" opacity="${opacity}"/>`;
+    })).join("");
+  const boxes = laidOut.map((node, index) => {
+    const { x, y } = posOf(node);
+    const colour = STATUS_COLOURS[node.status] ?? "#1F1F1F";
+    const opacity = ramp(t, revealOf.get(node.id) ?? 0, FADE);
+    const clipId = `clip${index}`;
+    return `<g opacity="${opacity}"><rect x="${x}" y="${y}" width="${GRAPH_BOX_W}" height="${GRAPH_BOX_H}" rx="8" fill="#F4E9D8" stroke="${colour}" stroke-width="2"/><clipPath id="${clipId}"><rect x="${x}" y="${y}" width="${GRAPH_BOX_W}" height="${GRAPH_BOX_H}"/></clipPath><g clip-path="url(#${clipId})"><text x="${x + 10}" y="${y + 24}" font-family="ui-monospace, monospace" font-size="14" fill="#1F1F1F">${escapeSvgText(node.id)}</text><text x="${x + 10}" y="${y + 44}" font-family="ui-sans-serif, sans-serif" font-size="13" fill="${colour}">${escapeSvgText(node.status)}</text></g></g>`;
+  }).join("");
+
+  const barW = WIDTH - 160;
+  const fillW = Math.round((scene.done / Math.max(1, scene.total)) * barW);
+  const statusText = `${scene.done}/${scene.total} · ${scene.cost ?? "-"}`;
+  const attentionText = scene.attention.length ? `⚠ ${scene.attention.join(", ")}` : "";
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${WIDTH} ${HEIGHT}" width="${WIDTH}" height="${HEIGHT}">`
+    + `<rect width="${WIDTH}" height="${HEIGHT}" fill="#F4E9D8"/>`
+    + `<text x="80" y="86" font-family="ui-sans-serif, sans-serif" font-size="40" fill="#1F1F1F" opacity="${titleOpacity}">${escapeSvgText(scene.title)}</text>`
+    + `<g transform="translate(${tx} ${ty}) scale(${scale})">${edges}${boxes}</g>`
+    + `<g opacity="${footerOpacity}">`
+    + `<rect x="80" y="${HEIGHT - 120}" width="${barW}" height="20" rx="10" fill="#1F1F1F" opacity="0.12"/>`
+    + `<rect x="80" y="${HEIGHT - 120}" width="${fillW}" height="20" rx="10" fill="#B5522A"/>`
+    + `<text x="80" y="${HEIGHT - 140}" font-family="ui-sans-serif, sans-serif" font-size="26" fill="#1F1F1F">${escapeSvgText(statusText)}</text>`
+    + (attentionText ? `<text x="80" y="${HEIGHT - 70}" font-family="ui-sans-serif, sans-serif" font-size="22" fill="#B5522A">${escapeSvgText(attentionText)}</text>` : "")
+    + `</g>`
+    + `</svg>`;
+}
+
+const GRAPH_COL_WIDTH = 260;
+const GRAPH_ROW_HEIGHT = 84;
+const GRAPH_BOX_W = 220;
+const GRAPH_BOX_H = 56;
+const GRAPH_MARGIN = 16;
+/** How long one node takes to fade in, in normalised time. */
+const FADE = 0.06;
+
+/**
+ * The reveal instant of each node, in topological order (depth first, then
+ * row): the first fades in at 0.12 and the last at 0.80, leaving a tail for
+ * the counters.
+ *
+ * @param {(GraphNode & {depth: number, row: number})[]} laidOut
+ * @returns {Map<string, number>}
+ */
+function revealSchedule(laidOut) {
+  const order = [...laidOut].sort((a, b) => a.depth - b.depth || a.row - b.row);
+  return new Map(order.map((node, index) => [node.id, 0.12 + 0.68 * (index / Math.max(1, laidOut.length - 1))]));
+}
+
+/** @param {{depth: number, row: number}} node @returns {{x: number, y: number}} */
+function posOf(node) {
+  return { x: GRAPH_MARGIN + node.depth * GRAPH_COL_WIDTH, y: GRAPH_MARGIN + node.row * GRAPH_ROW_HEIGHT };
+}
+
+/** @param {number} t @param {number} start @param {number} dur @returns {number} */
+function ramp(t, start, dur) {
+  return clamp((t - start) / dur, 0, 1);
+}
+
+/** @param {number} v @param {number} lo @param {number} hi @returns {number} */
+function clamp(v, lo, hi) {
+  return Math.max(lo, Math.min(hi, v));
+}
+
+/**
+ * Synthesize the narration as MP3 bytes through ElevenLabs. The key is read
+ * from the environment, never stored; the request carries it only as a header.
+ *
+ * @param {string} text
+ * @param {ElevenLabsOptions} options
+ * @param {{fetch?: typeof fetch}} [io]
+ * @returns {Promise<Buffer>}
+ */
+export async function synthesizeSpeech(text, options, io = {}) {
+  const fetchImpl = io.fetch ?? fetch;
+  const url = `https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(options.voice)}`;
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "xi-api-key": options.apiKey, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text,
+        model_id: options.model,
+        voice_settings: { stability: 0.5, similarity_boost: 0.75 },
+      }),
+    });
+  } catch (error) {
+    throw new ReportVideoError("VIDEO_TTS_FAILED", `ElevenLabs request failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (!response.ok) {
+    throw new ReportVideoError("VIDEO_TTS_FAILED", `ElevenLabs returned HTTP ${response.status}`);
+  }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (bytes.length === 0) throw new ReportVideoError("VIDEO_TTS_FAILED", "ElevenLabs returned no audio");
+  return bytes;
+}
+
+/** @param {string} command @param {string[]} args @returns {import("node:child_process").SpawnSyncReturns<string>} */
+function spawnRun(command, args) {
+  return spawnSync(command, args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+}
+
+/**
+ * The duration of the narration in milliseconds, read by ffprobe so the frames
+ * fill exactly the audio.
+ *
+ * @param {string} audioPath
+ * @param {(command: string, args: string[]) => import("node:child_process").SpawnSyncReturns<string>} run
+ * @returns {number}
+ */
+function probeDurationMs(audioPath, run) {
+  const result = run("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", audioPath]);
+  const seconds = Number((result.stdout ?? "").trim());
+  if (result.status !== 0 || !Number.isFinite(seconds) || seconds <= 0) {
+    throw new ReportVideoError("VIDEO_PROBE_FAILED", "could not measure the narration duration");
+  }
+  return Math.round(seconds * 1000);
+}
+
+/**
+ * The full pipeline: narration script (durable) → ElevenLabs MP3 → SVG frames
+ * → PNG frames via rsvg-convert → an MP4 via ffmpeg. The script is written
+ * first and survives every later failure; a missing key, voice or tool is a
+ * named code on the result, with any partial video removed, rather than a
+ * throw — the same contract as `generateReportHtml`.
+ *
+ * @param {string} runDir
+ * @param {{apiKey?: string, voice?: string, model?: string, env?: NodeJS.ProcessEnv, synthesize?: typeof synthesizeSpeech, run?: (command: string, args: string[]) => import("node:child_process").SpawnSyncReturns<string>}} options
+ * @returns {Promise<{narrationPath: string, videoPath: string|null, code: string|null}>}
+ */
+export async function generateReportVideo(runDir, options) {
+  const env = options.env ?? process.env;
+  const run = options.run ?? spawnRun;
+  const synthesize = options.synthesize ?? synthesizeSpeech;
+
+  const payload = /** @type {VideoPayload} */ (JSON.parse(renderReportJson(runDir)));
+  const scene = buildScene(runDir, payload);
+  const narration = buildNarration(payload, env);
+  const narrationPath = join(runDir, NARRATION_FILE);
+  const videoPath = join(runDir, VIDEO_FILE);
+  writeTextAtomic(narrationPath, narration);
+
+  try {
+    const apiKey = options.apiKey || env.ELEVENLABS_API_KEY || "";
+    const voice = options.voice || env.ELEVENLABS_VOICE || "";
+    if (!apiKey) throw new ReportVideoError("VIDEO_KEY_MISSING", "ELEVENLABS_API_KEY is not set");
+    if (!voice) throw new ReportVideoError("VIDEO_VOICE_MISSING", "ELEVENLABS_VOICE is not set");
+
+    const audio = await synthesize(narration, { apiKey, voice, model: options.model ?? "eleven_multilingual_v2" });
+    const stage = mkdtempSync(join(tmpdir(), "report-video-"));
+    try {
+      const audioPath = join(stage, "narration.mp3");
+      writeFileSync(audioPath, audio);
+      const durationMs = probeDurationMs(audioPath, run);
+      const frameCount = Math.max(2, Math.round((durationMs / 1000) * FPS));
+      const framesDir = join(stage, "frames");
+      mkdirSync(framesDir, { recursive: true });
+      for (let i = 0; i < frameCount; i += 1) {
+        const svg = renderReportSceneSvg(scene, { t: frameCount === 1 ? 1 : i / (frameCount - 1) });
+        const base = join(framesDir, `frame-${String(i).padStart(4, "0")}`);
+        writeFileSync(`${base}.svg`, svg, "utf8");
+        const raster = run("rsvg-convert", ["-w", String(WIDTH), "-h", String(HEIGHT), `${base}.svg`, "-o", `${base}.png`]);
+        if (raster.status !== 0) throw new ReportVideoError("VIDEO_RASTER_FAILED", `rsvg-convert failed: ${raster.stderr || raster.stdout}`);
+      }
+      const assemble = run("ffmpeg", [
+        "-y", "-framerate", String(FPS), "-i", join(framesDir, "frame-%04d.png"),
+        "-i", audioPath, "-shortest", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", videoPath,
+      ]);
+      if (assemble.status !== 0) throw new ReportVideoError("VIDEO_ASSEMBLE_FAILED", `ffmpeg failed: ${assemble.stderr || assemble.stdout}`);
+      return { narrationPath, videoPath, code: null };
+    } finally {
+      rmSync(stage, { recursive: true, force: true });
+    }
+  } catch (error) {
+    rmSync(videoPath, { force: true });
+    const code = error instanceof ReportVideoError ? error.code : "REPORT_VIDEO_FAILED";
+    return { narrationPath, videoPath: null, code };
+  }
+}
+
+/**
+ * The scene the frames render from: the report's graph, its counts, its spend
+ * and the nodes that wait on a person.
+ *
+ * @param {string} runDir
+ * @param {VideoPayload} payload
+ * @returns {Scene}
+ */
+function buildScene(runDir, payload) {
+  const dependsOn = readContractDependsOn(runDir);
+  const nodes = payload.nodes.map((node) => ({ id: node.id, status: node.status, dependsOn: dependsOn.get(node.id) ?? [] }));
+  return {
+    title: payload.run,
+    nodes,
+    done: doneCount(payload),
+    total: payload.nodes.length,
+    cost: typeof payload.totals.costUsd === "number" ? compactCost(payload.totals.costUsd) : null,
+    attention: payload.nodes.filter((node) => !QUIET.has(node.status)).map((node) => node.id),
+  };
+}

package/src/web/server.mjs

@@ -440,6 +440,7 @@ export async function startServer({ runsDir, tokenFile, port = 4173, host = "127
       if (asset) return sendFile(response, join(HERE, asset.file), asset.type);
       if (url.pathname === "/api/snapshot") return sendJson(response, buildSnapshot(runsDir, selectionOf(url)));
       if (url.pathname === "/api/stream") return streamSnapshots(request, response, runsDir, selectionOf(url), pollMs);
+      if (url.pathname === "/api/artifact") return serveRunArtifact(response, url, runsDir);
       if (url.pathname.startsWith("/api/")) {
         // A phone client that hangs up mid-request must not take the daemon
         // down as an unhandled rejection; the router catches its own errors,
@@ -536,6 +537,37 @@ function sendFile(response, path, type) {
   response.end(readFileSync(path));
 }
 
+/** The exact run artifacts the dashboard serves; the name is the allowlist. */
+const ARTIFACT_TYPES = {
+  "report.md.html": "text/html; charset=utf-8",
+  "report.mp4": "video/mp4",
+};
+
+/**
+ * Serve one run's report artifact behind the same bearer check as every other
+ * route. `run` is a bare run directory name and `file` one of the two names the
+ * report commands write, so nothing else under the runs root is reachable.
+ *
+ * @param {import("node:http").ServerResponse} response
+ * @param {URL} url
+ * @param {string} runsDir
+ */
+function serveRunArtifact(response, url, runsDir) {
+  const run = url.searchParams.get("run") ?? "";
+  const file = url.searchParams.get("file") ?? "";
+  const type = /** @type {Record<string, string>} */ (ARTIFACT_TYPES)[file];
+  if (!type || !/^[A-Za-z0-9_.-]+$/.test(run) || run === "." || run === "..") return notFound(response);
+  const artifactPath = join(runsDir, run, file);
+  if (!existsSync(artifactPath)) return notFound(response);
+  sendFile(response, artifactPath, type);
+}
+
+/** @param {import("node:http").ServerResponse} response */
+function notFound(response) {
+  response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+  response.end("not found");
+}
+
 /** @param {import("node:http").ServerResponse} response @param {unknown} payload */
 function sendJson(response, payload) {
   response.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });