agent-horde 0.1.6 → 0.2.0

package/src/run/swarm-report.ts

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

package/src/run/swarm.ts

@@ -0,0 +1,156 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { formatDateTime, formatRunId, taskHash } from "../format.js";
+import { hordePaths, initHordeDirAt } from "../ledger/files.js";
+import type { SiblingHorde } from "../member.js";
+import { hordeLabel } from "./types.js";
+import type { Swarm } from "./types.js";
+
+/** Where a swarm's ids and directories landed. */
+export interface SwarmLayout {
+  id: string;
+  /** `.horde/swarms/<id>`; undefined for a swarm of one. */
+  dir: string | undefined;
+  /** One complete horde directory per horde, `h1` first. */
+  hordeDirs: string[];
+  /** Run ids, `h1` first: the swarm id alone for a swarm of one, else `<id>-h<N>`. */
+  runIds: string[];
+  /** `<hordeDir>/runs/<runId>`, created and empty but for `sessions/`. */
+  runDirs: string[];
+}
+
+/** Make `<parent>/<base>` or the first free `<base>-<n>`, exclusively, and return its name. */
+function allocateUnique(parent: string, base: string): string {
+  for (let attempt = 0; ; attempt++) {
+    const name = attempt === 0 ? base : `${base}-${attempt}`;
+    try {
+      fs.mkdirSync(path.join(parent, name));
+      return name;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+}
+
+function makeRunDir(hordeDir: string, runId: string): string {
+  const runDir = path.join(hordePaths(hordeDir).runs, runId);
+  fs.mkdirSync(path.join(runDir, "sessions"), { recursive: true });
+  return runDir;
+}
+
+/** The swarm directories hold whole horde directories, so they are run output, not ledgers. */
+function ignoreSwarms(hordeDir: string): void {
+  const gitignore = hordePaths(hordeDir).gitignore;
+  const existing = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, "utf-8") : "";
+  if (existing.split("\n").some((line) => line.trim() === "swarms/")) return;
+  fs.writeFileSync(gitignore, `${existing}${existing === "" || existing.endsWith("\n") ? "" : "\n"}swarms/\n`, "utf-8");
+}
+
+/**
+ * Allocate the swarm's id and directories. A swarm of one keeps the plain time-based run id
+ * under `.horde/runs/`, so single runs share the project ledgers as before; a larger swarm gets
+ * `.horde/swarms/<id>/h<N>/`, each a complete horde directory with its own ledgers and lock.
+ */
+export function allocateSwarm(hordeDir: string, hordes: number, startedAt: number): SwarmLayout {
+  const base = formatRunId(new Date(startedAt));
+  if (hordes === 1) {
+    const id = allocateUnique(hordePaths(hordeDir).runs, base);
+    const runDir = path.join(hordePaths(hordeDir).runs, id);
+    fs.mkdirSync(path.join(runDir, "sessions"), { recursive: true });
+    return { id, dir: undefined, hordeDirs: [hordeDir], runIds: [id], runDirs: [runDir] };
+  }
+  const swarms = path.join(hordeDir, "swarms");
+  fs.mkdirSync(swarms, { recursive: true });
+  ignoreSwarms(hordeDir);
+  const id = allocateUnique(swarms, base);
+  const dir = path.join(swarms, id);
+  const layout: SwarmLayout = { id, dir, hordeDirs: [], runIds: [], runDirs: [] };
+  for (let horde = 1; horde <= hordes; horde++) {
+    const hordeDirN = initHordeDirAt(path.join(dir, hordeLabel(horde)));
+    const runId = `${id}-${hordeLabel(horde)}`;
+    layout.hordeDirs.push(hordeDirN);
+    layout.runIds.push(runId);
+    layout.runDirs.push(makeRunDir(hordeDirN, runId));
+  }
+  return layout;
+}
+
+/** Deal `plan` layers to `hordes` hordes round-robin: layer 1 to h1, layer 2 to h2, and so on. */
+export function dealLayers(plan: string[], hordes: number): string[][] {
+  const dealt: string[][] = Array.from({ length: hordes }, () => []);
+  plan.forEach((layer, index) => dealt[index % hordes]!.push(layer));
+  return dealt;
+}
+
+/** The horde directories a member may read besides its own, with each horde's workstream. */
+export function siblingHordes(layout: SwarmLayout, partition: string[] | undefined, horde: number): SiblingHorde[] {
+  return layout.hordeDirs
+    .map((hordeDir, index) => ({ label: hordeLabel(index + 1), hordeDir, slice: partition?.[index] }))
+    .filter((_sibling, index) => index + 1 !== horde);
+}
+
+/** SWARM.md: the prompt, the partition, and where each horde works. */
+export function swarmMarkdown(swarm: Swarm): string {
+  const partition = swarm.partition ?? [];
+  return [
+    `# Swarm ${swarm.id}`,
+    "",
+    `Started: ${formatDateTime(new Date(swarm.startedAt))}`,
+    `Hordes: ${swarm.hordes} x ${swarm.count} members (${hordeLabel(1)} .. ${hordeLabel(swarm.hordes)})`,
+    `Model: ${swarm.runs[0]?.model ?? "parent default"}`,
+    `Until stop: ${swarm.untilStop ? "yes (every horde continues until stop-clean or stop-hard)" : "no"}`,
+    `Partition: ${swarm.plan ? "plan layers dealt round-robin" : "planner helper"}`,
+    `Task-SHA256: ${taskHash(swarm.prompt)}`,
+    "",
+    "## Prompt",
+    "",
+    swarm.prompt,
+    "",
+    "## Partition",
+    "",
+    ...partition.map((slice, index) => `- ${hordeLabel(index + 1)}: ${slice}`),
+    "",
+    "## Hordes",
+    "",
+    ...swarm.runs.map((run) => `- ${hordeLabel(run.horde)}: ${run.runDir}`),
+    "",
+  ].join("\n");
+}
+
+/** A planner slice as the members read it: the workstream, then its acceptance criterion. */
+export function sliceText(workstream: string, acceptance: string | undefined): string {
+  const trimmed = workstream.trim();
+  const criterion = acceptance?.trim();
+  return criterion ? `${trimmed} Acceptance: ${criterion}` : trimmed;
+}
+
+/**
+ * The planner's output as H distinct workstreams, or why it is unusable. The helper is told to
+ * print only a JSON array; anything around it is tolerated, a wrong count or a repeat is not.
+ */
+export function parsePlannerOutput(output: string, hordes: number): { slices: string[] } | { error: string } {
+  const start = output.indexOf("[");
+  const end = output.lastIndexOf("]");
+  if (start === -1 || end <= start) return { error: "the planner printed no JSON array" };
+  let items: unknown;
+  try {
+    items = JSON.parse(output.slice(start, end + 1));
+  } catch (error) {
+    return { error: `the planner's JSON did not parse (${error instanceof Error ? error.message : String(error)})` };
+  }
+  if (!Array.isArray(items)) return { error: "the planner printed something other than an array" };
+  if (items.length !== hordes) return { error: `the planner produced ${items.length} workstream(s), not ${hordes}` };
+  const slices: string[] = [];
+  const seen = new Set<string>();
+  for (const item of items) {
+    const record = (typeof item === "object" && item !== null ? item : {}) as Record<string, unknown>;
+    const workstream = typeof record.workstream === "string" ? record.workstream : typeof item === "string" ? item : "";
+    const acceptance = typeof record.acceptance === "string" ? record.acceptance : undefined;
+    const key = workstream.trim().toLowerCase().replace(/\s+/g, " ");
+    if (key === "") return { error: "the planner produced an empty workstream" };
+    if (seen.has(key)) return { error: `the planner repeated a workstream: ${workstream.trim()}` };
+    seen.add(key);
+    slices.push(sliceText(workstream, acceptance));
+  }
+  return { slices };
+}

package/src/run/synthesis.ts

@@ -2,11 +2,16 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { oneLine } from "../format.js";
 import { childEnv, execPi, getPiInvocation } from "../member.js";
-import type { HordeRun, HordeState } from "./types.js";
+import { parsePlannerOutput } from "./swarm.js";
+import { hordeLabel } from "./types.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
 
 /** How long the post-mortem agent may run. */
 const POSTMORTEM_TIMEOUT_MS = Number(process.env.PI_HORDE_POSTMORTEM_MS) || 300_000;
 
+/** How long the planner that partitions a task between hordes may run. */
+const PLANNER_TIMEOUT_MS = Number(process.env.PI_HORDE_PLANNER_MS) || 300_000;
+
 const POSTMORTEM_SYSTEM_PROMPT =
   "You are a post-mortem reviewer for a multi-agent horde run. You have read-only tools. " +
   "Critique the run and the orchestrating extension, not just the underlying project. Be " +
@@ -17,43 +22,63 @@ const DELIVERABLE_SYSTEM_PROMPT =
   "You are the synthesis member of a horde. You have read-only tools and must produce one " +
   "deliverable that answers the task the horde was given, not a summary of the process.";
 
-type HelperLabel = "post-mortem" | "deliverable";
+const SWARM_DELIVERABLE_SYSTEM_PROMPT =
+  "You are the synthesis member of a swarm of hordes. You have read-only tools and must merge the " +
+  "hordes' deliverables into one deliverable that answers the task, keeping every claim attributed " +
+  "to the horde that made it and to the acceptance status that horde recorded.";
+
+const PLANNER_SYSTEM_PROMPT =
+  "You are the planner for a swarm of agent hordes. You have read-only tools. You partition one task " +
+  "into disjoint workstreams that independent teams can work in parallel without overlapping. You " +
+  "output only the JSON you are asked for.";
+
+type HelperLabel = "post-mortem" | "deliverable" | "swarm deliverable" | "planner";
 
 /** Run a one-shot pi helper and return its output, or a one-line failure text. */
 async function runHelper(
   label: HelperLabel,
   invocation: { command: string; args: string[] },
-  cwd: string,
-  signal: AbortSignal,
-): Promise<string> {
+  options: { cwd: string; signal: AbortSignal; timeoutMs?: number | undefined },
+): Promise<{ text: string; failed: boolean }> {
+  const timeoutMs = options.timeoutMs ?? POSTMORTEM_TIMEOUT_MS;
   const result = await execPi(invocation, {
-    cwd,
+    cwd: options.cwd,
     env: childEnv(),
-    timeoutMs: POSTMORTEM_TIMEOUT_MS,
-    signal,
+    timeoutMs,
+    signal: options.signal,
   });
   const text = result.stdout.trim();
   if (result.timedOut) {
-    return `${label} agent failed: timed out after ${Math.round(POSTMORTEM_TIMEOUT_MS / 1000)}s`;
+    return { text: `${label} agent failed: timed out after ${Math.round(timeoutMs / 1000)}s`, failed: true };
   }
   if (result.code !== 0 || text === "") {
     const detail = oneLine(result.stderr.trim() || "no output", 200);
-    return `${label} agent failed (code ${result.code ?? "signal"}): ${detail}`;
+    return { text: `${label} agent failed (code ${result.code ?? "signal"}): ${detail}`, failed: true };
   }
-  return text;
+  return { text, failed: false };
+}
+
+/** Read-only pi invocation with its own session directory. */
+function readOnlyInvocation(
+  sessions: string,
+  model: string | undefined,
+  systemPrompt: string,
+  task: string,
+): { command: string; args: string[] } {
+  fs.mkdirSync(sessions, { recursive: true });
+  const args = ["-p", "--tools", "read,grep,find,ls", "--session-dir", sessions];
+  if (model) args.push("--model", model);
+  args.push("--approve", "--append-system-prompt", systemPrompt, "--", task);
+  return getPiInvocation(args);
 }
 
-/** Read-only pi invocation for a helper, with its own session directory under the run. */
+/** A run helper's invocation: ledger paths are swapped for the frozen snapshot when one exists. */
 function helperInvocation(
   run: HordeRun,
   sessionDir: string,
   systemPrompt: string,
   task: string,
 ): { command: string; args: string[] } {
-  const sessions = path.join(run.runDir, sessionDir);
-  fs.mkdirSync(sessions, { recursive: true });
-  const args = ["-p", "--tools", "read,grep,find,ls", "--session-dir", sessions];
-  if (run.model) args.push("--model", run.model);
   for (const name of ["BOARD", "FINDINGS", "IDEAS", "FACTS", "CLAIMS", "RESOURCES", "CONCERNS"]) {
     const frozen = path.join(run.runDir, "snapshot", `${name}.md`);
     if (fs.existsSync(frozen)) task = task.split(path.join(run.hordeDir, `${name}.md`)).join(frozen);
@@ -62,8 +87,7 @@ function helperInvocation(
     "Use the frozen acceptance snapshot. Exclude unreviewed, disputed or stale artifacts from recommended runnable outputs. " +
     "acceptedDocuments establishes document-criteria review only; recommend runnable outputs only from acceptedRunnableArtifacts. Preserve recorded peer confirmation even if acceptance remains incomplete. " +
     "Disclose partial checks and unresolved coverage. Legacy verified labels alone do not establish a full reproduction.";
-  args.push("--approve", "--append-system-prompt", systemPrompt, "--", task);
-  return getPiInvocation(args);
+  return readOnlyInvocation(path.join(run.runDir, sessionDir), run.model, systemPrompt, task);
 }
 
 function postmortemTask(run: HordeRun): string {
@@ -125,6 +149,7 @@ function deliverableTask(run: HordeRun): string {
     ``,
     run.prompt,
     ``,
+    ...(run.slice ? [`This horde owned one workstream of that task: ${run.slice}`, `Deliver that workstream's part of the answer.`, ``] : []),
     `Read these with the read tool:`,
     `- ${path.join(run.runDir, "REPORT.md")}`,
     `- ${path.join(run.runDir, "SUMMARY.md")}`,
@@ -170,7 +195,7 @@ export async function runPostmortem(state: HordeState, run: HordeRun): Promise<s
   const controller = new AbortController();
   run.postmortemAbort = controller;
   try {
-    return await runHelper("post-mortem", invocation, run.cwd, controller.signal);
+    return (await runHelper("post-mortem", invocation, { cwd: run.cwd, signal: controller.signal })).text;
   } finally {
     run.postmortemAbort = undefined;
   }
@@ -188,8 +213,104 @@ export async function runDeliverable(state: HordeState, run: HordeRun): Promise<
   const controller = new AbortController();
   run.deliverableAbort = controller;
   try {
-    return await runHelper("deliverable", invocation, run.cwd, controller.signal);
+    return (await runHelper("deliverable", invocation, { cwd: run.cwd, signal: controller.signal })).text;
   } finally {
     run.deliverableAbort = undefined;
   }
 }
+
+function swarmDeliverableTask(swarm: Swarm): string {
+  const dir = swarm.dir ?? "";
+  return [
+    `Produce the single merged deliverable for swarm ${swarm.id}: ${swarm.hordes} hordes worked disjoint`,
+    `workstreams of one task in parallel, and each wrote its own deliverable.`,
+    ``,
+    `The task the swarm was given:`,
+    ``,
+    swarm.prompt,
+    ``,
+    `The partition:`,
+    ...(swarm.partition ?? []).map((slice, index) => `- ${hordeLabel(index + 1)}: ${slice}`),
+    ``,
+    `Read these with the read tool:`,
+    `- ${path.join(dir, "SWARM.md")}`,
+    ...swarm.runs.flatMap((run) => [
+      `- ${path.join(run.runDir, "DELIVERABLE.md")} (${hordeLabel(run.horde)}; absent when that horde was hard-stopped)`,
+      `- ${path.join(run.runDir, "REPORT.md")} (${hordeLabel(run.horde)})`,
+      `- ${path.join(run.runDir, "ACCEPTANCE.md")} (${hordeLabel(run.horde)}; when present)`,
+      `- ${path.join(run.runDir, "ANSWER.md")} (${hordeLabel(run.horde)}; when a solve was proposed)`,
+    ]),
+    ``,
+    `Merge the hordes' deliverables into one artifact that answers the whole task in the form the task`,
+    `implies. Keep every claim attributed to its horde (${swarm.runs.map((run) => hordeLabel(run.horde)).join(", ")})`,
+    `and keep the acceptance label its horde recorded; do not upgrade a claim's support by combining`,
+    `hordes, since no horde reviewed another's work. Where hordes overlap or contradict each other, say`,
+    `so and keep both attributions. Name any workstream whose horde produced no deliverable. Do not`,
+    `describe the process. Output only markdown.`,
+  ].join("\n");
+}
+
+/** Spawn the synthesis member that merges the hordes' deliverables into the swarm's. */
+export async function runSwarmDeliverable(state: HordeState, swarm: Swarm): Promise<string | undefined> {
+  if (state.disposed || !swarm.dir) return undefined;
+  const invocation = readOnlyInvocation(
+    path.join(swarm.dir, "deliverable-sessions"),
+    swarm.runs[0]?.model,
+    SWARM_DELIVERABLE_SYSTEM_PROMPT,
+    swarmDeliverableTask(swarm),
+  );
+  const controller = new AbortController();
+  swarm.deliverableAbort = controller;
+  try {
+    return (await runHelper("swarm deliverable", invocation, { cwd: swarm.cwd, signal: controller.signal })).text;
+  } finally {
+    swarm.deliverableAbort = undefined;
+  }
+}
+
+function plannerTask(prompt: string, hordes: number): string {
+  return [
+    `Partition the task below into exactly ${hordes} disjoint workstreams for ${hordes} independent teams`,
+    `that will work in parallel in this directory without talking to each other. Each workstream must`,
+    `be self-contained, must not overlap another, and should take about the same effort; together they`,
+    `must cover the whole task. Give each workstream one acceptance criterion a team can check on its`,
+    `own. Read the working directory as needed to split the task along real seams (modules, inputs,`,
+    `chapters, question groups); do not modify anything.`,
+    ``,
+    `Output ONLY a JSON array of exactly ${hordes} objects, nothing before or after it:`,
+    `[{"workstream": "<what this team does>", "acceptance": "<how the team knows it is done>"}, ...]`,
+    ``,
+    `Task:`,
+    ``,
+    prompt,
+  ].join("\n");
+}
+
+/**
+ * Partition a plain prompt between the hordes with a read-only planner. Returns the H slices,
+ * or the reason the launch must stop: a planner that cannot produce H distinct workstreams
+ * would have every horde doing the same work.
+ */
+export async function runPlanner(
+  state: HordeState,
+  input: { dir: string; cwd: string; model: string | undefined; prompt: string; hordes: number },
+): Promise<{ slices: string[] } | { error: string }> {
+  if (state.disposed) return { error: "session shut down" };
+  const invocation = readOnlyInvocation(
+    path.join(input.dir, "planner-sessions"),
+    input.model,
+    PLANNER_SYSTEM_PROMPT,
+    plannerTask(input.prompt, input.hordes),
+  );
+  const controller = new AbortController();
+  state.plannerAbort = controller;
+  try {
+    const result = await runHelper("planner", invocation, {
+      cwd: input.cwd, signal: controller.signal, timeoutMs: PLANNER_TIMEOUT_MS,
+    });
+    if (result.failed) return { error: result.text };
+    return parsePlannerOutput(result.text, input.hordes);
+  } finally {
+    state.plannerAbort = undefined;
+  }
+}

package/src/run/types.ts

@@ -11,6 +11,10 @@ export interface HordeRun extends MemberRunInfo {
   controllers: Map<string, AbortController>;
   procs: Map<string, ChildProcess>;
   cwd: string;
+  /** 1-based position in the swarm; the horde is addressed as `h<N>`. */
+  horde: number;
+  /** The horde's workstream when the swarm partitioned the task; every member sees it. */
+  slice?: string | undefined;
   /** Highest fact id at run start, to separate this run's facts from carried context. */
   startFactId: number;
   /** Highest idea id at run start; ideas created above it are this run's coverage. */
@@ -47,6 +51,12 @@ export interface HordeRun extends MemberRunInfo {
   deliverableAbort?: AbortController | undefined;
   /** Steps still running after members finished, e.g. ["deliverable", "post-mortem"]. */
   finalizing?: string[] | undefined;
+  /** The run's outcome label once REPORT.md is written, e.g. "solved" or "stopped-clean". */
+  outcome?: string | undefined;
+  /** True once members exited and REPORT.md is written; the swarm slot frees when every run is. */
+  reported?: boolean | undefined;
+  /** True once finalize completed, synthesis included. */
+  finalized?: boolean | undefined;
   /** Workstream partition when the run was started with `plan`. */
   plan?: string[] | undefined;
   /** Member carrying the verifier role, when one was assigned. */
@@ -79,6 +89,38 @@ export interface HordeRun extends MemberRunInfo {
   solvedCoverageNotice?: boolean | undefined;
   postmortemAbort?: AbortController | undefined;
   ui?: ExtensionUIContext;
+}
+
+/**
+ * H concurrent hordes on one task. A plain `12` is a swarm of one whose run lives in
+ * `.horde/runs/`; `3/12` gives each horde its own ledgers under `.horde/swarms/<id>/h<N>/`.
+ */
+export interface Swarm {
+  id: string;
+  /** `.horde/swarms/<id>`; undefined for a swarm of one. */
+  dir: string | undefined;
+  /** The project's `.horde` directory. */
+  hordeDir: string;
+  cwd: string;
+  prompt: string;
+  hordes: number;
+  /** Members per horde. */
+  count: number;
+  startedAt: number;
+  /** One run per horde, `h1` first. */
+  runs: HordeRun[];
+  /** The `plan` layers as given, before they were dealt to the hordes. */
+  plan?: string[] | undefined;
+  /** Per-horde workstream, indexed by horde - 1; absent for a swarm of one. */
+  partition?: string[] | undefined;
+  untilStop?: boolean | undefined;
+  dashboardUrl?: string | undefined;
+  /** Generated merged deliverable across the hordes' deliverables. */
+  deliverable?: string | undefined;
+  deliverableAbort?: AbortController | undefined;
+  /** The swarm step still running after every horde finalized, e.g. ["merge"]. */
+  finalizing?: string[] | undefined;
+  ui?: ExtensionUIContext;
   tui?: TUI;
   timer?: ReturnType<typeof setInterval> | undefined;
 }
@@ -96,13 +138,15 @@ export interface ReportDetails {
 /** Parent-side extension state shared by the command, run lifecycle, and shutdown. */
 export interface HordeState {
   pi: ExtensionAPI;
-  /** The run whose members are live; at most one at a time. */
-  active: HordeRun | undefined;
-  /** A run whose members finished but whose synthesis helpers are still running. */
-  finalizing: HordeRun | undefined;
+  /** The swarm whose members are live; at most one at a time. */
+  active: Swarm | undefined;
+  /** A swarm whose members finished but whose synthesis helpers are still running. */
+  finalizing: Swarm | undefined;
   dashboard: DashboardServer | undefined;
-  /** Set synchronously at startRun entry so a same-tick second start is refused. */
+  /** Set synchronously at startSwarm entry so a same-tick second start is refused. */
   starting: boolean;
+  /** The planner partitioning a task between hordes, so shutdown can end it. */
+  plannerAbort?: AbortController | undefined;
   /** Set at session shutdown; lifecycle steps check it and stop early. */
   disposed: boolean;
 }
@@ -117,3 +161,18 @@ export function createHordeState(pi: ExtensionAPI): HordeState {
     disposed: false,
   };
 }
+
+/** `h2` for the second horde; the label every notification, target, and file uses. */
+export function hordeLabel(horde: number): string {
+  return `h${horde}`;
+}
+
+/** Runs of the swarm whose members are not all finished and reported. */
+export function activeRuns(swarm: Swarm): HordeRun[] {
+  return swarm.runs.filter((run) => run.reported !== true);
+}
+
+/** Runs of the swarm whose members finished but whose synthesis is still running. */
+export function finalizingRuns(swarm: Swarm): HordeRun[] {
+  return swarm.runs.filter((run) => run.reported === true && run.finalized !== true);
+}