agent-horde 0.1.6 → 0.2.1

package/src/run/solved.ts

@@ -4,7 +4,7 @@ import { loadCollaborationReport } from "../collaboration-report.js";
 import { openMessages } from "../ledger/collaboration.js";
 import { postBoard } from "../ledger/board.js";
 import { unsettledFactCitations } from "../ledger/facts.js";
-import { listFindingsForRun, staleAnswerCitations, unverifiedFindings } from "../ledger/findings.js";
+import { staleAnswerFor, unverifiedFindings } from "../ledger/findings.js";
 import { listIdeas } from "../ledger/ideas.js";
 import { archiveSolved, clearCleanStop, clearSolved, readSolvedState, reopenSolved, resolveSolvedState, writeAnswer } from "../ledger/run-signals.js";
 import type { SolvedSignal } from "../ledger/run-signals.js";
@@ -80,14 +80,27 @@ function dropContested(run: HordeRun, proposal: SolvedSignal, contest: SolvedSig
 }
 
 /**
- * A proposal that cites a finding superseded or amended after it was made would ship the stale
- * reading as the answer. It is withdrawn for re-proposal rather than validated; the board names
- * the successor or the amendment.
+ * ANSWER.md keeps the withdrawn text for the record, but its status must stop naming the
+ * validation it held, or the run reads as validated after the proposal is gone.
+ */
+function recordWithdrawn(run: HordeRun, proposal: SolvedSignal, reason: string): void {
+  void recordLifecycle(run, "solved-withdrawn", { member: proposal.member, reason });
+  try {
+    writeAnswer(run.runDir, run.id, proposal, `withdrawn: it ${reason}; no validation carries over and no proposal is pending`);
+  } catch (error) {
+    safeNotify(run, `horde ${run.id}: could not write ANSWER.md (${oneLine(String(error), 200)})`, "error");
+  }
+}
+
+/**
+ * A proposal that cites a finding superseded or amended, or an artifact republished, after it was
+ * made would ship the stale reading as the answer. It is withdrawn for re-proposal rather than
+ * validated; the board names the successor, the amendment, or the republish.
  */
 function withdrawStale(run: HordeRun, proposal: SolvedSignal, stale: string[]): void {
   const reason = `cites ${stale.join(", ")}`;
   safeNotify(run, `horde ${run.id}: solved proposal withdrawn; it ${reason}`, "warning");
-  void recordLifecycle(run, "solved-withdrawn", { member: proposal.member, reason });
+  recordWithdrawn(run, proposal, reason);
   void postBoard(
     run.hordeDir,
     "parent",
@@ -111,13 +124,13 @@ function reopenContested(run: HordeRun): void {
   // The proposal returns with the citations it pinned when it was made; what went stale or
   // unsettled meanwhile makes it a re-proposal for its author, not a reopening.
   const stale = [
-    ...staleAnswerCitations(listFindingsForRun(run.hordeDir, run.id), contest.proposal.text, contest.proposal.cites),
+    ...staleAnswerFor(run.hordeDir, run.id, contest.proposal.text, contest.proposal.cites),
     ...unsettledFactCitations(run.hordeDir, contest.proposal.text).map((citation) => `provisional ${citation}`),
   ];
   run.solvedContest = undefined;
   if (stale.length) {
     const why = `cites ${stale.join(", ")}`;
-    void recordLifecycle(run, "solved-withdrawn", { member: contest.proposal.member, reason: why });
+    recordWithdrawn(run, contest.proposal, why);
     void postBoard(run.hordeDir, "parent", `SOLVED proposal by ${contest.proposal.member} is not re-opened after ${reason}: it ${why}. ${contest.proposal.member}: propose again citing the current findings.`);
     return;
   }
@@ -262,7 +275,7 @@ export function checkSolved(run: HordeRun, ctx: ExtensionCommandContext): void {
     dropContested(run, solved, state.contest);
     return;
   }
-  const stale = staleAnswerCitations(listFindingsForRun(run.hordeDir, run.id), solved.text, solved.cites);
+  const stale = staleAnswerFor(run.hordeDir, run.id, solved.text, solved.cites);
   if (stale.length && !run.solvedCommitted) {
     withdrawStale(run, solved, stale);
     return;

package/src/run/supervise.ts

@@ -11,7 +11,7 @@ import { resetMemberState, spawnMember } from "../member.js";
 import type { MemberState } from "../member.js";
 import { hardStopMembers } from "./controls.js";
 import { recordLifecycle } from "./lifecycle.js";
-import type { HordeRun, HordeState } from "./types.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
 import { refreshRun, safeNotify } from "./ui.js";
 
 /** A running member with no ledger write for this long is reset; 0 disables. */
@@ -37,6 +37,8 @@ const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout
 /** What spawning and supervising a run's members needs beyond the run itself. */
 export interface RunLaunch {
   state: HordeState;
+  /** The swarm the run belongs to; a plain run is a swarm of one. */
+  swarm: Swarm;
   run: HordeRun;
   ctx: ExtensionCommandContext;
   /** Per-member role instruction, indexed by member index - 1. */

package/src/run/swarm-finalize.ts

@@ -0,0 +1,121 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { errorMessage } from "../format.js";
+import { SWARM_REPORT_TYPE, swarmHordeRows, swarmReportMarkdown, swarmReportText } from "./swarm-report.js";
+import type { SwarmReportDetails } from "./swarm-report.js";
+import { runSwarmDeliverable } from "./synthesis.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
+import { refreshSwarm, safeNotify, unmountWidget } from "./ui.js";
+
+/** `SWARM.json`: the swarm's timeline for the dashboard once nothing is in memory. */
+export interface SwarmRecord {
+  id: string;
+  prompt: string;
+  hordes: number;
+  count: number;
+  startedAt: number;
+  untilStop: boolean;
+  partition: string[];
+  runs: Array<{ label: string; runId: string; runDir: string; hordeDir: string; startedAt: number; endedAt?: number | undefined; outcome?: string | undefined }>;
+  /** The merge step: when the swarm deliverable helper ran and whether it wrote anything. */
+  merge?: { startedAt: number; endedAt?: number | undefined; written?: boolean | undefined } | undefined;
+  endedAt?: number | undefined;
+}
+
+export function swarmRecord(swarm: Swarm): SwarmRecord {
+  return {
+    id: swarm.id,
+    prompt: swarm.prompt,
+    hordes: swarm.hordes,
+    count: swarm.count,
+    startedAt: swarm.startedAt,
+    untilStop: swarm.untilStop === true,
+    partition: swarm.partition ?? [],
+    runs: swarm.runs.map((run) => ({
+      label: `h${run.horde}`,
+      runId: run.id,
+      runDir: run.runDir,
+      hordeDir: run.hordeDir,
+      startedAt: run.startedAt,
+      endedAt: run.finalized ? Math.max(run.startedAt, ...run.members.map((m) => m.endedAt ?? 0)) : undefined,
+      outcome: run.outcome,
+    })),
+  };
+}
+
+/** Write a swarm file, reporting (not throwing) a failure so finalize keeps going. */
+function writeSwarmFile(swarm: Swarm, name: string, content: string): void {
+  if (!swarm.dir) return;
+  try {
+    fs.writeFileSync(path.join(swarm.dir, name), content, "utf-8");
+  } catch (error) {
+    safeNotify(swarm, `swarm ${swarm.id}: could not write ${name} (${errorMessage(error)})`, "error");
+  }
+}
+
+export function writeSwarmRecord(swarm: Swarm, extra: Partial<SwarmRecord> = {}): void {
+  writeSwarmFile(swarm, "SWARM.json", JSON.stringify({ ...swarmRecord(swarm), ...extra }, null, 2));
+}
+
+/**
+ * A horde's members exited and its REPORT.md is written. Once every horde is there the swarm
+ * slot frees, so a new launch can start while the (possibly slow) synthesis steps run.
+ */
+export function noteRunReported(state: HordeState, swarm: Swarm, run: HordeRun): void {
+  run.reported = true;
+  if (!swarm.runs.every((other) => other.reported === true)) return;
+  if (state.active === swarm) state.active = undefined;
+  state.finalizing = swarm;
+}
+
+/** The merged deliverable, REPORT.md, and the injected message of a swarm of several hordes. */
+async function mergeSwarm(state: HordeState, swarm: Swarm): Promise<void> {
+  swarm.finalizing = ["merge"];
+  refreshSwarm(swarm);
+  const merge: NonNullable<SwarmRecord["merge"]> = { startedAt: Date.now() };
+  writeSwarmRecord(swarm, { merge });
+  swarm.deliverable = process.env.PI_HORDE_DELIVERABLE === "off" ? undefined : await runSwarmDeliverable(state, swarm);
+  if (swarm.deliverable) writeSwarmFile(swarm, "DELIVERABLE.md", swarm.deliverable);
+  const now = Date.now();
+  merge.endedAt = now;
+  merge.written = Boolean(swarm.deliverable);
+  writeSwarmFile(swarm, "REPORT.md", swarmReportMarkdown(swarm, now));
+  writeSwarmRecord(swarm, { merge, endedAt: now });
+  if (state.disposed) return;
+  const details: SwarmReportDetails = {
+    swarmId: swarm.id,
+    elapsedMs: now - swarm.startedAt,
+    hordes: swarmHordeRows(swarm, now),
+    deliverable: swarm.deliverable,
+  };
+  const content = [swarmReportText(swarm, now), ...(swarm.deliverable ? ["## Deliverable", "", swarm.deliverable] : [])].join("\n\n");
+  // A hard stop of every horde keeps the parent idle, as it does for one horde.
+  const triggerTurn = swarm.runs.some((run) => run.cleanStopNames.length > 0 || !run.stopped);
+  state.pi.sendMessage(
+    { customType: SWARM_REPORT_TYPE, content, display: true, details },
+    { deliverAs: "followUp", triggerTurn },
+  );
+  safeNotify(swarm, `swarm ${swarm.id} finished`, "info");
+}
+
+/**
+ * A horde's finalize completed, synthesis included. The swarm step runs once every horde is
+ * done: a swarm of one has nothing to merge and only releases the widget.
+ */
+export async function noteRunFinalized(state: HordeState, swarm: Swarm, run: HordeRun): Promise<void> {
+  run.finalized = true;
+  if (!swarm.runs.every((other) => other.finalized === true)) {
+    refreshSwarm(swarm);
+    return;
+  }
+  try {
+    if (swarm.dir && !state.disposed) await mergeSwarm(state, swarm);
+  } catch (error) {
+    safeNotify(swarm, `swarm ${swarm.id} failed to finalize: ${errorMessage(error)}`, "error");
+  } finally {
+    swarm.finalizing = undefined;
+    if (state.active === swarm) state.active = undefined;
+    if (state.finalizing === swarm) state.finalizing = undefined;
+    unmountWidget(swarm);
+  }
+}

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