pi-agent-fleet 0.2.0 → 0.3.0

package/src/insert.ts

@@ -0,0 +1,90 @@
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ActiveFleet } from "./controller.js";
+import { validateFleetSpec } from "./dag.js";
+import { resolveModelReference, type ModelRegistryLike } from "./model-resolution.js";
+import { buildWorkerPrompt } from "./prompts.js";
+import { writeState } from "./state.js";
+
+export interface InsertResult {
+  ok: boolean;
+  message: string;
+  inserted?: string[];
+}
+
+async function persistFleetJson(fleet: ActiveFleet): Promise<void> {
+  const path = join(fleet.fleetRoot, "fleet.json");
+  const tmp = join(fleet.fleetRoot, `.fleet.json.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+  await writeFile(tmp, `${JSON.stringify(fleet.spec, null, 2)}\n`, "utf-8");
+  await rename(tmp, path);
+}
+
+async function insertWorkersSerialized(
+  fleet: ActiveFleet,
+  raw: unknown,
+  registry: ModelRegistryLike,
+): Promise<InsertResult> {
+  if (fleet.state.status === "completed") {
+    return { ok: false, message: "fleet is completed; relaunch a node instead of inserting" };
+  }
+  const list = Array.isArray(raw) ? raw : (raw as { workers?: unknown[] } | null)?.workers;
+  if (!Array.isArray(list) || list.length === 0) {
+    return { ok: false, message: "no workers to insert (expected an array or { \"workers\": [...] })" };
+  }
+  const candidate = {
+    fleet_name: fleet.spec.fleet_name,
+    type: "dag",
+    config: fleet.spec.config,
+    workers: [...fleet.spec.workers, ...list],
+  };
+  const v = validateFleetSpec(candidate);
+  if (!v.ok) return { ok: false, message: `invalid node insertion:\n${v.errors.join("\n")}` };
+  const fresh = v.spec.workers.slice(fleet.spec.workers.length);
+  for (const w of fresh) {
+    if (w.model) {
+      const r = resolveModelReference(registry, w.model);
+      if (!r.ok) return { ok: false, message: `worker "${w.id}" model: ${r.error}` };
+      w.model = `${r.model.provider}/${r.model.id}`;
+    }
+  }
+  try {
+    for (const w of fresh) {
+      await mkdir(join(fleet.fleetRoot, "workers", w.id, "output"), { recursive: true });
+      const prompt = buildWorkerPrompt({ spec: v.spec, state: fleet.state, workerId: w.id, fleetRoot: fleet.fleetRoot });
+      await writeFile(join(fleet.fleetRoot, "workers", w.id, "prompt.md"), prompt, "utf-8");
+    }
+    if (!fleet.running) {
+      const nodes = { ...fleet.state.nodes };
+      for (const w of fresh) {
+        nodes[w.id] = { status: "pending" as const, turns: 0, tokens: 0, cost_usd_estimate: 0, produced_outputs: [] };
+      }
+      const next = { ...fleet.state, nodes };
+      await writeState(fleet.fleetRoot, next);
+      fleet.state = next;
+    }
+  } catch (e: unknown) {
+    return { ok: false, message: `insert failed: ${e instanceof Error ? e.message : String(e)}` };
+  }
+  fleet.spec.workers.push(...fresh);
+  try {
+    await persistFleetJson(fleet);
+  } catch (e: unknown) {
+    fleet.spec.workers.length -= fresh.length;
+    return { ok: false, message: `insert failed: ${e instanceof Error ? e.message : String(e)}` };
+  }
+  const ids = fresh.map((w) => w.id);
+  return { ok: true, message: `inserted ${ids.join(", ")}`, inserted: ids };
+}
+
+const insertQueues = new WeakMap<ActiveFleet, Promise<unknown>>();
+
+export async function insertWorkers(
+  fleet: ActiveFleet,
+  raw: unknown,
+  registry: ModelRegistryLike,
+): Promise<InsertResult> {
+  const prev = insertQueues.get(fleet) ?? Promise.resolve();
+  const run = prev.then(() => insertWorkersSerialized(fleet, raw, registry));
+  insertQueues.set(fleet, run.catch(() => {}));
+  return run;
+}

package/src/model-resolution.ts

@@ -0,0 +1,73 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { FleetSpec } from "./types.js";
+
+export interface ModelRegistryLike {
+  getAvailable(): Model<Api>[];
+  getAll(): Model<Api>[];
+}
+
+export function aliasesFor(model: Model<Api>): string[] {
+  const extra = model as Model<Api> & { alias?: unknown; aliases?: unknown };
+  return [
+    model.id,
+    model.name,
+    ...(typeof extra.alias === "string" ? [extra.alias] : []),
+    ...(Array.isArray(extra.aliases) ? extra.aliases.filter((a): a is string => typeof a === "string") : []),
+  ];
+}
+
+export function resolveModelReference(
+  registry: ModelRegistryLike,
+  ref: string,
+): { ok: true; model: Model<Api> } | { ok: false; error: string } {
+  const models = registry.getAvailable();
+  const pool = models.length > 0 ? models : registry.getAll();
+  const needle = ref.toLowerCase();
+  const canonical = (m: Model<Api>) => `${m.provider}/${m.id}`.toLowerCase();
+  const byAlias = (m: Model<Api>, pred: (v: string) => boolean) => aliasesFor(m).some((a) => pred(a.toLowerCase()));
+
+  const tiers: Model<Api>[][] = [];
+  if (needle.includes("/")) {
+    tiers.push(pool.filter((m) => canonical(m) === needle));
+    const [provider, ...rest] = needle.split("/");
+    const alias = rest.join("/");
+    tiers.push(pool.filter((m) => m.provider.toLowerCase() === provider && byAlias(m, (a) => a === alias)));
+  }
+  tiers.push(pool.filter((m) => m.id.toLowerCase() === needle));
+  tiers.push(pool.filter((m) => byAlias(m, (a) => a === needle)));
+  tiers.push(pool.filter((m) => byAlias(m, (a) => a.startsWith(needle))));
+  tiers.push(pool.filter((m) => byAlias(m, (a) => a.includes(needle))));
+
+  for (const tier of tiers) {
+    const unique = [...new Map(tier.map((m) => [`${m.provider}/${m.id}`, m])).values()];
+    if (unique.length === 1) return { ok: true, model: unique[0] };
+    if (unique.length > 1) {
+      return {
+        ok: false,
+        error: `model "${ref}" is ambiguous: ${unique.map((m) => `${m.provider}/${m.id}`).join(", ")}`,
+      };
+    }
+  }
+  return { ok: false, error: `model "${ref}" not found` };
+}
+
+export function validateFleetModels(
+  spec: FleetSpec,
+  registry: ModelRegistryLike,
+): { ok: true } | { ok: false; errors: string[] } {
+  const errors: string[] = [];
+  const refs: Array<{ label: string; ref: string }> = [];
+  if (spec.config.model) refs.push({ label: "config.model", ref: spec.config.model });
+  for (const w of spec.workers) {
+    if (w.model) refs.push({ label: `worker "${w.id}" model`, ref: w.model });
+  }
+  const seen = new Set<string>();
+  for (const { label, ref } of refs) {
+    const key = `${label}\0${ref}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const r = resolveModelReference(registry, ref);
+    if (!r.ok) errors.push(`${label}: ${r.error}`);
+  }
+  return errors.length > 0 ? { ok: false, errors } : { ok: true };
+}

package/src/planner.ts

@@ -0,0 +1,148 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runWorker, type SessionFactory, type WorkerEvent } from "./runner.js";
+
+export const PLANNER_WORKER_ID = "planner";
+
+export interface FleetDesignResult {
+  ok: boolean;
+  error?: string;
+  draft?: unknown;
+  rationale?: string;
+  turns: number;
+  tokens: number;
+}
+
+export function slugifyFleetName(requirements: string): string {
+  const slug = requirements
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40)
+    .replace(/^-+|-+$/g, "");
+  return slug.length > 0 ? slug : "fleet";
+}
+
+export function buildPlannerPrompt(opts: { requirements: string; fleetName: string; plannerDir: string }): string {
+  const { requirements, fleetName, plannerDir } = opts;
+  return `# Fleet designer
+
+You design a DAG-of-agents "fleet" for the pi fleet runner. You produce ONE definition file plus a rationale.
+
+## Requirements from the user
+
+${requirements}
+
+## Your outputs (both REQUIRED)
+
+- ${plannerDir}/output/fleet.json — the fleet definition. A single raw JSON object, no markdown fences, no commentary.
+- ${plannerDir}/output/rationale.md — why this decomposition, what each node does, why the gate choice.
+
+## Fleet JSON schema
+
+{
+  "fleet_name": "${fleetName}",
+  "type": "dag",
+  "config": {
+    "max_concurrent": <integer >= 1, optional>,
+    "warn_cost_usd": <number >= 0, optional>,
+    "loop": { "gate": "reviewer" | "none", "max_iterations": <int >= 1>, "lgtm_count": <optional int, reviewer gate only> }
+  },
+  "workers": [
+    {
+      "id": "kebab-case",
+      "type": "research" | "code-run" | "reviewer" | "write" | "read-only",
+      "task": "full self-contained instructions for the worker",
+      "depends_on": ["upstream-worker-ids"],
+      "outputs": [{ "path": "output/<file> or repo-relative path", "kind": "markdown" | "file-exists" | "verdict" | "json" | "yaml", "required": true }],
+      "iterate": true,
+      "worktree": false
+    }
+  ]
+}
+
+config, outputs, iterate, worktree, and loop are optional (defaults: max_concurrent 4, iterate true, worktree false).
+
+## Hard rules (violations fail validation)
+
+1. fleet_name and worker ids are kebab-case; ids unique.
+2. depends_on references existing workers only; the graph must be acyclic.
+3. Do NOT set "model" or "effort" fields anywhere — the runner assigns models and effort.
+4. With gate "reviewer": exactly one worker declares an output of kind "verdict"; that worker must be a sink (nothing depends on it) and must iterate. Its task must instruct: the review file starts with exactly one of \`verdict: lgtm\` / \`verdict: iterate\` / \`verdict: escalate\`, followed by specific actionable per-worker feedback.
+5. With gate "none": at least one worker must have iterate enabled (default true counts).
+6. A worker with iterate: false may not depend on a worker that iterates.
+7. Output paths: "output/..." resolves under the worker dir (use for notes, reports, verdicts); any other relative path is repo-relative (use for code edits). No absolute paths, no "..".
+8. Worker types and tools: research (read/web/write), code-run (full coding tools), reviewer (read/write), write (read/write), read-only (read only).
+
+## Design guidance
+
+- Decompose into independent layer-0 research/analysis nodes that run in parallel, then synthesis/writer nodes, then optionally a reviewer gate.
+- Prefer few high-value nodes over many trivial ones; 3-10 workers is typical.
+- Each task must be self-contained: what to produce, where, format, constraints, done-criteria.
+- Use a loop with gate "reviewer" only when iterative refinement against feedback makes sense; otherwise a single pass is cheaper.
+`;
+}
+
+export function sanitizeDraft(draft: unknown): unknown {
+  if (typeof draft !== "object" || draft === null || Array.isArray(draft)) return draft;
+  const d = draft as Record<string, unknown>;
+  if (typeof d.config === "object" && d.config !== null && !Array.isArray(d.config)) {
+    const cfg = d.config as Record<string, unknown>;
+    delete cfg.model;
+    delete cfg.effort;
+  }
+  if (Array.isArray(d.workers)) {
+    for (const w of d.workers as Array<Record<string, unknown>>) {
+      if (typeof w === "object" && w !== null) {
+        delete w.model;
+        delete w.effort;
+      }
+    }
+  }
+  return d;
+}
+
+export async function runFleetDesign(opts: {
+  requirements: string;
+  fleetName: string;
+  designRoot: string;
+  repoCwd: string;
+  sessionFactory?: SessionFactory;
+  onEvent?: (e: WorkerEvent) => void;
+}): Promise<FleetDesignResult> {
+  const plannerDir = join(opts.designRoot, "planner");
+  await mkdir(join(plannerDir, "output"), { recursive: true });
+  const prompt = buildPlannerPrompt({ requirements: opts.requirements, fleetName: opts.fleetName, plannerDir });
+  const res = await runWorker({
+    nodeId: PLANNER_WORKER_ID,
+    worker: { id: PLANNER_WORKER_ID, type: "write", task: "design a fleet DAG", depends_on: [], outputs: [] },
+    prompt,
+    repoCwd: opts.repoCwd,
+    sessionDir: plannerDir,
+    sessionFactory: opts.sessionFactory,
+    thinkingLevel: "medium",
+    onEvent: opts.onEvent ?? (() => {}),
+  });
+  if (!res.ok) {
+    return { ok: false, error: res.error ?? "planner session failed", turns: res.turns, tokens: res.tokens };
+  }
+  let raw: string;
+  try {
+    raw = await readFile(join(plannerDir, "output", "fleet.json"), "utf-8");
+  } catch {
+    return { ok: false, error: "planner did not write output/fleet.json", turns: res.turns, tokens: res.tokens };
+  }
+  let draft: unknown;
+  try {
+    draft = sanitizeDraft(JSON.parse(raw));
+  } catch (e) {
+    return { ok: false, error: `fleet.json is not valid JSON: ${(e as Error).message}`, turns: res.turns, tokens: res.tokens };
+  }
+  let rationale: string | undefined;
+  try {
+    rationale = await readFile(join(plannerDir, "output", "rationale.md"), "utf-8");
+  } catch {
+    // rationale is optional in the result
+  }
+  return { ok: true, draft, rationale, turns: res.turns, tokens: res.tokens };
+}

package/src/preferences.ts

@@ -0,0 +1,103 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { THINKING_LEVELS } from "./types.js";
+import type { ThinkingLevelName } from "./types.js";
+
+export interface FleetPreferences {
+  max_concurrent?: number;
+  model?: string;
+  effort?: ThinkingLevelName;
+  warn_cost_usd?: number;
+}
+
+export const PREFERENCE_KEYS = ["max_concurrent", "model", "effort", "warn_cost_usd"] as const;
+
+export function defaultPreferencesPath(): string {
+  return join(homedir(), ".pi", "agent", "fleet.json");
+}
+
+export async function loadPreferences(path: string = defaultPreferencesPath()): Promise<FleetPreferences> {
+  try {
+    const raw = JSON.parse(await readFile(path, "utf-8")) as Record<string, unknown>;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {};
+    const prefs: FleetPreferences = {};
+    if (typeof raw.max_concurrent === "number" && Number.isInteger(raw.max_concurrent) && raw.max_concurrent >= 1) {
+      prefs.max_concurrent = raw.max_concurrent;
+    }
+    if (typeof raw.model === "string" && raw.model.length > 0) prefs.model = raw.model;
+    if (typeof raw.effort === "string" && THINKING_LEVELS.includes(raw.effort as ThinkingLevelName)) {
+      prefs.effort = raw.effort as ThinkingLevelName;
+    }
+    if (typeof raw.warn_cost_usd === "number" && Number.isFinite(raw.warn_cost_usd) && raw.warn_cost_usd >= 0) {
+      prefs.warn_cost_usd = raw.warn_cost_usd;
+    }
+    return prefs;
+  } catch {
+    return {};
+  }
+}
+
+export async function savePreferences(prefs: FleetPreferences, path: string = defaultPreferencesPath()): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(prefs, null, 2)}\n`, "utf-8");
+}
+
+export function mergeFleetConfig(raw: unknown, prefs: FleetPreferences): unknown {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return raw;
+  const fleet = raw as Record<string, unknown>;
+  const cfg = (typeof fleet.config === "object" && fleet.config !== null && !Array.isArray(fleet.config))
+    ? { ...(fleet.config as Record<string, unknown>) }
+    : {};
+  if (cfg.max_concurrent === undefined && prefs.max_concurrent !== undefined) cfg.max_concurrent = prefs.max_concurrent;
+  if (cfg.model === undefined && prefs.model !== undefined) cfg.model = prefs.model;
+  if (cfg.effort === undefined && prefs.effort !== undefined) cfg.effort = prefs.effort;
+  if (cfg.warn_cost_usd === undefined && prefs.warn_cost_usd !== undefined) cfg.warn_cost_usd = prefs.warn_cost_usd;
+  return { ...fleet, config: cfg };
+}
+
+export function validatePreferenceValue(
+  key: string,
+  value: string,
+): { ok: true; parsed: number | string } | { ok: false; error: string } {
+  switch (key) {
+    case "max_concurrent": {
+      const n = Number(value);
+      if (!Number.isInteger(n) || n < 1) return { ok: false, error: "max_concurrent must be an integer >= 1" };
+      return { ok: true, parsed: n };
+    }
+    case "warn_cost_usd": {
+      const n = Number(value);
+      if (!Number.isFinite(n) || n < 0) return { ok: false, error: "warn_cost_usd must be a number >= 0" };
+      return { ok: true, parsed: n };
+    }
+    case "effort": {
+      if (!THINKING_LEVELS.includes(value as ThinkingLevelName)) {
+        return { ok: false, error: `effort must be one of ${THINKING_LEVELS.join(", ")}` };
+      }
+      return { ok: true, parsed: value };
+    }
+    case "model": {
+      if (value.trim().length === 0) return { ok: false, error: "model must be non-empty" };
+      return { ok: true, parsed: value.trim() };
+    }
+    default:
+      return { ok: false, error: `unknown preference "${key}" (keys: ${PREFERENCE_KEYS.join(", ")})` };
+  }
+}
+
+export function setPreference(
+  prefs: FleetPreferences,
+  key: string,
+  value: string,
+): { ok: true; prefs: FleetPreferences } | { ok: false; error: string } {
+  const v = validatePreferenceValue(key, value);
+  if (!v.ok) return v;
+  return { ok: true, prefs: { ...prefs, [key]: v.parsed } };
+}
+
+export function clearPreference(prefs: FleetPreferences, key: string): FleetPreferences {
+  const next: Record<string, unknown> = { ...prefs };
+  delete next[key];
+  return next as FleetPreferences;
+}

package/src/prompts.ts

@@ -87,6 +87,13 @@ export function buildWorkerPrompt(opts: {
     );
   }
 
+  out.push("## Requesting additional nodes (optional)", "");
+  out.push(`If you discover work this DAG cannot do as currently shaped, write ${workerDir}/output/node-requests.json:`, "");
+  out.push(
+    `{ "workers": [{ "id": "kebab-case", "type": "research|code-run|reviewer|write|read-only", "task": "self-contained instructions", "depends_on": ["${workerId}"], "outputs": [{ "path": "output/file.md", "kind": "markdown", "required": true }] }] }`,
+    "",
+  );
+  out.push("The runner validates the merged graph (unique ids, known deps, acyclic, loop-gate rules) and inserts valid nodes as pending. Invalid batches are rejected atomically and noted on your node. Do not set model or effort fields — the runner assigns them. Depend on your own id when the new node needs your outputs.", "");
   out.push("## Your output obligations", "");
   if (worker.outputs.length === 0) {
     out.push("No declared outputs — completion is enough.", "");

package/src/runner.ts

@@ -1,7 +1,10 @@
-import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
-import type { WorkerSpec } from "./types.js";
+import { createAgentSession, SessionManager, type CreateAgentSessionOptions } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ThinkingLevelName, WorkerSpec } from "./types.js";
 import { WORKER_TYPE_TOOLS } from "./types.js";
 
+export type ThinkingLevelOption = NonNullable<CreateAgentSessionOptions["thinkingLevel"]>;
+
 export type WorkerEvent =
   | { type: "turn"; nodeId: string; turns: number }
   | { type: "tokens"; nodeId: string; tokens: number }
@@ -21,6 +24,7 @@ export interface SessionOpts {
   sessionDir: string;
   tools: string[];
   model?: string;
+  thinkingLevel?: ThinkingLevelName;
 }
 
 export type SessionFactory = (opts: SessionOpts) => Promise<AgentSessionLike>;
@@ -30,6 +34,7 @@ export const defaultSessionFactory: SessionFactory = async (opts) => {
     cwd: opts.cwd,
     tools: opts.tools,
     sessionManager: SessionManager.create(opts.cwd, opts.sessionDir),
+    thinkingLevel: opts.thinkingLevel as ThinkingLevelOption,
   });
   return session as unknown as AgentSessionLike;
 };
@@ -41,7 +46,9 @@ export interface RunWorkerOpts {
   repoCwd: string;
   sessionDir?: string;
   onEvent: (e: WorkerEvent) => void;
+  onSession?: (session: AgentSessionLike) => void;
   sessionFactory?: SessionFactory;
+  thinkingLevel?: ThinkingLevelName;
 }
 
 export interface RunWorkerResult {
@@ -54,12 +61,21 @@ export interface RunWorkerResult {
 
 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 session: AgentSessionLike;
+  try {
+    session = await factory({
+      cwd: opts.repoCwd,
+      sessionDir: opts.sessionDir ?? opts.repoCwd,
+      tools: WORKER_TYPE_TOOLS[opts.worker.type],
+      model: opts.worker.model,
+      thinkingLevel: opts.thinkingLevel,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    opts.onEvent({ type: "error", nodeId: opts.nodeId, message });
+    return { ok: false, turns: 0, tokens: 0, cost: 0, error: message };
+  }
+  opts.onSession?.(session);
   let turns = 0;
   let tokens = 0;
   let cost = 0;
@@ -93,3 +109,20 @@ export async function runWorker(opts: RunWorkerOpts): Promise<RunWorkerResult> {
     session.dispose();
   }
 }
+
+export function sessionFactoryForModel(model: Model<Api>): SessionFactory {
+  return async (opts) => {
+    const { session } = await createAgentSession({
+      cwd: opts.cwd,
+      tools: opts.tools,
+      sessionManager: SessionManager.create(opts.cwd, opts.sessionDir),
+      model,
+      thinkingLevel: opts.thinkingLevel as ThinkingLevelOption,
+    });
+    return session as unknown as AgentSessionLike;
+  };
+}
+
+export function workerWithResolvedModel(worker: WorkerSpec, model: Model<Api> | undefined): WorkerSpec {
+  return model ? { ...worker, model: `${model.provider}/${model.id}` } : worker;
+}

package/src/scheduler.ts

@@ -3,7 +3,7 @@ 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";
+import type { FleetSpec, FleetState, IterationSnapshot, NodeState, Verdict, WorkerSpec } from "./types.js";
 
 export type SpawnFn = (nodeId: string) => Promise<{ ok: boolean; turns: number; tokens: number; cost?: number; error?: string }>;
 
@@ -13,8 +13,11 @@ export interface RunFleetOpts {
   repoCwd: string | ((nodeId: string) => string);
   spawn: SpawnFn;
   onNodeChange?: (nodeId: string, s: NodeState) => void;
+  onNodeAdded?: (worker: WorkerSpec) => void | Promise<void>;
+  onNodeCompleted?: (nodeId: string) => Promise<string | undefined | void>;
   killSwitch?: { killed: boolean };
   pauseSwitch?: { paused: boolean };
+  nodeKills?: ReadonlySet<string>;
   resumeFrom?: FleetState;
   continuePass?: boolean;
   onIterationEnd?: (snap: IterationSnapshot) => void;
@@ -24,7 +27,10 @@ export interface RunFleetOpts {
 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));
+  return spec.workers.every((w) => {
+    const n = state.nodes[w.id];
+    return !!n && TERMINAL_NODE_STATUSES.has(n.status);
+  });
 }
 
 async function cleanReplayOutputs(spec: FleetSpec, fleetRoot: string): Promise<void> {
@@ -68,18 +74,34 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
 
   const runPass = async (): Promise<void> => {
     while (true) {
+      // auto-initialize workers inserted into the spec after the run started
+      for (const w of spec.workers) {
+        if (!state.nodes[w.id]) {
+          state = {
+            ...state,
+            nodes: {
+              ...state.nodes,
+              [w.id]: { status: "pending", turns: 0, tokens: 0, cost_usd_estimate: 0, produced_outputs: [] },
+            },
+          };
+          await writeState(fleetRoot, state);
+          await opts.onNodeAdded?.(w);
+          opts.onNodeChange?.(w.id, state.nodes[w.id]);
+        }
+      }
       // block nodes whose deps failed
       for (const w of spec.workers) {
         const n = state.nodes[w.id];
+        if (!n) continue;
         if (n.status !== "pending" && n.status !== "ready") continue;
-        if (w.depends_on.some((d) => FAILED.has(state.nodes[d].status))) {
+        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)) {
+          if (!n || !TERMINAL_NODE_STATUSES.has(n.status)) {
             await patch(w.id, { status: "killed", ended_at: new Date().toISOString() });
           }
         }
@@ -91,13 +113,22 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
       for (const w of spec.workers) {
         if (slots <= 0) break;
         const n = state.nodes[w.id];
+        if (!n) continue;
         if (n.status !== "pending" && n.status !== "ready") continue;
-        const depsDone = w.depends_on.every((d) => state.nodes[d].status === "completed");
+        if (opts.nodeKills?.has(w.id)) {
+          await patch(w.id, { status: "killed", ended_at: new Date().toISOString() });
+          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 (opts.nodeKills?.has(w.id)) {
+            await patch(w.id, { status: "killed", ended_at: new Date().toISOString(), turns: res.turns, tokens: res.tokens, cost_usd_estimate: res.cost ?? 0 });
+            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;
@@ -116,12 +147,19 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
             contract_result: contract,
             produced_outputs: contract.checks.filter((c) => c.ok).map((c) => c.path),
           });
+          if (contract.ok) {
+            const note = await opts.onNodeCompleted?.(w.id);
+            if (note) await patch(w.id, { status_note: note });
+          }
         }).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))) {
+      } else if (spec.workers.every((w) => {
+        const n = state.nodes[w.id];
+        return !!n && TERMINAL_NODE_STATUSES.has(n.status);
+      })) {
         break;
       }
     }
@@ -131,7 +169,7 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
   if (!loop) {
     await runPass();
     const anyFailed = spec.workers.some((w) =>
-      ["failed", "contract_failed"].includes(state.nodes[w.id].status));
+      ["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);
@@ -181,7 +219,7 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
     }
 
     const anyFailed = spec.workers.some((w) =>
-      ["failed", "contract_failed"].includes(state.nodes[w.id].status));
+      ["failed", "contract_failed"].includes(state.nodes[w.id]?.status ?? ""));
     if (anyFailed) {
       state = { ...state, status: "failed" };
       await writeState(fleetRoot, state);