agent-horde 0.1.5 → 0.2.0

package/src/run/solved.ts

@@ -3,9 +3,10 @@ import { oneLine } from "../format.js";
 import { loadCollaborationReport } from "../collaboration-report.js";
 import { openMessages } from "../ledger/collaboration.js";
 import { postBoard } from "../ledger/board.js";
-import { unverifiedFindings } from "../ledger/findings.js";
+import { unsettledFactCitations } from "../ledger/facts.js";
+import { listFindingsForRun, staleAnswerCitations, unverifiedFindings } from "../ledger/findings.js";
 import { listIdeas } from "../ledger/ideas.js";
-import { archiveSolved, clearCleanStop, clearSolved, readSolvedState, resolveSolvedState } from "../ledger/run-signals.js";
+import { archiveSolved, clearCleanStop, clearSolved, readSolvedState, reopenSolved, resolveSolvedState, writeAnswer } from "../ledger/run-signals.js";
 import type { SolvedSignal } from "../ledger/run-signals.js";
 import { requestCleanStop } from "./controls.js";
 import { recordLifecycle } from "./lifecycle.js";
@@ -46,14 +47,12 @@ function adoptProposal(run: HordeRun, proposal: SolvedSignal): void {
   refreshRun(run);
 }
 
-function dropContested(run: HordeRun, contest: SolvedSignal): void {
-  safeNotify(run, `horde ${run.id}: solved proposal contested by ${contest.member}`, "warning");
-  void recordLifecycle(run, "solved-contested", { member: contest.member, text: oneLine(contest.text, 200) });
-  void postBoard(
-    run.hordeDir,
-    "parent",
-    `SOLVED proposal contested by ${contest.member}: ${contest.text}. Work continues.`,
-  );
+/** Idea ids a contest names as what is still missing; the proposal reopens once they close. */
+export function contestBlockers(text: string): number[] {
+  return [...new Set([...text.matchAll(/(?:^|[\s(,;])#(\d{1,6})\b/g)].map((m) => Number(m[1])))];
+}
+
+function clearProposal(run: HordeRun): void {
   archiveSolved(run.runDir);
   clearSolved(run.runDir);
   if (!run.stopped) clearCleanStop(run.runDir);
@@ -62,10 +61,76 @@ function dropContested(run: HordeRun, contest: SolvedSignal): void {
   run.solvedCommitted = false;
   run.solvedCoverageNotice = undefined;
   run.solvedVerificationNotice = undefined;
+}
+
+function dropContested(run: HordeRun, proposal: SolvedSignal, contest: SolvedSignal): void {
+  const blockers = contestBlockers(contest.text);
+  safeNotify(run, `horde ${run.id}: solved proposal contested by ${contest.member}`, "warning");
+  void recordLifecycle(run, "solved-contested", { member: contest.member, text: oneLine(contest.text, 200), blockers });
+  const reopens = blockers.length ? ` It reopens for validation once ${blockers.map((id) => `#${id}`).join(", ")} are done or ruled out.` : "";
+  void postBoard(
+    run.hordeDir,
+    "parent",
+    `SOLVED proposal contested by ${contest.member}: ${contest.text}. Work continues.${reopens}`,
+  );
+  clearProposal(run);
   run.solvedContested = true;
+  run.solvedContest = blockers.length ? { proposal, blockers } : undefined;
   refreshRun(run);
 }
 
+/**
+ * A proposal that cites a finding superseded or amended after it was made would ship the stale
+ * reading as the answer. It is withdrawn for re-proposal rather than validated; the board names
+ * the successor or the amendment.
+ */
+function withdrawStale(run: HordeRun, proposal: SolvedSignal, stale: string[]): void {
+  const reason = `cites ${stale.join(", ")}`;
+  safeNotify(run, `horde ${run.id}: solved proposal withdrawn; it ${reason}`, "warning");
+  void recordLifecycle(run, "solved-withdrawn", { member: proposal.member, reason });
+  void postBoard(
+    run.hordeDir,
+    "parent",
+    `SOLVED proposal by ${proposal.member} withdrawn: it ${reason}. ${proposal.member}: propose again citing the current findings.`,
+  );
+  clearProposal(run);
+  refreshRun(run);
+}
+
+/**
+ * A contest that named open ideas as what was missing is answered by their closing: nothing else
+ * reopens the vote, so the run ended `solved-contested` with the closed negatives unapplied.
+ */
+function reopenContested(run: HordeRun): void {
+  const contest = run.solvedContest;
+  if (!contest || run.stopped) return;
+  const closed = new Map(listIdeas(run.hordeDir).map((idea) => [idea.id, idea.mark === "x" || idea.mark === "!"]));
+  if (!contest.blockers.every((id) => closed.get(id))) return;
+  const named = contest.blockers.map((id) => `#${id}`).join(", ");
+  const reason = `contest blockers ${named} closed`;
+  // The proposal returns with the citations it pinned when it was made; what went stale or
+  // unsettled meanwhile makes it a re-proposal for its author, not a reopening.
+  const stale = [
+    ...staleAnswerCitations(listFindingsForRun(run.hordeDir, run.id), contest.proposal.text, contest.proposal.cites),
+    ...unsettledFactCitations(run.hordeDir, contest.proposal.text).map((citation) => `provisional ${citation}`),
+  ];
+  run.solvedContest = undefined;
+  if (stale.length) {
+    const why = `cites ${stale.join(", ")}`;
+    void recordLifecycle(run, "solved-withdrawn", { member: contest.proposal.member, reason: why });
+    void postBoard(run.hordeDir, "parent", `SOLVED proposal by ${contest.proposal.member} is not re-opened after ${reason}: it ${why}. ${contest.proposal.member}: propose again citing the current findings.`);
+    return;
+  }
+  const signal = reopenSolved(run.runDir, run.id, contest.proposal, `re-opened: ${reason}; awaiting validation`, contest.proposal.cites);
+  run.solvedContested = false;
+  void recordLifecycle(run, "solved-reopened", { member: signal.member, reason, revision: signal.revision });
+  void postBoard(
+    run.hordeDir,
+    "parent",
+    `SOLVED proposal by ${signal.member} re-opened: ${reason}. Another member must validate it against the closed ideas with 'horde confirm-solved' or contest it again.`,
+  );
+}
+
 /**
  * Coverage is structural: a run that created ideas must close them before a
  * solve winds it down, regardless of the prompt's wording. A run that created
@@ -124,11 +189,43 @@ function verificationPending(run: HordeRun, othersRunning: boolean): boolean {
   return true;
 }
 
+/**
+ * `--until-stop`: bank the answer as the run's current one and reopen the proposal slot, so a
+ * materially better answer can be proposed later. Nobody is stopped; the supervisor gives every
+ * member that finishes a fresh session.
+ */
+function bankSolved(run: HordeRun, proposal: SolvedSignal, validator: string | undefined): void {
+  run.solveRounds = (run.solveRounds ?? 0) + 1;
+  run.lastRound = { proposal, validator };
+  const status = validator ? `validated by ${validator}` : "committed without a separate validator";
+  try {
+    writeAnswer(run.runDir, run.id, proposal, `${status} (banked as round ${run.solveRounds}; the run continues until stopped)`);
+  } catch (error) {
+    safeNotify(run, `horde ${run.id}: could not write ANSWER.md (${oneLine(String(error), 200)})`, "error");
+  }
+  clearProposal(run);
+  run.solvedContest = undefined;
+  void recordLifecycle(run, "solved-banked", { round: run.solveRounds, member: proposal.member, validator });
+  safeNotify(run, `horde ${run.id}: solve banked as round ${run.solveRounds}; the run continues until stopped`, "info");
+  void postBoard(
+    run.hordeDir,
+    "parent",
+    `SOLVED ${status}, banked as round ${run.solveRounds}: ${oneLine(proposal.text, 200)}. ` +
+      "This run continues until the user stops it. Keep working: extend, stress-test, or deepen the work, " +
+      "add ideas for what is still unexplored, and propose SOLVED again only when a materially better answer exists.",
+  );
+  refreshRun(run);
+}
+
 function commitSolved(
   run: HordeRun,
   ctx: ExtensionCommandContext,
   validator: string | undefined,
 ): void {
+  if (run.untilStop && run.solved && !run.stopped) {
+    bankSolved(run, run.solved, validator);
+    return;
+  }
   run.solvedValidatedBy = validator;
   run.solvedCommitted = true;
   void recordLifecycle(run, "solved-validated", { validator });
@@ -150,13 +247,24 @@ function commitSolved(
 }
 
 /** One poll of the two-phase solved protocol. */
-function checkSolved(run: HordeRun, ctx: ExtensionCommandContext): void {
+export function checkSolved(run: HordeRun, ctx: ExtensionCommandContext): void {
   const state = resolveSolvedState(readSolvedState(run.runDir));
-  if (!run.solved && state.proposal) adoptProposal(run, state.proposal);
+  if (!run.solved && state.proposal) {
+    run.solvedContest = undefined;
+    adoptProposal(run, state.proposal);
+  }
   const solved = run.solved;
-  if (!solved) return;
+  if (!solved) {
+    reopenContested(run);
+    return;
+  }
   if (state.contest) {
-    dropContested(run, state.contest);
+    dropContested(run, solved, state.contest);
+    return;
+  }
+  const stale = staleAnswerCitations(listFindingsForRun(run.hordeDir, run.id), solved.text, solved.cites);
+  if (stale.length && !run.solvedCommitted) {
+    withdrawStale(run, solved, stale);
     return;
   }
   const validator =
@@ -167,7 +275,9 @@ function checkSolved(run: HordeRun, ctx: ExtensionCommandContext): void {
   if (coveragePending(run, validator)) return;
   const collaboration = loadCollaborationReport(run.hordeDir, run.id);
   if (collaboration.issues.length || openMessages(collaboration.state).length) return;
-  const othersRunning = run.members.some(
+  // Members of an `--until-stop` run are always coming back, so a lull between sessions is not
+  // the absence of a validator; the proposal waits for one or for the timeout.
+  const othersRunning = run.untilStop === true || run.members.some(
     (member) =>
       (member.status === "running" || member.status === "starting") &&
       member.name !== solved.member,

package/src/run/supervise.ts

@@ -4,13 +4,14 @@ import * as path from "node:path";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { envNumber, errorMessage } from "../format.js";
 import { postBoard } from "../ledger/board.js";
+import { pendingReviewsForMember } from "../ledger/findings.js";
 import { reconcileOwnedIdeas } from "../ledger/ideas.js";
 import { cleanStopRequestedFor, clearHeartbeat, readHeartbeat } from "../ledger/run-signals.js";
 import { resetMemberState, spawnMember } from "../member.js";
 import type { MemberState } from "../member.js";
 import { hardStopMembers } from "./controls.js";
 import { recordLifecycle } from "./lifecycle.js";
-import type { HordeRun, HordeState } from "./types.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
 import { refreshRun, safeNotify } from "./ui.js";
 
 /** A running member with no ledger write for this long is reset; 0 disables. */
@@ -22,9 +23,22 @@ const RESET_CAP = envNumber("PI_HORDE_RESET_CAP", 2);
 /** Member exits that a fresh session may recover from; a user stop is never one. */
 const RESETTABLE_CAUSES = new Set(["model_error", "no_output", "exit_nonzero"]);
 
+/**
+ * An `--until-stop` session that finished sooner than this is held back until it has been this
+ * long since it started, so a member that keeps finding nothing to do cannot spin through
+ * sessions, each paying the full prompt for nothing.
+ */
+const CONTINUE_COOLDOWN_MS = envNumber("PI_HORDE_CONTINUE_COOLDOWN_MS", 60_000);
+
+const CONTINUE_REASON = "until-stop: earlier session finished";
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms).unref?.());
+
 /** What spawning and supervising a run's members needs beyond the run itself. */
 export interface RunLaunch {
   state: HordeState;
+  /** The swarm the run belongs to; a plain run is a swarm of one. */
+  swarm: Swarm;
   run: HordeRun;
   ctx: ExtensionCommandContext;
   /** Per-member role instruction, indexed by member index - 1. */
@@ -80,16 +94,34 @@ export async function spawnOne(
  * stop all mean the run is ending; the cap keeps a broken provider from being
  * retried forever.
  */
-function resetReasonForExit(launch: RunLaunch, member: MemberState): string | undefined {
-  const { state, run } = launch;
-  if (state.disposed || run.stopped || run.userStop || run.solved || run.canary !== "ok") {
+/**
+ * A verifier that closes its session with high-importance findings by other members unreviewed
+ * has not done its job, whatever its summary says. Its exit is answered with a fresh session
+ * that is told which F# it owes, within the same reset cap as a crash.
+ */
+export function verificationBacklog(run: HordeRun, member: MemberState): string | undefined {
+  if (member.name !== run.verifier || member.endCause !== "completed") return undefined;
+  try {
+    const owed = pendingReviewsForMember(run.hordeDir, run.id, member.name)
+      .filter((finding) => ["critical", "high"].includes((finding.importance ?? "").toLowerCase()));
+    if (!owed.length) return undefined;
+    return `verification backlog: ${owed.map((finding) => `F${finding.id}`).join(", ")} unreviewed at close`;
+  } catch {
     return undefined;
   }
+}
+
+function resetReasonForExit(launch: RunLaunch, member: MemberState): string | undefined {
+  const { state, run } = launch;
+  if (state.disposed || run.stopped || run.userStop || run.canary !== "ok") return undefined;
+  // A pending proposal means the run is about to end, unless it runs until stopped.
+  if (run.solved && !run.untilStop) return undefined;
   if (cleanStopRequestedFor(run.hordeDir, run.id, member.name)) return undefined;
   const reason =
     member.resetPending ??
-    (RESETTABLE_CAUSES.has(member.endCause ?? "") ? member.endCause : undefined);
-  if (!reason) return undefined;
+    (RESETTABLE_CAUSES.has(member.endCause ?? "") ? member.endCause : undefined) ??
+    verificationBacklog(run, member);
+  if (!reason) return run.untilStop && member.endCause === "completed" ? CONTINUE_REASON : undefined;
   if ((member.resets ?? 0) >= RESET_CAP) {
     fs.appendFileSync(
       path.join(run.runDir, `${member.name}.log`),
@@ -115,10 +147,13 @@ async function releaseForReset(
     const releasedText = released.map((id) => `#${id}`).join(", ") || "none";
     const closedText =
       result.closed.map((item) => `#${item.id} (F${item.findingId})`).join(", ") || "none";
+    const head = reason === CONTINUE_REASON
+      ? `${member.name} finished and continues in a fresh session (${run.id} runs until stopped)`
+      : `reset ${member.name} (${reason})`;
     await postBoard(
       run.hordeDir,
       "parent",
-      `reset ${member.name} (${reason}): released ${releasedText}; closed ${closedText}. ` +
+      `${head}: released ${releasedText}; closed ${closedText}. ` +
         `A fresh session of ${member.name} starts now; earlier claims by ${member.name} ` +
         "are void.",
     );
@@ -157,13 +192,41 @@ async function performReset(run: HordeRun, member: MemberState, reason: string):
   await recordLifecycle(run, "member-reset", { member: member.name, reason, released, closed, resets: member.resets });
   member.resetNote =
     `You replace an earlier session of ${member.name} that was reset for ${reason}; ` +
-    "its ideas were released. Read BOARD.md and FINDINGS.md before claiming.";
+    "its ideas were released. Read BOARD.md and FINDINGS.md before claiming." +
+    (reason.startsWith("verification backlog") ? " Review the findings named above, with any verdict and an honest unchecked scope, before anything else." : "");
   clearHeartbeat(run.runDir, member.name);
   resetMemberState(member);
   safeNotify(run, `horde ${run.id}: reset ${member.name} (${reason})`, "warning");
   refreshRun(run);
 }
 
+/**
+ * `--until-stop`: a member that finished its session gets a fresh one. Not a recovery, so it
+ * counts against no cap and is not a reset in the report; the cooldown keeps a member that
+ * finds nothing to do from spinning.
+ */
+async function performContinue(run: HordeRun, member: MemberState): Promise<boolean> {
+  const elapsed = Date.now() - member.startedAt;
+  if (elapsed < CONTINUE_COOLDOWN_MS) await sleep(CONTINUE_COOLDOWN_MS - elapsed);
+  // A stop during the cooldown leaves the member as it ended: finished, not killed.
+  if (run.stopped) return false;
+  member.continuations = (member.continuations ?? 0) + 1;
+  fs.appendFileSync(
+    path.join(run.runDir, `${member.name}.log`),
+    `[horde] continue ${member.continuations}: ${CONTINUE_REASON}\n`,
+  );
+  const { released, closed } = await releaseForReset(run, member, CONTINUE_REASON);
+  await recordLifecycle(run, "member-continue", { member: member.name, released, closed, continuations: member.continuations });
+  member.resetNote =
+    `You are a fresh session of ${member.name}; its earlier session finished and its claims were released. ` +
+    "Read BOARD.md, FINDINGS.md and ANSWER.md if present, then add ideas that extend, stress-test, or deepen the work, claim them, and pursue them.";
+  clearHeartbeat(run.runDir, member.name);
+  resetMemberState(member);
+  safeNotify(run, `horde ${run.id}: ${member.name} finished; continuing in a fresh session`, "info");
+  refreshRun(run);
+  return true;
+}
+
 /**
  * Resolves only when the member is down for good, so the fan-out's
  * Promise.all cannot finalize the run while a replacement is running.
@@ -179,7 +242,11 @@ export async function superviseMember(
     await exited;
     const reason = resetReasonForExit(launch, member);
     if (!reason || state.disposed) return;
-    await performReset(run, member, reason);
+    if (reason === CONTINUE_REASON) {
+      if (!(await performContinue(run, member))) return;
+    } else {
+      await performReset(run, member, reason);
+    }
     if (run.stopped || state.disposed) {
       // A stop landed during the reset: leave the member down, not "starting".
       member.status = "stopped";
@@ -196,7 +263,7 @@ export async function superviseMember(
  * hung. Mark it and kill it; the supervise loop turns the kill into a reset.
  */
 function checkStalls(run: HordeRun): void {
-  if (run.stopped || run.solved) return;
+  if (run.stopped || (run.solved && !run.untilStop)) return;
   const now = Date.now();
   for (const member of run.members) {
     if (member.status !== "running" || member.paused || member.resetPending) continue;

package/src/run/swarm-finalize.ts

@@ -0,0 +1,121 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { errorMessage } from "../format.js";
+import { SWARM_REPORT_TYPE, swarmHordeRows, swarmReportMarkdown, swarmReportText } from "./swarm-report.js";
+import type { SwarmReportDetails } from "./swarm-report.js";
+import { runSwarmDeliverable } from "./synthesis.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
+import { refreshSwarm, safeNotify, unmountWidget } from "./ui.js";
+
+/** `SWARM.json`: the swarm's timeline for the dashboard once nothing is in memory. */
+export interface SwarmRecord {
+  id: string;
+  prompt: string;
+  hordes: number;
+  count: number;
+  startedAt: number;
+  untilStop: boolean;
+  partition: string[];
+  runs: Array<{ label: string; runId: string; runDir: string; hordeDir: string; startedAt: number; endedAt?: number | undefined; outcome?: string | undefined }>;
+  /** The merge step: when the swarm deliverable helper ran and whether it wrote anything. */
+  merge?: { startedAt: number; endedAt?: number | undefined; written?: boolean | undefined } | undefined;
+  endedAt?: number | undefined;
+}
+
+export function swarmRecord(swarm: Swarm): SwarmRecord {
+  return {
+    id: swarm.id,
+    prompt: swarm.prompt,
+    hordes: swarm.hordes,
+    count: swarm.count,
+    startedAt: swarm.startedAt,
+    untilStop: swarm.untilStop === true,
+    partition: swarm.partition ?? [],
+    runs: swarm.runs.map((run) => ({
+      label: `h${run.horde}`,
+      runId: run.id,
+      runDir: run.runDir,
+      hordeDir: run.hordeDir,
+      startedAt: run.startedAt,
+      endedAt: run.finalized ? Math.max(run.startedAt, ...run.members.map((m) => m.endedAt ?? 0)) : undefined,
+      outcome: run.outcome,
+    })),
+  };
+}
+
+/** Write a swarm file, reporting (not throwing) a failure so finalize keeps going. */
+function writeSwarmFile(swarm: Swarm, name: string, content: string): void {
+  if (!swarm.dir) return;
+  try {
+    fs.writeFileSync(path.join(swarm.dir, name), content, "utf-8");
+  } catch (error) {
+    safeNotify(swarm, `swarm ${swarm.id}: could not write ${name} (${errorMessage(error)})`, "error");
+  }
+}
+
+export function writeSwarmRecord(swarm: Swarm, extra: Partial<SwarmRecord> = {}): void {
+  writeSwarmFile(swarm, "SWARM.json", JSON.stringify({ ...swarmRecord(swarm), ...extra }, null, 2));
+}
+
+/**
+ * A horde's members exited and its REPORT.md is written. Once every horde is there the swarm
+ * slot frees, so a new launch can start while the (possibly slow) synthesis steps run.
+ */
+export function noteRunReported(state: HordeState, swarm: Swarm, run: HordeRun): void {
+  run.reported = true;
+  if (!swarm.runs.every((other) => other.reported === true)) return;
+  if (state.active === swarm) state.active = undefined;
+  state.finalizing = swarm;
+}
+
+/** The merged deliverable, REPORT.md, and the injected message of a swarm of several hordes. */
+async function mergeSwarm(state: HordeState, swarm: Swarm): Promise<void> {
+  swarm.finalizing = ["merge"];
+  refreshSwarm(swarm);
+  const merge: NonNullable<SwarmRecord["merge"]> = { startedAt: Date.now() };
+  writeSwarmRecord(swarm, { merge });
+  swarm.deliverable = process.env.PI_HORDE_DELIVERABLE === "off" ? undefined : await runSwarmDeliverable(state, swarm);
+  if (swarm.deliverable) writeSwarmFile(swarm, "DELIVERABLE.md", swarm.deliverable);
+  const now = Date.now();
+  merge.endedAt = now;
+  merge.written = Boolean(swarm.deliverable);
+  writeSwarmFile(swarm, "REPORT.md", swarmReportMarkdown(swarm, now));
+  writeSwarmRecord(swarm, { merge, endedAt: now });
+  if (state.disposed) return;
+  const details: SwarmReportDetails = {
+    swarmId: swarm.id,
+    elapsedMs: now - swarm.startedAt,
+    hordes: swarmHordeRows(swarm, now),
+    deliverable: swarm.deliverable,
+  };
+  const content = [swarmReportText(swarm, now), ...(swarm.deliverable ? ["## Deliverable", "", swarm.deliverable] : [])].join("\n\n");
+  // A hard stop of every horde keeps the parent idle, as it does for one horde.
+  const triggerTurn = swarm.runs.some((run) => run.cleanStopNames.length > 0 || !run.stopped);
+  state.pi.sendMessage(
+    { customType: SWARM_REPORT_TYPE, content, display: true, details },
+    { deliverAs: "followUp", triggerTurn },
+  );
+  safeNotify(swarm, `swarm ${swarm.id} finished`, "info");
+}
+
+/**
+ * A horde's finalize completed, synthesis included. The swarm step runs once every horde is
+ * done: a swarm of one has nothing to merge and only releases the widget.
+ */
+export async function noteRunFinalized(state: HordeState, swarm: Swarm, run: HordeRun): Promise<void> {
+  run.finalized = true;
+  if (!swarm.runs.every((other) => other.finalized === true)) {
+    refreshSwarm(swarm);
+    return;
+  }
+  try {
+    if (swarm.dir && !state.disposed) await mergeSwarm(state, swarm);
+  } catch (error) {
+    safeNotify(swarm, `swarm ${swarm.id} failed to finalize: ${errorMessage(error)}`, "error");
+  } finally {
+    swarm.finalizing = undefined;
+    if (state.active === swarm) state.active = undefined;
+    if (state.finalizing === swarm) state.finalizing = undefined;
+    unmountWidget(swarm);
+  }
+}

package/src/run/swarm-report.ts

@@ -0,0 +1,152 @@
+import * as path from "node:path";
+import { formatDateTime, formatElapsed, formatTokens, oneLine } from "../format.js";
+import { listFindingsForRun } from "../ledger/findings.js";
+import { statusCounts, totalUsage } from "../prompt.js";
+import { hordeLabel } from "./types.js";
+import type { HordeRun, Swarm } from "./types.js";
+
+/** One horde's totals for the swarm report and the injected message. */
+export interface SwarmHordeRow {
+  label: string;
+  runId: string;
+  runDir: string;
+  outcome: string;
+  members: number;
+  done: number;
+  failed: number;
+  stopped: number;
+  turns: number;
+  tokens: number;
+  cost: number;
+  findings: number;
+  elapsedMs: number;
+  deliverable: boolean;
+  postmortem: boolean;
+}
+
+/** What the swarm report message carries for its renderer. */
+export interface SwarmReportDetails {
+  swarmId: string;
+  elapsedMs: number;
+  hordes: SwarmHordeRow[];
+  deliverable?: string | undefined;
+}
+
+export const SWARM_REPORT_TYPE = "agent-horde-swarm-report";
+
+function findingCount(run: HordeRun): number {
+  try {
+    return listFindingsForRun(run.hordeDir, run.id).length;
+  } catch {
+    return 0;
+  }
+}
+
+function hordeRow(run: HordeRun, now: number): SwarmHordeRow {
+  const counts = statusCounts(run.members);
+  const usage = totalUsage(run.members);
+  const ended = Math.max(...run.members.map((member) => member.endedAt ?? now), run.startedAt);
+  return {
+    label: hordeLabel(run.horde),
+    runId: run.id,
+    runDir: run.runDir,
+    outcome: run.outcome ?? (run.finalized ? "finished" : "running"),
+    members: run.members.length,
+    done: counts.done,
+    failed: counts.failed,
+    stopped: counts.stopped,
+    turns: usage.turns,
+    tokens: usage.input + usage.output,
+    cost: usage.cost,
+    findings: findingCount(run),
+    elapsedMs: ended - run.startedAt,
+    deliverable: Boolean(run.deliverable),
+    postmortem: Boolean(run.postmortem),
+  };
+}
+
+export function swarmHordeRows(swarm: Swarm, now: number = Date.now()): SwarmHordeRow[] {
+  return swarm.runs.map((run) => hordeRow(run, now));
+}
+
+function sum(rows: SwarmHordeRow[], pick: (row: SwarmHordeRow) => number): number {
+  return rows.reduce((total, row) => total + pick(row), 0);
+}
+
+function hordeTable(rows: SwarmHordeRow[]): string[] {
+  return [
+    "| horde | run | outcome | members | done | failed | stopped | turns | tokens | cost | findings | elapsed |",
+    "|---|---|---|---|---|---|---|---|---|---|---|---|",
+    ...rows.map((row) =>
+      `| ${row.label} | ${row.runId} | ${row.outcome} | ${row.members} | ${row.done} | ${row.failed} | ` +
+      `${row.stopped} | ${row.turns} | ${formatTokens(row.tokens)} | $${row.cost.toFixed(4)} | ${row.findings} | ${formatElapsed(row.elapsedMs)} |`),
+    `| total | | | ${sum(rows, (r) => r.members)} | ${sum(rows, (r) => r.done)} | ${sum(rows, (r) => r.failed)} | ` +
+    `${sum(rows, (r) => r.stopped)} | ${sum(rows, (r) => r.turns)} | ${formatTokens(sum(rows, (r) => r.tokens))} | ` +
+    `$${sum(rows, (r) => r.cost).toFixed(4)} | ${sum(rows, (r) => r.findings)} | |`,
+  ];
+}
+
+/** REPORT.md of a swarm: the partition, per-horde totals, where each horde's files are, the merged deliverable. */
+export function swarmReportMarkdown(swarm: Swarm, now: number = Date.now()): string {
+  const rows = swarmHordeRows(swarm, now);
+  return [
+    `# Swarm ${swarm.id}`,
+    "",
+    `- started: ${formatDateTime(new Date(swarm.startedAt))}`,
+    `- elapsed: ${formatElapsed(now - swarm.startedAt)}`,
+    `- hordes: ${swarm.hordes} x ${swarm.count} members`,
+    `- until stop: ${swarm.untilStop ? "yes" : "no"}`,
+    `- outcomes: ${rows.map((row) => `${row.label} ${row.outcome}`).join(", ")}`,
+    `- merged deliverable: ${swarm.deliverable ? "DELIVERABLE.md" : "not written"}`,
+    "",
+    "## Prompt",
+    "",
+    swarm.prompt,
+    "",
+    "## Partition",
+    "",
+    ...(swarm.partition ?? []).map((slice, index) => `- ${hordeLabel(index + 1)}: ${slice}`),
+    "",
+    "## Hordes",
+    "",
+    ...hordeTable(rows),
+    "",
+    ...rows.flatMap((row) => [
+      `### ${row.label}: ${row.runId}`,
+      "",
+      `- ${path.join(row.runDir, "REPORT.md")}`,
+      ...(row.deliverable ? [`- ${path.join(row.runDir, "DELIVERABLE.md")}`] : []),
+      ...(row.postmortem ? [`- ${path.join(row.runDir, "POSTMORTEM.md")}`] : []),
+      "",
+    ]),
+    ...(swarm.deliverable ? ["## Deliverable", "", swarm.deliverable, ""] : []),
+  ].join("\n");
+}
+
+/** The message injected into the parent conversation when a swarm finishes. */
+export function swarmReportText(swarm: Swarm, now: number = Date.now()): string {
+  const rows = swarmHordeRows(swarm, now);
+  const dir = swarm.dir ?? "";
+  return [
+    `Swarm ${swarm.id} finished after ${formatElapsed(now - swarm.startedAt)}: ${swarm.hordes} hordes of ` +
+      `${swarm.count} members on one task, partitioned as ${rows.map((row) => `${row.label} (${row.outcome})`).join(", ")}.`,
+    `${sum(rows, (r) => r.turns)} turns, ${formatTokens(sum(rows, (r) => r.tokens))} tokens, ` +
+      `$${sum(rows, (r) => r.cost).toFixed(2)}, ${sum(rows, (r) => r.findings)} findings across the hordes.`,
+    "",
+    "Partition:",
+    ...(swarm.partition ?? []).map((slice, index) => `- ${hordeLabel(index + 1)}: ${oneLine(slice, 200)}`),
+    "",
+    "Files:",
+    `- ${path.join(dir, "REPORT.md")}        per-horde totals and where each horde's files are`,
+    ...(swarm.deliverable ? [`- ${path.join(dir, "DELIVERABLE.md")}   merged deliverable, each claim attributed to its horde`] : []),
+    `- ${path.join(dir, "SWARM.md")}         the prompt and the partition`,
+    ...rows.map((row) => `- ${row.runDir}/   ${row.label}: REPORT.md, DELIVERABLE.md, POSTMORTEM.md, SUMMARY.md`),
+    "",
+    ...(swarm.deliverable
+      ? [
+          "The merged deliverable is included below. No horde reviewed another's work, so verify claims",
+          "against the owning horde's FINDINGS.md and ACCEPTANCE.md before presenting them to the user.",
+        ]
+      : ["No merged deliverable was written; read each horde's REPORT.md and DELIVERABLE.md."]),
+  ].join("\n");
+}