agent-horde 0.1.6 → 0.2.1

package/src/run/synthesis.ts

@@ -2,11 +2,16 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { oneLine } from "../format.js";
 import { childEnv, execPi, getPiInvocation } from "../member.js";
-import type { HordeRun, HordeState } from "./types.js";
+import { parsePlannerOutput } from "./swarm.js";
+import { hordeLabel } from "./types.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
 
 /** How long the post-mortem agent may run. */
 const POSTMORTEM_TIMEOUT_MS = Number(process.env.PI_HORDE_POSTMORTEM_MS) || 300_000;
 
+/** How long the planner that partitions a task between hordes may run. */
+const PLANNER_TIMEOUT_MS = Number(process.env.PI_HORDE_PLANNER_MS) || 300_000;
+
 const POSTMORTEM_SYSTEM_PROMPT =
   "You are a post-mortem reviewer for a multi-agent horde run. You have read-only tools. " +
   "Critique the run and the orchestrating extension, not just the underlying project. Be " +
@@ -17,43 +22,63 @@ const DELIVERABLE_SYSTEM_PROMPT =
   "You are the synthesis member of a horde. You have read-only tools and must produce one " +
   "deliverable that answers the task the horde was given, not a summary of the process.";
 
-type HelperLabel = "post-mortem" | "deliverable";
+const SWARM_DELIVERABLE_SYSTEM_PROMPT =
+  "You are the synthesis member of a swarm of hordes. You have read-only tools and must merge the " +
+  "hordes' deliverables into one deliverable that answers the task, keeping every claim attributed " +
+  "to the horde that made it and to the acceptance status that horde recorded.";
+
+const PLANNER_SYSTEM_PROMPT =
+  "You are the planner for a swarm of agent hordes. You have read-only tools. You partition one task " +
+  "into disjoint workstreams that independent teams can work in parallel without overlapping. You " +
+  "output only the JSON you are asked for.";
+
+type HelperLabel = "post-mortem" | "deliverable" | "swarm deliverable" | "planner";
 
 /** Run a one-shot pi helper and return its output, or a one-line failure text. */
 async function runHelper(
   label: HelperLabel,
   invocation: { command: string; args: string[] },
-  cwd: string,
-  signal: AbortSignal,
-): Promise<string> {
+  options: { cwd: string; signal: AbortSignal; timeoutMs?: number | undefined },
+): Promise<{ text: string; failed: boolean }> {
+  const timeoutMs = options.timeoutMs ?? POSTMORTEM_TIMEOUT_MS;
   const result = await execPi(invocation, {
-    cwd,
+    cwd: options.cwd,
     env: childEnv(),
-    timeoutMs: POSTMORTEM_TIMEOUT_MS,
-    signal,
+    timeoutMs,
+    signal: options.signal,
   });
   const text = result.stdout.trim();
   if (result.timedOut) {
-    return `${label} agent failed: timed out after ${Math.round(POSTMORTEM_TIMEOUT_MS / 1000)}s`;
+    return { text: `${label} agent failed: timed out after ${Math.round(timeoutMs / 1000)}s`, failed: true };
   }
   if (result.code !== 0 || text === "") {
     const detail = oneLine(result.stderr.trim() || "no output", 200);
-    return `${label} agent failed (code ${result.code ?? "signal"}): ${detail}`;
+    return { text: `${label} agent failed (code ${result.code ?? "signal"}): ${detail}`, failed: true };
   }
-  return text;
+  return { text, failed: false };
+}
+
+/** Read-only pi invocation with its own session directory. */
+function readOnlyInvocation(
+  sessions: string,
+  model: string | undefined,
+  systemPrompt: string,
+  task: string,
+): { command: string; args: string[] } {
+  fs.mkdirSync(sessions, { recursive: true });
+  const args = ["-p", "--tools", "read,grep,find,ls", "--session-dir", sessions];
+  if (model) args.push("--model", model);
+  args.push("--approve", "--append-system-prompt", systemPrompt, "--", task);
+  return getPiInvocation(args);
 }
 
-/** Read-only pi invocation for a helper, with its own session directory under the run. */
+/** A run helper's invocation: ledger paths are swapped for the frozen snapshot when one exists. */
 function helperInvocation(
   run: HordeRun,
   sessionDir: string,
   systemPrompt: string,
   task: string,
 ): { command: string; args: string[] } {
-  const sessions = path.join(run.runDir, sessionDir);
-  fs.mkdirSync(sessions, { recursive: true });
-  const args = ["-p", "--tools", "read,grep,find,ls", "--session-dir", sessions];
-  if (run.model) args.push("--model", run.model);
   for (const name of ["BOARD", "FINDINGS", "IDEAS", "FACTS", "CLAIMS", "RESOURCES", "CONCERNS"]) {
     const frozen = path.join(run.runDir, "snapshot", `${name}.md`);
     if (fs.existsSync(frozen)) task = task.split(path.join(run.hordeDir, `${name}.md`)).join(frozen);
@@ -62,8 +87,7 @@ function helperInvocation(
     "Use the frozen acceptance snapshot. Exclude unreviewed, disputed or stale artifacts from recommended runnable outputs. " +
     "acceptedDocuments establishes document-criteria review only; recommend runnable outputs only from acceptedRunnableArtifacts. Preserve recorded peer confirmation even if acceptance remains incomplete. " +
     "Disclose partial checks and unresolved coverage. Legacy verified labels alone do not establish a full reproduction.";
-  args.push("--approve", "--append-system-prompt", systemPrompt, "--", task);
-  return getPiInvocation(args);
+  return readOnlyInvocation(path.join(run.runDir, sessionDir), run.model, systemPrompt, task);
 }
 
 function postmortemTask(run: HordeRun): string {
@@ -125,6 +149,7 @@ function deliverableTask(run: HordeRun): string {
     ``,
     run.prompt,
     ``,
+    ...(run.slice ? [`This horde owned one workstream of that task: ${run.slice}`, `Deliver that workstream's part of the answer.`, ``] : []),
     `Read these with the read tool:`,
     `- ${path.join(run.runDir, "REPORT.md")}`,
     `- ${path.join(run.runDir, "SUMMARY.md")}`,
@@ -170,7 +195,7 @@ export async function runPostmortem(state: HordeState, run: HordeRun): Promise<s
   const controller = new AbortController();
   run.postmortemAbort = controller;
   try {
-    return await runHelper("post-mortem", invocation, run.cwd, controller.signal);
+    return (await runHelper("post-mortem", invocation, { cwd: run.cwd, signal: controller.signal })).text;
   } finally {
     run.postmortemAbort = undefined;
   }
@@ -188,8 +213,104 @@ export async function runDeliverable(state: HordeState, run: HordeRun): Promise<
   const controller = new AbortController();
   run.deliverableAbort = controller;
   try {
-    return await runHelper("deliverable", invocation, run.cwd, controller.signal);
+    return (await runHelper("deliverable", invocation, { cwd: run.cwd, signal: controller.signal })).text;
   } finally {
     run.deliverableAbort = undefined;
   }
 }
+
+function swarmDeliverableTask(swarm: Swarm): string {
+  const dir = swarm.dir ?? "";
+  return [
+    `Produce the single merged deliverable for swarm ${swarm.id}: ${swarm.hordes} hordes worked disjoint`,
+    `workstreams of one task in parallel, and each wrote its own deliverable.`,
+    ``,
+    `The task the swarm was given:`,
+    ``,
+    swarm.prompt,
+    ``,
+    `The partition:`,
+    ...(swarm.partition ?? []).map((slice, index) => `- ${hordeLabel(index + 1)}: ${slice}`),
+    ``,
+    `Read these with the read tool:`,
+    `- ${path.join(dir, "SWARM.md")}`,
+    ...swarm.runs.flatMap((run) => [
+      `- ${path.join(run.runDir, "DELIVERABLE.md")} (${hordeLabel(run.horde)}; absent when that horde was hard-stopped)`,
+      `- ${path.join(run.runDir, "REPORT.md")} (${hordeLabel(run.horde)})`,
+      `- ${path.join(run.runDir, "ACCEPTANCE.md")} (${hordeLabel(run.horde)}; when present)`,
+      `- ${path.join(run.runDir, "ANSWER.md")} (${hordeLabel(run.horde)}; when a solve was proposed)`,
+    ]),
+    ``,
+    `Merge the hordes' deliverables into one artifact that answers the whole task in the form the task`,
+    `implies. Keep every claim attributed to its horde (${swarm.runs.map((run) => hordeLabel(run.horde)).join(", ")})`,
+    `and keep the acceptance label its horde recorded; do not upgrade a claim's support by combining`,
+    `hordes, since no horde reviewed another's work. Where hordes overlap or contradict each other, say`,
+    `so and keep both attributions. Name any workstream whose horde produced no deliverable. Do not`,
+    `describe the process. Output only markdown.`,
+  ].join("\n");
+}
+
+/** Spawn the synthesis member that merges the hordes' deliverables into the swarm's. */
+export async function runSwarmDeliverable(state: HordeState, swarm: Swarm): Promise<string | undefined> {
+  if (state.disposed || !swarm.dir) return undefined;
+  const invocation = readOnlyInvocation(
+    path.join(swarm.dir, "deliverable-sessions"),
+    swarm.runs[0]?.model,
+    SWARM_DELIVERABLE_SYSTEM_PROMPT,
+    swarmDeliverableTask(swarm),
+  );
+  const controller = new AbortController();
+  swarm.deliverableAbort = controller;
+  try {
+    return (await runHelper("swarm deliverable", invocation, { cwd: swarm.cwd, signal: controller.signal })).text;
+  } finally {
+    swarm.deliverableAbort = undefined;
+  }
+}
+
+function plannerTask(prompt: string, hordes: number): string {
+  return [
+    `Partition the task below into exactly ${hordes} disjoint workstreams for ${hordes} independent teams`,
+    `that will work in parallel in this directory without talking to each other. Each workstream must`,
+    `be self-contained, must not overlap another, and should take about the same effort; together they`,
+    `must cover the whole task. Give each workstream one acceptance criterion a team can check on its`,
+    `own. Read the working directory as needed to split the task along real seams (modules, inputs,`,
+    `chapters, question groups); do not modify anything.`,
+    ``,
+    `Output ONLY a JSON array of exactly ${hordes} objects, nothing before or after it:`,
+    `[{"workstream": "<what this team does>", "acceptance": "<how the team knows it is done>"}, ...]`,
+    ``,
+    `Task:`,
+    ``,
+    prompt,
+  ].join("\n");
+}
+
+/**
+ * Partition a plain prompt between the hordes with a read-only planner. Returns the H slices,
+ * or the reason the launch must stop: a planner that cannot produce H distinct workstreams
+ * would have every horde doing the same work.
+ */
+export async function runPlanner(
+  state: HordeState,
+  input: { dir: string; cwd: string; model: string | undefined; prompt: string; hordes: number },
+): Promise<{ slices: string[] } | { error: string }> {
+  if (state.disposed) return { error: "session shut down" };
+  const invocation = readOnlyInvocation(
+    path.join(input.dir, "planner-sessions"),
+    input.model,
+    PLANNER_SYSTEM_PROMPT,
+    plannerTask(input.prompt, input.hordes),
+  );
+  const controller = new AbortController();
+  state.plannerAbort = controller;
+  try {
+    const result = await runHelper("planner", invocation, {
+      cwd: input.cwd, signal: controller.signal, timeoutMs: PLANNER_TIMEOUT_MS,
+    });
+    if (result.failed) return { error: result.text };
+    return parsePlannerOutput(result.text, input.hordes);
+  } finally {
+    state.plannerAbort = undefined;
+  }
+}

package/src/run/types.ts

@@ -11,6 +11,10 @@ export interface HordeRun extends MemberRunInfo {
   controllers: Map<string, AbortController>;
   procs: Map<string, ChildProcess>;
   cwd: string;
+  /** 1-based position in the swarm; the horde is addressed as `h<N>`. */
+  horde: number;
+  /** The horde's workstream when the swarm partitioned the task; every member sees it. */
+  slice?: string | undefined;
   /** Highest fact id at run start, to separate this run's facts from carried context. */
   startFactId: number;
   /** Highest idea id at run start; ideas created above it are this run's coverage. */
@@ -34,6 +38,8 @@ export interface HordeRun extends MemberRunInfo {
   repairTokens?: number;
   /** Members whose queued repair work was skipped because the budget could not fund an attempt. */
   repairSkipped?: string[];
+  /** Members whose remaining repair threads their own completed attempt could not move. */
+  repairStalled?: string[];
   /** True when a user command or session shutdown ended the run. */
   userStop?: boolean | undefined;
   /** Human-readable stop reason for the report, e.g. "stopped by user". */
@@ -47,6 +53,12 @@ export interface HordeRun extends MemberRunInfo {
   deliverableAbort?: AbortController | undefined;
   /** Steps still running after members finished, e.g. ["deliverable", "post-mortem"]. */
   finalizing?: string[] | undefined;
+  /** The run's outcome label once REPORT.md is written, e.g. "solved" or "stopped-clean". */
+  outcome?: string | undefined;
+  /** True once members exited and REPORT.md is written; the swarm slot frees when every run is. */
+  reported?: boolean | undefined;
+  /** True once finalize completed, synthesis included. */
+  finalized?: boolean | undefined;
   /** Workstream partition when the run was started with `plan`. */
   plan?: string[] | undefined;
   /** Member carrying the verifier role, when one was assigned. */
@@ -79,6 +91,38 @@ export interface HordeRun extends MemberRunInfo {
   solvedCoverageNotice?: boolean | undefined;
   postmortemAbort?: AbortController | undefined;
   ui?: ExtensionUIContext;
+}
+
+/**
+ * H concurrent hordes on one task. A plain `12` is a swarm of one whose run lives in
+ * `.horde/runs/`; `3/12` gives each horde its own ledgers under `.horde/swarms/<id>/h<N>/`.
+ */
+export interface Swarm {
+  id: string;
+  /** `.horde/swarms/<id>`; undefined for a swarm of one. */
+  dir: string | undefined;
+  /** The project's `.horde` directory. */
+  hordeDir: string;
+  cwd: string;
+  prompt: string;
+  hordes: number;
+  /** Members per horde. */
+  count: number;
+  startedAt: number;
+  /** One run per horde, `h1` first. */
+  runs: HordeRun[];
+  /** The `plan` layers as given, before they were dealt to the hordes. */
+  plan?: string[] | undefined;
+  /** Per-horde workstream, indexed by horde - 1; absent for a swarm of one. */
+  partition?: string[] | undefined;
+  untilStop?: boolean | undefined;
+  dashboardUrl?: string | undefined;
+  /** Generated merged deliverable across the hordes' deliverables. */
+  deliverable?: string | undefined;
+  deliverableAbort?: AbortController | undefined;
+  /** The swarm step still running after every horde finalized, e.g. ["merge"]. */
+  finalizing?: string[] | undefined;
+  ui?: ExtensionUIContext;
   tui?: TUI;
   timer?: ReturnType<typeof setInterval> | undefined;
 }
@@ -96,13 +140,15 @@ export interface ReportDetails {
 /** Parent-side extension state shared by the command, run lifecycle, and shutdown. */
 export interface HordeState {
   pi: ExtensionAPI;
-  /** The run whose members are live; at most one at a time. */
-  active: HordeRun | undefined;
-  /** A run whose members finished but whose synthesis helpers are still running. */
-  finalizing: HordeRun | undefined;
+  /** The swarm whose members are live; at most one at a time. */
+  active: Swarm | undefined;
+  /** A swarm whose members finished but whose synthesis helpers are still running. */
+  finalizing: Swarm | undefined;
   dashboard: DashboardServer | undefined;
-  /** Set synchronously at startRun entry so a same-tick second start is refused. */
+  /** Set synchronously at startSwarm entry so a same-tick second start is refused. */
   starting: boolean;
+  /** The planner partitioning a task between hordes, so shutdown can end it. */
+  plannerAbort?: AbortController | undefined;
   /** Set at session shutdown; lifecycle steps check it and stop early. */
   disposed: boolean;
 }
@@ -117,3 +163,18 @@ export function createHordeState(pi: ExtensionAPI): HordeState {
     disposed: false,
   };
 }
+
+/** `h2` for the second horde; the label every notification, target, and file uses. */
+export function hordeLabel(horde: number): string {
+  return `h${horde}`;
+}
+
+/** Runs of the swarm whose members are not all finished and reported. */
+export function activeRuns(swarm: Swarm): HordeRun[] {
+  return swarm.runs.filter((run) => run.reported !== true);
+}
+
+/** Runs of the swarm whose members finished but whose synthesis is still running. */
+export function finalizingRuns(swarm: Swarm): HordeRun[] {
+  return swarm.runs.filter((run) => run.reported === true && run.finalized !== true);
+}

package/src/run/ui.ts

@@ -3,7 +3,10 @@ import { Text } from "@earendil-works/pi-tui";
 import { formatElapsed, formatTokens } from "../format.js";
 import { statusCounts } from "../prompt.js";
 import { HordeWidget } from "../widget.js";
-import type { HordeRun, ReportDetails } from "./types.js";
+import { SWARM_REPORT_TYPE } from "./swarm-report.js";
+import type { SwarmReportDetails } from "./swarm-report.js";
+import { hordeLabel } from "./types.js";
+import type { HordeRun, ReportDetails, Swarm } from "./types.js";
 
 const WIDGET_KEY = "agent-horde";
 
@@ -11,7 +14,26 @@ export const REPORT_TYPE = "agent-horde-report";
 
 const RENDER_INTERVAL_MS = 100;
 
+function registerSwarmReportRenderer(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer<SwarmReportDetails>(SWARM_REPORT_TYPE, (message, { outputPad }, theme) => {
+    const d = message.details;
+    if (!d) return undefined;
+    const title = `swarm ${d.swarmId} finished: ${d.hordes.length} hordes, ${formatElapsed(d.elapsedMs)}`;
+    const lines = [theme.bold(theme.fg("accent", title))];
+    for (const h of d.hordes) {
+      lines.push(theme.fg("muted", `  ${h.label.padEnd(3)} ${h.outcome.padEnd(18)} ${h.done} done ${h.failed} failed ` +
+        `${h.stopped} stopped  t${h.turns}  ${formatTokens(h.tokens)} tok  $${h.cost.toFixed(2)}  ${h.findings} findings`));
+    }
+    if (d.deliverable) {
+      lines.push("", theme.bold(theme.fg("accent", `swarm ${d.swarmId} deliverable`)), "");
+      lines.push(d.deliverable.trimEnd());
+    }
+    return new Text(lines.join("\n"), outputPad, 0);
+  });
+}
+
 export function registerReportRenderer(pi: ExtensionAPI): void {
+  registerSwarmReportRenderer(pi);
   pi.registerMessageRenderer<ReportDetails>(REPORT_TYPE, (message, { outputPad }, theme) => {
     const d = message.details;
     if (!d) return undefined;
@@ -38,50 +60,73 @@ export function registerReportRenderer(pi: ExtensionAPI): void {
   });
 }
 
-/** Which run owns the widget on a shared UI context; a later run must not be clobbered. */
-const widgetOwners = new WeakMap<ExtensionUIContext, HordeRun>();
+/** Which swarm owns the widget on a shared UI context; a later swarm must not be clobbered. */
+const widgetOwners = new WeakMap<ExtensionUIContext, Swarm>();
 
-export function refreshRun(run: HordeRun): void {
-  if (!run.ui || widgetOwners.get(run.ui) !== run) return;
-  if (run.finalizing && run.finalizing.length > 0) {
-    run.ui.setStatus(WIDGET_KEY, `horde ${run.id} synthesizing: ${run.finalizing.join(", ")}`);
-    run.tui?.requestRender();
-    return;
-  }
+/** The swarm each live run belongs to, so a per-run refresh redraws the whole widget. */
+const swarmOf = new WeakMap<HordeRun, Swarm>();
+
+/** One run's share of the status line: `h2 11/12 running, 1 paused, clean stop in 40s`. */
+function runStatus(run: HordeRun, labelled: boolean): string {
   const c = statusCounts(run.members);
   const paused = run.members.filter((m) => m.paused).length;
-  let text = `horde ${c.running + c.starting}/${run.count} running`;
+  let text = `${labelled ? `${hordeLabel(run.horde)} ` : ""}${c.running + c.starting}/${run.count} running`;
   if (paused > 0) text += `, ${paused} paused`;
   if (run.cleanStopUntil !== undefined) {
     const left = Math.max(0, Math.ceil((run.cleanStopUntil - Date.now()) / 1000));
     text += `, clean stop in ${left}s`;
   }
-  run.ui.setStatus(WIDGET_KEY, text);
-  run.tui?.requestRender();
+  if (run.finalizing && run.finalizing.length > 0) text += `, synthesizing ${run.finalizing.join(", ")}`;
+  return text;
+}
+
+export function refreshSwarm(swarm: Swarm): void {
+  if (!swarm.ui || widgetOwners.get(swarm.ui) !== swarm) return;
+  const single = swarm.runs.length === 1;
+  let text: string;
+  if (swarm.finalizing && swarm.finalizing.length > 0) {
+    text = `swarm ${swarm.id} synthesizing: ${swarm.finalizing.join(", ")}`;
+  } else if (single && swarm.runs[0]!.finalizing && swarm.runs[0]!.finalizing.length > 0) {
+    text = `horde ${swarm.id} synthesizing: ${swarm.runs[0]!.finalizing.join(", ")}`;
+  } else {
+    const parts = swarm.runs.map((run) => runStatus(run, !single));
+    text = single ? `horde ${parts[0]}` : `swarm ${parts.join("; ")}`;
+  }
+  swarm.ui.setStatus(WIDGET_KEY, text);
+  swarm.tui?.requestRender();
 }
 
-export function mountWidget(run: HordeRun, ui: ExtensionUIContext): void {
-  run.ui = ui;
-  widgetOwners.set(ui, run);
+export function refreshRun(run: HordeRun): void {
+  const swarm = swarmOf.get(run);
+  if (swarm) refreshSwarm(swarm);
+}
+
+export function mountWidget(swarm: Swarm, ui: ExtensionUIContext): void {
+  swarm.ui = ui;
+  for (const run of swarm.runs) {
+    run.ui = ui;
+    swarmOf.set(run, swarm);
+  }
+  widgetOwners.set(ui, swarm);
   ui.setWidget(
     WIDGET_KEY,
     (tui, theme) => {
-      run.tui = tui;
-      return new HordeWidget(run, theme);
+      swarm.tui = tui;
+      return new HordeWidget(swarm, theme);
     },
     { placement: "aboveEditor" },
   );
-  run.timer = setInterval(() => refreshRun(run), RENDER_INTERVAL_MS);
-  run.timer.unref();
+  swarm.timer = setInterval(() => refreshSwarm(swarm), RENDER_INTERVAL_MS);
+  swarm.timer.unref();
 }
 
-export function unmountWidget(run: HordeRun): void {
-  if (run.timer) clearInterval(run.timer);
-  run.timer = undefined;
-  if (!run.ui || widgetOwners.get(run.ui) !== run) return;
-  widgetOwners.delete(run.ui);
-  run.ui.setWidget(WIDGET_KEY, undefined);
-  run.ui.setStatus(WIDGET_KEY, undefined);
+export function unmountWidget(swarm: Swarm): void {
+  if (swarm.timer) clearInterval(swarm.timer);
+  swarm.timer = undefined;
+  if (!swarm.ui || widgetOwners.get(swarm.ui) !== swarm) return;
+  widgetOwners.delete(swarm.ui);
+  swarm.ui.setWidget(WIDGET_KEY, undefined);
+  swarm.ui.setStatus(WIDGET_KEY, undefined);
 }
 
 export function reportDetails(run: HordeRun, now: number): ReportDetails {
@@ -114,7 +159,7 @@ export function safeNotifyUi(
   }
 }
 
-export function safeNotify(run: HordeRun, message: string, level: "info" | "warning" | "error"): void {
+export function safeNotify(run: Pick<HordeRun, "ui">, message: string, level: "info" | "warning" | "error"): void {
   try {
     run.ui?.notify(message, level);
   } catch {

package/src/run-graph.ts

@@ -117,14 +117,14 @@ export function entityHref(runId: string, id: string): string | undefined {
   if (!match) return undefined;
   const letter = match[1] ?? "";
   const number = match[2] ?? "";
-  const run = encodeURIComponent(runId);
+  const base = `/runs/${encodeURIComponent(runId)}`;
   switch (letter) {
-    case "I": return `/ideas#idea-${number}`;
-    case "F": return `/findings?run=${run}#F${number}`;
-    case "T": return `/facts?run=${run}#T${number}`;
-    case "C": return `/claims#C${number}`;
-    case "R": return `/resources#R${number}`;
-    case "A": case "V": case "Q": return `/runs/${run}/collaboration#${id}`;
+    case "I": return `${base}/ideas#idea-${number}`;
+    case "F": return `${base}/findings#F${number}`;
+    case "T": return `${base}/facts#T${number}`;
+    case "C": return `${base}/claims#C${number}`;
+    case "R": return `${base}/resources#R${number}`;
+    case "A": case "V": case "Q": return `${base}/collaboration#${id}`;
     case "E": return eventHref(runId, Number(number));
     default: return undefined;
   }

package/src/swarm-graph.ts

@@ -0,0 +1,127 @@
+import { oneLine } from "./format.js";
+import type { HordeEvent } from "./ledger/events.js";
+import { LIFECYCLE_ATTEMPT, eventHref } from "./run-graph.js";
+import type { GraphEdge, GraphLane, GraphNode, RunGraph } from "./run-graph.js";
+
+/** One horde's events and where its run page is. */
+export interface SwarmGraphHorde {
+  label: string;
+  runId: string;
+  events: HordeEvent[];
+  status?: string | undefined;
+}
+
+export interface SwarmGraphInput {
+  swarmId: string;
+  startedAt: number;
+  hordes: SwarmGraphHorde[];
+  /** The swarm's merge step, once it started. */
+  merge?: { startedAt: number; endedAt?: number | undefined; written?: boolean | undefined } | undefined;
+  /** Graph end for a live swarm (epoch ms); a finished swarm ends at its last event. */
+  now?: number | undefined;
+}
+
+const SWARM_LANE = "swarm";
+
+/** The parent lifecycle actions that mark a horde's progress; member-level churn stays on the run graph. */
+const PHASE_ACTIONS = new Set([
+  "run-start", "phase-start", "phase-end", "stop-clean", "stop-hard", "solved-validated", "solved-banked",
+  "solved-contested", "acceptance", "run-end",
+]);
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function labelOf(event: HordeEvent): [string, string] {
+  const p = event.payload;
+  switch (event.action) {
+    case "run-start": return ["start", `${String(p.count ?? "?")} members${str(p.slice) ? `; workstream: ${oneLine(str(p.slice) ?? "", 160)}` : ""}`];
+    case "phase-start": return [`${str(p.phase) ?? "phase"} start`, `${str(p.phase) ?? "phase"} started`];
+    case "phase-end": return [`${str(p.phase) ?? "phase"} end`, `${str(p.phase) ?? "phase"} ended`];
+    case "stop-clean": return [`stop-clean (${str(p.label) ?? "stop-clean"})`, "clean stop requested"];
+    case "stop-hard": return [`stop-hard (${str(p.by) ?? "user"})`, "members terminated"];
+    case "solved-validated": return ["solved validated", str(p.validator) ? `by ${str(p.validator)}` : "without a separate validator"];
+    case "solved-banked": return [`solved banked (round ${String(p.round ?? "?")})`, "the run continues until stopped"];
+    case "solved-contested": return ["solved contested", `by ${str(p.member) ?? ""}`];
+    case "acceptance": return [`acceptance ${str(p.status) ?? ""}`.trim(), `${String(p.issues ?? 0)} issues`];
+    case "run-end": return ["end", `outcome ${str(p.outcome) ?? "unknown"}`];
+    default: return [event.action, ""];
+  }
+}
+
+function hordeNodes(horde: SwarmGraphHorde): GraphNode[] {
+  return horde.events
+    .filter((event) => event.attempt === LIFECYCLE_ATTEMPT && event.outcome === "applied" && PHASE_ACTIONS.has(event.action))
+    .map((event) => {
+      const [label, title] = labelOf(event);
+      const at = Date.parse(event.at);
+      return {
+        id: `${horde.label}:${event.eventId}`,
+        kind: "lifecycle" as const,
+        action: event.action,
+        label,
+        title: `${horde.label} ${event.eventId} ${title}`.trim(),
+        lane: horde.label,
+        at: Number.isFinite(at) ? at : 0,
+        eventId: event.eventId,
+        href: eventHref(horde.runId, event.seq),
+        outcome: "applied" as const,
+        marker: true,
+        placeholder: false,
+      };
+    })
+    .filter((node) => node.at > 0);
+}
+
+function mergeNodes(input: SwarmGraphInput): GraphNode[] {
+  const merge = input.merge;
+  if (!merge) return [];
+  const node = (id: string, label: string, title: string, at: number): GraphNode => ({
+    id, kind: "lifecycle", action: id, label, title, lane: SWARM_LANE, at, eventId: "",
+    href: `/swarms/${encodeURIComponent(input.swarmId)}`, outcome: "applied", marker: true, placeholder: false,
+  });
+  const nodes = [node("merge-start", "merge start", "merging the hordes' deliverables", merge.startedAt)];
+  if (merge.endedAt !== undefined) {
+    nodes.push(node("merge-end", `merge end${merge.written === false ? " (no deliverable)" : ""}`,
+      merge.written === false ? "the swarm deliverable was not written" : "DELIVERABLE.md written", merge.endedAt));
+  }
+  return nodes;
+}
+
+/** One lane per horde plus the swarm lane, so the hordes' phases line up against the merge step. */
+export function buildSwarmGraph(input: SwarmGraphInput): RunGraph {
+  const perHorde = input.hordes.map((horde) => hordeNodes(horde));
+  const nodes = [...perHorde.flat(), ...mergeNodes(input)].sort((a, b) => a.at - b.at);
+  const edges: GraphEdge[] = [];
+  if (input.merge) {
+    for (const horde of perHorde) {
+      const end = horde.find((node) => node.action === "run-end");
+      if (end) edges.push({ from: end.id, to: "merge-start", label: "merged", tone: "lifecycle" });
+    }
+  }
+  const lanes: GraphLane[] = [
+    { id: SWARM_LANE, label: SWARM_LANE },
+    ...input.hordes.map((horde) => ({
+      id: horde.label,
+      label: `${horde.label} ${horde.runId}`,
+      href: `/runs/${encodeURIComponent(horde.runId)}`,
+      status: horde.status,
+    })),
+  ];
+  const start = input.startedAt;
+  const latest = Math.max(input.now ?? 0, input.merge?.endedAt ?? 0, ...nodes.map((node) => node.at));
+  const end = latest > start ? latest : start + 1_000;
+  const hordeTimes = perHorde.flat().map((node) => node.at);
+  const live = input.now !== undefined && !input.hordes.every((horde) => horde.events.some((event) => event.action === "run-end"));
+  return {
+    runId: input.swarmId,
+    start,
+    end,
+    membersEnd: live || hordeTimes.length === 0 ? end : Math.min(end, Math.max(start, ...hordeTimes)),
+    lanes,
+    phases: [],
+    nodes,
+    edges,
+  };
+}