agent-horde 0.1.6 → 0.2.0

package/src/run/launch.ts

@@ -1,7 +1,9 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { DashboardOption, HordeRunArgs } from "../args.js";
 import { resolveDashboardPort, startDashboard } from "../dashboard.js";
-import { errorMessage, oneLine } from "../format.js";
+import { envNumber, errorMessage, oneLine } from "../format.js";
 import { initHordeDir } from "../ledger/files.js";
 import { resetMemberState } from "../member.js";
 import type { MemberState } from "../member.js";
@@ -9,17 +11,26 @@ import { hardStopMembers, requestCleanStop } from "./controls.js";
 import { finalizeRun, stopRunTimers } from "./finalize.js";
 import { recordLifecycle, recordPhase } from "./lifecycle.js";
 import { createRun, seedRun } from "./setup.js";
+import type { RunSpec } from "./setup.js";
 import { drainRepairs } from "./repair.js";
 import { startCollaborationScheduler } from "./schedule.js";
 import { startSolvedWatch } from "./solved.js";
 import { spawnOne, startStallWatch, superviseMember } from "./supervise.js";
 import type { RunLaunch } from "./supervise.js";
-import type { HordeRun, HordeState } from "./types.js";
+import { allocateSwarm, dealLayers, siblingHordes, swarmMarkdown } from "./swarm.js";
+import type { SwarmLayout } from "./swarm.js";
+import { noteRunFinalized, noteRunReported, writeSwarmRecord } from "./swarm-finalize.js";
+import { runPlanner } from "./synthesis.js";
+import { activeRuns, finalizingRuns, hordeLabel } from "./types.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
 import { mountWidget, safeNotify, safeNotifyUi, unmountWidget } from "./ui.js";
 
 /** How long the canary preflight waits for the first token before declaring failure. */
 const CANARY_TIMEOUT_MS = Number(process.env.PI_HORDE_CANARY_MS) || 60_000;
 
+/** Pause between one horde's launch and the next, so H canaries do not hit the provider at once. */
+const SWARM_STAGGER_MS = envNumber("PI_HORDE_SWARM_STAGGER_MS", 5_000);
+
 type CanaryOutcome = "output" | "exit" | "timeout";
 
 function sleep(ms: number): Promise<void> {
@@ -53,7 +64,15 @@ async function ensureDashboard(
   try {
     state.dashboard = await startDashboard({
       port: resolveDashboardPort(option.port),
-      source: { hordeDir, getActive: () => state.active, getFinalizing: () => state.finalizing },
+      source: {
+        hordeDir,
+        getActive: () => (state.active ? activeRuns(state.active) : []),
+        getFinalizing: () => [
+          ...(state.active ? finalizingRuns(state.active) : []),
+          ...(state.finalizing ? finalizingRuns(state.finalizing) : []),
+        ],
+        getSwarm: () => state.active ?? state.finalizing,
+      },
       onError: (error) => {
         state.dashboard = undefined;
         safeNotifyUi(ctx, `dashboard error: ${error.message}; the run continues`, "error");
@@ -143,13 +162,18 @@ async function runCanary(launch: RunLaunch, spawns: Promise<void>[]): Promise<Ca
  * One retry distinguishes a flaky process from a dead provider.
  */
 async function preflightAndFanOut(launch: RunLaunch): Promise<void> {
-  const { state, run, ctx } = launch;
+  const { state, swarm, run, ctx } = launch;
+  if (run.stopped) {
+    // A stop arrived while this horde waited its turn: nothing to spawn, finalize now.
+    await finalizeRun(state, swarm, run);
+    return;
+  }
   const spawns: Promise<void>[] = [];
   const outcome = await runCanary(launch, spawns);
   if (run.stopped) {
     // A stop arrived during preflight: do not fan out, finalize now.
     await Promise.all(spawns);
-    await finalizeRun(state, run);
+    await finalizeRun(state, swarm, run);
     return;
   }
   if (outcome === "output") {
@@ -175,48 +199,169 @@ async function preflightAndFanOut(launch: RunLaunch): Promise<void> {
   if (run.scheduleTimer) clearInterval(run.scheduleTimer);
   run.scheduleTimer = undefined;
   await drainRepairs(launch);
-  await finalizeRun(state, run);
+  await finalizeRun(state, swarm, run);
+}
+
+/** The hordes' workstreams and plans: dealt layers, the planner's slices, or nothing for one horde. */
+interface Partition {
+  slices: string[] | undefined;
+  /** Per-horde plan layers, indexed by horde - 1. */
+  plans: Array<string[] | undefined>;
+}
+
+/** Note the planner's failure where the dashboard and the operator can find it. */
+function writeNotStarted(layout: SwarmLayout, reason: string): void {
+  if (!layout.dir) return;
+  fs.writeFileSync(path.join(layout.dir, "SWARM.md"), `# Swarm ${layout.id}\n\nNot started: ${reason}\n`, "utf-8");
+}
+
+/**
+ * Decide what each horde works on. `plan` layers go round-robin to the hordes and each horde
+ * runs its share as its own plan; a plain prompt is split by the planner helper, and a planner
+ * that cannot produce H distinct workstreams stops the launch rather than running H hordes on
+ * one slice.
+ */
+async function partitionTask(
+  state: HordeState,
+  ctx: ExtensionCommandContext,
+  parsed: HordeRunArgs,
+  layout: SwarmLayout,
+): Promise<Partition | undefined> {
+  if (parsed.hordes === 1) return { slices: undefined, plans: [parsed.plan] };
+  if (parsed.plan) {
+    const dealt = dealLayers(parsed.plan, parsed.hordes);
+    return { slices: dealt.map((layers) => layers.join("; ")), plans: dealt };
+  }
+  ctx.ui.notify(`swarm ${layout.id}: planner is partitioning the task into ${parsed.hordes} workstreams`, "info");
+  const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+  const result = await runPlanner(state, { dir: layout.dir!, cwd: ctx.cwd, model, prompt: parsed.prompt, hordes: parsed.hordes });
+  if ("error" in result) {
+    writeNotStarted(layout, result.error);
+    ctx.ui.notify(`swarm ${layout.id} not started: ${result.error}`, "error");
+    return undefined;
+  }
+  return { slices: result.slices, plans: Array.from({ length: parsed.hordes }, () => undefined) };
+}
+
+function buildSwarm(
+  ctx: ExtensionCommandContext,
+  parsed: HordeRunArgs,
+  layout: SwarmLayout,
+  partition: Partition,
+  dashboardUrl: string | undefined,
+): { swarm: Swarm; launches: Array<{ run: HordeRun; roles: string[] }> } {
+  const launches = layout.runIds.map((id, index) => {
+    const spec: RunSpec = {
+      id,
+      hordeDir: layout.hordeDirs[index]!,
+      runDir: layout.runDirs[index]!,
+      horde: index + 1,
+      hordes: parsed.hordes,
+      swarmId: layout.id,
+      slice: partition.slices?.[index],
+      plan: partition.plans[index],
+      siblings: siblingHordes(layout, partition.slices, index + 1),
+    };
+    return createRun(ctx, parsed, spec, dashboardUrl);
+  });
+  const swarm: Swarm = {
+    id: layout.id,
+    dir: layout.dir,
+    hordeDir: layout.hordeDirs.length === 1 ? layout.hordeDirs[0]! : path.resolve(layout.dir!, "..", ".."),
+    cwd: ctx.cwd,
+    prompt: parsed.prompt,
+    hordes: parsed.hordes,
+    count: parsed.count,
+    startedAt: Date.now(),
+    runs: launches.map((launch) => launch.run),
+    plan: parsed.plan,
+    partition: partition.slices,
+    untilStop: parsed.untilStop === true ? true : undefined,
+    dashboardUrl,
+  };
+  return { swarm, launches };
+}
+
+/** Seed one horde's ledgers and record its start; throws on a ledger failure. */
+async function seedHorde(swarm: Swarm, run: HordeRun, roles: string[]): Promise<void> {
+  await seedRun(run);
+  await recordLifecycle(run, "run-start", {
+    count: run.count, model: run.model, verifier: run.verifier, plan: run.plan, untilStop: run.untilStop,
+    roles: roles.map((role) => oneLine(role, 120)), dashboardUrl: run.dashboardUrl,
+    ...(swarm.hordes > 1 ? { swarm: swarm.id, horde: run.horde, hordes: swarm.hordes, slice: run.slice } : {}),
+  });
+  await recordPhase(run, "discovery", "start");
+}
+
+function announceStart(ctx: ExtensionCommandContext, swarm: Swarm): void {
+  if (swarm.hordes === 1) {
+    const run = swarm.runs[0]!;
+    const plural = run.count === 1 ? "" : "s";
+    ctx.ui.notify(`horde ${run.id} started with ${run.count} member${plural} in ${run.hordeDir}`, "info");
+    if (run.dashboardUrl) ctx.ui.notify(`horde ${run.id} dashboard: ${run.dashboardUrl}runs/${run.id}`, "info");
+    return;
+  }
+  ctx.ui.notify(
+    `swarm ${swarm.id} started: ${swarm.hordes} hordes of ${swarm.count} members in ${swarm.dir}, ` +
+      `${Math.round(SWARM_STAGGER_MS / 1000)}s apart`,
+    "info",
+  );
+  for (const [index, slice] of (swarm.partition ?? []).entries()) {
+    ctx.ui.notify(`${hordeLabel(index + 1)}: ${oneLine(slice, 160)}`, "info");
+  }
+  if (swarm.dashboardUrl) ctx.ui.notify(`swarm ${swarm.id} dashboard: ${swarm.dashboardUrl}swarms/${swarm.id}`, "info");
+}
+
+/** Start the hordes' preflights a few seconds apart; a stop during the wait is honoured. */
+async function staggerLaunches(state: HordeState, launches: RunLaunch[]): Promise<void> {
+  for (const [index, launch] of launches.entries()) {
+    if (index > 0 && !state.disposed) await sleep(SWARM_STAGGER_MS);
+    if (state.disposed) return;
+    void preflightAndFanOut(launch).catch((error) => {
+      safeNotify(launch.run, `horde ${launch.run.id} failed: ${errorMessage(error)}`, "error");
+      // The horde is down for good; let the swarm account for it so the slot and widget free.
+      noteRunReported(state, launch.swarm, launch.run);
+      void noteRunFinalized(state, launch.swarm, launch.run);
+    });
+  }
 }
 
-async function launchRun(
+async function launchSwarm(
   state: HordeState,
   ctx: ExtensionCommandContext,
   parsed: HordeRunArgs,
   hordeDir: string,
 ): Promise<void> {
-  const { run, roles } = createRun(ctx, parsed, hordeDir, state.dashboard?.url);
-  // Claim the run synchronously, before the first await, so a second
+  const layout = allocateSwarm(hordeDir, parsed.hordes, Date.now());
+  const partition = await partitionTask(state, ctx, parsed, layout);
+  if (!partition || state.disposed) return;
+  const { swarm, launches } = buildSwarm(ctx, parsed, layout, partition, state.dashboard?.url);
+  // Claim the slot synchronously, before the first await, so a second
   // /agent-horde invocation in the same tick sees `active` and is refused.
-  state.active = run;
-  if (ctx.hasUI) mountWidget(run, ctx.ui);
-  startDeadline(run, ctx);
-  startSolvedWatch(run, ctx);
+  state.active = swarm;
+  if (ctx.hasUI) mountWidget(swarm, ctx.ui);
+  for (const run of swarm.runs) {
+    startDeadline(run, ctx);
+    startSolvedWatch(run, ctx);
+  }
   try {
-    await seedRun(run);
-    await recordLifecycle(run, "run-start", {
-      count: run.count, model: run.model, verifier: run.verifier, plan: run.plan, untilStop: run.untilStop,
-      roles: roles.map((role) => oneLine(role, 120)), dashboardUrl: run.dashboardUrl,
-    });
-    await recordPhase(run, "discovery", "start");
+    if (swarm.dir) {
+      fs.writeFileSync(path.join(swarm.dir, "SWARM.md"), swarmMarkdown(swarm), "utf-8");
+      writeSwarmRecord(swarm);
+    }
+    for (const { run, roles } of launches) await seedHorde(swarm, run, roles);
   } catch (error) {
-    stopRunTimers(run);
-    unmountWidget(run);
-    if (state.active === run) state.active = undefined;
-    ctx.ui.notify(`horde ${run.id} failed to start: ${errorMessage(error)}`, "error");
+    for (const run of swarm.runs) stopRunTimers(run);
+    unmountWidget(swarm);
+    if (state.active === swarm) state.active = undefined;
+    ctx.ui.notify(`horde ${swarm.id} failed to start: ${errorMessage(error)}`, "error");
     return;
   }
-  void preflightAndFanOut({ state, run, ctx, roles }).catch((error) => {
-    safeNotify(run, `horde ${run.id} failed: ${errorMessage(error)}`, "error");
-    if (state.active === run) state.active = undefined;
-  });
-  const plural = run.count === 1 ? "" : "s";
-  ctx.ui.notify(`horde ${run.id} started with ${run.count} member${plural} in ${hordeDir}`, "info");
-  if (run.dashboardUrl) {
-    ctx.ui.notify(`horde ${run.id} dashboard: ${run.dashboardUrl}runs/${run.id}`, "info");
-  }
+  void staggerLaunches(state, launches.map(({ run, roles }) => ({ state, swarm, run, ctx, roles })));
+  announceStart(ctx, swarm);
 }
 
-export async function startRun(
+export async function startSwarm(
   state: HordeState,
   ctx: ExtensionCommandContext,
   parsed: HordeRunArgs,
@@ -225,7 +370,7 @@ export async function startRun(
   try {
     const hordeDir = initHordeDir(ctx.cwd);
     if (!(await ensureDashboard(state, ctx, hordeDir, parsed.dashboard))) return;
-    await launchRun(state, ctx, parsed, hordeDir);
+    await launchSwarm(state, ctx, parsed, hordeDir);
   } finally {
     state.starting = false;
   }

package/src/run/setup.ts

@@ -4,15 +4,31 @@ import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { HordeRunArgs } from "../args.js";
-import { formatRunId } from "../format.js";
 import { appendRunHeading } from "../ledger/board.js";
 import { listFacts } from "../ledger/facts.js";
 import { ensureFindingIds } from "../ledger/findings.js";
 import { claimIdea, listIdeas, seedPlan } from "../ledger/ideas.js";
 import { newMemberState } from "../member.js";
+import type { SiblingHorde } from "../member.js";
 import { VERIFIER_ROLE, memberSystemPrompt, taskMarkdown } from "../prompt.js";
 import type { HordeRun } from "./types.js";
 
+/** Where one horde of a swarm runs and what it was given. */
+export interface RunSpec {
+  id: string;
+  hordeDir: string;
+  runDir: string;
+  /** 1-based horde index in the swarm. */
+  horde: number;
+  hordes: number;
+  swarmId: string;
+  /** The horde's workstream when the swarm partitioned the task. */
+  slice?: string | undefined;
+  /** The `plan` layers this horde runs as its own plan. */
+  plan?: string[] | undefined;
+  siblings: SiblingHorde[];
+}
+
 function planMarkdown(id: string, layers: string[], count: number): string {
   return [
     `# Plan ${id}`,
@@ -55,32 +71,17 @@ function defaultRoles(count: number, noVerifier: boolean): string[] {
   return roles;
 }
 
-function allocateRunDir(hordeDir: string, startedAt: number): { id: string; runDir: string } {
-  const base = formatRunId(new Date(startedAt));
-  for (let attempt = 0; ; attempt++) {
-    const id = attempt === 0 ? base : `${base}-${attempt}`;
-    const runDir = path.join(hordeDir, "runs", id);
-    try {
-      fs.mkdirSync(runDir);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
-      throw error;
-    }
-    fs.mkdirSync(path.join(runDir, "sessions"), { recursive: true });
-    return { id, runDir };
-  }
-}
-
-/** Allocate the run directory, write TASK.md and SYSTEM.md, and build the run record. */
+/** Write TASK.md and SYSTEM.md into the allocated run directory and build the run record. */
 export function createRun(
   ctx: ExtensionCommandContext,
   parsed: HordeRunArgs,
-  hordeDir: string,
+  spec: RunSpec,
   dashboardUrl: string | undefined,
 ): { run: HordeRun; roles: string[] } {
-  const { count, prompt, plan } = parsed;
+  const { count, prompt } = parsed;
+  const { id, hordeDir, runDir, plan } = spec;
   const startedAt = Date.now();
-  const { id, runDir } = allocateRunDir(hordeDir, startedAt);
+  fs.mkdirSync(path.join(runDir, "sessions"), { recursive: true });
   const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
   const roles =
     plan && plan.length > 0
@@ -88,18 +89,27 @@ export function createRun(
       : defaultRoles(count, parsed.noVerifier === true);
   const verifierIndex = roles.indexOf(VERIFIER_ROLE);
   const verifier = verifierIndex === -1 ? undefined : `member-${verifierIndex + 1}`;
+  const swarm = spec.hordes > 1 ? { id: spec.swarmId, horde: spec.horde, hordes: spec.hordes, slice: spec.slice } : undefined;
   fs.writeFileSync(
     path.join(runDir, "TASK.md"),
     taskMarkdown({
-      id, prompt, count, model, thinkingLevel: ctx.thinkingLevel, startedAt, verifier, untilStop: parsed.untilStop,
+      id, prompt, count, model, thinkingLevel: ctx.thinkingLevel, startedAt, verifier, untilStop: parsed.untilStop, swarm,
     }),
     "utf-8",
   );
-  fs.writeFileSync(path.join(runDir, "SYSTEM.md"), memberSystemPrompt({ hordeDir, count }), "utf-8");
+  fs.writeFileSync(
+    path.join(runDir, "SYSTEM.md"),
+    memberSystemPrompt({ hordeDir, count, siblings: spec.siblings }),
+    "utf-8",
+  );
   fs.mkdirSync(path.join(runDir, "artifacts"), { recursive: true });
-  writeManifest(runDir, { model, thinking: ctx.thinkingLevel, roles, prompt });
+  writeManifest(runDir, { model, thinking: ctx.thinkingLevel, roles, prompt, swarm });
   const run: HordeRun = {
     id, hordeDir, runDir, prompt, count, startedAt,
+    horde: spec.horde,
+    hordes: spec.hordes,
+    slice: spec.slice,
+    siblings: spec.siblings,
     members: Array.from({ length: count }, (_, i) => newMemberState(i + 1)),
     controller: new AbortController(),
     controllers: new Map(),
@@ -131,7 +141,7 @@ function writeManifest(runDir: string, settings: Record<string, unknown>): void
     }
   };
   visit(root);
-  const config = Object.fromEntries(Object.entries(process.env).filter(([key]) => /^PI_HORDE_(?:REPAIR|REMIND|STALL|RESET|MAX|ALLOW|SOLVED|INBOX|CANARY|DELIVERABLE|POSTMORTEM|CLEANUP)/.test(key)));
+  const config = Object.fromEntries(Object.entries(process.env).filter(([key]) => /^PI_HORDE_(?:REPAIR|REMIND|STALL|RESET|MAX|ALLOW|SOLVED|INBOX|CANARY|DELIVERABLE|POSTMORTEM|CLEANUP|SWARM|PLANNER)/.test(key)));
   fs.writeFileSync(path.join(runDir, "MANIFEST.json"), JSON.stringify({ protocol: 1, codeHash: code.digest("hex"),
     promptHash: createHash("sha256").update(String(settings.prompt)).digest("hex"),
     systemHash: createHash("sha256").update(fs.readFileSync(path.join(runDir, "SYSTEM.md"))).digest("hex"), settings, config }, null, 2));

package/src/run/supervise.ts

@@ -11,7 +11,7 @@ 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. */
@@ -37,6 +37,8 @@ const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout
 /** 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. */

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