agent-horde 0.1.6 → 0.2.1

package/src/prompt.ts

@@ -9,7 +9,7 @@ import type { PeerMessage, ReviewRecord } from "./ledger/collaboration.js";
 import type { Idea } from "./ledger/ideas.js";
 import type { ResourceEntry } from "./ledger/resources.js";
 import type { SolvedSignal } from "./ledger/run-signals.js";
-import type { MemberReset, MemberState } from "./member.js";
+import type { MemberReset, MemberState, SiblingHorde } from "./member.js";
 
 /** A resource with the non-owner members whose findings, evidence, reviews or leases cite it. */
 export type ReportResource = ResourceEntry & { citedBy?: string[] | undefined };
@@ -34,6 +34,8 @@ export interface RunSummaryInput {
   solvedCommitted?: boolean | undefined;
   /** Members whose queued repair work was skipped for budget. */
   repairSkipped?: string[] | undefined;
+  /** Members held back from later rounds because their attempt left every thread unchanged. */
+  repairStalled?: string[] | undefined;
   /** The REPORT.md outcome, so SUMMARY.md states the same end cause. */
   outcome?: string | undefined;
   /** One-line run diagnosis shown in the report message. */
@@ -126,6 +128,8 @@ Collaboration loop:
   a finding on that idea, explicitly set responseTarget=F#. Superseded F# requests follow the correction.
   Requester: attach/review evidence on the current response target, then resolve target=Q# refs=[E#]
   revision=current-hash text=decision, or defer with a reason. Disclosed finding limitations remain debt.
+  A blocking request about your own work resolves on the recipient's full supporting review of the
+  current revision, since you cannot review it yourself.
   Do not repeat your existing check: inspect collaboration first and test a specific remaining gap.
   A deferred blocking issue stays visible as acceptance debt; its recipient can still respond to it and
   the requester then resolves it. Never silently ignore a peer's failed test.
@@ -169,7 +173,26 @@ Collaboration loop:
   attempt after discovery exits. Repair attempts must address assigned feedback only.
 `;
 
-export function memberSystemPrompt(input: { hordeDir: string; count: number }): string {
+/** What a member of a swarm is told about the other hordes: shared read, local write. */
+function siblingsSection(siblings: SiblingHorde[]): string {
+  if (siblings.length === 0) return "";
+  const lines = siblings.map(
+    (sibling) => `- ${sibling.label}: ${sibling.hordeDir}/${sibling.slice ? ` (workstream: ${sibling.slice})` : ""}`,
+  );
+  return `
+Your horde is one of ${siblings.length + 1} hordes working the same task in parallel, each with its
+own ledgers. The other hordes' directories are read-only for you:
+
+${lines.join("\n")}
+
+'horde facts' and 'horde resources' include their entries tagged [hN], and 'horde list' includes
+their done and ruled-out ideas, so a fact, a rule-out, or a resource another horde recorded is not
+re-derived here; reuse a sibling's resource by its path. Every write goes to your own horde's
+ledgers; never write to a sibling's directory, and never claim or cite a sibling's ideas as yours.
+`;
+}
+
+export function memberSystemPrompt(input: { hordeDir: string; count: number; siblings?: SiblingHorde[] | undefined }): string {
   const count = input.count;
   return `You are one member of a horde of ${count} agents. Every member received the same task
 and works in parallel in this repository with its own separate context. Coordinate through the
@@ -188,9 +211,9 @@ horde tool. Durable run events retain messages, evidence, reviews and revisions;
 - PLAN.md     workstream partition and your assigned layer, when the run was started with plan.
 
 Read them with the read tool. Write them ONLY with the horde tool; never edit them directly.
-Put reproduction snippets under .horde/runs/<run-id>/artifacts/ using PI_HORDE_RUN, so evidence
-survives finalization and line references do not drift.
-
+Put reproduction snippets under ${input.hordeDir}/runs/<run-id>/artifacts/ using PI_HORDE_RUN, so
+evidence survives finalization and line references do not drift.
+${siblingsSection(input.siblings ?? [])}
 Protocol:
 1. Run 'horde list', 'horde findings', 'horde facts', and read BOARD.md before planning.
 2. Prefer the shared queue. Add an idea only for an uncovered question or concrete evidence gap.
@@ -254,7 +277,8 @@ Protocol:
     proposal reopens for validation once every idea it named is done or ruled out. Pass the revision
     from ANSWER.md or 'horde inspect' target=answer to either action, so stale reviews cannot approve
     a newer proposal. An answer that cites a superseded F# or quotes a provisional T# is refused, and a
-    pending proposal is withdrawn for re-proposal when a finding it cites is superseded. A request to
+    pending proposal is withdrawn for re-proposal when a finding it cites is superseded or amended,
+    or an artifact it cites is republished. A request to
     the proposer or a validator about the pending answer (target=answer) is served with the blockers.
     The parent enforces coverage before wind-down.
 
@@ -275,7 +299,10 @@ export function taskMarkdown(input: {
   startedAt: number;
   verifier?: string | undefined;
   untilStop?: boolean | undefined;
+  /** Set for a horde of a larger swarm: which horde this is and its workstream. */
+  swarm?: { id: string; horde: number; hordes: number; slice?: string | undefined } | undefined;
 }): string {
+  const swarm = input.swarm;
   return [
     `# Horde run ${input.id}`,
     "",
@@ -285,6 +312,8 @@ export function taskMarkdown(input: {
     `Thinking: ${input.thinkingLevel ?? "parent default"}`,
     `Verifier: ${input.verifier ?? "none"}`,
     `Until stop: ${input.untilStop ? "yes (the run continues until stop-clean or stop-hard)" : "no"}`,
+    ...(swarm ? [`Swarm: ${swarm.id} (horde h${swarm.horde} of ${swarm.hordes})`] : []),
+    ...(swarm?.slice ? [`Workstream: ${swarm.slice}`] : []),
     `Task-SHA256: ${taskHash(input.prompt)}`,
     "",
     "## Prompt",
@@ -438,10 +467,12 @@ export function runEndSentence(run: RunSummaryInput): string {
   const attempts = run.members.reduce((n, m) => n + (m.repairs ?? 0), 0);
   const killed = run.members.filter((m) => ["tokens", "turns", "time"].includes(m.repairStopReason ?? ""));
   const skipped = run.repairSkipped ?? [];
+  const stalled = run.repairStalled ?? [];
   if (attempts > 0 || skipped.length > 0) {
     const detail = [
       killed.length ? `${killed.length} killed on budget (${killed.map((m) => `${m.name}: ${m.repairStopReason}`).join(", ")})` : "",
       skipped.length ? `${skipped.length} skipped for budget (${skipped.join(", ")})` : "",
+      stalled.length ? `${stalled.length} held after no progress (${stalled.join(", ")})` : "",
     ].filter(Boolean).join(", ");
     parts.push(`Repair: ${attempts} attempt(s)${detail ? `, ${detail}` : ""}.`);
   }

package/src/run/command.ts

@@ -1,20 +1,40 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { USAGE, parseHordeArgs } from "../args.js";
+import type { HordeTarget } from "../args.js";
 import { clearCleanStop } from "../ledger/run-signals.js";
 import { terminateAllChildren } from "../member.js";
 import { formatStatusReport } from "../prompt.js";
-import { requestCleanStop, setPaused, stopHard, targetMembers } from "./controls.js";
+import { requestCleanStop, resolveTargets, setPaused, stopHard, targetMembers } from "./controls.js";
+import type { RunSelection } from "./controls.js";
 import { stopRunTimers } from "./finalize.js";
-import { closeDashboard, startRun } from "./launch.js";
-import type { HordeRun, HordeState } from "./types.js";
+import { closeDashboard, startSwarm } from "./launch.js";
+import type { HordeState, Swarm } from "./types.js";
 import { unmountWidget } from "./ui.js";
 
-/** The active run, or undefined after telling the user there is none. */
-function requireActive(state: HordeState, ctx: ExtensionCommandContext): HordeRun | undefined {
+/** The active swarm, or undefined after telling the user there is none. */
+function requireActive(state: HordeState, ctx: ExtensionCommandContext): Swarm | undefined {
   if (!state.active) ctx.ui.notify("no horde run is active", "info");
   return state.active;
 }
 
+/** The runs and members a control command addresses, or undefined after the user was told why not. */
+function select(state: HordeState, target: HordeTarget, ctx: ExtensionCommandContext): RunSelection[] | undefined {
+  const swarm = requireActive(state, ctx);
+  if (!swarm) return undefined;
+  const selections = resolveTargets(swarm, target, ctx);
+  if (selections && selections.length === 0) ctx.ui.notify("the target selects no members", "info");
+  return selections && selections.length > 0 ? selections : undefined;
+}
+
+function showStatus(selections: RunSelection[], ctx: ExtensionCommandContext): void {
+  const blocks: string[] = [];
+  for (const { run, target } of selections) {
+    const members = targetMembers(run, target, ctx);
+    if (members) blocks.push(formatStatusReport({ ...run, members }));
+  }
+  if (blocks.length > 0) ctx.ui.notify(blocks.join("\n\n"), "info");
+}
+
 /** Handle one `/agent-horde` invocation. */
 export async function handleHordeCommand(
   state: HordeState,
@@ -31,61 +51,72 @@ export async function handleHordeCommand(
       ctx.ui.notify(USAGE, "info");
       return;
     case "status": {
-      const run = requireActive(state, ctx);
-      const members = run && targetMembers(run, parsed.target, ctx);
-      if (run && members) ctx.ui.notify(formatStatusReport({ ...run, members }), "info");
+      const selections = select(state, parsed.target, ctx);
+      if (selections) showStatus(selections, ctx);
       return;
     }
     case "stop": {
-      const run = requireActive(state, ctx);
-      if (!run) return;
-      if (parsed.mode === "clean") {
-        await requestCleanStop(run, parsed.target, ctx, {
-          graceMs: parsed.graceMs,
-          postmortem: parsed.postmortem,
-        });
-      } else {
-        stopHard(run, parsed.target, ctx);
+      const selections = select(state, parsed.target, ctx);
+      if (!selections) return;
+      for (const { run, target } of selections) {
+        if (parsed.mode === "clean") {
+          await requestCleanStop(run, target, ctx, { graceMs: parsed.graceMs, postmortem: parsed.postmortem });
+        } else {
+          stopHard(run, target, ctx);
+        }
       }
       return;
     }
     case "pause":
     case "resume": {
-      const run = requireActive(state, ctx);
-      if (run) setPaused(run, parsed.target, ctx, parsed.kind === "pause");
+      const selections = select(state, parsed.target, ctx);
+      if (!selections) return;
+      for (const { run, target } of selections) setPaused(run, target, ctx, parsed.kind === "pause");
       return;
     }
     case "run":
       if (state.active || state.starting) {
+        const noun = state.active && state.active.hordes > 1 ? "swarm" : "horde";
         ctx.ui.notify(
-          `horde ${state.active?.id ?? ""} is still active; use /agent-horde status or /agent-horde stop-hard`.replace("  ", " "),
+          `${noun} ${state.active?.id ?? ""} is still active; use /agent-horde status or /agent-horde stop-hard`.replace("  ", " "),
           "error",
         );
         return;
       }
-      await startRun(state, ctx, parsed);
+      await startSwarm(state, ctx, parsed);
+  }
+}
+
+function abortSwarm(swarm: Swarm): void {
+  swarm.deliverableAbort?.abort();
+  for (const run of swarm.runs) {
+    run.stopped = true;
+    run.userStop = true;
+    run.postmortemAbort?.abort();
+    run.deliverableAbort?.abort();
+    stopRunTimers(run);
+    clearCleanStop(run.runDir);
+    run.controller.abort();
+    run.ui = undefined;
   }
+  try {
+    unmountWidget(swarm);
+  } catch {
+    // The UI is already being torn down.
+  }
+  swarm.ui = undefined;
 }
 
-/** Session teardown: abort the active run and every helper, without finalizing. */
+/** Session teardown: abort the active swarm and every helper, without finalizing. */
 export function shutdownHorde(state: HordeState): void {
   state.disposed = true;
   process.off("exit", terminateAllChildren);
   closeDashboard(state);
-  const run = state.active;
+  state.plannerAbort?.abort();
+  const active = state.active;
+  const finalizing = state.finalizing;
   state.active = undefined;
-  if (!run) return;
-  run.stopped = true;
-  run.userStop = true;
-  run.postmortemAbort?.abort();
-  run.deliverableAbort?.abort();
-  stopRunTimers(run);
-  clearCleanStop(run.runDir);
-  run.controller.abort();
-  try {
-    unmountWidget(run);
-  } catch {
-    // The UI is already being torn down.
-  }
-  run.ui = undefined;
+  state.finalizing = undefined;
+  if (active) abortSwarm(active);
+  if (finalizing && finalizing !== active) abortSwarm(finalizing);
 }

package/src/run/completions.ts

@@ -1,5 +1,6 @@
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
-import type { HordeRun } from "./types.js";
+import { hordeLabel } from "./types.js";
+import type { Swarm } from "./types.js";
 
 const CONTROL_SUBCOMMANDS: Array<{
   value: string;
@@ -41,7 +42,24 @@ const EXTRA_COMPLETIONS: Record<string, Array<{ value: string; description: stri
   plan: [DASHBOARD_COMPLETION],
 };
 
-export function controlCompletions(prefix: string, active: HordeRun | undefined): AutocompleteItem[] | null {
+/** `all`, then the members of a single horde, or `hN` and `hN:member-M` for a larger swarm. */
+function targetNames(active: Swarm | undefined): Array<{ name: string; description: string }> {
+  if (!active) return [{ name: "all", description: "all members" }];
+  const total = active.runs.reduce((sum, run) => sum + run.members.length, 0);
+  const names = [{ name: "all", description: active.hordes > 1 ? `all ${total} members of ${active.hordes} hordes` : `all ${total} members` }];
+  if (active.hordes === 1) {
+    for (const member of active.runs[0]?.members ?? []) names.push({ name: member.name, description: member.status });
+    return names;
+  }
+  for (const run of active.runs) {
+    const label = hordeLabel(run.horde);
+    names.push({ name: label, description: `horde ${label}: ${run.members.length} members` });
+    for (const member of run.members) names.push({ name: `${label}:${member.name}`, description: member.status });
+  }
+  return names;
+}
+
+export function controlCompletions(prefix: string, active: Swarm | undefined): AutocompleteItem[] | null {
   const space = prefix.search(/\s/);
   if (space === -1 && prefix.startsWith("-")) {
     const items = LAUNCH_FLAG_COMPLETIONS.filter((flag) => flag.value.startsWith(prefix)).map(
@@ -66,18 +84,12 @@ export function controlCompletions(prefix: string, active: HordeRun | undefined)
   const match = /^([\s\S]*?)([^\s,]*)$/.exec(rest);
   const base = match?.[1] ?? "";
   const token = match?.[2] ?? "";
-  const names = active && sub.takesTarget ? active.members.map((m) => m.name) : [];
-  const targetItems: AutocompleteItem[] = (sub.takesTarget ? ["all", ...names] : [])
-    .filter((name) => name.startsWith(token))
-    .map((name) => ({
-      value: `${head} ${base}${name}`,
-      label: name,
-      description:
-        name === "all"
-          ? active
-            ? `all ${active.count} members`
-            : "all members"
-          : active?.members.find((m) => m.name === name)?.status,
+  const targetItems: AutocompleteItem[] = (sub.takesTarget ? targetNames(active) : [])
+    .filter((target) => target.name.startsWith(token))
+    .map((target) => ({
+      value: `${head} ${base}${target.name}`,
+      label: target.name,
+      description: target.description,
     }));
   const extraItems: AutocompleteItem[] = (EXTRA_COMPLETIONS[head] ?? [])
     .filter((extra) => {

package/src/run/controls.ts

@@ -5,7 +5,8 @@ import { postBoard } from "../ledger/board.js";
 import { readCleanStop, readSolvedState, writeCleanStop } from "../ledger/run-signals.js";
 import { recordLifecycle } from "./lifecycle.js";
 import type { MemberState } from "../member.js";
-import type { HordeRun } from "./types.js";
+import { hordeLabel } from "./types.js";
+import type { HordeRun, Swarm } from "./types.js";
 import { refreshRun, safeNotify } from "./ui.js";
 
 /** How long stop-clean lets members wrap up before it escalates to stop-hard. */
@@ -26,10 +27,63 @@ interface CleanStopOptions {
   label?: CleanStopLabel | undefined;
 }
 
-function selectedMembers(
-  run: HordeRun,
+/** A control target resolved to one run: every member, or the named ones. */
+export type RunTarget = { kind: "all" } | { kind: "members"; names: string[] };
+
+/** One run a control command applies to, with its share of the target. */
+export interface RunSelection {
+  run: HordeRun;
+  target: RunTarget;
+}
+
+/**
+ * Resolve a target across the swarm: `all` and `hN` select whole runs, a bare member selects
+ * that member in every horde, `hN:member-M` one member of one horde. Runs the target does not
+ * touch are left out. Notifies and returns undefined when a horde or member does not exist.
+ */
+export function resolveTargets(
+  swarm: Swarm,
   target: HordeTarget,
-): { members: MemberState[]; invalid: string[] } {
+  ctx: ExtensionCommandContext,
+): RunSelection[] | undefined {
+  if (target.kind === "all") return swarm.runs.map((run) => ({ run, target: { kind: "all" } }));
+  const whole = new Set<HordeRun>();
+  const named = new Map<HordeRun, Set<string>>();
+  const invalid: string[] = [];
+  for (const item of target.items) {
+    const runs = item.horde === undefined ? swarm.runs : swarm.runs.filter((run) => run.horde === item.horde);
+    if (runs.length === 0) {
+      invalid.push(hordeLabel(item.horde ?? 0));
+      continue;
+    }
+    for (const run of runs) {
+      if (item.member === undefined) {
+        whole.add(run);
+        continue;
+      }
+      if (!run.members.some((member) => member.name === item.member)) {
+        invalid.push(swarm.hordes > 1 ? `${hordeLabel(run.horde)}:${item.member}` : item.member);
+        continue;
+      }
+      if (!named.has(run)) named.set(run, new Set());
+      named.get(run)!.add(item.member);
+    }
+  }
+  if (invalid.length > 0) {
+    const hordes = invalid.filter((name) => !name.includes("member"));
+    const members = invalid.filter((name) => name.includes("member"));
+    if (hordes.length > 0) ctx.ui.notify(`no such horde: ${[...new Set(hordes)].join(", ")}`, "error");
+    if (members.length > 0) ctx.ui.notify(`no such member: ${[...new Set(members)].join(", ")}`, "error");
+    return undefined;
+  }
+  return swarm.runs.flatMap((run): RunSelection[] => {
+    if (whole.has(run)) return [{ run, target: { kind: "all" } }];
+    const names = named.get(run);
+    return names ? [{ run, target: { kind: "members", names: [...names] } }] : [];
+  });
+}
+
+function selectedMembers(run: HordeRun, target: RunTarget): { members: MemberState[]; invalid: string[] } {
   if (target.kind === "all") return { members: run.members, invalid: [] };
   const known = new Set(run.members.map((m) => m.name));
   return {
@@ -38,10 +92,10 @@ function selectedMembers(
   };
 }
 
-/** Resolve a target, or notify and return undefined when it names unknown members. */
+/** Resolve a run target, or notify and return undefined when it names unknown members. */
 export function targetMembers(
   run: HordeRun,
-  target: HordeTarget,
+  target: RunTarget,
   ctx: ExtensionCommandContext,
 ): MemberState[] | undefined {
   const { members, invalid } = selectedMembers(run, target);
@@ -63,7 +117,12 @@ export function hardStopMembers(run: HordeRun, names: string[]): void {
   }
 }
 
-export function stopHard(run: HordeRun, target: HordeTarget, ctx: ExtensionCommandContext): void {
+/** `h2: ` in a swarm's notifications, nothing for a swarm of one. */
+function prefix(run: HordeRun): string {
+  return (run.hordes ?? 1) > 1 ? `${hordeLabel(run.horde)}: ` : "";
+}
+
+export function stopHard(run: HordeRun, target: RunTarget, ctx: ExtensionCommandContext): void {
   const members = targetMembers(run, target, ctx);
   if (!members) return;
   const names = members.map((m) => m.name);
@@ -72,13 +131,13 @@ export function stopHard(run: HordeRun, target: HordeTarget, ctx: ExtensionComma
   run.stopLabel = "stopped by user";
   hardStopMembers(run, names);
   void recordLifecycle(run, "stop-hard", { members: names, by: "user" });
-  ctx.ui.notify(`stop-hard: terminating ${names.join(", ")}`, "warning");
+  ctx.ui.notify(`${prefix(run)}stop-hard: terminating ${names.join(", ")}`, "warning");
 }
 
 /** Suspend (SIGSTOP) or resume (SIGCONT) the targeted live members. */
 export function setPaused(
   run: HordeRun,
-  target: HordeTarget,
+  target: RunTarget,
   ctx: ExtensionCommandContext,
   paused: boolean,
 ): void {
@@ -104,7 +163,7 @@ export function setPaused(
     : changed > 0
       ? `resumed ${changed} member(s)`
       : "no paused members to resume";
-  ctx.ui.notify(message, "info");
+  ctx.ui.notify(`${prefix(run)}${message}`, "info");
 }
 
 function stopLabelFor(label: CleanStopLabel): string {
@@ -134,7 +193,7 @@ function holdCleanStop(
   run.cleanStopUntil = Date.now() + holdMs;
   run.cleanStopTimer = setTimeout(() => finishCleanStop(run, members, label), holdMs);
   run.cleanStopTimer.unref?.();
-  safeNotify(run, message, "info");
+  safeNotify(run, `${prefix(run)}${message}`, "info");
   refreshRun(run);
 }
 
@@ -184,7 +243,7 @@ function finishCleanStop(run: HordeRun, members: MemberState[], label: CleanStop
   run.cleanStopUntil = undefined;
   hardStopMembers(run, run.cleanStopNames);
   void recordLifecycle(run, "stop-hard", { members: run.cleanStopNames, by: label });
-  safeNotify(run, `${label} deadline reached: terminating ${run.cleanStopNames.join(", ")}`, "warning");
+  safeNotify(run, `${prefix(run)}${label} deadline reached: terminating ${run.cleanStopNames.join(", ")}`, "warning");
   refreshRun(run);
 }
 
@@ -202,7 +261,7 @@ function wakePaused(run: HordeRun, members: MemberState[]): void {
 /** Ask the targeted members to wrap up, with a hard stop once the grace period ends. */
 export async function requestCleanStop(
   run: HordeRun,
-  target: HordeTarget,
+  target: RunTarget,
   ctx: ExtensionCommandContext,
   options: CleanStopOptions = {},
 ): Promise<void> {
@@ -210,7 +269,7 @@ export async function requestCleanStop(
   const members = targetMembers(run, target, ctx);
   if (!members) return;
   if (members.length === 0) {
-    ctx.ui.notify("no running members to stop", "info");
+    ctx.ui.notify(`${prefix(run)}no running members to stop`, "info");
     return;
   }
   const grace = options.graceMs ?? CLEAN_STOP_GRACE_MS;
@@ -236,7 +295,7 @@ export async function requestCleanStop(
   refreshRun(run);
   const graceSeconds = Math.round(grace / 1000);
   ctx.ui.notify(
-    `${label}: ${requested.length} member(s) wrapping up, hard stop in ${graceSeconds}s`,
+    `${prefix(run)}${label}: ${requested.length} member(s) wrapping up, hard stop in ${graceSeconds}s`,
     "warning",
   );
   try {

package/src/run/finalize.ts

@@ -20,7 +20,7 @@ import { clusterFindings } from "../ledger/clusters.js";
 import { listFacts } from "../ledger/facts.js";
 import type { FactEntry } from "../ledger/facts.js";
 import { readHordeFile } from "../ledger/files.js";
-import { listFindingsForRun, parseFindings, supersededCitations } from "../ledger/findings.js";
+import { listFindingsForRun, parseFindings, staleAnswerFor } from "../ledger/findings.js";
 import type { FindingEntry } from "../ledger/findings.js";
 import { countIdeas, parseIdeas, reconcileOwnedIdeas } from "../ledger/ideas.js";
 import type { Idea } from "../ledger/ideas.js";
@@ -35,9 +35,10 @@ import { runGraphMarkdown } from "../run-graph-mermaid.js";
 import type { CleanupStatus, ReportResource, RunReportInput } from "../prompt.js";
 import { buildDiagnosis } from "./diagnosis.js";
 import { recordLifecycle, recordPhase } from "./lifecycle.js";
+import { noteRunFinalized, noteRunReported } from "./swarm-finalize.js";
 import { runDeliverable, runPostmortem } from "./synthesis.js";
-import type { HordeRun, HordeState } from "./types.js";
-import { REPORT_TYPE, refreshRun, reportDetails, safeNotify, unmountWidget } from "./ui.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
+import { REPORT_TYPE, refreshRun, reportDetails, safeNotify } from "./ui.js";
 
 /** Most deliverable warnings shown inline; REPORT.md keeps the full list. */
 const INLINE_WARNING_CAP = 12;
@@ -136,19 +137,18 @@ interface SettledAnswer {
   status: string;
 }
 
-/** Findings the proposal names that a later finding corrected; labeled, not re-versioned. */
 /**
  * The proposal body is the member's verbatim text and can predate later challenges and corrections.
- * The status names the blockers still open at freeze and the findings a later finding superseded,
- * and, once synthesis wrote it, points the operator at DELIVERABLE.md as the reconciled output.
+ * The status names the blockers still open at freeze and the citations that changed after the
+ * proposal pinned them (superseded or amended findings, republished artifacts), and, once
+ * synthesis wrote it, points the operator at DELIVERABLE.md as the reconciled output.
  */
-function annotateAnswer(run: HordeRun, answer: SettledAnswer, acceptance: { hash: string; issues: string[] }, findings: FindingEntry[]): void {
+function annotateAnswer(run: HordeRun, answer: SettledAnswer, acceptance: { hash: string; issues: string[] }, stale: string[]): void {
   const blockers = acceptance.issues.filter((issue) => /^Q\d+ .*: \w+ blocking /.test(issue)).map((issue) => issue.replace(/:/, ""));
   const parts = [answer.status];
   if (acceptance.issues.length) parts.push("acceptance incomplete");
   if (blockers.length) parts.push(`open blocking at freeze: ${blockers.join(", ")}`);
-  const superseded = supersededCitations(answer.proposal.text, findings);
-  if (superseded.length) parts.push(`cites superseded ${superseded.join(", ")}`);
+  if (stale.length) parts.push(`cites ${stale.join(", ")}`);
   parts.push(`see ACCEPTANCE.md (snapshot ${acceptance.hash})`);
   if (run.deliverable) parts.push("reconciled operator output: DELIVERABLE.md; the proposal text below is verbatim and may be superseded there");
   try {
@@ -279,12 +279,11 @@ async function runCleanup(run: HordeRun, item: PendingCleanup): Promise<CleanupR
  * Tear down the labs this run registered before writing the report, so the
  * report states whether cleanup succeeded and no containers outlive the run.
  */
-async function runCleanups(state: HordeState, run: HordeRun): Promise<CleanupResult[]> {
+async function runCleanups(run: HordeRun): Promise<CleanupResult[]> {
   const pending =
     process.env.PI_HORDE_CLEANUP === "off" ? [] : pendingCleanups(run.hordeDir, run.id);
   if (pending.length === 0) return [];
   run.finalizing = ["cleanup"];
-  state.finalizing = run;
   refreshRun(run);
   const cleanups: CleanupResult[] = [];
   for (const item of pending) cleanups.push(await runCleanup(run, item));
@@ -337,6 +336,7 @@ function writeRunReports(
   });
   const memberPosts = lastBoardPostsByMember(run.hordeDir, run.id);
   const outcome = runOutcome(run);
+  run.outcome = outcome;
   let events: HordeEvent[] = [];
   try {
     events = readEvents(run.hordeDir, run.id);
@@ -461,7 +461,6 @@ async function synthesize(
   if (wantPostmortem) steps.push("post-mortem");
   if (steps.length > 0) {
     run.finalizing = steps;
-    state.finalizing = run;
     refreshRun(run);
   }
   run.deliverable = undefined;
@@ -502,7 +501,15 @@ async function synthesize(
   }
 }
 
-function sendReport(state: HordeState, run: HordeRun, ledgers: RunLedgers, now: number): void {
+/**
+ * Inject the run report into the parent conversation. A horde of a larger swarm only notifies:
+ * the swarm sends one merged report once every horde has finished.
+ */
+function sendReport(state: HordeState, swarm: Swarm, run: HordeRun, ledgers: RunLedgers, now: number): void {
+  if (swarm.hordes > 1) {
+    safeNotify(run, `horde ${run.id} ${run.stopped ? "stopped" : "finished"} (${run.outcome ?? "finished"})`, "info");
+    return;
+  }
   const sections = [reportText(run, ledgers.ideaCounts, ledgers.findings.length, now)];
   if (run.deliverable) sections.push("## Deliverable", "", run.deliverable);
   if (run.postmortem) sections.push("## Post-mortem", "", run.postmortem);
@@ -535,8 +542,11 @@ export function writeRunGraph(run: HordeRun): void {
   }
 }
 
-/** Wind a run down once every member has exited: reconcile, report, synthesize, notify. */
-export async function finalizeRun(state: HordeState, run: HordeRun): Promise<void> {
+/**
+ * Wind a run down once every member has exited: reconcile, report, synthesize, notify. The
+ * swarm's slot frees once every horde has reported, and the swarm step follows the last finalize.
+ */
+export async function finalizeRun(state: HordeState, swarm: Swarm, run: HordeRun): Promise<void> {
   const now = Date.now();
   try {
     if (state.disposed) return;
@@ -548,25 +558,24 @@ export async function finalizeRun(state: HordeState, run: HordeRun): Promise<voi
     run.acceptance = acceptance.status;
     run.snapshotHash = acceptance.hash;
     await recordLifecycle(run, "acceptance", { status: acceptance.status, hash: acceptance.hash, issues: acceptance.issues.length });
-    const annotate = answer !== undefined &&
-      (acceptance.issues.length > 0 || supersededCitations(answer.proposal.text, ledgers.findings).length > 0);
-    if (annotate) annotateAnswer(run, answer, acceptance, ledgers.findings);
+    const stale = answer ? staleAnswerFor(run.hordeDir, run.id, answer.proposal.text, answer.proposal.cites) : [];
+    const annotate = answer !== undefined && (acceptance.issues.length > 0 || stale.length > 0);
+    if (annotate) annotateAnswer(run, answer, acceptance, stale);
     // Workers and bounded repairs have exited; only now may their labs be torn down.
-    const cleanups = await runCleanups(state, run);
+    const cleanups = await runCleanups(run);
     const reportInput = writeRunReports(run, ledgers, releasedIdeas, cleanups, now);
     // Free the slot before the (possibly slow) synthesis so a new run can start.
-    if (state.active === run) state.active = undefined;
+    noteRunReported(state, swarm, run);
     await synthesize(state, run, ledgers, reportInput, now);
-    if (annotate && run.deliverable) annotateAnswer(run, answer, acceptance, ledgers.findings);
-    sendReport(state, run, ledgers, now);
+    if (annotate && run.deliverable) annotateAnswer(run, answer, acceptance, stale);
+    sendReport(state, swarm, run, ledgers, now);
     await recordLifecycle(run, "run-end", { outcome: runOutcome(run), elapsedMs: Date.now() - run.startedAt, stopLabel: run.stopLabel });
     writeRunGraph(run);
   } catch (error) {
     safeNotify(run, `horde ${run.id} failed to finalize: ${errorMessage(error)}`, "error");
   } finally {
-    if (state.active === run) state.active = undefined;
+    noteRunReported(state, swarm, run);
     run.finalizing = undefined;
-    if (state.finalizing === run) state.finalizing = undefined;
-    unmountWidget(run);
+    await noteRunFinalized(state, swarm, run);
   }
 }