agent-horde 0.1.6 → 0.2.0

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/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() ?? "";

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 };
@@ -169,7 +169,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 +207,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.
@@ -275,7 +294,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 +307,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",