pi-agent-fleet 0.3.0 → 0.5.0

package/src/command.ts

@@ -1,19 +1,19 @@
-import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { activeFleet, currentState, ensureCanvas, killFleet, prepareRelaunch, startLoop, stopCanvas, updateWidget } from "./controller.js";
+import { activeFleet, currentState, ensureCanvas, killFleet, prepareRelaunch, startLoop, statusText, stopCanvas, updateWidget } from "./controller.js";
+import { persistFleetJson, writeWorkerPrompts } from "./fleet-store.js";
 import { openInBrowser, listFleetRoots } from "./canvas.js";
 import { insertWorkers } from "./insert.js";
 import { editConfig, editNode, type ConfigEditKey, type NodeEditKey } from "./edits.js";
-import { resolveModelReference } from "./model-resolution.js";
+import { listModelRefs, resolveModelReference } from "./model-resolution.js";
 import { clearPreference, loadPreferences, PREFERENCE_KEYS, savePreferences, setPreference } from "./preferences.js";
+import { recoverLatestFleet } from "./fleet-recovery.js";
 import { resetForRelaunch, writeState } from "./state.js";
 import { buildWidgetLines } from "./ui.js";
 import { renderDag } from "./viz.js";
 
 export function registerFleetCommand(pi: ExtensionAPI): void {
   pi.registerCommand("fleet", {
-    description: "Fleet commands: /fleet viz, /fleet status, /fleet canvas [stop], /fleet configure [show|set k v], /fleet add <json>, /fleet edit <node_id>|config ..., /fleet clear, /fleet kill all|<node_id>, /fleet pause, /fleet resume, /fleet relaunch <node_id> [model]",
+    description: "Fleet commands: /fleet viz, /fleet status, /fleet models, /fleet canvas [stop], /fleet configure [show|set k v], /fleet add <json>, /fleet edit <node_id>|config ..., /fleet clear, /fleet kill all|<node_id>, /fleet pause, /fleet resume, /fleet continue, /fleet relaunch <node_id> [model]",
     handler: async (args, ctx) => {
       const [cmd, target] = args.trim().split(/\s+/);
       if (cmd === "configure") {
@@ -32,7 +32,7 @@ export function registerFleetCommand(pi: ExtensionAPI): void {
             return;
           }
           const prefs = await loadPreferences();
-          const r = setPreference(prefs, key, value);
+          const r = setPreference(prefs, key, value, ctx.modelRegistry);
           if (!r.ok) {
             ctx.ui.notify(r.error, "error");
             return;
@@ -50,15 +50,19 @@ export function registerFleetCommand(pi: ExtensionAPI): void {
           const key = field.split(":")[0] as (typeof PREFERENCE_KEYS)[number];
           const input = await ctx.ui.input(`${key} (current: ${prefs[key] ?? "—"}):`, "empty clears");
           if (input === undefined) break;
+          let err: string | undefined;
           const next = input.trim().length === 0
             ? clearPreference(prefs, key)
             : (() => {
-                const r = setPreference(prefs, key, input.trim());
-                if (!r.ok) return undefined;
+                const r = setPreference(prefs, key, input.trim(), ctx.modelRegistry);
+                if (!r.ok) {
+                  err = r.error;
+                  return undefined;
+                }
                 return r.prefs;
               })();
           if (next === undefined) {
-            ctx.ui.notify(`invalid value for ${key}`, "error");
+            ctx.ui.notify(err ?? `invalid value for ${key}`, "error");
             continue;
           }
           await savePreferences(next);
@@ -87,26 +91,36 @@ export function registerFleetCommand(pi: ExtensionAPI): void {
         ctx.ui.notify(`fleet canvas: ${url}`, "info");
         return;
       }
-      const active = activeFleet.current;
+      if (cmd === "models") {
+        ctx.ui.notify(`available models:\n${listModelRefs(ctx.modelRegistry).join("\n")}`, "info");
+        return;
+      }
+      const active = activeFleet.current ?? await recoverLatestFleet(ctx.cwd);
+      if (active) activeFleet.current ??= active;
       if (!active) {
         ctx.ui.notify("no fleet planned yet", "warning");
         return;
       }
       if (cmd === "viz") {
+        active.widgetVisible = true;
         const lines = renderDag(active.spec, active.state).split("\n");
         ctx.ui.setWidget("fleet", lines);
+        ctx.ui.notify("fleet widget visible; fleet canvas link: " + (await ensureCanvas(ctx)).url, "info");
         return;
       }
       if (cmd === "status" || cmd === "") {
-        ctx.ui.setWidget("fleet", buildWidgetLines(active.spec, active.state));
+        const server = await ensureCanvas(ctx);
+        ctx.ui.notify(`${await statusText(active)}\n\nfleet canvas: ${server.url}`, "info");
         return;
       }
       if (cmd === "clear") {
+        active.widgetVisible = false;
         ctx.ui.setWidget("fleet", []);
+        ctx.ui.notify("fleet widget hidden", "info");
         return;
       }
       if (cmd === "kill") {
-        const text = await killFleet(target ?? "");
+        const text = await killFleet(target ?? "", ctx.cwd);
         const severity = text.includes("kill") && !text.startsWith("unknown") && !text.includes("already") ? "warning" : "error";
         ctx.ui.notify(text, severity);
         return;
@@ -141,6 +155,33 @@ export function registerFleetCommand(pi: ExtensionAPI): void {
         ctx.ui.notify("fleet resumed", "info");
         return;
       }
+      if (cmd === "continue") {
+        if (active.running) {
+          ctx.ui.notify("fleet already running", "warning");
+          return;
+        }
+        await currentState(active);
+        if (active.state.status === "completed") {
+          ctx.ui.notify("fleet completed, nothing to continue", "warning");
+          return;
+        }
+        if (active.state.status === "paused") {
+          ctx.ui.notify("fleet is paused; use /fleet resume for paused loop fleets", "warning");
+          return;
+        }
+        if (active.state.status === "planned" && Object.values(active.state.nodes).every((n) => n.status === "pending")) {
+          ctx.ui.notify("fleet has not started; use /fleet launch", "warning");
+          return;
+        }
+        active.killSwitch.killed = false;
+        active.pauseSwitch.paused = false;
+        active.state = { ...active.state, status: "running", paused: false };
+        await writeState(active.fleetRoot, active.state);
+        await writeWorkerPrompts(active);
+        void startLoop(active, ctx, false, true);
+        ctx.ui.notify("fleet continue requested", "info");
+        return;
+      }
       if (cmd === "relaunch") {
         if (!target) {
           ctx.ui.notify("usage: /fleet relaunch <node_id> [model]", "warning");
@@ -175,10 +216,11 @@ export function registerFleetCommand(pi: ExtensionAPI): void {
           }
           const canonical = `${resolved.model.provider}/${resolved.model.id}`;
           active.spec.workers = active.spec.workers.map((w) => w.id === target ? { ...w, model: canonical } : w);
-          await writeFile(join(active.fleetRoot, "fleet.json"), `${JSON.stringify(active.spec, null, 2)}\n`, "utf-8");
+          await persistFleetJson(active);
         }
         active.state = resetForRelaunch(active.state, active.spec, target);
         await writeState(active.fleetRoot, active.state);
+        await writeWorkerPrompts(active);
         prepareRelaunch(active, target);
         void startLoop(active, ctx, false, true);
         ctx.ui.notify(`fleet relaunch requested for ${target}`, "info");
@@ -241,7 +283,7 @@ export function registerFleetCommand(pi: ExtensionAPI): void {
         if (r.ok) updateWidget(ctx, active);
         return;
       }
-      ctx.ui.notify("usage: /fleet viz | /fleet status | /fleet canvas [stop] | /fleet configure [show|set k v] | /fleet add <json> | /fleet edit <node_id>|config ... | /fleet clear | /fleet kill all|<node_id> | /fleet pause | /fleet resume | /fleet relaunch <node_id> [model]", "warning");
+      ctx.ui.notify("usage: /fleet viz | /fleet status | /fleet models | /fleet canvas [stop] | /fleet configure [show|set k v] | /fleet add <json> | /fleet edit <node_id>|config ... | /fleet clear | /fleet kill all|<node_id> | /fleet pause | /fleet resume | /fleet continue | /fleet relaunch <node_id> [model]", "warning");
     },
   });
 }

package/src/contracts.ts

@@ -4,53 +4,91 @@ import type { ContractCheck, ContractOutput, ContractResult, Verdict } from "./t
 
 export const VERDICT_RE = /^verdict:\s*(lgtm|iterate|escalate)\s*$/mi;
 
+// Leading metadata lines that a markdown file may place before its first heading.
+const MARKDOWN_METADATA_RE = /^(status|verdict):\s*(approved|needs-revision|escalate|lgtm|iterate)\s*$/i;
+
 function resolvePath(workerDir: string, repoCwd: string, p: string): string {
   if (isAbsolute(p)) return p;
   return p.startsWith("output/") ? join(workerDir, p) : join(repoCwd, p);
 }
 
+function firstLines(content: string, n = 5): string {
+  return content
+    .split("\n")
+    .slice(0, n)
+    .map((l) => l.trimEnd())
+    .join(" / ");
+}
+
 async function checkOne(workerDir: string, repoCwd: string, o: ContractOutput): Promise<ContractCheck> {
   const full = resolvePath(workerDir, repoCwd, o.path);
-  const fail = (error: string): ContractCheck => ({ path: o.path, kind: o.kind, required: o.required, ok: false, error });
+  const base: Omit<ContractCheck, "ok" | "error"> = { path: o.path, kind: o.kind, required: o.required, actualPath: full };
+  const fail = (error: string): ContractCheck => ({ ...base, ok: false, error });
   let content: string;
   try {
     const s = await stat(full);
     if (o.kind === "file-exists") {
       return s.size > 0
-        ? { path: o.path, kind: o.kind, required: o.required, ok: true }
+        ? { ...base, ok: true }
         : fail("empty file");
     }
     content = await readFile(full, "utf-8");
   } catch {
-    return fail("file not found");
+    return { path: o.path, kind: o.kind, required: o.required, ok: false, error: "file not found" };
   }
+
   switch (o.kind) {
     case "markdown": {
-      const first = content.split("\n").find((l) => l.trim().length > 0) ?? "";
-      return first.startsWith("#")
-        ? { path: o.path, kind: o.kind, required: o.required, ok: true }
-        : fail("no markdown heading");
+      const meaningful = content.split("\n").filter((l) => l.trim().length > 0);
+      const first10 = meaningful.slice(0, 10);
+      const heading = first10.find((l) => l.trim().startsWith("#"));
+      if (heading) {
+        return { ...base, ok: true };
+      }
+      // Check whether the only blocker was a leading metadata line like Status: ...
+      const metadataFirst = first10[0]?.match(MARKDOWN_METADATA_RE);
+      return { ...fail(metadataFirst ? "no markdown heading after leading metadata line" : "no markdown heading"), firstLines: firstLines(content) };
     }
     case "verdict": {
       const m = content.match(VERDICT_RE);
-      if (!m) return fail("no verdict line");
+      if (!m) return { ...base, ok: false, error: "no verdict line", firstLines: firstLines(content) };
       const body = content.slice(content.indexOf(m[0]) + m[0].length).trim();
       return body.length > 0
-        ? { path: o.path, kind: o.kind, required: o.required, ok: true }
-        : fail("verdict line without body");
+        ? { ...base, ok: true }
+        : { ...base, ok: false, error: "verdict line without body", firstLines: firstLines(content) };
     }
-    case "json":
+    case "json": {
+      let parsed: unknown;
       try {
-        JSON.parse(content);
-        return { path: o.path, kind: o.kind, required: o.required, ok: true };
+        parsed = JSON.parse(content);
       } catch (e) {
-        return fail(`json parse error: ${(e as Error).message}`);
+        return { ...base, ok: false, error: `json parse error: ${(e as Error).message}`, firstLines: firstLines(content) };
       }
+      if (o.schema) {
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+          return { ...base, ok: false, error: "json schema requires an object", firstLines: firstLines(content) };
+        }
+        const obj = parsed as Record<string, unknown>;
+        for (const key of o.schema.required_keys ?? []) {
+          if (!Object.hasOwn(obj, key)) {
+            return { ...base, ok: false, error: `missing required key "${key}"`, firstLines: firstLines(content) };
+          }
+        }
+        for (const key of o.schema.number_keys ?? []) {
+          const v = obj[key];
+          const ok = typeof v === "number" || (Array.isArray(v) && v.every((x) => typeof x === "number"));
+          if (!ok) {
+            return { ...base, ok: false, error: `key "${key}" must be a number or number[]`, firstLines: firstLines(content) };
+          }
+        }
+      }
+      return { ...base, ok: true };
+    }
     case "yaml": {
       const bad = content.split("\n").some((l) => l.includes("\t"));
       return content.trim().length > 0 && !bad
-        ? { path: o.path, kind: o.kind, required: o.required, ok: true }
-        : fail("empty or invalid yaml");
+        ? { ...base, ok: true }
+        : { ...base, ok: false, error: "empty or invalid yaml" };
     }
     default:
       return fail(`unknown kind`);
@@ -76,3 +114,17 @@ export async function verifyOutputs(opts: {
   const verdict_body = content.slice(content.indexOf(m[0]) + m[0].length).trim();
   return verdict_body.length > 0 ? { ok, checks, verdict, verdict_body } : { ok, checks };
 }
+
+/** Format a concise, actionable note for the first failed required contract. */
+export function contractFailureNote(checks: ContractCheck[]): string {
+  const failed = checks.find((c) => c.required && !c.ok);
+  if (!failed) return "contract failed";
+  const parts = [
+    `${failed.path}: ${failed.error}`,
+    `actual: ${failed.actualPath ?? "(not found)"}`,
+  ];
+  if (failed.firstLines) {
+    parts.push(`first lines: ${failed.firstLines}`);
+  }
+  return parts.join("; ");
+}

package/src/controller.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { writeWorkerPrompts } from "./fleet-store.js";
+import { recoverLatestFleet } from "./fleet-recovery.js";
 import { resolveModelReference, type ModelRegistryLike } from "./model-resolution.js";
 import { insertWorkers } from "./insert.js";
 import { writeReport } from "./report.js";
@@ -25,6 +26,7 @@ export interface ActiveFleet {
   costWarned?: boolean;
   sessions: Map<string, AgentSessionLike>;
   killedNodes: Set<string>;
+  widgetVisible?: boolean;
 }
 
 export interface ActiveFleetCell {
@@ -34,7 +36,7 @@ export interface ActiveFleetCell {
 export const activeFleet: ActiveFleetCell = { current: undefined };
 
 export function updateWidget(ctx: ExtensionContext, fleet: ActiveFleet, spinnerFrame?: number): void {
-  if (ctx.hasUI) ctx.ui.setWidget("fleet", buildWidgetLines(fleet.spec, fleet.state, { spinnerFrame }));
+  if (ctx.hasUI && fleet.widgetVisible) ctx.ui.setWidget("fleet", buildWidgetLines(fleet.spec, fleet.state, { spinnerFrame }));
 }
 
 export function startSpinner(ctx: ExtensionContext, fleet: ActiveFleet, intervalMs = 150): () => void {
@@ -60,7 +62,14 @@ export async function currentState(fleet: ActiveFleet): Promise<FleetState> {
 
 export async function statusText(fleet: ActiveFleet): Promise<string> {
   const state = await currentState(fleet);
-  return renderDag(fleet.spec, state);
+  const reportPath = join(fleet.fleetRoot, "report.md");
+  const failed = Object.entries(state.nodes).find(([, n]) => n.status === "failed" || n.status === "contract_failed");
+  const next = state.status === "planned" ? "next: fleet_launch"
+    : state.status === "running" ? "next: fleet_status, fleet_canvas, or fleet_kill <id>|all"
+    : failed ? `next: fleet_relaunch ${failed[0]}`
+    : state.status === "completed" ? `next: read report ${reportPath}`
+    : `next: inspect ${join(fleet.fleetRoot, "state.json")}`;
+  return `${renderDag(fleet.spec, state)}\n\nreport: ${reportPath}\n${next}`;
 }
 
 export async function dagPreview(spec: FleetSpec, state: FleetState | undefined, fleetRoot: string): Promise<string> {
@@ -166,12 +175,15 @@ export async function startLoop(fleet: ActiveFleet, ctx: ExtensionContext, resum
       const prompt = await readFile(join(fleet.fleetRoot, "workers", nodeId, "prompt.md"), "utf-8");
       const sessionDir = join(fleet.fleetRoot, "workers", nodeId);
       const effort = worker.effort ?? fleet.spec.config.effort ?? "medium";
+      const worktreeCwd = worker?.worktree || worker?.id === "fleet-integrator"
+        ? join(fleet.fleetRoot, "worktrees", nodeId)
+        : ctx.cwd;
       try {
         return await runWorker({
           nodeId,
           worker: workerWithResolvedModel(worker, resolvedModel),
           prompt,
-          repoCwd: ctx.cwd,
+          repoCwd: worktreeCwd,
           sessionDir,
           thinkingLevel: effort,
           sessionFactory: resolvedModel ? sessionFactoryForModel(resolvedModel) : undefined,
@@ -200,9 +212,12 @@ export async function startLoop(fleet: ActiveFleet, ctx: ExtensionContext, resum
     const state = await runFleet({
       spec: fleet.spec,
       fleetRoot: fleet.fleetRoot,
+      baseRepo: ctx.cwd,
       repoCwd: (nodeId) => {
         const worker = fleet.spec.workers.find((w) => w.id === nodeId);
-        return worker?.worktree ? join(fleet.fleetRoot, "worktrees", nodeId) : ctx.cwd;
+        return worker?.worktree || worker?.id === "fleet-integrator"
+          ? join(fleet.fleetRoot, "worktrees", nodeId)
+          : ctx.cwd;
       },
       spawn,
       killSwitch: fleet.killSwitch,
@@ -257,9 +272,21 @@ export async function startLoop(fleet: ActiveFleet, ctx: ExtensionContext, resum
   }
 }
 
-export async function killFleet(target: string): Promise<string> {
-  const active = activeFleet.current;
+export async function killFleet(target: string, cwd?: string): Promise<string> {
+  const active = activeFleet.current ?? (cwd ? await recoverLatestFleet(cwd) : undefined);
+  if (active) activeFleet.current ??= active;
   if (!active) return "no fleet planned yet";
+  if (!active.running) {
+    try {
+      active.state = await readState(active.fleetRoot);
+    } catch {
+      // keep in-memory state
+    }
+    if (active.state.status === "running") {
+      const where = target === "all" ? "fleet" : `node "${target}"`;
+      return `${where} not killed: fleet state on disk is "running" — it appears to be running in another live session; kill it there (this session holds no live scheduler, so a kill here would silently no-op)`;
+    }
+  }
   if (target === "all") {
     active.killSwitch.killed = true;
     return "fleet kill requested";

package/src/dag.ts

@@ -1,4 +1,4 @@
-import type { FleetSpec, GateKind, LoopConfig, OutputKind, ThinkingLevelName, WorkerSpec, WorkerType } from "./types.js";
+import type { ContractOutput, FleetSpec, GateKind, JsonOutputSchema, LoopConfig, OutputKind, ThinkingLevelName, WorkerSpec, WorkerType } from "./types.js";
 import { THINKING_LEVELS } from "./types.js";
 
 export class CycleError extends Error {
@@ -49,6 +49,46 @@ export function getDependents(spec: FleetSpec, nodeId: string): string[] {
   return spec.workers.filter((w) => w.depends_on.includes(nodeId)).map((w) => w.id);
 }
 
+export function findRepoOutputOwnershipConflicts(workers: WorkerSpec[]): string[] {
+  const claims = new Map<string, string[]>();
+  for (const w of workers) {
+    for (const o of w.outputs) {
+      if (!o.path.startsWith("output/")) {
+        const list = claims.get(o.path) ?? [];
+        list.push(w.id);
+        claims.set(o.path, list);
+      }
+    }
+  }
+  const errors: string[] = [];
+  const byId = new Map(workers.map((w) => [w.id, w]));
+  for (const [path, ids] of claims) {
+    if (ids.length < 2) continue;
+    for (let i = 0; i < ids.length; i++) {
+      for (let j = i + 1; j < ids.length; j++) {
+        const a = ids[i], b = ids[j];
+        const aBeforeB = byId.get(a)!.depends_on.includes(b);
+        const bBeforeA = byId.get(b)!.depends_on.includes(a);
+        if (!aBeforeB && !bBeforeA) {
+          errors.push(`repo output ownership conflict: "${path}" claimed by "${a}" and "${b}" without ordered handoff`);
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+function hasIntegratorPath(workers: WorkerSpec[]): boolean {
+  const worktreeIds = new Set(workers.filter((w) => w.worktree).map((w) => w.id));
+  if (worktreeIds.size < 2) return true;
+  return workers.some((w) => {
+    if (w.worktree) return false;
+    const deps = new Set(w.depends_on);
+    for (const id of worktreeIds) if (!deps.has(id)) return false;
+    return true;
+  });
+}
+
 export function validateFleetSpec(
   raw: unknown,
 ): { ok: true; spec: FleetSpec; layers: string[][] } | { ok: false; errors: string[] } {
@@ -91,6 +131,21 @@ export function validateFleetSpec(
           errors.push(`worker "${id}": output path must be relative and stay within the repo`);
         }
       }
+      if (o.schema !== undefined) {
+        if (o.kind !== "json") {
+          errors.push(`worker "${id}": output schema only allowed with kind "json"`);
+        } else if (typeof o.schema !== "object" || o.schema === null || Array.isArray(o.schema)) {
+          errors.push(`worker "${id}": output schema must be an object`);
+        } else {
+          const s = o.schema as Record<string, unknown>;
+          for (const name of ["required_keys", "number_keys"] as const) {
+            const keys = s[name];
+            if (keys !== undefined && (!Array.isArray(keys) || keys.some((k) => typeof k !== "string" || k.length === 0))) {
+              errors.push(`worker "${id}": schema.${name} must be an array of non-empty strings`);
+            }
+          }
+        }
+      }
     }
     const wEffort = typeof w.effort === "string" ? w.effort as ThinkingLevelName : undefined;
     if (wEffort !== undefined && !THINKING_LEVELS.includes(wEffort)) {
@@ -103,7 +158,18 @@ export function validateFleetSpec(
       model: typeof w.model === "string" ? w.model : undefined,
       effort: wEffort,
       depends_on: Array.isArray(w.depends_on) ? (w.depends_on as string[]) : [],
-      outputs: outputs.map((o) => ({ path: String(o.path), kind: o.kind as OutputKind, required: o.required !== false })),
+      outputs: outputs.map((o) => {
+        const out: ContractOutput = { path: String(o.path), kind: o.kind as OutputKind, required: o.required !== false };
+        const s = o.schema;
+        if (o.kind === "json" && typeof s === "object" && s !== null && !Array.isArray(s)) {
+          const rec = s as Record<string, unknown>;
+          const schema: JsonOutputSchema = {};
+          if (Array.isArray(rec.required_keys)) schema.required_keys = rec.required_keys as string[];
+          if (Array.isArray(rec.number_keys)) schema.number_keys = rec.number_keys as string[];
+          out.schema = schema;
+        }
+        return out;
+      }),
       iterate: w.iterate !== false,
       worktree: w.worktree === true,
     });
@@ -115,6 +181,23 @@ export function validateFleetSpec(
     }
   }
 
+  const worktreeIds = new Set(workers.filter((w) => w.worktree).map((w) => w.id));
+  if (worktreeIds.size >= 2) {
+    if (!workers.some((w) => w.id === "fleet-integrator")) {
+      workers.push({
+        id: "fleet-integrator",
+        type: "code-run",
+        task: `Merge worktree branches in order: ${[...worktreeIds].join(", ")}. Verify the combined repo is consistent and commit if needed.`,
+        depends_on: [...worktreeIds],
+        outputs: [],
+      });
+    }
+    if (!hasIntegratorPath(workers)) {
+      errors.push("multiple worktree workers require an integrator that depends on all worktree workers");
+    }
+  }
+  errors.push(...findRepoOutputOwnershipConflicts(workers));
+
   let loopConfig: LoopConfig | undefined;
   if (cfg.loop !== undefined && cfg.loop !== null) {
     if (typeof cfg.loop !== "object" || Array.isArray(cfg.loop)) {

package/src/edits.ts

@@ -1,10 +1,11 @@
 import { rename, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { ActiveFleet } from "./controller.js";
+import { persistFleetJson } from "./fleet-store.js";
 import { resolveModelReference, type ModelRegistryLike } from "./model-resolution.js";
 import { buildWorkerPrompt } from "./prompts.js";
+import type { NodeStatus, ThinkingLevelName } from "./types.js";
 import { THINKING_LEVELS } from "./types.js";
-import type { ThinkingLevelName } from "./types.js";
 
 export type NodeEditKey = "model" | "effort" | "task";
 export type ConfigEditKey = "max_concurrent" | "warn_cost_usd" | "model" | "effort";
@@ -14,9 +15,7 @@ export interface EditResult {
   message: string;
 }
 
-async function persistSpec(fleet: ActiveFleet): Promise<void> {
-  await writeFile(join(fleet.fleetRoot, "fleet.json"), `${JSON.stringify(fleet.spec, null, 2)}\n`, "utf-8");
-}
+const EDITABLE_NODE_STATUSES: ReadonlySet<NodeStatus> = new Set(["pending", "ready", "failed", "contract_failed", "killed"]);
 
 export async function editNode(
   fleet: ActiveFleet,
@@ -28,9 +27,9 @@ export async function editNode(
   const worker = fleet.spec.workers.find((w) => w.id === nodeId);
   const node = fleet.state.nodes[nodeId];
   if (!worker || !node) return { ok: false, message: `unknown node "${nodeId}"` };
-  if (node.status !== "pending" && node.status !== "ready") {
-    return { ok: false, message: `node "${nodeId}" is ${node.status}; only pending nodes can be edited` };
-  }
+  if (!EDITABLE_NODE_STATUSES.has(node.status)) {
+      return { ok: false, message: `node "${nodeId}" is ${node.status}; only pending, failed, contract_failed, or killed nodes can be edited` };
+    }
   switch (key) {
     case "model": {
       const r = resolveModelReference(registry, value);
@@ -63,7 +62,7 @@ export async function editNode(
     default:
       return { ok: false, message: `unknown node edit key "${String(key)}" (keys: model, effort, task)` };
   }
-  await persistSpec(fleet);
+  await persistFleetJson(fleet);
   return { ok: true, message: `node "${nodeId}" ${key} updated` };
 }
 
@@ -102,6 +101,6 @@ export async function editConfig(
     default:
       return { ok: false, message: `unknown config key "${String(key)}" (keys: max_concurrent, warn_cost_usd, model, effort)` };
   }
-  await persistSpec(fleet);
+  await persistFleetJson(fleet);
   return { ok: true, message: `config.${key} updated` };
 }

package/src/fleet-recovery.ts

@@ -0,0 +1,73 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { ActiveFleet } from "./controller.js";
+import { readState } from "./state.js";
+import type { FleetSpec, FleetState } from "./types.js";
+
+export interface FleetRootInfo {
+  name: string;
+  root: string;
+  status: string;
+  created_at: string;
+}
+
+export async function readDiskFleet(fleetRoot: string): Promise<ActiveFleet> {
+  const spec = JSON.parse(await readFile(join(fleetRoot, "fleet.json"), "utf-8")) as FleetSpec;
+  const state = await readState(fleetRoot);
+  return {
+    spec,
+    fleetRoot,
+    state,
+    killSwitch: { killed: false },
+    pauseSwitch: { paused: false },
+    running: false,
+    sessions: new Map(),
+    killedNodes: new Set(),
+  };
+}
+
+export async function listFleetRoots(cwd: string): Promise<FleetRootInfo[]> {
+  const base = join(cwd, ".fleet");
+  let entries: string[];
+  try {
+    entries = await readdir(base);
+  } catch {
+    return [];
+  }
+  const out: FleetRootInfo[] = [];
+  for (const name of entries) {
+    const root = join(base, name);
+    try {
+      const s = await stat(join(root, "fleet.json"));
+      if (!s.isFile()) continue;
+      const state = JSON.parse(await readFile(join(root, "state.json"), "utf-8")) as Partial<FleetState>;
+      out.push({
+        name,
+        root,
+        status: typeof state.status === "string" ? state.status : "unknown",
+        created_at: typeof state.created_at === "string" ? state.created_at : new Date(s.mtimeMs).toISOString(),
+      });
+    } catch {
+      // not a fleet root (no fleet.json) or unreadable state — skip or mark unknown
+      try {
+        await stat(join(root, "fleet.json"));
+        out.push({ name, root, status: "unknown", created_at: "" });
+      } catch {
+        // not a fleet root
+      }
+    }
+  }
+  out.sort((a, b) => b.created_at.localeCompare(a.created_at));
+  return out;
+}
+
+export async function recoverLatestFleet(cwd: string): Promise<ActiveFleet | undefined> {
+  const roots = await listFleetRoots(cwd);
+  const latest = roots.find((r) => r.status !== "unknown") ?? roots[0];
+  if (!latest) return undefined;
+  try {
+    return await readDiskFleet(latest.root);
+  } catch {
+    return undefined;
+  }
+}

package/src/fleet-store.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { buildWorkerPrompt } from "./prompts.js";
 import { writeState } from "./state.js";
@@ -47,9 +47,18 @@ export async function writePlanFiles(fleetRoot: string, spec: FleetSpec, state:
   await writeState(fleetRoot, state);
 }
 
+export async function persistFleetJson(fleet: { fleetRoot: string; spec: FleetSpec }): 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);
+}
+
 export async function writeWorkerPrompts(fleet: { spec: FleetSpec; state: FleetState; fleetRoot: string }): Promise<void> {
   await Promise.all(fleet.spec.workers.map(async (w) => {
+    const dir = join(fleet.fleetRoot, "workers", w.id);
+    await mkdir(dir, { recursive: true });
     const prompt = buildWorkerPrompt({ spec: fleet.spec, state: fleet.state, workerId: w.id, fleetRoot: fleet.fleetRoot });
-    await writeFile(join(fleet.fleetRoot, "workers", w.id, "prompt.md"), prompt, "utf-8");
+    await writeFile(join(dir, "prompt.md"), prompt, "utf-8");
   }));
 }

package/src/insert.ts

@@ -1,7 +1,8 @@
-import { mkdir, rename, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { ActiveFleet } from "./controller.js";
 import { validateFleetSpec } from "./dag.js";
+import { persistFleetJson } from "./fleet-store.js";
 import { resolveModelReference, type ModelRegistryLike } from "./model-resolution.js";
 import { buildWorkerPrompt } from "./prompts.js";
 import { writeState } from "./state.js";
@@ -12,13 +13,6 @@ export interface InsertResult {
   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,