agent-horde 0.1.5 → 0.2.0

package/src/dashboard-html.ts

@@ -20,25 +20,47 @@ import type {
   RunIndexVm,
   RunOverviewVm,
   SessionsVm,
+  SwarmGraphVm,
+  SwarmHorde,
+  SwarmLedgerVm,
+  SwarmVm,
   TranscriptEntryVm,
   TranscriptVm,
 } from "./dashboard-data.js";
-import { RUN_FILES } from "./dashboard-data.js";
+import { RUN_FILES, SWARM_FILES } from "./dashboard-data.js";
+import { buildInfo } from "./build-info.js";
 import { detailKey, formatClock, formatElapsed, formatTokens, oneLine } from "./format.js";
 import { renderRunGraphMermaid } from "./run-graph-mermaid.js";
 import { GRAPH_CSS, graphLegendHtml, renderRunGraphSvg } from "./run-graph-svg.js";
 import type { TranscriptEntry, TranscriptPart } from "./session-log.js";
 
+/**
+ * What a page is about, fixed by its URL: the ledgers single runs share (`/`, `/findings`), one run
+ * (`/runs/<id>/...`), or a whole swarm (`/swarms/<id>/...`). A horde of a swarm is a run scope that
+ * also knows its swarm, so the nav can offer the sibling hordes. Every scoped link derives from this.
+ */
+export type Scope =
+  | { kind: "project" }
+  | { kind: "run"; runId: string; swarm?: { id: string; hordes: SwarmHorde[] } | undefined }
+  | { kind: "swarm"; swarmId: string; hordes: SwarmHorde[] };
+
+/** The page types every scope offers in the page row; `other` is a run-only page such as a transcript. */
+export type PageKind =
+  | "overview" | "ideas" | "board" | "findings" | "claims" | "facts" | "resources" | "collaboration" | "graph" | "other";
+
 /** Per-request facts the renderers need beyond the view model. */
 export interface RenderContext {
   href?: string;
-  runId?: string | undefined;
-  activeId?: string | undefined;
+  scope?: Scope | undefined;
+  pageKind?: PageKind | undefined;
+  /**
+   * A swarm in memory, set on project pages only: its hordes write their own ledgers, so the
+   * project page points at the same page in the swarm. `finishing` once no horde is running.
+   */
+  liveSwarm?: { id: string; finishing: boolean } | undefined;
   refresh?: { on: boolean; toggleHref: string; seconds: number } | undefined;
   /** Scheme and host of the request, for exports that need absolute links. */
   origin?: string | undefined;
-  /** The run the collaboration and graph links target: this page's run, else the newest. */
-  navRun?: string | undefined;
   /** Rendering for the static export: no refresh, no export control, native disclosure. */
   export?: boolean | undefined;
 }
@@ -53,8 +75,8 @@ const CSS =
   "table{border-collapse:collapse;margin:4px 0}" +
   "th,td{border:1px solid #000;padding:2px 6px;vertical-align:top;text-align:left}" +
   "th{background:#eee}pre{white-space:pre-wrap;word-break:break-word;margin:0}" +
-  "nav a{margin-right:8px}.r{text-align:right}h1,h2{font-size:13px;margin:8px 0 4px}" +
-  "details>summary{cursor:pointer}a{color:#000}" +
+  "nav{margin:2px 0}nav a,nav b{margin-right:8px}.scope{margin:2px 0}.scope a,.scope b{margin-right:6px}.pointer{border:1px solid #000;padding:2px 6px;display:inline-block}.r{text-align:right}h1,h2{font-size:13px;margin:8px 0 4px}" +
+  "details>summary{cursor:pointer}a{color:#000}footer{margin-top:16px;color:#666}footer a{color:#666}" +
   ".export{position:absolute;top:8px;right:8px;line-height:0}" +
   ".modal{display:none;position:fixed;inset:0;background:rgba(0,0,0,.7)}" +
   ".modal:target{display:flex;align-items:center;justify-content:center}" +
@@ -122,21 +144,92 @@ function memberHref(runId: string, member: string): string {
   return `${runHref(runId)}/members/${encodeURIComponent(member)}`;
 }
 
-function runLinks(run: string | undefined): string {
-  if (!run) return "";
-  return link(`${runHref(run)}/collaboration`, "collaboration") + link(`${runHref(run)}/graph`, "graph");
+function swarmHref(swarmId: string): string {
+  return `/swarms/${encodeURIComponent(swarmId)}`;
 }
 
-function nav(ctx: RenderContext): string {
-  const run = ctx.runId ?? ctx.activeId;
-  const q = run ? query({ run }) : "";
+/** The path every scoped link starts from: `` for the project, `/runs/<id>`, or `/swarms/<id>`. */
+function scopeBase(scope: Scope | undefined): string {
+  if (scope?.kind === "run") return runHref(scope.runId);
+  if (scope?.kind === "swarm") return swarmHref(scope.swarmId);
+  return "";
+}
+
+/** The run a page's member names link into; none in the project or swarm scope. */
+function scopeRunId(ctx: RenderContext): string | undefined {
+  return ctx.scope?.kind === "run" ? ctx.scope.runId : undefined;
+}
+
+const LEDGER_PAGES = ["ideas", "board", "findings", "claims", "facts", "resources"] as const;
+
+/** The project scope has its ledgers only; a run or swarm also has an overview, collaboration and graph. */
+function pagesOf(scope: Scope | undefined): PageKind[] {
+  return scope === undefined || scope.kind === "project"
+    ? [...LEDGER_PAGES]
+    : ["overview", ...LEDGER_PAGES, "collaboration", "graph"];
+}
+
+/** The same page type under another base; pages a scope does not share fall back to its overview. */
+function pageHref(base: string, kind: PageKind | undefined): string {
+  if (kind === undefined || kind === "overview" || kind === "other") return base || "/";
+  return `${base}/${kind}`;
+}
+
+/** The current item is shown, not linked. */
+function navItem(href: string, text: string, current: boolean): string {
+  return current ? `<b>${e(text)}</b>` : link(href, text);
+}
+
+/** `all | h1 | h2 ...` for a swarm or one of its hordes; each tab keeps the page type. */
+function hordeTabs(swarmId: string, hordes: SwarmHorde[], current: string | undefined, kind: PageKind | undefined): string {
+  const tabs = [
+    navItem(pageHref(swarmHref(swarmId), kind), "all", current === undefined),
+    ...hordes.map((horde) => navItem(pageHref(runHref(horde.runId), kind), horde.label, horde.runId === current)),
+  ];
+  return ` hordes: ${tabs.join(" ")}`;
+}
+
+/** On a project page while a swarm is live: where the swarm's activity is, on the same page type. */
+function swarmPointer(ctx: RenderContext): string {
+  const swarm = ctx.liveSwarm;
+  if (!swarm) return "";
+  const target = ctx.pageKind === undefined || ctx.pageKind === "overview" || ctx.pageKind === "other"
+    ? "the swarm"
+    : `the swarm's ${ctx.pageKind}`;
   return (
-    `<nav>${link("/", "runs")}${link("/ideas", "ideas")}${link(`/board${q}`, "board")}` +
-    `${link(`/findings${q}`, "findings")}${link("/claims", "claims")}${link(`/facts${q}`, "facts")}` +
-    `${link("/resources", "resources")}${runLinks(ctx.navRun ?? run)}</nav>`
+    `<p class="pointer">swarm ${e(swarm.id)} is ${swarm.finishing ? "finishing" : "running"} in its own ledgers, ` +
+    `not these: ${link(pageHref(swarmHref(swarm.id), ctx.pageKind), target)}</p>`
   );
 }
 
+/** The scope line: what this page is about, and inside a swarm the tabs to move between hordes. */
+function scopeLine(ctx: RenderContext): string {
+  const scope = ctx.scope;
+  if (scope === undefined || scope.kind === "project") {
+    return `<p class="scope">scope: <b>project</b></p>${swarmPointer(ctx)}`;
+  }
+  if (scope.kind === "swarm") {
+    return `<p class="scope">scope: <b>swarm ${e(scope.swarmId)}</b>${hordeTabs(scope.swarmId, scope.hordes, undefined, ctx.pageKind)}</p>`;
+  }
+  if (!scope.swarm) return `<p class="scope">scope: <b>run ${e(scope.runId)}</b></p>`;
+  const horde = scope.swarm.hordes.find((h) => h.runId === scope.runId)?.label ?? "horde";
+  return (
+    `<p class="scope">scope: ${link(swarmHref(scope.swarm.id), `swarm ${scope.swarm.id}`)} &rsaquo; <b>${e(horde)}</b>` +
+    `${hordeTabs(scope.swarm.id, scope.swarm.hordes, scope.runId, ctx.pageKind)}</p>`
+  );
+}
+
+/**
+ * Three rows: `runs` to the index, the scope line, and the page row. Every link in the page row is
+ * built from the page's own scope, so nothing silently points at some other run.
+ */
+function nav(ctx: RenderContext): string {
+  const base = scopeBase(ctx.scope);
+  const pages = pagesOf(ctx.scope).map((kind) => navItem(pageHref(base, kind), kind, kind === ctx.pageKind));
+  const onIndex = (ctx.href ?? "").split("?")[0] === "/";
+  return `<nav>${navItem("/", "runs", onIndex)}</nav>${scopeLine(ctx)}<nav>${pages.join("")}</nav>`;
+}
+
 /** An id cell that deep links, including the run graph, can target. */
 function anchor(id: string): string {
   return `<span id="${e(id)}">${e(id)}</span>`;
@@ -154,21 +247,37 @@ function messageThread(m: PeerMessage): string {
   return lines.join("\n");
 }
 
-export function renderCollaboration(vm: CollaborationVm, ctx: RenderContext): string {
+/** Acceptance, requests, artifacts, reviews, resources and metrics; the event audit only on a run's own page. */
+function collaborationBody(vm: CollaborationVm, withAudit: boolean): string {
   const { report } = vm;
   const { state } = report;
   const messages = table(["request", "owner", "state / age", "target", "question / response"], state.messages.map((m) => [
     anchor(m.id), e(`${m.sender} -> ${m.to}`), e(`${m.state}${m.blocking ? " BLOCKING" : ""} / ${formatElapsed(Date.now() - Date.parse(m.createdAt))}`),
     e(`${m.target}@${m.revision}`), pre(messageThread(m)),
   ]));
-  const reviews = table(["review", "target revision", "verdict", "scope / evidence"], state.reviews.map((r) => [`${anchor(r.id)} @${e(r.actor)}`, e(`${r.target}@${r.revision}`), e(`${r.verdict} [${r.support}]`), pre(`Checked: ${r.checked}\nUnchecked: ${r.unchecked || "none declared"}\nEvidence: ${r.evidence.join(", ")}\n${r.text}`)]));
+  const reviews = table(["review", "target revision", "verdict", "scope / evidence"], state.reviews.map((r) => [`${anchor(r.id)} @${e(r.actor)}`, e(`${r.target}@${r.revision}`), e(`${r.verdict} [${r.support}]`), pre(`Checked: ${r.checked}\nUnchecked: ${r.unchecked || "none declared"}\nLimits: ${r.limits || "none disclosed"}\nEvidence: ${r.evidence.join(", ")}${r.reattests ? `\nReattests: ${r.reattests}` : ""}\n${r.text}`)]));
   const artifacts = table(["artifact", "hash / dependencies", "acceptance"], state.artifacts.map((a) => [`${anchor(a.id)} ${e(`${a.path} @${a.owner} (${a.kind ?? "runnable"})`)}`, pre(`${a.hash}\n${JSON.stringify(a.dependencies)}`), e(report.acceptedArtifacts.includes(a.id) ? "accepted" : "excluded / needs review")]));
-  const events = vm.events.map((event) => `<div id="${e(event.eventId)}">${details(`${event.eventId} ${event.at} ${event.actor}/${event.attempt} ${event.action} ${event.outcome}`, pre(JSON.stringify(event, null, 2)), `event:${report.runId}:${event.eventId}`)}</div>`).join("");
-  return page(`Collaboration ${report.runId}`, [{ text: "runs", href: "/" }, { text: report.runId, href: runHref(report.runId) }, { text: "collaboration" }],
+  const summary =
     (vm.historical ? "<p>Historical run: no delivery/revision history was recorded.</p>" : "") +
     `<h2>Acceptance issues</h2>${pre(report.issues.join("\n") || "none recorded")}<h2>Requests</h2>${messages}<h2>Artifacts</h2>${artifacts}<h2>Reviews</h2>${reviews}` +
-    `<h2>Resource readiness and leases</h2>${pre(JSON.stringify(state.resources, null, 2))}<h2>Metrics</h2>${pre(JSON.stringify(report.metrics, null, 2))}<h2>Event audit</h2>${events}` +
-    (vm.next !== undefined ? link(`${runHref(report.runId)}/collaboration?from=${vm.next}`, "next 100 events") : ""), ctx);
+    `<h2>Resource readiness and leases</h2>${pre(JSON.stringify(state.resources, null, 2))}<h2>Metrics</h2>${pre(JSON.stringify(report.metrics, null, 2))}`;
+  if (!withAudit) {
+    return `${summary}<p>${link(`${runHref(report.runId)}/collaboration`, "event audit")} on the horde's own page</p>`;
+  }
+  const events = vm.events.map((event) => `<div id="${e(event.eventId)}">${details(`${event.eventId} ${event.at} ${event.actor}/${event.attempt} ${event.action} ${event.outcome}`, pre(JSON.stringify(event, null, 2)), `event:${report.runId}:${event.eventId}`)}</div>`).join("");
+  return `${summary}<h2>Event audit</h2>${events}` +
+    (vm.next !== undefined ? link(`${runHref(report.runId)}/collaboration?from=${vm.next}`, "next 100 events") : "");
+}
+
+export function renderCollaboration(vm: CollaborationVm, ctx: RenderContext): string {
+  const runId = vm.report.runId;
+  const crumbs = [{ text: "runs", href: "/" }, { text: runId, href: runHref(runId) }, { text: "collaboration" }];
+  return page(`Collaboration ${runId}`, crumbs, collaborationBody(vm, true), ctx);
+}
+
+/** Each horde's acceptance, requests and reviews, under per-horde headings. */
+export function renderSwarmCollaboration(vm: SwarmLedgerVm<CollaborationVm>, ctx: RenderContext): string {
+  return swarmLedgerPage("collaboration", vm, (section) => collaborationBody(section, false), ctx);
 }
 
 function crumbLine(crumbs: Crumb[]): string {
@@ -230,13 +339,20 @@ function nativeDetails(body: string): string {
   return body.replace(/<details data-expand="[a-f0-9]+">/g, "<details>");
 }
 
+/** Which agent-horde produced the page: the package version and, from a checkout, the commit. */
+function footer(): string {
+  const { name, version, commit, repository } = buildInfo();
+  const at = commit ? ` at ${repository ? link(`${repository}/commit/${commit.replace(/-dirty$/, "")}`, commit) : e(commit)}` : "";
+  return `<footer>${e(name)} ${e(version)}${at}</footer>`;
+}
+
 export function page(title: string, crumbs: Crumb[], body: string, ctx: RenderContext, head = ""): string {
   body = ctx.export ? nativeDetails(body) : persistentDetails(body, ctx.href);
   const meta = ctx.refresh?.on ? `<meta http-equiv="refresh" content="${ctx.refresh.seconds}">` : head;
   return (
     `<!doctype html><html><head><meta charset="utf-8"><title>${e(title)}</title>${meta}` +
     `<style>${CSS}</style></head><body>${exportControl(ctx)}${nav(ctx)}${crumbLine(crumbs)}${refreshLine(ctx)}` +
-    `<h1>${e(title)}</h1>${body}</body></html>`
+    `<h1>${e(title)}</h1>${body}${footer()}</body></html>`
   );
 }
 
@@ -261,10 +377,31 @@ function cost(value: number): string {
   return `$${value.toFixed(4)}`;
 }
 
+/** The state column: a live run stands out; pending, finalizing, finished and not started read as written. */
+function stateCell(state: string): string {
+  return state === "active" ? "<b>ACTIVE</b>" : e(state);
+}
+
+function swarmIndexTable(vm: RunIndexVm): string {
+  if (vm.swarms.length === 0) return "";
+  const rows = vm.swarms.map((swarm) => [
+    link(swarmHref(swarm.id), swarm.id),
+    stateCell(swarm.state),
+    e(swarm.started ?? ""),
+    `${swarm.hordes} x ${num(swarm.count) || "?"}`,
+    e(swarm.outcomes.map((outcome, index) => `h${index + 1} ${outcome || "?"}`).join(", ")),
+    e(oneLine(swarm.prompt, 100)),
+    ...SWARM_FILES.map((name) => yn(swarm.files[name])),
+  ]);
+  const headers = ["swarm", "state", "started", "hordes", "outcomes", "prompt", ...SWARM_FILES.map((n) => n.toLowerCase())];
+  return `<h2>swarms</h2>${table(headers, rows)}<h2>runs</h2>`;
+}
+
 export function renderRunIndex(vm: RunIndexVm, ctx: RenderContext): string {
   const rows = vm.runs.map((run) => [
     link(runHref(run.id), run.id),
-    run.active ? "<b>ACTIVE</b>" : run.finalizing ? "finalizing" : "finished",
+    run.swarm ? link(swarmHref(run.swarm), run.swarm) : "",
+    stateCell(run.state),
     e(run.started ?? ""),
     num(run.count),
     e(run.model ?? ""),
@@ -272,8 +409,8 @@ export function renderRunIndex(vm: RunIndexVm, ctx: RenderContext): string {
     e(oneLine(run.prompt, 100)),
     ...RUN_FILES.map((name) => yn(run.files[name])),
   ]);
-  const headers = ["run", "state", "started", "members", "model", "outcome", "prompt", ...RUN_FILES.map((n) => n.toLowerCase())];
-  return page("horde runs", [{ text: "runs" }], table(headers, rows, "no runs in .horde/runs"), ctx);
+  const headers = ["run", "swarm", "state", "started", "members", "model", "outcome", "prompt", ...RUN_FILES.map((n) => n.toLowerCase())];
+  return page("horde runs", [{ text: "runs" }], swarmIndexTable(vm) + table(headers, rows, "no runs in .horde/runs"), ctx);
 }
 
 function memberRow(runId: string, m: MemberRowVm): string[] {
@@ -523,7 +660,8 @@ export function renderSessions(vm: SessionsVm, ctx: RenderContext): string {
 }
 
 export function renderFile(vm: FileVm, ctx: RenderContext): string {
-  const crumbs = [{ text: "runs", href: "/" }, { text: vm.runId, href: runHref(vm.runId) }, { text: `${vm.name}.md` }];
+  const parent = vm.swarm ? swarmHref(vm.runId) : runHref(vm.runId);
+  const crumbs = [{ text: "runs", href: "/" }, { text: vm.runId, href: parent }, { text: `${vm.name}.md` }];
   const note = vm.truncated ? `<p>showing the first ${vm.content.length} of ${vm.bytes} characters</p>` : "";
   return page(`${vm.name}.md`, crumbs, note + pre(vm.content), ctx);
 }
@@ -540,51 +678,50 @@ function ideaRows(ideas: Idea[], ctx: RenderContext): string[][] {
   return ideas.map((idea) => [
     `<span id="idea-${idea.id}">#${idea.id}</span>`,
     e(idea.text),
-    idea.owner ? authorLink(idea.owner, ctx.activeId) : "",
+    idea.owner ? authorLink(idea.owner, scopeRunId(ctx)) : "",
     e(idea.note ?? ""),
   ]);
 }
 
-export function renderIdeas(vm: IdeasVm, ctx: RenderContext): string {
-  const filters = [
-    vm.owner ? link("/ideas", "all") : "all",
-    ...vm.owners.map((o) => (o === vm.owner ? e(o) : link(`/ideas${query({ owner: o })}`, o))),
-  ];
+function ideasBody(vm: IdeasVm, ctx: RenderContext): string {
   const sections: Array<[string, Idea[]]> = [
     ["in progress", vm.inProgress], ["open", vm.open], ["done", vm.done], ["ruled out", vm.ruledOut],
   ];
-  const body =
-    `<p>owner: ${filters.join(" ")}</p>` +
-    sections
-      .map(([title, ideas]) => `<h2>${e(title)} (${ideas.length})</h2>${table(["id", "idea", "owner", "note"], ideaRows(ideas, ctx))}`)
-      .join("");
-  return page("ideas", [{ text: "ideas" }], body, ctx);
+  return sections
+    .map(([title, ideas]) => `<h2>${e(title)} (${ideas.length})</h2>${table(["id", "idea", "owner", "note"], ideaRows(ideas, ctx))}`)
+    .join("");
 }
 
-function runPicker(base: string, current: string, runs: string[], extra: Record<string, string | undefined>): string {
-  const items = ["all", ...runs].map((run) =>
-    run === current ? e(run) : link(`${base}${query({ ...extra, run })}`, run),
-  );
-  return `<p>run: ${items.join(" ")}</p>`;
+export function renderIdeas(vm: IdeasVm, ctx: RenderContext): string {
+  const base = `${scopeBase(ctx.scope)}/ideas`;
+  const filters = [
+    vm.owner ? link(base, "all") : "all",
+    ...vm.owners.map((o) => (o === vm.owner ? e(o) : link(`${base}${query({ owner: o })}`, o))),
+  ];
+  return page("ideas", [{ text: "ideas" }], `<p>owner: ${filters.join(" ")}</p>${ideasBody(vm, ctx)}`, ctx);
 }
 
-export function renderBoard(vm: BoardVm, ctx: RenderContext): string {
-  const other = vm.order === "newest" ? "oldest" : "newest";
+function boardBody(vm: BoardVm, ctx: RenderContext): string {
   const rows = vm.entries.map((entry: BoardEntry) => [
     entry.runId ? link(runHref(entry.runId), entry.runId) : "",
     e(entry.time),
-    authorLink(entry.author, entry.runId || ctx.activeId),
+    authorLink(entry.author, entry.runId || scopeRunId(ctx)),
     pre(entry.text),
   ]);
+  return table(["run", "time", "author", "message"], rows, "no posts");
+}
+
+export function renderBoard(vm: BoardVm, ctx: RenderContext): string {
+  const other = vm.order === "newest" ? "oldest" : "newest";
   const body =
-    runPicker("/board", vm.run, vm.runs, { order: vm.order }) +
-    `<p>order: ${vm.order} ${link(`/board${query({ run: vm.run, order: other })}`, `[${other} first]`)}</p>` +
-    table(["run", "time", "author", "message"], rows, "no posts");
+    `<p>order: ${vm.order} ${link(`${scopeBase(ctx.scope)}/board${query({ order: other })}`, `[${other} first]`)}</p>` +
+    boardBody(vm, ctx);
   return page("board", [{ text: "board" }], body, ctx);
 }
 
-function findingsHref(vm: FindingsVm, open: number[]): string {
-  return `/findings${query({ run: vm.run, view: vm.view, open: open.length > 0 ? open.join(",") : undefined })}`;
+/** The findings page of the scope this finding is shown in, with a body opened or closed. */
+function findingsHref(vm: FindingsVm, ctx: RenderContext, open: number[]): string {
+  return `${scopeBase(ctx.scope)}/findings${query({ view: vm.view, open: open.length > 0 ? open.join(",") : undefined })}`;
 }
 
 /** The body is expanded when its id is in the URL, so the state survives auto-refresh; the export shows it inline. */
@@ -592,13 +729,14 @@ function findingBody(f: FindingEntry, vm: FindingsVm, ctx: RenderContext): strin
   if (!f.body) return "";
   if (ctx.export) return pre(f.body);
   if (vm.open.includes(f.id)) {
-    return pre(f.body) + link(findingsHref(vm, vm.open.filter((id) => id !== f.id)), "[hide body]");
+    return pre(f.body) + link(findingsHref(vm, ctx, vm.open.filter((id) => id !== f.id)), "[hide body]");
   }
-  return ` ${link(findingsHref(vm, [...vm.open, f.id]), "[show body]")}`;
+  return ` ${link(findingsHref(vm, ctx, [...vm.open, f.id]), "[show body]")}`;
 }
 
 function findingRow(f: FindingEntry, vm: FindingsVm, ctx: RenderContext): string[] {
-  const idea = f.ideaId === undefined ? "" : link(`/ideas#idea-${f.ideaId}`, `#${f.ideaId}`);
+  const ideas = f.runId ? `${runHref(f.runId)}/ideas` : "/ideas";
+  const idea = f.ideaId === undefined ? "" : link(`${ideas}#idea-${f.ideaId}`, `#${f.ideaId}`);
   const authors = [f.author, ...f.corroborators].map((a) => authorLink(a, f.runId)).join(", ");
   const title = (f.supersededBy !== undefined ? "<b>SUPERSEDED</b> " : "") + e(f.title);
   return [
@@ -623,83 +761,138 @@ const FINDING_HEADERS = [
   "superseded by", "review status", "title",
 ];
 
+function findingsBody(vm: FindingsVm, ctx: RenderContext): string {
+  if (!vm.clusters) return table(FINDING_HEADERS, vm.findings.map((f) => findingRow(f, vm, ctx)), "no findings");
+  if (vm.clusters.length === 0) return "<p>no findings</p>";
+  return vm.clusters
+    .map((cluster, i) => {
+      const members = cluster.members.join(", ") || "none";
+      const deltas = cluster.deltaMembers.length > 0 ? `; deltas ${cluster.deltaMembers.join(", ")}` : "";
+      return (
+        `<h2>cluster ${i + 1}: F${cluster.representative}, members ${e(members)}${e(deltas)}</h2>` +
+        table(FINDING_HEADERS, cluster.findings.map((f) => findingRow(f, vm, ctx)))
+      );
+    })
+    .join("");
+}
+
 export function renderFindings(vm: FindingsVm, ctx: RenderContext): string {
   const other = vm.view === "list" ? "clusters" : "list";
   const open = vm.open.length > 0 ? vm.open.join(",") : undefined;
-  let body =
-    runPicker("/findings", vm.run, vm.runs, { view: vm.view, open }) +
-    `<p>view: ${vm.view} ${link(`/findings${query({ run: vm.run, view: other, open })}`, `[${other}]`)}</p>`;
-  if (vm.clusters) {
-    body += vm.clusters
-      .map((cluster, i) => {
-        const members = cluster.members.join(", ") || "none";
-        const deltas = cluster.deltaMembers.length > 0 ? `; deltas ${cluster.deltaMembers.join(", ")}` : "";
-        return (
-          `<h2>cluster ${i + 1}: F${cluster.representative}, members ${e(members)}${e(deltas)}</h2>` +
-          table(FINDING_HEADERS, cluster.findings.map((f) => findingRow(f, vm, ctx)))
-        );
-      })
-      .join("");
-    if (vm.clusters.length === 0) body += "<p>no findings</p>";
-  } else {
-    body += table(FINDING_HEADERS, vm.findings.map((f) => findingRow(f, vm, ctx)), "no findings");
-  }
+  const body =
+    `<p>view: ${vm.view} ${link(`${scopeBase(ctx.scope)}/findings${query({ view: other, open })}`, `[${other}]`)}</p>` +
+    findingsBody(vm, ctx);
   return page("findings", [{ text: "findings" }], body, ctx);
 }
 
-export function renderClaims(vm: ClaimsVm, ctx: RenderContext): string {
+function claimsBody(vm: ClaimsVm, ctx: RenderContext): string {
   const body = vm.groups
     .map(
       (group) =>
         `<h2>${e(group.state)} (${group.claims.length})</h2>` +
         table(
           ["id", "statement", "owner", "notes"],
-          group.claims.map((c: ClaimEntry) => [anchor(`C${c.id}`), e(c.statement), authorLink(c.owner, ctx.activeId), e(c.notes.join(" | "))]),
+          group.claims.map((c: ClaimEntry) => [anchor(`C${c.id}`), e(c.statement), authorLink(c.owner, scopeRunId(ctx)), e(c.notes.join(" | "))]),
         ),
     )
     .join("");
-  return page("claims", [{ text: "claims" }], body || "<p>no claims</p>", ctx);
+  return body || "<p>no claims</p>";
+}
+
+export function renderClaims(vm: ClaimsVm, ctx: RenderContext): string {
+  return page("claims", [{ text: "claims" }], claimsBody(vm, ctx), ctx);
 }
 
 function factRows(facts: FactEntry[], ctx: RenderContext): string[][] {
   return facts.map((f) => [
     anchor(`T${f.id}`),
     e(f.text),
-    authorLink(f.author, ctx.activeId),
+    authorLink(f.author, scopeRunId(ctx)),
     f.deltaOf === undefined ? "" : `T${f.deltaOf}`,
   ]);
 }
 
-export function renderFacts(vm: FactsVm, ctx: RenderContext): string {
+function factsBody(vm: FactsVm, ctx: RenderContext): string {
   const headers = ["id", "fact", "author", "delta of"];
-  const body =
-    vm.attribution === "split"
-      ? `<h2>this run (${vm.thisRun.length})</h2>${table(headers, factRows(vm.thisRun, ctx))}` +
-        `<h2>carried from earlier runs (${vm.carried.length})</h2>${table(headers, factRows(vm.carried, ctx))}`
-      : `<p>${vm.run ? "per-run attribution is only available for the active run; " : ""}all facts:</p>` +
-        table(headers, factRows(vm.all, ctx), "no facts");
-  return page("facts", [{ text: "facts" }], body, ctx);
+  return vm.attribution === "split"
+    ? `<h2>this run (${vm.thisRun.length})</h2>${table(headers, factRows(vm.thisRun, ctx))}` +
+      `<h2>carried from earlier runs (${vm.carried.length})</h2>${table(headers, factRows(vm.carried, ctx))}`
+    : `<p>${vm.run ? "per-run attribution is only available for the active run; " : ""}all facts:</p>` +
+      table(headers, factRows(vm.all, ctx), "no facts");
 }
 
-export function renderResources(vm: ResourcesVm, ctx: RenderContext): string {
+export function renderFacts(vm: FactsVm, ctx: RenderContext): string {
+  return page("facts", [{ text: "facts" }], factsBody(vm, ctx), ctx);
+}
+
+function resourcesBody(vm: ResourcesVm, ctx: RenderContext): string {
   const rows = vm.resources.map((resource) => [
     anchor(`R${resource.id}`),
     e(resource.name),
-    authorLink(resource.owner, ctx.activeId),
+    authorLink(resource.owner, scopeRunId(ctx)),
     e(resource.note ?? ""),
-    resource.reusers.map((name) => authorLink(name, ctx.activeId)).join(", "),
-    resource.citedBy.map((name) => authorLink(name, ctx.activeId)).join(", "),
+    resource.reusers.map((name) => authorLink(name, scopeRunId(ctx))).join(", "),
+    resource.citedBy.map((name) => authorLink(name, scopeRunId(ctx))).join(", "),
     e(resource.cleanup ?? ""),
   ]);
   const scope = vm.run
     ? `<p>cited by: non-owners whose findings, evidence, reviews or leases name the resource in run ${e(vm.run)}</p>`
     : "<p>cited by: needs an active run; only explicit reclaims are shown</p>";
-  return page(
-    "resources",
-    [{ text: "resources" }],
-    scope + table(["id", "name", "owner", "note", "reused by", "cited by", "cleanup"], rows, "no shared resources claimed"),
-    ctx,
-  );
+  return scope + table(["id", "name", "owner", "note", "reused by", "cited by", "cleanup"], rows, "no shared resources claimed");
+}
+
+export function renderResources(vm: ResourcesVm, ctx: RenderContext): string {
+  return page("resources", [{ text: "resources" }], resourcesBody(vm, ctx), ctx);
+}
+
+// ---------------------------------------------------------------------------
+// Swarm ledgers: every horde's ledger on one page, under per-horde headings
+// ---------------------------------------------------------------------------
+
+/** Render a ledger aggregated across a swarm: one `<h2>hN</h2>` section per horde, ids stay unambiguous. */
+function swarmLedgerPage<T>(
+  kind: string,
+  vm: SwarmLedgerVm<T>,
+  body: (sectionVm: T, ctx: RenderContext) => string,
+  ctx: RenderContext,
+): string {
+  const crumbs: Crumb[] = [{ text: "runs", href: "/" }, { text: `swarm ${vm.swarmId}`, href: swarmHref(vm.swarmId) }, { text: kind }];
+  // Links inside a section (member names, finding bodies, idea anchors) belong to that horde.
+  const sectionCtx = (runId: string): RenderContext => ({ ...ctx, scope: { kind: "run", runId } });
+  const inner =
+    vm.sections.length === 0
+      ? "<p>this swarm has no hordes</p>"
+      : `<p>${kind} across ${vm.sections.length} hordes; ids repeat per horde, so each section is one horde's ledger</p>` +
+        vm.sections
+          .map((section) =>
+            `<h2>${e(section.label)} &mdash; ${link(pageHref(runHref(section.runId), ctx.pageKind), section.runId)}</h2>` +
+            body(section.vm, sectionCtx(section.runId)))
+          .join("");
+  return page(kind, crumbs, inner, ctx);
+}
+
+export function renderSwarmIdeas(vm: SwarmLedgerVm<IdeasVm>, ctx: RenderContext): string {
+  return swarmLedgerPage("ideas", vm, ideasBody, ctx);
+}
+
+export function renderSwarmBoard(vm: SwarmLedgerVm<BoardVm>, ctx: RenderContext): string {
+  return swarmLedgerPage("board", vm, boardBody, ctx);
+}
+
+export function renderSwarmFindings(vm: SwarmLedgerVm<FindingsVm>, ctx: RenderContext): string {
+  return swarmLedgerPage("findings", vm, findingsBody, ctx);
+}
+
+export function renderSwarmClaims(vm: SwarmLedgerVm<ClaimsVm>, ctx: RenderContext): string {
+  return swarmLedgerPage("claims", vm, claimsBody, ctx);
+}
+
+export function renderSwarmFacts(vm: SwarmLedgerVm<FactsVm>, ctx: RenderContext): string {
+  return swarmLedgerPage("facts", vm, factsBody, ctx);
+}
+
+export function renderSwarmResources(vm: SwarmLedgerVm<ResourcesVm>, ctx: RenderContext): string {
+  return swarmLedgerPage("resources", vm, resourcesBody, ctx);
 }
 
 // ---------------------------------------------------------------------------
@@ -746,3 +939,105 @@ export function renderGraph(vm: RunGraphVm, ctx: RenderContext): string {
 export function renderGraphMermaid(vm: RunGraphVm, ctx: RenderContext): string {
   return renderRunGraphMermaid(vm.graph, ctx.origin ?? "");
 }
+
+// ---------------------------------------------------------------------------
+// Swarms
+// ---------------------------------------------------------------------------
+
+const SWARM_HORDE_HEADERS = [
+  "horde", "run", "state", "outcome", "members", "running", "done", "failed", "stopped", "turns", "in", "out",
+  "cost", "findings", "accepted artifacts", "elapsed", "workstream",
+];
+
+function swarmHordeRow(row: SwarmVm["rows"][number]): string[] {
+  return [
+    e(row.label),
+    link(runHref(row.runId), row.runId),
+    stateCell(row.state),
+    e(row.outcome ?? ""),
+    String(row.count),
+    String(row.counts.running + row.counts.starting),
+    String(row.counts.done),
+    String(row.counts.failed),
+    String(row.counts.stopped),
+    String(row.totals.turns),
+    formatTokens(row.totals.input),
+    formatTokens(row.totals.output),
+    cost(row.totals.cost),
+    String(row.findings),
+    String(row.acceptedArtifacts),
+    row.elapsedMs === undefined ? "" : formatElapsed(row.elapsedMs),
+    e(oneLine(row.slice ?? "", 120)),
+  ];
+}
+
+function swarmHeader(vm: SwarmVm): string {
+  const rows: Array<[string, string]> = [
+    ["state", stateCell(vm.state) + (vm.state === "pending" ? " (the planner is partitioning the task, or the launch did not reach the hordes)" : "")],
+    ["prompt", pre(vm.prompt)],
+    ["hordes", `${vm.hordes} x ${vm.count ?? "?"} members`],
+    ["started", e(vm.started ?? "")],
+    ["elapsed", vm.elapsedMs === undefined ? "" : formatElapsed(vm.elapsedMs)],
+    ["until stop", vm.untilStop ? "yes" : "no"],
+    ["merge", e(vm.merge)],
+  ];
+  if (vm.notStarted) rows.push(["not started", e(vm.notStarted)]);
+  if (vm.partition.length > 0) {
+    rows.push(["partition", pre(vm.partition.map((slice, index) => `h${index + 1}: ${slice}`).join("\n"))]);
+  }
+  return grid(rows);
+}
+
+function swarmFiles(vm: SwarmVm): string {
+  const cells = SWARM_FILES.map((name) =>
+    vm.files[name] ? link(`${swarmHref(vm.id)}/files/${name}`, `${name}.md`) : `${name}.md: not yet`,
+  );
+  return `<p>${cells.join(" | ")} | ${link(`${swarmHref(vm.id)}/graph`, "swarm graph")}</p>`;
+}
+
+export function renderSwarm(vm: SwarmVm, ctx: RenderContext): string {
+  const totals = [
+    "<b>total</b>", "", "", "",
+    String(vm.rows.reduce((n, r) => n + r.count, 0)),
+    String(vm.rows.reduce((n, r) => n + r.counts.running + r.counts.starting, 0)),
+    String(vm.rows.reduce((n, r) => n + r.counts.done, 0)),
+    String(vm.rows.reduce((n, r) => n + r.counts.failed, 0)),
+    String(vm.rows.reduce((n, r) => n + r.counts.stopped, 0)),
+    String(vm.rows.reduce((n, r) => n + r.totals.turns, 0)),
+    formatTokens(vm.rows.reduce((n, r) => n + r.totals.input, 0)),
+    formatTokens(vm.rows.reduce((n, r) => n + r.totals.output, 0)),
+    cost(vm.rows.reduce((n, r) => n + r.totals.cost, 0)),
+    String(vm.rows.reduce((n, r) => n + r.findings, 0)),
+    String(vm.rows.reduce((n, r) => n + r.acceptedArtifacts, 0)),
+    "", "",
+  ];
+  const body =
+    swarmHeader(vm) +
+    `<h2>hordes</h2>` +
+    table(SWARM_HORDE_HEADERS, [...vm.rows.map(swarmHordeRow), totals], "no hordes started") +
+    `<h2>files</h2>${swarmFiles(vm)}`;
+  return page(`swarm ${vm.id}`, [{ text: "runs", href: "/" }, { text: `swarm ${vm.id}` }], body, ctx);
+}
+
+function swarmGraphHref(swarmId: string, view: SwarmGraphVm["view"]): string {
+  const seconds = (ms: number): string | undefined => (ms > 0 ? String(Math.round(ms / 1000)) : undefined);
+  return `${swarmHref(swarmId)}/graph${query({ w: String(view.width), from: seconds(view.from), to: seconds(view.to) })}`;
+}
+
+/** One lane per horde with its phases, and the merge step in the swarm lane. */
+export function renderSwarmGraph(vm: SwarmGraphVm, ctx: RenderContext): string {
+  const { graph, view } = vm;
+  const crumbs: Crumb[] = [{ text: "runs", href: "/" }, { text: `swarm ${vm.swarmId}`, href: swarmHref(vm.swarmId) }, { text: "graph" }];
+  if (vm.empty) return page(`swarm graph ${vm.swarmId}`, crumbs, "<p>no events recorded for this swarm's hordes</p>", ctx);
+  const widths = GRAPH_WIDTHS.map((width) =>
+    width === view.width ? String(width) : link(swarmGraphHref(vm.swarmId, { ...view, width }), String(width)),
+  );
+  const summary =
+    `${graph.lanes.length - 1} hordes, ${graph.nodes.length} lifecycle marks, ${formatElapsed(graph.end - graph.start)} elapsed; ` +
+    "each horde's own graph is on its run page";
+  const body =
+    `<p>${e(summary)}</p>` +
+    `<p>width: ${widths.join(" ")}</p>` +
+    `<div class="graph">${renderRunGraphSvg(graph, view)}</div>`;
+  return page(`swarm graph ${vm.swarmId}`, crumbs, body, ctx);
+}