agent-horde 0.1.6 → 0.2.0

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,
+  };
+}

package/src/tool/actions.ts

@@ -14,6 +14,7 @@ import type { Idea } from "../ledger/ideas.js";
 import { claimResource, listResources } from "../ledger/resources.js";
 import { cleanStopRequestedFor, confirmSolved, contestSolved, markSolved, readSolved } from "../ledger/run-signals.js";
 import { oneLine } from "../format.js";
+import type { SiblingHorde } from "../member.js";
 import { validateFindingResourceCitations } from "../citations.js";
 import { idleHint } from "./hints.js";
 import type { HordeToolParams } from "./params.js";
@@ -54,6 +55,29 @@ interface ActionContext {
   cleanStop: boolean;
   /** The member's role instruction, when one was assigned. */
   role: string | undefined;
+  /** Other hordes of the swarm whose ledgers the read actions include, tagged by label. */
+  siblings: SiblingHorde[];
+}
+
+/**
+ * Shared read, local write: the read actions append each sibling horde's entries, tagged `[hN]`,
+ * so a fact, a rule-out or a resource another horde recorded is not re-derived here. A sibling
+ * whose ledger cannot be read is reported, not fatal.
+ */
+function siblingSections(siblings: SiblingHorde[], what: string, lines: (hordeDir: string) => string[]): string {
+  return siblings
+    .map((sibling) => {
+      const tag = `[${sibling.label}]`;
+      let entries: string[];
+      try {
+        entries = lines(sibling.hordeDir).map((line) => `${tag} ${line}`);
+      } catch (error) {
+        entries = [`${tag} unreadable: ${oneLine(error instanceof Error ? error.message : String(error), 120)}`];
+      }
+      const head = `${tag} ${what} of horde ${sibling.label} (read-only; ${sibling.hordeDir}):`;
+      return `\n\n${head}\n${entries.length > 0 ? entries.join("\n") : `${tag} none`}`;
+    })
+    .join("");
 }
 
 export function isVerifierRole(role: string | undefined): boolean {
@@ -108,18 +132,19 @@ function closedIdea(ctx: ActionContext, idea: Idea, text: string): ActionResult
   return { text: `${text}${hint}`, id: idea.id };
 }
 
-function listAction({ hordeDir }: ActionContext): ActionResult {
+function ideaLine(idea: Idea): string {
+  const owner = idea.owner ? ` @${idea.owner}` : "";
+  const note = idea.note ? `: ${idea.note}` : "";
+  return `#${idea.id} [${idea.mark}]${owner} ${idea.text}${note}`;
+}
+
+function listAction({ hordeDir, siblings }: ActionContext): ActionResult {
   const ideas = listIdeas(hordeDir);
-  if (ideas.length === 0) return { text: "IDEAS.md has no ideas yet" };
-  return {
-    text: ideas
-      .map((idea) => {
-        const owner = idea.owner ? ` @${idea.owner}` : "";
-        const note = idea.note ? `: ${idea.note}` : "";
-        return `#${idea.id} [${idea.mark}]${owner} ${idea.text}${note}`;
-      })
-      .join("\n"),
-  };
+  const own = ideas.length === 0 ? "IDEAS.md has no ideas yet" : ideas.map(ideaLine).join("\n");
+  // Only closed ideas cross hordes: results prevent re-derivation, open ones would invite claims.
+  const shared = siblingSections(siblings, "done and ruled-out ideas", (dir) =>
+    listIdeas(dir).filter((idea) => idea.mark === "x" || idea.mark === "!").map(ideaLine));
+  return { text: `${own}${shared}` };
 }
 
 async function postAction({ hordeDir, member, params }: ActionContext): Promise<ActionResult> {
@@ -282,14 +307,18 @@ async function factAction({ hordeDir, member, params }: ActionContext): Promise<
   return { text: `Recorded fact T${fact.id}: ${fact.text}${provisional}`, id: fact.id };
 }
 
-function factsAction({ hordeDir }: ActionContext): ActionResult {
-  const facts = listFacts(hordeDir);
-  if (facts.length === 0) return { text: "FACTS.md has no facts yet" };
+function factLines(hordeDir: string): string[] {
   const status = (fact: FactEntry): string => {
     if (!fact.provisionalOn) return "";
     return factUnsettled(hordeDir, fact) ? ` [provisional: ${fact.provisionalOn} open]` : ` [was provisional on ${fact.provisionalOn}, now closed]`;
   };
-  return { text: facts.map((fact) => `T${fact.id} ${fact.text} @${fact.author}${status(fact)}`).join("\n") };
+  return listFacts(hordeDir).map((fact) => `T${fact.id} ${fact.text} @${fact.author}${status(fact)}`);
+}
+
+function factsAction({ hordeDir, siblings }: ActionContext): ActionResult {
+  const own = factLines(hordeDir);
+  const shared = siblingSections(siblings, "facts", factLines);
+  return { text: `${own.length === 0 ? "FACTS.md has no facts yet" : own.join("\n")}${shared}` };
 }
 
 /** An answer that quotes a provisional fact as settled asserts what an open idea is still auditing. */
@@ -421,19 +450,19 @@ async function resourceAction(ctx: ActionContext): Promise<ActionResult> {
   };
 }
 
-function resourcesAction({ hordeDir }: ActionContext): ActionResult {
-  const resources = listResources(hordeDir);
-  if (resources.length === 0) return { text: "RESOURCES.md has no resources yet" };
-  return {
-    text: resources
-      .map(
-        (resource) =>
-          `R${resource.id} ${resource.name} @${resource.owner}` +
-          `${resource.note ? `: ${resource.note}` : ""}` +
-          `${resource.reusers.length > 0 ? ` reuse=${resource.reusers.join(",")}` : ""}`,
-      )
-      .join("\n"),
-  };
+function resourceLines(hordeDir: string): string[] {
+  return listResources(hordeDir).map(
+    (resource) =>
+      `R${resource.id} ${resource.name} @${resource.owner}` +
+      `${resource.note ? `: ${resource.note}` : ""}` +
+      `${resource.reusers.length > 0 ? ` reuse=${resource.reusers.join(",")}` : ""}`,
+  );
+}
+
+function resourcesAction({ hordeDir, siblings }: ActionContext): ActionResult {
+  const own = resourceLines(hordeDir);
+  const shared = siblingSections(siblings, "resources (reuse by path; cite the path, not the R#)", resourceLines);
+  return { text: `${own.length === 0 ? "RESOURCES.md has no resources yet" : own.join("\n")}${shared}` };
 }
 
 /**
@@ -564,11 +593,11 @@ export async function runHordeAction(
   member: string,
   params: HordeToolParams,
   runId: string | undefined = process.env.PI_HORDE_RUN,
-  tracking: { attempt?: string; requestId?: string; role?: string | undefined } = {},
+  tracking: { attempt?: string; requestId?: string; role?: string | undefined; siblings?: SiblingHorde[] | undefined } = {},
 ): Promise<ActionResult> {
   const cleanStop = Boolean(runId && cleanStopRequestedFor(hordeDir, runId, member));
-  const role = tracking.role;
-  const ctx: EventContext = { hordeDir, runId: runId ?? "", actor: member, ...tracking, requestId: params.requestId ?? tracking.requestId };
+  const { role, siblings = [], ...eventTracking } = tracking;
+  const ctx: EventContext = { hordeDir, runId: runId ?? "", actor: member, ...eventTracking, requestId: params.requestId ?? tracking.requestId };
   if (COLLABORATION_ACTIONS.has(params.action)) {
     if (!runId) throw new Error("horde: collaboration needs an active run");
     return runCollaborationAction(ctx, params);
@@ -580,7 +609,7 @@ export async function runHordeAction(
   const intent = audit ? await recordEvent({ ...ctx, requestId: ctx.requestId ? `${ctx.requestId}:intent` : undefined }, params.action, { outcome: "intent", payload: { input: params } }) : undefined;
   try {
     const refused = cleanStop && NEW_WORK_ACTIONS.has(params.action);
-    const result = refused ? { text: CLEAN_STOP_NOTICE } : await handler({ hordeDir, member, params, runId, cleanStop, role });
+    const result = refused ? { text: CLEAN_STOP_NOTICE } : await handler({ hordeDir, member, params, runId, cleanStop, role, siblings });
     // A refusal and a no-op both record `noop`; the no-op keeps `result.noop` so the graph and the
     // report can tell an absorbed duplicate from refused work.
     if (audit) await recordEvent(ctx, params.action, { outcome: refused || result.noop ? "noop" : "applied", payload: { input: params, result }, parents: intent ? [intent.eventId] : [] });

package/src/tool/register.ts

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { cleanStopRequestedFor, writeHeartbeat } from "../ledger/run-signals.js";
 import { envNumber } from "../format.js";
+import { parseSiblings } from "../member.js";
 import { ReminderGate, goalReminder } from "../reminder.js";
 import { isVerifierRole, runHordeAction } from "./actions.js";
 import { pendingVerificationHint, solvedHint } from "./hints.js";
@@ -31,6 +32,7 @@ export function registerMemberTool(pi: ExtensionAPI): void {
     throw new Error("agent-horde: PI_HORDE_DIR and PI_HORDE_NAME must be set for a horde member");
   }
   const attempt = process.env.PI_HORDE_ATTEMPT ?? `pid-${process.pid}`;
+  const siblings = parseSiblings(process.env.PI_HORDE_SIBLINGS);
   const activeRun = process.env.PI_HORDE_RUN;
   if (activeRun) registerInbox(pi, { hordeDir, runId: activeRun, actor: member, attempt });
   // One member per process, so one gate is the per-member reminder counter.
@@ -64,7 +66,7 @@ export function registerMemberTool(pi: ExtensionAPI): void {
     async execute(toolCallId, params) {
       const runId = process.env.PI_HORDE_RUN;
       const role = process.env.PI_HORDE_ROLE;
-      const result = await runHordeAction(hordeDir, member, params, runId, { attempt, requestId: toolCallId, role });
+      const result = await runHordeAction(hordeDir, member, params, runId, { attempt, requestId: toolCallId, role, siblings });
       const runDir = runId ? path.join(hordeDir, "runs", runId) : undefined;
       if (runDir && MUTATING_ACTIONS.has(params.action)) touchHeartbeat(runDir, member);
       let text = compactReceipt(result.text, params) + solvedHint(hordeDir, runId, member, params.action);

package/src/widget.ts

@@ -1,17 +1,30 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import { formatElapsed } from "./format.js";
+import { formatElapsed, formatTokens } from "./format.js";
 import type { MemberState } from "./member.js";
-import { memberActivity, statusCounts } from "./prompt.js";
+import { memberActivity, statusCounts, totalUsage } from "./prompt.js";
 
 interface WidgetRun {
   id: string;
+  horde: number;
   members: MemberState[];
   startedAt: number;
   cleanStopUntil?: number | undefined;
   dashboardUrl?: string | undefined;
   /** Steps still running after members finished, e.g. ["deliverable", "post-mortem"]. */
   finalizing?: string[] | undefined;
+  reported?: boolean | undefined;
+  finalized?: boolean | undefined;
+  outcome?: string | undefined;
+}
+
+interface WidgetSwarm {
+  id: string;
+  runs: WidgetRun[];
+  startedAt: number;
+  dashboardUrl?: string | undefined;
+  /** The swarm step still running after every horde finalized, e.g. ["merge"]. */
+  finalizing?: string[] | undefined;
 }
 
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
@@ -65,8 +78,8 @@ function memberLine(m: MemberState, now: number, frame: number, theme: Theme): s
   );
 }
 
-export function widgetLines(run: WidgetRun, now: number, width: number, theme: Theme): string[] {
-  const frame = Math.floor(now / 100) % SPINNER.length;
+/** The widget for one horde: a header, then a line per member (a glyph strip past eight). */
+function runLines(run: WidgetRun, now: number, frame: number, theme: Theme): string[] {
   const lines = [headerLine(run, now, theme)];
   if (run.members.length > COLLAPSE_ABOVE) {
     lines.push(` ${run.members.map((m) => statusGlyph(m, frame, theme)).join(" ")}`);
@@ -77,22 +90,81 @@ export function widgetLines(run: WidgetRun, now: number, width: number, theme: T
   } else {
     for (const m of run.members) lines.push(memberLine(m, now, frame, theme));
   }
+  return lines;
+}
+
+/** What one horde of a swarm is doing, in a word. */
+function hordeActivity(run: WidgetRun, c: ReturnType<typeof statusCounts>): string {
+  if (run.finalized) return run.outcome ?? "finished";
+  if (run.finalizing && run.finalizing.length > 0) return `synthesizing ${run.finalizing.join(", ")}`;
+  if (run.reported) return "finalizing";
+  if (run.cleanStopUntil !== undefined) return "stopping";
+  return c.running + c.starting > 0 ? "running" : "finishing";
+}
+
+/** One line per horde: `h2  11/12 running  1 done  t120  45.2k tok  $1.20  running`. */
+export function hordeLine(run: WidgetRun, now: number, frame: number, theme: Theme): string {
+  const c = statusCounts(run.members);
+  const usage = totalUsage(run.members);
+  const live = run.members.find((m) => m.status === "running");
+  const glyph = run.finalized
+    ? theme.fg("success", "✓")
+    : live
+      ? theme.fg("accent", SPINNER[frame % SPINNER.length] ?? "⠋")
+      : theme.fg("dim", "·");
+  const parts = [
+    `${c.running + c.starting}/${run.members.length} running`,
+    `${c.done} done`,
+  ];
+  if (c.failed) parts.push(theme.fg("error", `${c.failed} failed`));
+  if (c.stopped) parts.push(theme.fg("warning", `${c.stopped} stopped`));
+  parts.push(theme.fg("dim", `t${usage.turns}  ${formatTokens(usage.input + usage.output)} tok  $${usage.cost.toFixed(2)}`));
+  parts.push(theme.fg("muted", hordeActivity(run, c)));
+  return ` ${glyph} ${`h${run.horde}`.padEnd(3)} ${parts.join("  ")}`;
+}
+
+function swarmHeader(swarm: WidgetSwarm, now: number, theme: Theme): string {
+  const members = swarm.runs.flatMap((run) => run.members);
+  const c = statusCounts(members);
+  const parts = [
+    theme.bold(theme.fg("accent", `swarm ${swarm.id}`)),
+    `${swarm.runs.length} hordes`,
+    `${c.running + c.starting} running`,
+    `${c.done} done`,
+  ];
+  if (c.failed) parts.push(theme.fg("error", `${c.failed} failed`));
+  if (c.stopped) parts.push(theme.fg("warning", `${c.stopped} stopped`));
+  parts.push(formatElapsed(now - swarm.startedAt));
+  if (swarm.finalizing && swarm.finalizing.length > 0) {
+    parts.push(theme.fg("warning", `synthesizing ${swarm.finalizing.join(", ")}`));
+  }
+  if (swarm.dashboardUrl) parts.push(`${swarm.dashboardUrl}swarms/${swarm.id}`);
+  return `${parts.join("  ")}  ${theme.fg("dim", "/agent-horde status | stop-hard | stop-clean [hN]")}`;
+}
+
+/** A swarm of one shows its run as before; a larger swarm shows one line per horde. */
+export function widgetLines(swarm: WidgetSwarm, now: number, width: number, theme: Theme): string[] {
+  const frame = Math.floor(now / 100) % SPINNER.length;
+  const single = swarm.runs.length === 1 ? swarm.runs[0] : undefined;
+  const lines = single
+    ? runLines(single, now, frame, theme)
+    : [swarmHeader(swarm, now, theme), ...swarm.runs.map((run) => hordeLine(run, now, frame, theme))];
   return lines.map((line) => truncateToWidth(line, width));
 }
 
 export class HordeWidget {
-  private readonly run: WidgetRun;
+  private readonly swarm: WidgetSwarm;
   private readonly theme: Theme;
   private readonly now: () => number;
 
-  constructor(run: WidgetRun, theme: Theme, now: () => number = Date.now) {
-    this.run = run;
+  constructor(swarm: WidgetSwarm, theme: Theme, now: () => number = Date.now) {
+    this.swarm = swarm;
     this.theme = theme;
     this.now = now;
   }
 
   render(width: number): string[] {
-    return widgetLines(this.run, this.now(), width, this.theme);
+    return widgetLines(this.swarm, this.now(), width, this.theme);
   }
 
   invalidate(): void {}