pi-agent-fleet 0.2.0

package/src/prompts.ts

@@ -0,0 +1,116 @@
+import { basename } from "node:path";
+import { getDependents } from "./dag.js";
+import type { FleetSpec, FleetState } from "./types.js";
+import { renderDag } from "./viz.js";
+
+export function buildWorkerPrompt(opts: {
+  spec: FleetSpec;
+  state: FleetState;
+  workerId: string;
+  fleetRoot: string;
+}): string {
+  const { spec, state, workerId, fleetRoot } = opts;
+  const worker = spec.workers.find((w) => w.id === workerId);
+  if (!worker) throw new Error(`unknown worker "${workerId}"`);
+  const workerDir = `${fleetRoot}/workers/${workerId}`;
+  const deps = spec.workers.filter((w) => worker.depends_on.includes(w.id));
+  const dependents = getDependents(spec, workerId);
+  const out: string[] = [];
+
+  const fleetTs = basename(fleetRoot);
+
+  out.push(`# Fleet worker: ${workerId}`, "", `Type: ${worker.type}`, "", `## Task`, "", worker.task, "");
+
+  if (state.iteration > 1 && worker.iterate !== false) {
+    const last = state.iterations[state.iterations.length - 1];
+    if (last?.verdict_body) {
+      out.push(`## Reviewer feedback (iteration ${state.iteration - 1})`, "", last.verdict_body, "");
+    }
+  }
+
+  if (worker.outputs.some((o) => o.kind === "verdict") && state.iterations.length > 0) {
+    const reviews = state.iterations.filter((s) => s.verdict !== null);
+    if (reviews.length > 0) {
+      out.push("## Previous reviews", "");
+      for (const s of reviews) {
+        out.push(`### Iteration ${s.n} — verdict: ${s.verdict}`);
+        if (s.verdict_body) out.push(s.verdict_body);
+        out.push("");
+      }
+    }
+  }
+
+  out.push("## The fleet DAG", "", "```", renderDag(spec), "```", "");
+  for (const w of spec.workers) {
+    if (w.id !== workerId) out.push(`- ${w.id} (${w.type}): ${w.task}`);
+  }
+  out.push("");
+
+  out.push("## Your upstream inputs", "");
+  if (deps.length === 0) {
+    out.push("No upstream dependencies — you are a layer-0 node.", "");
+  } else {
+    for (const d of deps) {
+      if (d.worktree === true) {
+        out.push(`- ${d.id} worktree: ${fleetRoot}/worktrees/${d.id} (branch fleet/${fleetTs}/${d.id})`);
+        out.push("  — merge or cherry-pick from here if you need its repo changes");
+      }
+      if (d.outputs.length === 0) out.push(`- ${d.id}: (no declared outputs — read its session notes in ${fleetRoot}/workers/${d.id}/output/ if present)`);
+      for (const o of d.outputs) {
+        const abs = o.path.startsWith("output/")
+          ? `${fleetRoot}/workers/${d.id}/${o.path}`
+          : o.path;
+        out.push(`- ${d.id}: ${abs} (${o.kind})`);
+      }
+    }
+    out.push("");
+  }
+
+  out.push("## What downstream nodes need from you", "");
+  if (dependents.length === 0) {
+    out.push("No downstream nodes — your outputs terminate the DAG.", "");
+  } else {
+    for (const dep of dependents) out.push(`- ${dep} depends on your outputs`);
+    out.push("");
+  }
+
+  if (worker.outputs.some((o) => o.kind === "verdict")) {
+    out.push(
+      "## Writing your verdict",
+      "",
+      "Your review file MUST start with a verdict line, exactly one of:",
+      "verdict: lgtm",
+      "verdict: iterate",
+      "verdict: escalate",
+      "Below the verdict line, write actionable fix instructions per worker — file path, function name, what to change. A verdict line with no body FAILS the contract. The builders see this body as feedback next iteration, so be specific.",
+      "",
+    );
+  }
+
+  out.push("## Your output obligations", "");
+  if (worker.outputs.length === 0) {
+    out.push("No declared outputs — completion is enough.", "");
+  } else {
+    for (const o of worker.outputs) {
+      out.push(`- ${o.path} (${o.kind}${o.required ? ", REQUIRED" : ", optional"})`);
+    }
+    out.push("");
+  }
+  if (worker.outputs.some((o) => o.path.startsWith("output/"))) {
+    out.push(`Save ALL output files to ${workerDir}/output/ — use absolute paths.`, "");
+  }
+  if (worker.outputs.some((o) => !o.path.startsWith("output/"))) {
+    out.push("Write code changes directly at their repo paths.", "");
+  }
+  if (worker.worktree === true) {
+    out.push("## Your worktree", "");
+    out.push("Work inside your own git worktree, not the main checkout.");
+    out.push("If it does not exist yet, create it:");
+    out.push(`  git worktree add ${fleetRoot}/worktrees/${workerId} -b fleet/${fleetTs}/${workerId}`);
+    out.push("If it already exists (iteration > 1), reuse it and your existing branch.");
+    out.push("Make ALL repo changes inside the worktree. Commit your work there.");
+    out.push("");
+  }
+
+  return out.join("\n");
+}

package/src/report.ts

@@ -0,0 +1,81 @@
+import { execFile } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import type { FleetSpec, FleetState } from "./types.js";
+import { renderDag } from "./viz.js";
+
+const execFileP = promisify(execFile);
+
+function formatDuration(ms: number): string {
+  if (ms <= 0) return "0.0s";
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+export async function gitDiffStat(repoCwd: string, _sinceIso: string): Promise<string> {
+  try {
+    const { stdout } = await execFileP("git", ["-C", repoCwd, "diff", "--stat", "HEAD"]);
+    const out = stdout.trim();
+    return out.length > 0 ? out : "(no changes)";
+  } catch {
+    return "(not a git repo)";
+  }
+}
+
+export async function writeReport(opts: {
+  spec: FleetSpec;
+  state: FleetState;
+  fleetRoot: string;
+  repoCwd: string;
+}): Promise<string> {
+  const { spec, state, fleetRoot, repoCwd } = opts;
+  const experiment = (spec as unknown as { experiment?: string }).experiment;
+  const lines: string[] = [];
+  lines.push(`# Fleet report: ${spec.fleet_name}`, "");
+  lines.push(`- status: **${state.status}**`);
+  lines.push(`- created: ${state.created_at}`);
+  lines.push(`- total cost estimate: $${state.cost_usd_estimate.toFixed(2)}`);
+  if (experiment) lines.push(`- experiment: ${experiment}`);
+  lines.push("", "## DAG", "", "```", renderDag(spec, state), "```", "");
+  lines.push("## Nodes", "", "| id | status | turns | tokens | cost | contract | outputs |",
+    "|---|---|---|---|---|---|---|");
+  for (const w of spec.workers) {
+    const n = state.nodes[w.id];
+    const contract = n.contract_result
+      ? n.contract_result.ok ? "✓" : `✗ ${n.contract_result.checks.filter((c) => !c.ok).map((c) => c.path).join(", ")}`
+      : "—";
+    lines.push(`| ${w.id} | ${n.status} | ${n.turns} | ${n.tokens} | $${n.cost_usd_estimate.toFixed(2)} | ${contract} | ${n.produced_outputs.join(", ") || "—"} |`);
+  }
+  if (spec.config.loop) {
+    lines.push("", "## Iterations", "", "| n | verdict | tokens | cost | duration |",
+      "|---|---|---|---|---|");
+    for (const it of state.iterations) {
+      const tokens = Object.values(it.nodes).reduce((sum, n) => sum + n.tokens, 0);
+      const cost = Object.values(it.nodes).reduce((sum, n) => sum + n.cost_usd_estimate, 0);
+      const durationMs = new Date(it.ended_at).getTime() - new Date(it.started_at).getTime();
+      lines.push(`| ${it.n} | ${it.verdict ?? "—"} | ${tokens} | $${cost.toFixed(2)} | ${formatDuration(durationMs)} |`);
+    }
+    for (const it of state.iterations) {
+      lines.push("", `### Iteration ${it.n}`, "");
+      lines.push(`- verdict: ${it.verdict ?? "—"}`);
+      if (it.verdict_body) lines.push("", it.verdict_body);
+      for (const w of spec.workers) {
+        const n = it.nodes[w.id];
+        if (n) lines.push(`- ${w.id}: ${n.status} · ${n.turns} turns · ${n.tokens} tok`);
+      }
+    }
+  }
+  if (spec.workers.some((w) => w.worktree)) {
+    lines.push("", "## Worktree branches", "");
+    const base = basename(fleetRoot);
+    for (const w of spec.workers) {
+      if (w.worktree) lines.push(`- fleet/${base}/${w.id}`);
+    }
+  }
+  lines.push("", "## Code changes", "", "```", await gitDiffStat(repoCwd, state.created_at), "```", "");
+  lines.push("## Artifacts", "", `- state: ${join(fleetRoot, "state.json")}`,
+    `- sessions: ${join(fleetRoot, "workers", "<id>", "session.jsonl")}`, "");
+  const md = lines.join("\n");
+  await writeFile(join(fleetRoot, "report.md"), md, "utf-8");
+  return md;
+}

package/src/runner.ts

@@ -0,0 +1,95 @@
+import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import type { WorkerSpec } from "./types.js";
+import { WORKER_TYPE_TOOLS } from "./types.js";
+
+export type WorkerEvent =
+  | { type: "turn"; nodeId: string; turns: number }
+  | { type: "tokens"; nodeId: string; tokens: number }
+  | { type: "cost"; nodeId: string; cost: number }
+  | { type: "done"; nodeId: string }
+  | { type: "error"; nodeId: string; message: string };
+
+export interface AgentSessionLike {
+  prompt(t: string): Promise<void>;
+  abort(): Promise<void>;
+  subscribe(l: (e: { type: string; message?: unknown }) => void): () => void;
+  dispose(): void;
+}
+
+export interface SessionOpts {
+  cwd: string;
+  sessionDir: string;
+  tools: string[];
+  model?: string;
+}
+
+export type SessionFactory = (opts: SessionOpts) => Promise<AgentSessionLike>;
+
+export const defaultSessionFactory: SessionFactory = async (opts) => {
+  const { session } = await createAgentSession({
+    cwd: opts.cwd,
+    tools: opts.tools,
+    sessionManager: SessionManager.create(opts.cwd, opts.sessionDir),
+  });
+  return session as unknown as AgentSessionLike;
+};
+
+export interface RunWorkerOpts {
+  nodeId: string;
+  worker: WorkerSpec;
+  prompt: string;
+  repoCwd: string;
+  sessionDir?: string;
+  onEvent: (e: WorkerEvent) => void;
+  sessionFactory?: SessionFactory;
+}
+
+export interface RunWorkerResult {
+  ok: boolean;
+  turns: number;
+  tokens: number;
+  cost: number;
+  error?: string;
+}
+
+export async function runWorker(opts: RunWorkerOpts): Promise<RunWorkerResult> {
+  const factory = opts.sessionFactory ?? defaultSessionFactory;
+  const session = await factory({
+    cwd: opts.repoCwd,
+    sessionDir: opts.sessionDir ?? opts.repoCwd,
+    tools: WORKER_TYPE_TOOLS[opts.worker.type],
+    model: opts.worker.model,
+  });
+  let turns = 0;
+  let tokens = 0;
+  let cost = 0;
+  const unsub = session.subscribe((e) => {
+    if (e.type === "turn_end") {
+      turns++;
+      opts.onEvent({ type: "turn", nodeId: opts.nodeId, turns });
+    }
+    if (e.type === "message_end") {
+      const msg = e.message as { role?: string; usage?: { totalTokens?: number; cost?: { total?: number } } } | undefined;
+      if (msg?.role === "assistant" && msg.usage?.totalTokens) {
+        tokens += msg.usage.totalTokens;
+        opts.onEvent({ type: "tokens", nodeId: opts.nodeId, tokens });
+      }
+      if (msg?.role === "assistant" && msg.usage?.cost?.total) {
+        cost += msg.usage.cost.total;
+        opts.onEvent({ type: "cost", nodeId: opts.nodeId, cost });
+      }
+    }
+  });
+  try {
+    await session.prompt(opts.prompt);
+    opts.onEvent({ type: "done", nodeId: opts.nodeId });
+    return { ok: true, turns, tokens, cost };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    opts.onEvent({ type: "error", nodeId: opts.nodeId, message });
+    return { ok: false, turns, tokens, cost, error: message };
+  } finally {
+    unsub();
+    session.dispose();
+  }
+}

package/src/scheduler.ts

@@ -0,0 +1,226 @@
+import { mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { verifyOutputs } from "./contracts.js";
+import { archiveIteration, initFleetState, patchNode, resetForIteration, snapshotIteration, writeState } from "./state.js";
+import { TERMINAL_NODE_STATUSES } from "./types.js";
+import type { FleetSpec, FleetState, IterationSnapshot, NodeState, Verdict } from "./types.js";
+
+export type SpawnFn = (nodeId: string) => Promise<{ ok: boolean; turns: number; tokens: number; cost?: number; error?: string }>;
+
+export interface RunFleetOpts {
+  spec: FleetSpec;
+  fleetRoot: string;
+  repoCwd: string | ((nodeId: string) => string);
+  spawn: SpawnFn;
+  onNodeChange?: (nodeId: string, s: NodeState) => void;
+  killSwitch?: { killed: boolean };
+  pauseSwitch?: { paused: boolean };
+  resumeFrom?: FleetState;
+  continuePass?: boolean;
+  onIterationEnd?: (snap: IterationSnapshot) => void;
+  prepareIteration?: (n: number, state: FleetState) => Promise<void>;
+}
+
+const FAILED: ReadonlySet<string> = new Set(["failed", "contract_failed", "killed", "blocked"]);
+
+function allNodesTerminal(state: FleetState, spec: FleetSpec): boolean {
+  return spec.workers.every((w) => TERMINAL_NODE_STATUSES.has(state.nodes[w.id].status));
+}
+
+async function cleanReplayOutputs(spec: FleetSpec, fleetRoot: string): Promise<void> {
+  for (const w of spec.workers) {
+    if (w.iterate === false) continue;
+    const outDir = join(fleetRoot, "workers", w.id, "output");
+    await rm(outDir, { recursive: true, force: true });
+    await mkdir(outDir, { recursive: true });
+  }
+}
+
+export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
+  const { spec, fleetRoot } = opts;
+  const loop = spec.config.loop;
+
+  let state: FleetState;
+  if (opts.resumeFrom) {
+    state = { ...opts.resumeFrom, paused: false, status: "running" };
+    await writeState(fleetRoot, state);
+    if (allNodesTerminal(state, spec) && !opts.continuePass) {
+      state = resetForIteration(state, spec);
+      await writeState(fleetRoot, state);
+      await cleanReplayOutputs(spec, fleetRoot);
+    }
+  } else {
+    state = initFleetState(spec);
+    state = { ...state, status: "running" };
+    await writeState(fleetRoot, state);
+  }
+
+  const patch = async (id: string, p: Partial<NodeState>) => {
+    state = patchNode(fleetRoot, state, id, p);
+    await writeState(fleetRoot, state);
+    opts.onNodeChange?.(id, state.nodes[id]);
+  };
+
+  const running = new Set<Promise<void>>();
+
+  const repoCwdFor = (nodeId: string): string =>
+    typeof opts.repoCwd === "function" ? opts.repoCwd(nodeId) : opts.repoCwd;
+
+  const runPass = async (): Promise<void> => {
+    while (true) {
+      // block nodes whose deps failed
+      for (const w of spec.workers) {
+        const n = state.nodes[w.id];
+        if (n.status !== "pending" && n.status !== "ready") continue;
+        if (w.depends_on.some((d) => FAILED.has(state.nodes[d].status))) {
+          await patch(w.id, { status: "blocked", ended_at: new Date().toISOString() });
+        }
+      }
+      if (opts.killSwitch?.killed) {
+        for (const w of spec.workers) {
+          const n = state.nodes[w.id];
+          if (!TERMINAL_NODE_STATUSES.has(n.status)) {
+            await patch(w.id, { status: "killed", ended_at: new Date().toISOString() });
+          }
+        }
+        break;
+      }
+      // dispatch ready
+      const activeCount = running.size;
+      let slots = spec.config.max_concurrent - activeCount;
+      for (const w of spec.workers) {
+        if (slots <= 0) break;
+        const n = state.nodes[w.id];
+        if (n.status !== "pending" && n.status !== "ready") continue;
+        const depsDone = w.depends_on.every((d) => state.nodes[d].status === "completed");
+        if (!depsDone) continue;
+        slots--;
+        await patch(w.id, { status: "running", started_at: new Date().toISOString() });
+        const p = opts.spawn(w.id).then(async (res) => {
+          if (opts.killSwitch?.killed) return;
+          if (!res.ok) {
+            await patch(w.id, { status: "failed", ended_at: new Date().toISOString(), turns: res.turns, tokens: res.tokens, cost_usd_estimate: res.cost ?? 0 });
+            return;
+          }
+          const contract = await verifyOutputs({
+            workerDir: `${fleetRoot}/workers/${w.id}`,
+            repoCwd: repoCwdFor(w.id),
+            outputs: w.outputs,
+          });
+          await patch(w.id, {
+            status: contract.ok ? "completed" : "contract_failed",
+            ended_at: new Date().toISOString(),
+            turns: res.turns,
+            tokens: res.tokens,
+            cost_usd_estimate: res.cost ?? 0,
+            contract_result: contract,
+            produced_outputs: contract.checks.filter((c) => c.ok).map((c) => c.path),
+          });
+        }).finally(() => running.delete(p));
+        running.add(p);
+      }
+      if (running.size > 0) {
+        await Promise.race(running);
+      } else if (spec.workers.every((w) => TERMINAL_NODE_STATUSES.has(state.nodes[w.id].status))) {
+        break;
+      }
+    }
+    await Promise.allSettled([...running]);
+  };
+
+  if (!loop) {
+    await runPass();
+    const anyFailed = spec.workers.some((w) =>
+      ["failed", "contract_failed"].includes(state.nodes[w.id].status));
+    const finalStatus = opts.killSwitch?.killed ? "killed" : anyFailed ? "failed" : "completed";
+    state = { ...state, status: finalStatus };
+    await writeState(fleetRoot, state);
+    return state;
+  }
+
+  const maxIterations = loop.max_iterations;
+  const reviewerId = loop.gate === "reviewer"
+    ? spec.workers.find((w) => w.outputs.some((o) => o.kind === "verdict"))?.id
+    : undefined;
+
+  const initialIteration = state.iteration;
+  for (let n = state.iteration; n <= maxIterations; n++) {
+    if (opts.pauseSwitch?.paused || state.paused) {
+      state = { ...state, status: "paused", paused: true };
+      await writeState(fleetRoot, state);
+      return state;
+    }
+
+    if (n > initialIteration) {
+      state = resetForIteration(state, spec);
+      await writeState(fleetRoot, state);
+      await cleanReplayOutputs(spec, fleetRoot);
+    }
+
+    await opts.prepareIteration?.(n, state);
+
+    await runPass();
+
+    let verdict: Verdict | null = null;
+    let verdictBody: string | null = null;
+    if (reviewerId) {
+      const cr = state.nodes[reviewerId].contract_result;
+      verdict = cr?.verdict ?? null;
+      verdictBody = cr?.verdict_body ?? null;
+    }
+
+    state = snapshotIteration(state, verdict, verdictBody, spec);
+    const snap = state.iterations[state.iterations.length - 1];
+    opts.onIterationEnd?.(snap);
+    await archiveIteration(fleetRoot, state.iteration, spec.workers.map((w) => w.id));
+
+    if (opts.killSwitch?.killed) {
+      state = { ...state, status: "killed" };
+      await writeState(fleetRoot, state);
+      return state;
+    }
+
+    const anyFailed = spec.workers.some((w) =>
+      ["failed", "contract_failed"].includes(state.nodes[w.id].status));
+    if (anyFailed) {
+      state = { ...state, status: "failed" };
+      await writeState(fleetRoot, state);
+      return state;
+    }
+
+    if (loop.gate === "reviewer") {
+      const v = verdict;
+      if (v === "lgtm") {
+        const streak = state.lgtm_streak + 1;
+        if (streak >= loop.lgtm_count) {
+          state = { ...state, status: "completed", lgtm_streak: streak };
+          await writeState(fleetRoot, state);
+          return state;
+        }
+        state = { ...state, lgtm_streak: streak };
+        await writeState(fleetRoot, state);
+        continue;
+      }
+      if (v === "iterate") {
+        state = { ...state, lgtm_streak: 0 };
+        await writeState(fleetRoot, state);
+        continue;
+      }
+      if (v === "escalate") {
+        state = { ...state, status: "paused", paused: true };
+        await writeState(fleetRoot, state);
+        return state;
+      }
+      // Reviewer completed without a readable verdict; treat as fleet failure.
+      state = { ...state, status: "failed" };
+      await writeState(fleetRoot, state);
+      return state;
+    }
+
+    // gate: "none" — continue to next iteration until cap.
+  }
+
+  state = { ...state, status: "failed" };
+  await writeState(fleetRoot, state);
+  return state;
+}

package/src/state.ts

@@ -0,0 +1,156 @@
+import { cp, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { FleetSpec, FleetState, IterationSnapshot, NodeState, Verdict } from "./types.js";
+
+export function initFleetState(spec: FleetSpec): FleetState {
+  const nodes: Record<string, NodeState> = {};
+  for (const w of spec.workers) {
+    nodes[w.id] = { status: "pending", turns: 0, tokens: 0, cost_usd_estimate: 0, produced_outputs: [] };
+  }
+  return {
+    fleet_name: spec.fleet_name,
+    status: "planned",
+    created_at: new Date().toISOString(),
+    cost_usd_estimate: 0,
+    nodes,
+    iteration: 1,
+    lgtm_streak: 0,
+    paused: false,
+    iterations: [],
+  };
+}
+
+export async function readState(fleetRoot: string): Promise<FleetState> {
+  const parsed = JSON.parse(await readFile(join(fleetRoot, "state.json"), "utf-8")) as Partial<FleetState>;
+  if (!parsed.fleet_name || !parsed.status || !parsed.created_at || !parsed.nodes) {
+    throw new Error("invalid state.json");
+  }
+  return {
+    ...parsed as FleetState,
+    cost_usd_estimate: parsed.cost_usd_estimate ?? 0,
+    iteration: parsed.iteration ?? 1,
+    lgtm_streak: parsed.lgtm_streak ?? 0,
+    paused: parsed.paused ?? false,
+    iterations: parsed.iterations ?? [],
+  };
+}
+
+export function fleetCost(state: FleetState): number {
+  const liveCost = Object.values(state.nodes).reduce((sum, n) => sum + n.cost_usd_estimate, 0);
+  const archivedCost = state.iterations.reduce(
+    (sum, iter) => sum + Object.values(iter.nodes).reduce((s, n) => s + n.cost_usd_estimate, 0),
+    0,
+  );
+  return liveCost + archivedCost;
+}
+
+export async function writeState(fleetRoot: string, state: FleetState): Promise<void> {
+  const unique = `${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+  const tmp = join(fleetRoot, `.state.json.${unique}.tmp`);
+  await writeFile(tmp, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+  await rename(tmp, join(fleetRoot, "state.json"));
+}
+
+export function snapshotIteration(
+  state: FleetState,
+  verdict: Verdict | null,
+  verdictBody: string | null,
+  spec?: FleetSpec,
+): FleetState {
+  const now = new Date().toISOString();
+  const startedAts = spec
+    ? spec.workers
+        .filter((w) => w.iterate !== false)
+        .map((w) => state.nodes[w.id]?.started_at)
+        .filter((s): s is string => !!s)
+        .sort()
+    : Object.values(state.nodes)
+        .map((n) => n.started_at)
+        .filter((s): s is string => !!s)
+        .sort();
+  const snapshot: IterationSnapshot = {
+    n: state.iteration,
+    verdict,
+    verdict_body: verdictBody,
+    started_at: startedAts[0] ?? now,
+    ended_at: now,
+    nodes: structuredClone(state.nodes) as Record<string, NodeState>,
+  };
+  const zeroed: Record<string, NodeState> = {};
+  for (const [id, n] of Object.entries(state.nodes)) {
+    zeroed[id] = { ...n, cost_usd_estimate: 0 };
+  }
+  return { ...state, nodes: zeroed, iterations: [...state.iterations, snapshot] };
+}
+
+export function resetForIteration(state: FleetState, spec: FleetSpec): FleetState {
+  const nodes = { ...state.nodes };
+  for (const w of spec.workers) {
+    if (w.iterate !== false) {
+      nodes[w.id] = { status: "pending", turns: 0, tokens: 0, cost_usd_estimate: 0, produced_outputs: [] };
+    }
+  }
+  const cost = fleetCost({ ...state, nodes });
+  return { ...state, iteration: state.iteration + 1, nodes, cost_usd_estimate: cost };
+}
+
+export async function archiveIteration(fleetRoot: string, n: number, nodeIds: string[]): Promise<void> {
+  for (const id of nodeIds) {
+    const workerDir = join(fleetRoot, "workers", id);
+    const iterDir = join(fleetRoot, "iterations", String(n), "workers", id);
+    await cp(join(workerDir, "output"), join(iterDir, "output"), { recursive: true });
+    try {
+      await cp(join(workerDir, "prompt.md"), join(iterDir, "..", `${id}-prompt.md`));
+    } catch (e: unknown) {
+      const err = e as { code?: string };
+      if (err.code !== "ENOENT") throw e;
+    }
+  }
+}
+
+export function patchNode(
+  _fleetRoot: string,
+  state: FleetState,
+  nodeId: string,
+  patch: Partial<NodeState>,
+): FleetState {
+  const node = state.nodes[nodeId];
+  if (!node) throw new Error(`unknown node "${nodeId}"`);
+  const nodes = { ...state.nodes, [nodeId]: { ...node, ...patch } };
+  const cost = fleetCost({ ...state, nodes });
+  return { ...state, nodes, cost_usd_estimate: cost };
+}
+
+export function resetForRelaunch(state: FleetState, spec: FleetSpec, nodeId: string): FleetState {
+  if (!state.nodes[nodeId]) throw new Error(`unknown node "${nodeId}"`);
+
+  const dependents: Record<string, string[]> = {};
+  for (const w of spec.workers) {
+    for (const dep of w.depends_on) {
+      (dependents[dep] ??= []).push(w.id);
+    }
+  }
+
+  const downstream = new Set<string>();
+  const walk = (id: string) => {
+    for (const d of dependents[id] ?? []) {
+      if (!downstream.has(d)) {
+        downstream.add(d);
+        walk(d);
+      }
+    }
+  };
+  walk(nodeId);
+
+  const fresh: NodeState = { status: "pending", turns: 0, tokens: 0, cost_usd_estimate: 0, produced_outputs: [] };
+  const nodes = { ...state.nodes };
+  nodes[nodeId] = fresh;
+  for (const id of downstream) {
+    if (state.nodes[id].status === "blocked") {
+      nodes[id] = fresh;
+    }
+  }
+
+  const cost = fleetCost({ ...state, nodes });
+  return { ...state, nodes, paused: false, cost_usd_estimate: cost };
+}