agent-horde 0.1.6 → 0.2.1

package/src/dashboard.ts

@@ -1,7 +1,6 @@
 import * as http from "node:http";
 import {
   DashboardError,
-  latestRunId,
   listRunSessions,
   listRuns,
   loadBoard,
@@ -18,10 +17,22 @@ import {
   loadResources,
   loadSessionEntry,
   loadSessionTranscript,
+  loadSwarm,
+  loadSwarmBoard,
+  loadSwarmClaims,
+  loadSwarmCollaboration,
+  loadSwarmFacts,
+  loadSwarmFile,
+  loadSwarmFindings,
+  loadSwarmGraph,
+  loadSwarmIdeas,
+  loadSwarmResources,
   loadTranscript,
   loadTranscriptEntry,
   MEMBER_RE,
-  RUN_ID_RE,
+  requireRun,
+  swarmHordes,
+  swarmOfRun,
 } from "./dashboard-data.js";
 import type { DashboardSource, GraphView } from "./dashboard-data.js";
 import {
@@ -42,10 +53,19 @@ import {
   renderRunOverview,
   renderResources,
   renderSessions,
+  renderSwarm,
+  renderSwarmBoard,
+  renderSwarmClaims,
+  renderSwarmCollaboration,
+  renderSwarmFacts,
+  renderSwarmFindings,
+  renderSwarmGraph,
+  renderSwarmIdeas,
+  renderSwarmResources,
   renderTranscript,
   renderTranscriptEntry,
 } from "./dashboard-html.js";
-import type { RenderContext } from "./dashboard-html.js";
+import type { PageKind, RenderContext, Scope } from "./dashboard-html.js";
 import { collect, exportDashboard } from "./dashboard-export.js";
 import type { ExportPage } from "./dashboard-export.js";
 
@@ -72,6 +92,10 @@ interface Route {
   live: (vm: unknown, src: DashboardSource, params: string[], query: URLSearchParams) => boolean;
   load: (src: DashboardSource, params: string[], query: URLSearchParams) => unknown;
   render: (vm: never, ctx: RenderContext) => string;
+  /** What the page is about; params[0] is the run or swarm id for those scopes. */
+  scope: "project" | "run" | "swarm";
+  /** Which page-row item the page is, so the nav can mark it and horde tabs can keep it. */
+  page: PageKind;
   /** Serve the renderer's output as text/plain instead of a page. */
   text?: boolean;
 }
@@ -103,12 +127,6 @@ function queryFrom(query: URLSearchParams): number | "last" {
   return query.get("from") === "last" ? "last" : queryInt(query, "from", 0, 999_999_999, 0);
 }
 
-function queryRun(query: URLSearchParams): string {
-  const value = query.get("run") ?? "all";
-  if (value !== "all" && !RUN_ID_RE.test(value)) throw new DashboardError(400, `invalid run: ${value}`);
-  return value;
-}
-
 function queryOwner(query: URLSearchParams): string | undefined {
   const value = query.get("owner");
   if (value === null || value === "") return undefined;
@@ -116,17 +134,39 @@ function queryOwner(query: URLSearchParams): string | undefined {
   return value;
 }
 
+function queryOrder(query: URLSearchParams): "newest" | "oldest" {
+  return queryEnum(query, "order", ["newest", "oldest"] as const, "newest");
+}
+
+function queryView(query: URLSearchParams): "list" | "clusters" {
+  return queryEnum(query, "view", ["list", "clusters"] as const, "list");
+}
+
 function isActive(src: DashboardSource, runId: string | undefined): boolean {
-  return runId !== undefined && src.getActive()?.id === runId;
+  return runId !== undefined && src.getActive().some((run) => run.id === runId);
 }
 
 function isFinalizing(src: DashboardSource, runId: string | undefined): boolean {
-  return runId !== undefined && src.getFinalizing?.()?.id === runId;
+  return runId !== undefined && (src.getFinalizing?.() ?? []).some((run) => run.id === runId);
+}
+
+function isRunLive(src: DashboardSource, runId: string): boolean {
+  return isActive(src, runId) || isFinalizing(src, runId);
+}
+
+/** A swarm page is live while the swarm is in memory: members running or the merge step pending. */
+function isSwarmLive(src: DashboardSource, swarmId: string | undefined): boolean {
+  return swarmId !== undefined && src.getSwarm?.()?.id === swarmId;
+}
+
+/** The project ledgers change while a single run (one writing to the project `.horde`) is live. */
+function isProjectLive(src: DashboardSource): boolean {
+  return src.getActive().some((run) => run.hordeDir === src.hordeDir);
 }
 
 function memberRunning(src: DashboardSource, runId: string, member: string): boolean {
-  const state = src.getActive()?.members.find((m) => m.name === member);
-  return isActive(src, runId) && state !== undefined && (state.status === "running" || state.status === "starting");
+  const state = src.getActive().find((run) => run.id === runId)?.members.find((m) => m.name === member);
+  return state !== undefined && (state.status === "running" || state.status === "starting");
 }
 
 const p = (params: string[], i: number): string => params[i] ?? "";
@@ -142,84 +182,112 @@ function graphView(query: URLSearchParams): GraphView {
   };
 }
 
-const ROUTES: Route[] = [
-  {
-    pattern: /^\/$/,
-    live: () => true,
-    load: (src) => listRuns(src),
-    render: renderRunIndex,
-  },
-  {
-    pattern: /^\/runs\/([^/]+)$/,
-    live: (_vm, src, params) => isActive(src, p(params, 0)) || isFinalizing(src, p(params, 0)),
-    load: (src, params) => loadRunOverview(src, p(params, 0)),
-    render: renderRunOverview,
-  },
-  {
-    pattern: /^\/runs\/([^/]+)\/collaboration$/,
-    live: (_vm, src, params) => isActive(src, p(params, 0)),
-    load: (src, params, query) => loadCollaboration(src, p(params, 0), queryInt(query, "from", 0, 999_999_999, 0)),
-    render: renderCollaboration,
-  },
-  {
-    pattern: /^\/runs\/([^/]+)\/graph$/,
-    live: (_vm, src, params) => isActive(src, p(params, 0)) || isFinalizing(src, p(params, 0)),
-    load: (src, params, query) => loadRunGraph(src, p(params, 0), graphView(query)),
-    render: renderGraph,
-  },
-  {
-    pattern: /^\/runs\/([^/]+)\/graph\.mmd$/,
-    live: () => false,
-    load: (src, params) => loadRunGraph(src, p(params, 0), { width: GRAPH_WIDTH_DEFAULT, from: 0, to: 0 }),
-    render: renderGraphMermaid,
-    text: true,
-  },
+const LEDGERS = ["ideas", "board", "findings", "claims", "facts", "resources"] as const;
+type Ledger = (typeof LEDGERS)[number];
+
+/** A ledger page for the project (`run` undefined) or for one run, which may be a swarm horde. */
+const LEDGER_LOAD: Record<Ledger, (src: DashboardSource, run: string | undefined, query: URLSearchParams) => unknown> = {
+  ideas: (src, run, query) => loadIdeas(src, queryOwner(query), run),
+  board: (src, run, query) => loadBoard(src, run ?? "all", queryOrder(query)),
+  findings: (src, run, query) => loadFindings(src, run ?? "all", queryView(query), queryIds(query, "open")),
+  claims: (src, run) => loadClaims(src, run),
+  facts: (src, run) => loadFacts(src, run),
+  resources: (src, run) => loadResources(src, run),
+};
+
+const SWARM_LEDGER_LOAD: Record<Ledger, (src: DashboardSource, swarmId: string, query: URLSearchParams) => unknown> = {
+  ideas: (src, swarmId, query) => loadSwarmIdeas(src, swarmId, queryOwner(query)),
+  board: (src, swarmId, query) => loadSwarmBoard(src, swarmId, queryOrder(query)),
+  findings: (src, swarmId, query) => loadSwarmFindings(src, swarmId, queryView(query), queryIds(query, "open")),
+  claims: (src, swarmId) => loadSwarmClaims(src, swarmId),
+  facts: (src, swarmId) => loadSwarmFacts(src, swarmId),
+  resources: (src, swarmId) => loadSwarmResources(src, swarmId),
+};
+
+const LEDGER_RENDER: Record<Ledger, Route["render"]> = {
+  ideas: renderIdeas, board: renderBoard, findings: renderFindings, claims: renderClaims, facts: renderFacts, resources: renderResources,
+};
+
+const SWARM_LEDGER_RENDER: Record<Ledger, Route["render"]> = {
+  ideas: renderSwarmIdeas, board: renderSwarmBoard, findings: renderSwarmFindings,
+  claims: renderSwarmClaims, facts: renderSwarmFacts, resources: renderSwarmResources,
+};
+
+/** Every ledger page in its three scopes: `/<ledger>`, `/runs/<id>/<ledger>`, `/swarms/<id>/<ledger>`. */
+function ledgerRoutes(): Route[] {
+  return LEDGERS.flatMap((kind): Route[] => [
+    {
+      pattern: new RegExp(`^/${kind}$`), scope: "project", page: kind,
+      live: (_vm, src) => isProjectLive(src),
+      load: (src, _params, query) => LEDGER_LOAD[kind](src, undefined, query),
+      render: LEDGER_RENDER[kind],
+    },
+    {
+      pattern: new RegExp(`^/runs/([^/]+)/${kind}$`), scope: "run", page: kind,
+      live: (_vm, src, params) => isRunLive(src, p(params, 0)),
+      load: (src, params, query) => {
+        requireRun(src, p(params, 0));
+        return LEDGER_LOAD[kind](src, p(params, 0), query);
+      },
+      render: LEDGER_RENDER[kind],
+    },
+    {
+      pattern: new RegExp(`^/swarms/([^/]+)/${kind}$`), scope: "swarm", page: kind,
+      live: (_vm, src, params) => isSwarmLive(src, p(params, 0)),
+      load: (src, params, query) => SWARM_LEDGER_LOAD[kind](src, p(params, 0), query),
+      render: SWARM_LEDGER_RENDER[kind],
+    },
+  ]);
+}
+
+/** Pages that exist for one run only: members, logs, transcripts, sessions, run files. */
+const RUN_DETAIL_ROUTES: Route[] = [
   {
-    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)$/,
+    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)$/, scope: "run", page: "other",
     live: (_vm, src, params) => memberRunning(src, p(params, 0), p(params, 1)),
     load: (src, params, query) => loadMemberDetail(src, p(params, 0), p(params, 1), queryInt(query, "tail", 1, 2000, 60)),
     render: renderMemberDetail,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/log$/,
+    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/log$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params, query) => loadMemberLog(src, p(params, 0), p(params, 1), queryInt(query, "tail", 0, 2000, 500)),
     render: renderMemberLog,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/transcript$/,
+    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/transcript$/, scope: "run", page: "other",
     live: (_vm, src, params, query) => query.get("from") === "last" && memberRunning(src, p(params, 0), p(params, 1)),
     load: (src, params, query) =>
       loadTranscript(src, p(params, 0), p(params, 1), queryFrom(query), queryInt(query, "n", 1, 200, 50)),
     render: renderTranscript,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/transcript\/(\d{1,9})$/,
+    pattern: /^\/runs\/([^/]+)\/members\/([^/]+)\/transcript\/(\d{1,9})$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params) => loadTranscriptEntry(src, p(params, 0), p(params, 1), Number(p(params, 2))),
     render: renderTranscriptEntry,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/sessions$/,
+    pattern: /^\/runs\/([^/]+)\/sessions$/, scope: "run", page: "other",
     live: (_vm, src, params) => isActive(src, p(params, 0)),
     load: (src, params) => listRunSessions(src, p(params, 0)),
     render: renderSessions,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/sessions\/([^/]+)$/,
+    pattern: /^\/runs\/([^/]+)\/sessions\/([^/]+)$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params, query) =>
       loadSessionTranscript(src, p(params, 0), p(params, 1), queryFrom(query), queryInt(query, "n", 1, 200, 50)),
     render: renderTranscript,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/sessions\/([^/]+)\/(\d{1,9})$/,
+    pattern: /^\/runs\/([^/]+)\/sessions\/([^/]+)\/(\d{1,9})$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params) => loadSessionEntry(src, p(params, 0), p(params, 1), Number(p(params, 2))),
     render: renderTranscriptEntry,
   },
   {
-    pattern: /^\/runs\/([^/]+)\/files\/([^/]+)$/,
+    pattern: /^\/runs\/([^/]+)\/files\/([^/]+)$/, scope: "run", page: "other",
     live: () => false,
     load: (src, params) => {
       const vm = loadRunFile(src, p(params, 0), p(params, 1));
@@ -228,52 +296,70 @@ const ROUTES: Route[] = [
     },
     render: renderFile,
   },
+];
+
+const ROUTES: Route[] = [
   {
-    pattern: /^\/ideas$/,
+    pattern: /^\/$/, scope: "project", page: "overview",
     live: () => true,
-    load: (src, _params, query) => loadIdeas(src, queryOwner(query)),
-    render: renderIdeas,
+    load: (src) => listRuns(src),
+    render: renderRunIndex,
   },
   {
-    pattern: /^\/board$/,
-    live: () => true,
-    load: (src, _params, query) =>
-      loadBoard(src, queryRun(query), queryEnum(query, "order", ["newest", "oldest"] as const, "newest")),
-    render: renderBoard,
+    pattern: /^\/runs\/([^/]+)$/, scope: "run", page: "overview",
+    live: (_vm, src, params) => isRunLive(src, p(params, 0)),
+    load: (src, params) => loadRunOverview(src, p(params, 0)),
+    render: renderRunOverview,
   },
   {
-    pattern: /^\/findings$/,
-    live: () => true,
-    load: (src, _params, query) =>
-      loadFindings(
-        src,
-        queryRun(query),
-        queryEnum(query, "view", ["list", "clusters"] as const, "list"),
-        queryIds(query, "open"),
-      ),
-    render: renderFindings,
+    pattern: /^\/runs\/([^/]+)\/collaboration$/, scope: "run", page: "collaboration",
+    live: (_vm, src, params) => isActive(src, p(params, 0)),
+    load: (src, params, query) => loadCollaboration(src, p(params, 0), queryInt(query, "from", 0, 999_999_999, 0)),
+    render: renderCollaboration,
   },
   {
-    pattern: /^\/claims$/,
-    live: () => true,
-    load: (src) => loadClaims(src),
-    render: renderClaims,
+    pattern: /^\/runs\/([^/]+)\/graph$/, scope: "run", page: "graph",
+    live: (_vm, src, params) => isRunLive(src, p(params, 0)),
+    load: (src, params, query) => loadRunGraph(src, p(params, 0), graphView(query)),
+    render: renderGraph,
   },
   {
-    pattern: /^\/facts$/,
-    live: () => true,
-    load: (src, _params, query) => {
-      const run = queryRun(query);
-      return loadFacts(src, run === "all" ? undefined : run);
-    },
-    render: renderFacts,
+    pattern: /^\/runs\/([^/]+)\/graph\.mmd$/, scope: "run", page: "graph",
+    live: () => false,
+    load: (src, params) => loadRunGraph(src, p(params, 0), { width: GRAPH_WIDTH_DEFAULT, from: 0, to: 0 }),
+    render: renderGraphMermaid,
+    text: true,
   },
+  ...RUN_DETAIL_ROUTES,
   {
-    pattern: /^\/resources$/,
-    live: () => true,
-    load: (src) => loadResources(src),
-    render: renderResources,
+    pattern: /^\/swarms\/([^/]+)$/, scope: "swarm", page: "overview",
+    live: (_vm, src, params) => isSwarmLive(src, p(params, 0)),
+    load: (src, params) => loadSwarm(src, p(params, 0)),
+    render: renderSwarm,
+  },
+  {
+    pattern: /^\/swarms\/([^/]+)\/collaboration$/, scope: "swarm", page: "collaboration",
+    live: (_vm, src, params) => isSwarmLive(src, p(params, 0)),
+    load: (src, params) => loadSwarmCollaboration(src, p(params, 0)),
+    render: renderSwarmCollaboration,
+  },
+  {
+    pattern: /^\/swarms\/([^/]+)\/graph$/, scope: "swarm", page: "graph",
+    live: (_vm, src, params) => isSwarmLive(src, p(params, 0)),
+    load: (src, params, query) => loadSwarmGraph(src, p(params, 0), graphView(query)),
+    render: renderSwarmGraph,
   },
+  {
+    pattern: /^\/swarms\/([^/]+)\/files\/([^/]+)$/, scope: "swarm", page: "other",
+    live: () => false,
+    load: (src, params) => {
+      const vm = loadSwarmFile(src, p(params, 0), p(params, 1));
+      if (!vm.present) throw new DashboardError(404, `${vm.name}.md has not been written yet`);
+      return vm;
+    },
+    render: renderFile,
+  },
+  ...ledgerRoutes(),
 ];
 
 function baseHeaders(): Record<string, string> {
@@ -329,12 +415,36 @@ function routeMatch(pathname: string): { route: Route; params: string[] } | unde
   return undefined;
 }
 
-/** The run this page belongs to, and the run the nav's collaboration and graph links target. */
-function runContext(src: DashboardSource, url: URL, params: string[]): Pick<RenderContext, "runId" | "navRun"> {
-  const runId = RUN_ID_RE.test(params[0] ?? "") ? params[0] : undefined;
-  const filterRun = url.searchParams.get("run");
-  const navRun = runId ?? (filterRun && RUN_ID_RE.test(filterRun) ? filterRun : undefined) ?? latestRunId(src);
-  return { runId, navRun };
+/**
+ * The scope the route declares, filled in from its id. A horde run also carries its swarm's hordes
+ * for the tabs; a swarm that cannot be read leaves the run without tabs rather than failing the page.
+ */
+function scopeOf(src: DashboardSource, route: Route, params: string[]): Scope {
+  if (route.scope === "project") return { kind: "project" };
+  const id = p(params, 0);
+  if (route.scope === "swarm") return { kind: "swarm", swarmId: id, hordes: swarmHordes(src, id) };
+  const swarm = swarmOfRun(id);
+  if (!swarm) return { kind: "run", runId: id };
+  try {
+    return { kind: "run", runId: id, swarm: { id: swarm.swarmId, hordes: swarmHordes(src, swarm.swarmId) } };
+  } catch {
+    return { kind: "run", runId: id };
+  }
+}
+
+/** The page's place in the nav: its scope and which page-row item it is. */
+/** A swarm (not a swarm of one, which writes the project ledgers) the parent still holds in memory. */
+function liveSwarmOf(src: DashboardSource): RenderContext["liveSwarm"] {
+  const swarm = src.getSwarm?.();
+  if (!swarm || swarm.dir === undefined) return undefined;
+  const running = src.getActive().some((run) => swarmOfRun(run.id)?.swarmId === swarm.id);
+  return { id: swarm.id, finishing: !running };
+}
+
+/** The page's place in the nav: its scope, which page-row item it is, and a live swarm for project pages. */
+function pageContext(src: DashboardSource, route: Route, params: string[]): Pick<RenderContext, "scope" | "pageKind" | "liveSwarm"> {
+  const liveSwarm = route.scope === "project" ? liveSwarmOf(src) : undefined;
+  return { scope: scopeOf(src, route, params), pageKind: route.page, liveSwarm };
 }
 
 /** The export costs seconds of work per request, so pages from other sites may not start one. */
@@ -355,7 +465,7 @@ function handleRoute(src: DashboardSource, url: URL, json: boolean, ctx: RenderC
   const on = live && refreshParam !== "0";
   const pageCtx: RenderContext = {
     ...ctx,
-    ...runContext(src, url, params),
+    ...pageContext(src, route, params),
     refresh: live ? { on, toggleHref: refreshToggle(url, on), seconds: REFRESH_SECONDS } : undefined,
   };
   const body = route.render(vm as never, pageCtx);
@@ -365,13 +475,13 @@ function handleRoute(src: DashboardSource, url: URL, json: boolean, ctx: RenderC
 
 /** One page of the static export; errors become pages so no exported link dangles. */
 function exportPage(src: DashboardSource, url: URL): ExportPage {
-  const ctx: RenderContext = { activeId: src.getActive()?.id, href: url.pathname + url.search, export: true };
+  const ctx: RenderContext = { href: url.pathname + url.search, export: true };
   try {
     const matched = routeMatch(url.pathname);
     if (!matched) throw new DashboardError(404, `no such page: ${url.pathname}`);
     const { route, params } = matched;
     const vm = route.load(src, params, url.searchParams);
-    return { body: route.render(vm as never, { ...ctx, ...runContext(src, url, params) }), text: route.text };
+    return { body: route.render(vm as never, { ...ctx, ...pageContext(src, route, params) }), text: route.text };
   } catch (error) {
     const status = error instanceof DashboardError ? error.status : 500;
     const message = error instanceof DashboardError ? error.message : `dashboard error: ${error instanceof Error ? error.message : String(error)}`;
@@ -414,7 +524,6 @@ function exportResponse(src: DashboardSource, url: URL, ctx: RenderContext): Das
 export function routeRequest(src: DashboardSource, method: string, url: URL, host: string | undefined, fetchSite?: string): DashboardResponse {
   const json = url.pathname === "/api" || url.pathname.startsWith("/api/");
   const ctx: RenderContext = {
-    activeId: src.getActive()?.id,
     origin: host ? `http://${host}` : undefined,
     href: url.pathname + url.search,
   };

package/src/ledger/files.ts

@@ -79,7 +79,12 @@ function writeIfMissing(filePath: string, content: string): void {
 }
 
 export function initHordeDir(cwd: string): string {
-  const paths = hordePaths(path.join(cwd, ".horde"));
+  return initHordeDirAt(path.join(cwd, ".horde"));
+}
+
+/** Create a complete horde directory (ledgers, lock, runs/) at `hordeDir`; existing ledgers are kept. */
+export function initHordeDirAt(hordeDir: string): string {
+  const paths = hordePaths(hordeDir);
   fs.mkdirSync(paths.runs, { recursive: true });
   writeIfMissing(paths.gitignore, "runs/\n");
   writeIfMissing(paths.ideas, IDEAS_HEADER);

package/src/ledger/findings.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import { createHash } from "node:crypto";
 import { collaborationState } from "./collaboration.js";
-import type { PeerMessage, ReviewRecord } from "./collaboration.js";
+import type { ArtifactRecord, PeerMessage, ReviewRecord } from "./collaboration.js";
 import { formatClock } from "../format.js";
 import { RUN_HEADING } from "./board.js";
 import { registerConcern } from "./concerns.js";
@@ -558,28 +558,47 @@ export function supersededCitations(text: string, findings: FindingEntry[]): str
     .map((finding) => `F${finding.id} (now F${finding.supersededBy})`);
 }
 
-/** The current revision of every live finding a text cites, pinned so a later amend is visible. */
-export function answerCitations(findings: FindingEntry[], text: string): Record<string, string> {
+/**
+ * The current revision of every live finding and published artifact a text cites, pinned so a
+ * later amend or republish is visible.
+ */
+export function answerCitations(findings: FindingEntry[], text: string, artifacts: ArtifactRecord[] = []): Record<string, string> {
   const cites: Record<string, string> = {};
   for (const finding of findings) {
     if (finding.supersededBy === undefined && new RegExp(`\\bF${finding.id}\\b`).test(text)) cites[`F${finding.id}`] = findingRevision(finding);
   }
+  for (const artifact of artifacts) {
+    if (new RegExp(`\\b${artifact.id}\\b`).test(text)) cites[artifact.id] = artifact.hash;
+  }
   return cites;
 }
 
 /**
- * Citations an answer can no longer stand on: findings superseded since it was written, and
- * findings amended since the revisions it pinned. Both ship a stale reading as the result.
+ * Citations an answer can no longer stand on: findings superseded since it was written, findings
+ * amended and artifacts republished since the revisions it pinned. Each ships a stale reading as
+ * the result.
  */
-export function staleAnswerCitations(findings: FindingEntry[], text: string, cites: Record<string, string> = {}): string[] {
+export function staleAnswerCitations(
+  findings: FindingEntry[],
+  text: string,
+  cites: Record<string, string> = {},
+  artifacts: ArtifactRecord[] = [],
+): string[] {
   const stale = supersededCitations(text, findings).map((citation) => `superseded ${citation}`);
   for (const [target, revision] of Object.entries(cites)) {
     const finding = findings.find((entry) => `F${entry.id}` === target);
     if (finding && finding.supersededBy === undefined && findingRevision(finding) !== revision) stale.push(`amended ${target}`);
+    const artifact = artifacts.find((entry) => entry.id === target);
+    if (artifact && artifact.hash !== revision) stale.push(`republished ${target}`);
   }
   return stale;
 }
 
+/** The answer's stale citations against this run's current findings and artifacts. */
+export function staleAnswerFor(hordeDir: string, runId: string, text: string, cites?: Record<string, string>): string[] {
+  return staleAnswerCitations(listFindingsForRun(hordeDir, runId), text, cites, collaborationState(hordeDir, runId).artifacts);
+}
+
 /** A body line that reads as a verification note would move the subject boundary the revision hashes. */
 function neutralizeNotes(text: string): string {
   return text.replace(/^((?:Verified|Reviewed) by )/gm, "\\$1");

package/src/member.ts

@@ -77,6 +77,15 @@ export interface MemberReset {
   tokens: number;
 }
 
+/** Another horde of the same swarm, whose ledgers a member may read but never write. */
+export interface SiblingHorde {
+  /** `h1`, `h2`, ... */
+  label: string;
+  hordeDir: string;
+  /** That horde's workstream, when the swarm partitioned the task. */
+  slice?: string | undefined;
+}
+
 export interface MemberRunInfo {
   id: string;
   hordeDir: string;
@@ -85,6 +94,13 @@ export interface MemberRunInfo {
   count: number;
   /** True when started with `--until-stop`: the run continues until the user stops it. */
   untilStop?: boolean | undefined;
+  /** 1-based horde index in the swarm and the swarm's size; a single run is horde 1 of 1. */
+  horde?: number | undefined;
+  hordes?: number | undefined;
+  /** This horde's workstream, told to every member, when the swarm partitioned the task. */
+  slice?: string | undefined;
+  /** The other hordes of the swarm. */
+  siblings?: SiblingHorde[] | undefined;
 }
 
 interface SpawnMemberInput {
@@ -294,9 +310,21 @@ export const UNTIL_STOP_NOTE =
   "SOLVED when the task has a complete answer; once an answer is banked, propose again only when a " +
   "materially better one exists.";
 
+/** What a member of a partitioned swarm is told about its horde's workstream. */
+export function sliceNote(run: MemberRunInfo): string | undefined {
+  if (!run.slice || !run.horde || !run.hordes || run.hordes < 2) return undefined;
+  return (
+    `Your horde is h${run.horde} of ${run.hordes} hordes working the same task in parallel, each in its own ` +
+    `ledgers. Your horde owns workstream ${run.horde}: "${run.slice}". Work only on your horde's workstream; ` +
+    "do not duplicate another horde's."
+  );
+}
+
 /** The per-member system line: name, assigned role, a reset note for a replacement, the until-stop rule. */
 function identityLine(run: MemberRunInfo, member: MemberState, role: string | undefined): string {
   const parts = [`You are ${member.name}.`];
+  const slice = sliceNote(run);
+  if (slice) parts.push(slice);
   if (role) parts.push(role);
   if (member.resetNote) parts.push(member.resetNote);
   if (run.untilStop) parts.push(UNTIL_STOP_NOTE);
@@ -319,6 +347,7 @@ export function buildMemberArgs(input: SpawnMemberInput): string[] {
 }
 
 export function memberEnv(input: SpawnMemberInput): NodeJS.ProcessEnv {
+  const siblings = input.run.siblings ?? [];
   return childEnv({
     PI_HORDE_MEMBER: "1",
     PI_HORDE_DIR: input.run.hordeDir,
@@ -326,9 +355,27 @@ export function memberEnv(input: SpawnMemberInput): NodeJS.ProcessEnv {
     PI_HORDE_RUN: input.run.id,
     PI_HORDE_ROLE: input.role ?? "",
     PI_HORDE_ATTEMPT: input.member.attempt ??= randomUUID(),
+    PI_HORDE_SIBLINGS: siblings.length > 0 ? JSON.stringify(siblings.map((s) => ({ label: s.label, hordeDir: s.hordeDir }))) : "",
   });
 }
 
+/** The sibling hordes a member process was given, from `PI_HORDE_SIBLINGS`; empty outside a swarm. */
+export function parseSiblings(raw: string | undefined): SiblingHorde[] {
+  if (!raw) return [];
+  try {
+    const items = JSON.parse(raw) as unknown;
+    if (!Array.isArray(items)) return [];
+    return items
+      .filter((item): item is { label: string; hordeDir: string } =>
+        typeof item === "object" && item !== null &&
+        typeof (item as { label?: unknown }).label === "string" &&
+        typeof (item as { hordeDir?: unknown }).hordeDir === "string")
+      .map((item) => ({ label: item.label, hordeDir: item.hordeDir }));
+  } catch {
+    return [];
+  }
+}
+
 export function splitNdjson(buffer: string, onLine: (line: string) => void): string {
   const lines = buffer.split("\n");
   const remainder = lines.pop() ?? "";