agent-horde 0.1.5 → 0.2.0

package/src/run/launch.ts

@@ -1,7 +1,9 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { DashboardOption, HordeRunArgs } from "../args.js";
 import { resolveDashboardPort, startDashboard } from "../dashboard.js";
-import { errorMessage, oneLine } from "../format.js";
+import { envNumber, errorMessage, oneLine } from "../format.js";
 import { initHordeDir } from "../ledger/files.js";
 import { resetMemberState } from "../member.js";
 import type { MemberState } from "../member.js";
@@ -9,17 +11,26 @@ import { hardStopMembers, requestCleanStop } from "./controls.js";
 import { finalizeRun, stopRunTimers } from "./finalize.js";
 import { recordLifecycle, recordPhase } from "./lifecycle.js";
 import { createRun, seedRun } from "./setup.js";
+import type { RunSpec } from "./setup.js";
 import { drainRepairs } from "./repair.js";
 import { startCollaborationScheduler } from "./schedule.js";
 import { startSolvedWatch } from "./solved.js";
 import { spawnOne, startStallWatch, superviseMember } from "./supervise.js";
 import type { RunLaunch } from "./supervise.js";
-import type { HordeRun, HordeState } from "./types.js";
+import { allocateSwarm, dealLayers, siblingHordes, swarmMarkdown } from "./swarm.js";
+import type { SwarmLayout } from "./swarm.js";
+import { noteRunFinalized, noteRunReported, writeSwarmRecord } from "./swarm-finalize.js";
+import { runPlanner } from "./synthesis.js";
+import { activeRuns, finalizingRuns, hordeLabel } from "./types.js";
+import type { HordeRun, HordeState, Swarm } from "./types.js";
 import { mountWidget, safeNotify, safeNotifyUi, unmountWidget } from "./ui.js";
 
 /** How long the canary preflight waits for the first token before declaring failure. */
 const CANARY_TIMEOUT_MS = Number(process.env.PI_HORDE_CANARY_MS) || 60_000;
 
+/** Pause between one horde's launch and the next, so H canaries do not hit the provider at once. */
+const SWARM_STAGGER_MS = envNumber("PI_HORDE_SWARM_STAGGER_MS", 5_000);
+
 type CanaryOutcome = "output" | "exit" | "timeout";
 
 function sleep(ms: number): Promise<void> {
@@ -53,7 +64,15 @@ async function ensureDashboard(
   try {
     state.dashboard = await startDashboard({
       port: resolveDashboardPort(option.port),
-      source: { hordeDir, getActive: () => state.active, getFinalizing: () => state.finalizing },
+      source: {
+        hordeDir,
+        getActive: () => (state.active ? activeRuns(state.active) : []),
+        getFinalizing: () => [
+          ...(state.active ? finalizingRuns(state.active) : []),
+          ...(state.finalizing ? finalizingRuns(state.finalizing) : []),
+        ],
+        getSwarm: () => state.active ?? state.finalizing,
+      },
       onError: (error) => {
         state.dashboard = undefined;
         safeNotifyUi(ctx, `dashboard error: ${error.message}; the run continues`, "error");
@@ -143,13 +162,18 @@ async function runCanary(launch: RunLaunch, spawns: Promise<void>[]): Promise<Ca
  * One retry distinguishes a flaky process from a dead provider.
  */
 async function preflightAndFanOut(launch: RunLaunch): Promise<void> {
-  const { state, run, ctx } = launch;
+  const { state, swarm, run, ctx } = launch;
+  if (run.stopped) {
+    // A stop arrived while this horde waited its turn: nothing to spawn, finalize now.
+    await finalizeRun(state, swarm, run);
+    return;
+  }
   const spawns: Promise<void>[] = [];
   const outcome = await runCanary(launch, spawns);
   if (run.stopped) {
     // A stop arrived during preflight: do not fan out, finalize now.
     await Promise.all(spawns);
-    await finalizeRun(state, run);
+    await finalizeRun(state, swarm, run);
     return;
   }
   if (outcome === "output") {
@@ -175,48 +199,169 @@ async function preflightAndFanOut(launch: RunLaunch): Promise<void> {
   if (run.scheduleTimer) clearInterval(run.scheduleTimer);
   run.scheduleTimer = undefined;
   await drainRepairs(launch);
-  await finalizeRun(state, run);
+  await finalizeRun(state, swarm, run);
+}
+
+/** The hordes' workstreams and plans: dealt layers, the planner's slices, or nothing for one horde. */
+interface Partition {
+  slices: string[] | undefined;
+  /** Per-horde plan layers, indexed by horde - 1. */
+  plans: Array<string[] | undefined>;
+}
+
+/** Note the planner's failure where the dashboard and the operator can find it. */
+function writeNotStarted(layout: SwarmLayout, reason: string): void {
+  if (!layout.dir) return;
+  fs.writeFileSync(path.join(layout.dir, "SWARM.md"), `# Swarm ${layout.id}\n\nNot started: ${reason}\n`, "utf-8");
+}
+
+/**
+ * Decide what each horde works on. `plan` layers go round-robin to the hordes and each horde
+ * runs its share as its own plan; a plain prompt is split by the planner helper, and a planner
+ * that cannot produce H distinct workstreams stops the launch rather than running H hordes on
+ * one slice.
+ */
+async function partitionTask(
+  state: HordeState,
+  ctx: ExtensionCommandContext,
+  parsed: HordeRunArgs,
+  layout: SwarmLayout,
+): Promise<Partition | undefined> {
+  if (parsed.hordes === 1) return { slices: undefined, plans: [parsed.plan] };
+  if (parsed.plan) {
+    const dealt = dealLayers(parsed.plan, parsed.hordes);
+    return { slices: dealt.map((layers) => layers.join("; ")), plans: dealt };
+  }
+  ctx.ui.notify(`swarm ${layout.id}: planner is partitioning the task into ${parsed.hordes} workstreams`, "info");
+  const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+  const result = await runPlanner(state, { dir: layout.dir!, cwd: ctx.cwd, model, prompt: parsed.prompt, hordes: parsed.hordes });
+  if ("error" in result) {
+    writeNotStarted(layout, result.error);
+    ctx.ui.notify(`swarm ${layout.id} not started: ${result.error}`, "error");
+    return undefined;
+  }
+  return { slices: result.slices, plans: Array.from({ length: parsed.hordes }, () => undefined) };
+}
+
+function buildSwarm(
+  ctx: ExtensionCommandContext,
+  parsed: HordeRunArgs,
+  layout: SwarmLayout,
+  partition: Partition,
+  dashboardUrl: string | undefined,
+): { swarm: Swarm; launches: Array<{ run: HordeRun; roles: string[] }> } {
+  const launches = layout.runIds.map((id, index) => {
+    const spec: RunSpec = {
+      id,
+      hordeDir: layout.hordeDirs[index]!,
+      runDir: layout.runDirs[index]!,
+      horde: index + 1,
+      hordes: parsed.hordes,
+      swarmId: layout.id,
+      slice: partition.slices?.[index],
+      plan: partition.plans[index],
+      siblings: siblingHordes(layout, partition.slices, index + 1),
+    };
+    return createRun(ctx, parsed, spec, dashboardUrl);
+  });
+  const swarm: Swarm = {
+    id: layout.id,
+    dir: layout.dir,
+    hordeDir: layout.hordeDirs.length === 1 ? layout.hordeDirs[0]! : path.resolve(layout.dir!, "..", ".."),
+    cwd: ctx.cwd,
+    prompt: parsed.prompt,
+    hordes: parsed.hordes,
+    count: parsed.count,
+    startedAt: Date.now(),
+    runs: launches.map((launch) => launch.run),
+    plan: parsed.plan,
+    partition: partition.slices,
+    untilStop: parsed.untilStop === true ? true : undefined,
+    dashboardUrl,
+  };
+  return { swarm, launches };
+}
+
+/** Seed one horde's ledgers and record its start; throws on a ledger failure. */
+async function seedHorde(swarm: Swarm, run: HordeRun, roles: string[]): Promise<void> {
+  await seedRun(run);
+  await recordLifecycle(run, "run-start", {
+    count: run.count, model: run.model, verifier: run.verifier, plan: run.plan, untilStop: run.untilStop,
+    roles: roles.map((role) => oneLine(role, 120)), dashboardUrl: run.dashboardUrl,
+    ...(swarm.hordes > 1 ? { swarm: swarm.id, horde: run.horde, hordes: swarm.hordes, slice: run.slice } : {}),
+  });
+  await recordPhase(run, "discovery", "start");
+}
+
+function announceStart(ctx: ExtensionCommandContext, swarm: Swarm): void {
+  if (swarm.hordes === 1) {
+    const run = swarm.runs[0]!;
+    const plural = run.count === 1 ? "" : "s";
+    ctx.ui.notify(`horde ${run.id} started with ${run.count} member${plural} in ${run.hordeDir}`, "info");
+    if (run.dashboardUrl) ctx.ui.notify(`horde ${run.id} dashboard: ${run.dashboardUrl}runs/${run.id}`, "info");
+    return;
+  }
+  ctx.ui.notify(
+    `swarm ${swarm.id} started: ${swarm.hordes} hordes of ${swarm.count} members in ${swarm.dir}, ` +
+      `${Math.round(SWARM_STAGGER_MS / 1000)}s apart`,
+    "info",
+  );
+  for (const [index, slice] of (swarm.partition ?? []).entries()) {
+    ctx.ui.notify(`${hordeLabel(index + 1)}: ${oneLine(slice, 160)}`, "info");
+  }
+  if (swarm.dashboardUrl) ctx.ui.notify(`swarm ${swarm.id} dashboard: ${swarm.dashboardUrl}swarms/${swarm.id}`, "info");
+}
+
+/** Start the hordes' preflights a few seconds apart; a stop during the wait is honoured. */
+async function staggerLaunches(state: HordeState, launches: RunLaunch[]): Promise<void> {
+  for (const [index, launch] of launches.entries()) {
+    if (index > 0 && !state.disposed) await sleep(SWARM_STAGGER_MS);
+    if (state.disposed) return;
+    void preflightAndFanOut(launch).catch((error) => {
+      safeNotify(launch.run, `horde ${launch.run.id} failed: ${errorMessage(error)}`, "error");
+      // The horde is down for good; let the swarm account for it so the slot and widget free.
+      noteRunReported(state, launch.swarm, launch.run);
+      void noteRunFinalized(state, launch.swarm, launch.run);
+    });
+  }
 }
 
-async function launchRun(
+async function launchSwarm(
   state: HordeState,
   ctx: ExtensionCommandContext,
   parsed: HordeRunArgs,
   hordeDir: string,
 ): Promise<void> {
-  const { run, roles } = createRun(ctx, parsed, hordeDir, state.dashboard?.url);
-  // Claim the run synchronously, before the first await, so a second
+  const layout = allocateSwarm(hordeDir, parsed.hordes, Date.now());
+  const partition = await partitionTask(state, ctx, parsed, layout);
+  if (!partition || state.disposed) return;
+  const { swarm, launches } = buildSwarm(ctx, parsed, layout, partition, state.dashboard?.url);
+  // Claim the slot synchronously, before the first await, so a second
   // /agent-horde invocation in the same tick sees `active` and is refused.
-  state.active = run;
-  if (ctx.hasUI) mountWidget(run, ctx.ui);
-  startDeadline(run, ctx);
-  startSolvedWatch(run, ctx);
+  state.active = swarm;
+  if (ctx.hasUI) mountWidget(swarm, ctx.ui);
+  for (const run of swarm.runs) {
+    startDeadline(run, ctx);
+    startSolvedWatch(run, ctx);
+  }
   try {
-    await seedRun(run);
-    await recordLifecycle(run, "run-start", {
-      count: run.count, model: run.model, verifier: run.verifier, plan: run.plan,
-      roles: roles.map((role) => oneLine(role, 120)), dashboardUrl: run.dashboardUrl,
-    });
-    await recordPhase(run, "discovery", "start");
+    if (swarm.dir) {
+      fs.writeFileSync(path.join(swarm.dir, "SWARM.md"), swarmMarkdown(swarm), "utf-8");
+      writeSwarmRecord(swarm);
+    }
+    for (const { run, roles } of launches) await seedHorde(swarm, run, roles);
   } catch (error) {
-    stopRunTimers(run);
-    unmountWidget(run);
-    if (state.active === run) state.active = undefined;
-    ctx.ui.notify(`horde ${run.id} failed to start: ${errorMessage(error)}`, "error");
+    for (const run of swarm.runs) stopRunTimers(run);
+    unmountWidget(swarm);
+    if (state.active === swarm) state.active = undefined;
+    ctx.ui.notify(`horde ${swarm.id} failed to start: ${errorMessage(error)}`, "error");
     return;
   }
-  void preflightAndFanOut({ state, run, ctx, roles }).catch((error) => {
-    safeNotify(run, `horde ${run.id} failed: ${errorMessage(error)}`, "error");
-    if (state.active === run) state.active = undefined;
-  });
-  const plural = run.count === 1 ? "" : "s";
-  ctx.ui.notify(`horde ${run.id} started with ${run.count} member${plural} in ${hordeDir}`, "info");
-  if (run.dashboardUrl) {
-    ctx.ui.notify(`horde ${run.id} dashboard: ${run.dashboardUrl}runs/${run.id}`, "info");
-  }
+  void staggerLaunches(state, launches.map(({ run, roles }) => ({ state, swarm, run, ctx, roles })));
+  announceStart(ctx, swarm);
 }
 
-export async function startRun(
+export async function startSwarm(
   state: HordeState,
   ctx: ExtensionCommandContext,
   parsed: HordeRunArgs,
@@ -225,7 +370,7 @@ export async function startRun(
   try {
     const hordeDir = initHordeDir(ctx.cwd);
     if (!(await ensureDashboard(state, ctx, hordeDir, parsed.dashboard))) return;
-    await launchRun(state, ctx, parsed, hordeDir);
+    await launchSwarm(state, ctx, parsed, hordeDir);
   } finally {
     state.starting = false;
   }

package/src/run/repair.ts

@@ -13,9 +13,12 @@ import { scheduleCollaboration, stopReason } from "./schedule.js";
 import { spawnOne } from "./supervise.js";
 import type { RunLaunch } from "./supervise.js";
 
-/** Blockers and independent checks take precedence over administrative exchanges. */
+/**
+ * Blockers and independent checks take precedence over administrative exchanges. A request to
+ * validate the pending answer decides the run's outcome, so it ranks with the blockers.
+ */
 function repairPriority(message: PeerMessage): number {
-  if (message.blocking) return 0;
+  if (message.blocking || message.target === "answer") return 0;
   if (message.kind === "review-request" && /^[AF]\d+$/.test(message.target)) return 1;
   if (message.state === "responded") return 2;
   return 3;
@@ -33,7 +36,7 @@ function queueFor(launch: RunLaunch, member: MemberState): PeerMessage[] {
  * three reviews demands three, so its share is sized to the work rather than to the member.
  */
 export function repairDemand(queue: PeerMessage[]): number {
-  const checks = queue.filter((m) => m.blocking || (m.kind === "review-request" && /^[AF]\d+$/.test(m.target))).length;
+  const checks = queue.filter((m) => m.blocking || m.target === "answer" || (m.kind === "review-request" && /^[AF]\d+$/.test(m.target))).length;
   return Math.max(1, checks);
 }
 
@@ -135,8 +138,12 @@ interface FirstTurnCost {
   cacheWrite: number;
 }
 
-/** A finished worker receives a fresh, bounded attempt with a precise evidence handoff. */
-async function repairMember(launch: RunLaunch, member: MemberState, deadline: number, limits: RepairLimits, floors: RepairFloors): Promise<void> {
+/**
+ * A finished worker receives a fresh, bounded attempt with a precise evidence handoff. The time
+ * share is the allowance recorded and the deadline is derived from it once, so the record cannot
+ * read a millisecond under the floor the share was raised to.
+ */
+async function repairMember(launch: RunLaunch, member: MemberState, ms: number, limits: RepairLimits, floors: RepairFloors): Promise<void> {
   const { run } = launch;
   const ctx = { hordeDir: run.hordeDir, runId: run.id, actor: member.name };
   const queue = queueFor(launch, member);
@@ -146,7 +153,8 @@ async function repairMember(launch: RunLaunch, member: MemberState, deadline: nu
   member.repairs = (member.repairs ?? 0) + 1;
   member.repairStopReason = undefined;
   member.attempt = randomUUID();
-  const allowance = { ...limits, ms: Math.max(0, deadline - Date.now()) };
+  const deadline = Date.now() + ms;
+  const allowance = { ...limits, ms };
   let firstTurn: FirstTurnCost | undefined;
   member.resetNote = `Repair attempt ${member.repairs}. Discovery is closed. Budget: about ${allowance.tokens} input+output tokens, ${allowance.turns} turns and ${allowance.ms}ms. ` +
     `Read horde inbox and referenced evidence. Work in this priority order: ${queue.map((m) => `${m.id} ${m.target} (${m.state})`).join(", ")}. ` +
@@ -264,7 +272,7 @@ async function runRepairRounds(launch: RunLaunch, begin: (budget: RepairBudget)
       }
       await begin(budget);
       served.add(next.member.name);
-      await repairMember(launch, next.member, Date.now() + ms, { tokens, turns: budget.turns }, floors);
+      await repairMember(launch, next.member, ms, { tokens, turns: budget.turns }, floors);
     }
   }
 }

package/src/run/schedule.ts

@@ -1,7 +1,7 @@
 import { collaborationState, openMessages } from "../ledger/collaboration.js";
 import type { ArtifactRecord, CollaborationState } from "../ledger/collaboration.js";
 import { runCollaborationAction } from "../tool/collaboration-actions.js";
-import { currentTarget } from "../tool/collaboration-target.js";
+import { currentTarget, targetInfo } from "../tool/collaboration-target.js";
 import type { MemberState } from "../member.js";
 import type { RunLaunch } from "./supervise.js";
 import { safeNotify } from "./ui.js";
@@ -24,12 +24,17 @@ interface ScheduleOptions {
   liveOnly: boolean;
 }
 
-/** The non-owner with the fewest open review requests; ties go to the verifier, then roster order. */
-function pickReviewer(launch: RunLaunch, load: Map<string, number>, owner: string, liveOnly: boolean): MemberState | undefined {
+/**
+ * A member that reviewed an earlier revision can reattest a behaviour-neutral change cheaply, so
+ * it goes first; otherwise the non-owner with the fewest open review requests, ties to the
+ * verifier, then roster order.
+ */
+function pickReviewer(launch: RunLaunch, load: Map<string, number>, owner: string, liveOnly: boolean, prior: Set<string>): MemberState | undefined {
   const { run } = launch;
   const count = (member: MemberState) => load.get(member.name) ?? 0;
   const candidates = run.members.filter((m) => m.name !== owner && (!liveOnly || m.status === "running"));
-  return candidates.sort((a, b) => count(a) - count(b) || Number(b.name === run.verifier) - Number(a.name === run.verifier))[0];
+  return candidates.sort((a, b) =>
+    Number(prior.has(b.name)) - Number(prior.has(a.name)) || count(a) - count(b) || Number(b.name === run.verifier) - Number(a.name === run.verifier))[0];
 }
 
 function reviewLoad(state: CollaborationState): Map<string, number> {
@@ -53,12 +58,17 @@ async function assignArtifactReviews(launch: RunLaunch, options: ScheduleOptions
     if (!settled(artifact, options.settleMs)) continue;
     if (state.reviews.some((r) => r.target === artifact.id && r.revision === artifact.hash)) continue;
     if (state.messages.some((m) => m.target === artifact.id && m.revision === artifact.hash && m.kind === "review-request")) continue;
-    const reviewer = pickReviewer(launch, load, artifact.owner, options.liveOnly);
+    const prior = new Set(state.reviews.filter((r) => r.target === artifact.id && r.actor !== artifact.owner).map((r) => r.actor));
+    const reviewer = pickReviewer(launch, load, artifact.owner, options.liveOnly, prior);
     if (!reviewer) continue;
+    const carry = prior.has(reviewer.name)
+      ? ` You reviewed an earlier revision${artifact.changeNote ? ` (owner's change note: ${artifact.changeNote})` : ""}: if what you checked is unchanged, reattest with evidence instead of repeating the review.`
+      : "";
     await runCollaborationAction(ctx, { action: "message", kind: "review-request", target: artifact.id, to: reviewer.name,
       text: `Independently check ${artifact.path}@${artifact.hash} (${artifact.kind ?? "runnable"}) against: ${artifact.criteria}. ` +
         `${artifact.kind === "document" ? "Full-scope sourced/derived review may establish document acceptance; this does not establish runtime reproduction." : "Runnable acceptance requires full independent tested/reproduced support."} ` +
-        "Attach evidence and record a revision-scoped review. The review closes this parent assignment; a failed/partial check opens a challenge to the owner.",
+        "Attach evidence and record a revision-scoped review: unchecked names in-criteria gaps, limits names what lies outside the criteria. " +
+        `The review closes this parent assignment; a refuting check opens a challenge to the owner.${carry}`,
       requestId: `review:${artifact.id}:${artifact.hash}` });
     load.set(reviewer.name, (load.get(reviewer.name) ?? 0) + 1);
   }
@@ -74,10 +84,23 @@ function successorOf(ctx: { hordeDir: string; runId: string; actor: string }, ta
   }
 }
 
+/** A pinned dependency whose current revision moved on, with the owner's change note when it is an artifact. */
+function revisionDrift(ctx: { hordeDir: string; runId: string; actor: string }, state: CollaborationState, dependency: ArtifactRecord["dependencies"][number]): string | undefined {
+  try {
+    const current = targetInfo(ctx, state, dependency.target).revision;
+    if (current === dependency.revision) return undefined;
+    const note = state.artifacts.find((a) => a.id === dependency.target)?.changeNote;
+    return `${dependency.target}@${dependency.revision.slice(0, 12)} -> @${current.slice(0, 12)}${note ? ` (${note})` : ""}`;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
- * A superseded dependency excludes the artifact from acceptance. Repointing it automatically would
- * carry acceptance to content nobody reviewed against this artifact, so the owner is asked to
- * republish against the successor instead.
+ * A superseded or re-hashed dependency excludes the artifact from acceptance. Repointing it
+ * automatically would carry acceptance to content nobody reviewed against this artifact, so the
+ * owner is asked to republish against the successor or the new revision; reviewers of the old
+ * revision can then reattest when the change was behaviour-neutral.
  */
 async function assignDependencyRepins(launch: RunLaunch): Promise<void> {
   const { run } = launch;
@@ -89,12 +112,19 @@ async function assignDependencyRepins(launch: RunLaunch): Promise<void> {
       const successor = successorOf(ctx, target);
       return successor === undefined ? [] : [`${target} -> ${successor}`];
     });
-    if (!moved.length) continue;
+    const drifted = artifact.dependencies.flatMap((dependency) => {
+      const drift = successorOf(ctx, dependency.target) === undefined ? revisionDrift(ctx, state, dependency) : undefined;
+      return drift === undefined ? [] : [drift];
+    });
+    if (!moved.length && !drifted.length) continue;
     if (state.messages.some((m) => m.sender === "parent" && m.kind === "handoff" && m.target === artifact.id && m.revision === artifact.hash)) continue;
+    const parts = [
+      moved.length ? `Dependencies of ${artifact.id} were superseded (${moved.join(", ")}). Check the corrected findings, update ${artifact.path} where the correction changes it, and republish with dependsOn naming the successors.` : "",
+      drifted.length ? `Dependencies of ${artifact.id} changed revision (${drifted.join(", ")}). Check whether the change affects ${artifact.path}, then republish with dependsOn pinning the current revisions.` : "",
+      "Acceptance needs a review of the new revision; reviewers of the earlier one can reattest when the behaviour they checked is unchanged.",
+    ].filter(Boolean);
     await runCollaborationAction(ctx, { action: "message", kind: "handoff", target: artifact.id, to: artifact.owner,
-      text: `Dependencies of ${artifact.id} were superseded (${moved.join(", ")}). Check the corrected findings, update ${artifact.path} ` +
-        "where the correction changes it, and republish with dependsOn naming the successors. Acceptance needs a fresh review of the new revision.",
-      requestId: `repin:${artifact.id}:${artifact.hash}` });
+      text: parts.join(" "), requestId: `repin:${artifact.id}:${artifact.hash}` });
   }
 }
 

package/src/run/setup.ts

@@ -4,15 +4,31 @@ import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { HordeRunArgs } from "../args.js";
-import { formatRunId } from "../format.js";
 import { appendRunHeading } from "../ledger/board.js";
 import { listFacts } from "../ledger/facts.js";
 import { ensureFindingIds } from "../ledger/findings.js";
 import { claimIdea, listIdeas, seedPlan } from "../ledger/ideas.js";
 import { newMemberState } from "../member.js";
+import type { SiblingHorde } from "../member.js";
 import { VERIFIER_ROLE, memberSystemPrompt, taskMarkdown } from "../prompt.js";
 import type { HordeRun } from "./types.js";
 
+/** Where one horde of a swarm runs and what it was given. */
+export interface RunSpec {
+  id: string;
+  hordeDir: string;
+  runDir: string;
+  /** 1-based horde index in the swarm. */
+  horde: number;
+  hordes: number;
+  swarmId: string;
+  /** The horde's workstream when the swarm partitioned the task. */
+  slice?: string | undefined;
+  /** The `plan` layers this horde runs as its own plan. */
+  plan?: string[] | undefined;
+  siblings: SiblingHorde[];
+}
+
 function planMarkdown(id: string, layers: string[], count: number): string {
   return [
     `# Plan ${id}`,
@@ -55,32 +71,17 @@ function defaultRoles(count: number, noVerifier: boolean): string[] {
   return roles;
 }
 
-function allocateRunDir(hordeDir: string, startedAt: number): { id: string; runDir: string } {
-  const base = formatRunId(new Date(startedAt));
-  for (let attempt = 0; ; attempt++) {
-    const id = attempt === 0 ? base : `${base}-${attempt}`;
-    const runDir = path.join(hordeDir, "runs", id);
-    try {
-      fs.mkdirSync(runDir);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
-      throw error;
-    }
-    fs.mkdirSync(path.join(runDir, "sessions"), { recursive: true });
-    return { id, runDir };
-  }
-}
-
-/** Allocate the run directory, write TASK.md and SYSTEM.md, and build the run record. */
+/** Write TASK.md and SYSTEM.md into the allocated run directory and build the run record. */
 export function createRun(
   ctx: ExtensionCommandContext,
   parsed: HordeRunArgs,
-  hordeDir: string,
+  spec: RunSpec,
   dashboardUrl: string | undefined,
 ): { run: HordeRun; roles: string[] } {
-  const { count, prompt, plan } = parsed;
+  const { count, prompt } = parsed;
+  const { id, hordeDir, runDir, plan } = spec;
   const startedAt = Date.now();
-  const { id, runDir } = allocateRunDir(hordeDir, startedAt);
+  fs.mkdirSync(path.join(runDir, "sessions"), { recursive: true });
   const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
   const roles =
     plan && plan.length > 0
@@ -88,18 +89,27 @@ export function createRun(
       : defaultRoles(count, parsed.noVerifier === true);
   const verifierIndex = roles.indexOf(VERIFIER_ROLE);
   const verifier = verifierIndex === -1 ? undefined : `member-${verifierIndex + 1}`;
+  const swarm = spec.hordes > 1 ? { id: spec.swarmId, horde: spec.horde, hordes: spec.hordes, slice: spec.slice } : undefined;
   fs.writeFileSync(
     path.join(runDir, "TASK.md"),
     taskMarkdown({
-      id, prompt, count, model, thinkingLevel: ctx.thinkingLevel, startedAt, verifier,
+      id, prompt, count, model, thinkingLevel: ctx.thinkingLevel, startedAt, verifier, untilStop: parsed.untilStop, swarm,
     }),
     "utf-8",
   );
-  fs.writeFileSync(path.join(runDir, "SYSTEM.md"), memberSystemPrompt({ hordeDir, count }), "utf-8");
+  fs.writeFileSync(
+    path.join(runDir, "SYSTEM.md"),
+    memberSystemPrompt({ hordeDir, count, siblings: spec.siblings }),
+    "utf-8",
+  );
   fs.mkdirSync(path.join(runDir, "artifacts"), { recursive: true });
-  writeManifest(runDir, { model, thinking: ctx.thinkingLevel, roles, prompt });
+  writeManifest(runDir, { model, thinking: ctx.thinkingLevel, roles, prompt, swarm });
   const run: HordeRun = {
     id, hordeDir, runDir, prompt, count, startedAt,
+    horde: spec.horde,
+    hordes: spec.hordes,
+    slice: spec.slice,
+    siblings: spec.siblings,
     members: Array.from({ length: count }, (_, i) => newMemberState(i + 1)),
     controller: new AbortController(),
     controllers: new Map(),
@@ -112,6 +122,7 @@ export function createRun(
     model,
     plan,
     verifier,
+    untilStop: parsed.untilStop === true ? true : undefined,
     resets: [],
     dashboardUrl,
   };
@@ -130,7 +141,7 @@ function writeManifest(runDir: string, settings: Record<string, unknown>): void
     }
   };
   visit(root);
-  const config = Object.fromEntries(Object.entries(process.env).filter(([key]) => /^PI_HORDE_(?:REPAIR|REMIND|STALL|RESET|MAX|ALLOW|SOLVED|INBOX|CANARY|DELIVERABLE|POSTMORTEM|CLEANUP)/.test(key)));
+  const config = Object.fromEntries(Object.entries(process.env).filter(([key]) => /^PI_HORDE_(?:REPAIR|REMIND|STALL|RESET|MAX|ALLOW|SOLVED|INBOX|CANARY|DELIVERABLE|POSTMORTEM|CLEANUP|SWARM|PLANNER)/.test(key)));
   fs.writeFileSync(path.join(runDir, "MANIFEST.json"), JSON.stringify({ protocol: 1, codeHash: code.digest("hex"),
     promptHash: createHash("sha256").update(String(settings.prompt)).digest("hex"),
     systemHash: createHash("sha256").update(fs.readFileSync(path.join(runDir, "SYSTEM.md"))).digest("hex"), settings, config }, null, 2));