pi-agent-fleet 0.3.0 → 0.5.0

package/src/model-resolution.ts

@@ -16,6 +16,32 @@ export function aliasesFor(model: Model<Api>): string[] {
   ];
 }
 
+export function canonicalModelRef(model: Model<Api>): string {
+  return `${model.provider}/${model.id}`;
+}
+
+export function listModelRefs(registry: ModelRegistryLike, limit = 40): string[] {
+  const models = registry.getAvailable().length > 0 ? registry.getAvailable() : registry.getAll();
+  return [...new Map(models.map((m) => [canonicalModelRef(m), m])).keys()].slice(0, limit);
+}
+
+export function suggestModelRefs(registry: ModelRegistryLike, ref: string, limit = 8): string[] {
+  const needle = ref.toLowerCase();
+  return listModelRefs(registry, 200)
+    .filter((r) => r.toLowerCase().includes(needle) || needle.split(/[/-]/).some((p) => p.length > 2 && r.toLowerCase().includes(p)))
+    .slice(0, limit);
+}
+
+export function formatModelError(registry: ModelRegistryLike, label: string, ref: string, error: string): string {
+  const suggestions = suggestModelRefs(registry, ref);
+  const available = listModelRefs(registry);
+  return [
+    `${label}: ${error}`,
+    suggestions.length > 0 ? `suggestions: ${suggestions.join(", ")}` : undefined,
+    `available models: ${available.join(", ")}`,
+  ].filter(Boolean).join("\n");
+}
+
 export function resolveModelReference(
   registry: ModelRegistryLike,
   ref: string,
@@ -36,7 +62,6 @@ export function resolveModelReference(
   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()];
@@ -67,7 +92,7 @@ export function validateFleetModels(
     if (seen.has(key)) continue;
     seen.add(key);
     const r = resolveModelReference(registry, ref);
-    if (!r.ok) errors.push(`${label}: ${r.error}`);
+    if (!r.ok) errors.push(formatModelError(registry, label, ref, r.error));
   }
   return errors.length > 0 ? { ok: false, errors } : { ok: true };
 }

package/src/preferences.ts

@@ -1,6 +1,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { canonicalModelRef, formatModelError, resolveModelReference } from "./model-resolution.js";
+import type { ModelRegistryLike } from "./model-resolution.js";
 import { THINKING_LEVELS } from "./types.js";
 import type { ThinkingLevelName } from "./types.js";
 
@@ -59,6 +61,7 @@ export function mergeFleetConfig(raw: unknown, prefs: FleetPreferences): unknown
 export function validatePreferenceValue(
   key: string,
   value: string,
+  registry?: ModelRegistryLike,
 ): { ok: true; parsed: number | string } | { ok: false; error: string } {
   switch (key) {
     case "max_concurrent": {
@@ -79,6 +82,11 @@ export function validatePreferenceValue(
     }
     case "model": {
       if (value.trim().length === 0) return { ok: false, error: "model must be non-empty" };
+      if (registry) {
+        const r = resolveModelReference(registry, value.trim());
+        if (!r.ok) return { ok: false, error: formatModelError(registry, "preference model", value.trim(), r.error) };
+        return { ok: true, parsed: canonicalModelRef(r.model) };
+      }
       return { ok: true, parsed: value.trim() };
     }
     default:
@@ -90,8 +98,9 @@ export function setPreference(
   prefs: FleetPreferences,
   key: string,
   value: string,
+  registry?: ModelRegistryLike,
 ): { ok: true; prefs: FleetPreferences } | { ok: false; error: string } {
-  const v = validatePreferenceValue(key, value);
+  const v = validatePreferenceValue(key, value, registry);
   if (!v.ok) return v;
   return { ok: true, prefs: { ...prefs, [key]: v.parsed } };
 }

package/src/prompts.ts

@@ -100,6 +100,16 @@ export function buildWorkerPrompt(opts: {
   } else {
     for (const o of worker.outputs) {
       out.push(`- ${o.path} (${o.kind}${o.required ? ", REQUIRED" : ", optional"})`);
+      if (o.kind === "json" && o.schema) {
+        const bits: string[] = [];
+        if (o.schema.required_keys && o.schema.required_keys.length > 0) {
+          bits.push(`must be a JSON object containing keys: ${o.schema.required_keys.join(", ")}`);
+        }
+        if (o.schema.number_keys && o.schema.number_keys.length > 0) {
+          bits.push(`these keys must be numbers or arrays of numbers: ${o.schema.number_keys.join(", ")}`);
+        }
+        if (bits.length > 0) out.push(`  - ${bits.join("; ")}`);
+      }
     }
     out.push("");
   }

package/src/report.ts

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { promisify } from "node:util";
 import type { FleetSpec, FleetState } from "./types.js";
@@ -72,6 +72,33 @@ export async function writeReport(opts: {
       if (w.worktree) lines.push(`- fleet/${base}/${w.id}`);
     }
   }
+  lines.push("", "## Next steps", "");
+  const reportPath = join(fleetRoot, "report.md");
+  const failed = Object.entries(state.nodes).find(([, n]) => n.status === "failed" || n.status === "contract_failed");
+  const next = state.status === "planned" ? "fleet_launch"
+    : state.status === "running" ? "fleet_status, fleet_canvas, or fleet_kill <id>|all"
+    : failed ? `fleet_relaunch ${failed[0]}`
+    : state.status === "completed" ? `read report ${reportPath}`
+    : `inspect ${join(fleetRoot, "state.json")}`;
+  lines.push(`- next: ${next}`);
+  lines.push("", "## JSON outputs", "");
+  let anyJson = false;
+  for (const w of spec.workers) {
+    const n = state.nodes[w.id];
+    for (const out of n?.produced_outputs ?? []) {
+      if (!out.startsWith("output/") || !out.endsWith(".json") || out.includes("..")) continue;
+      anyJson = true;
+      let content: string;
+      try {
+        const raw = await readFile(join(fleetRoot, "workers", w.id, out), "utf-8");
+        content = raw.length > 4096 ? `${raw.slice(0, 4096)}\n... (truncated)` : raw;
+      } catch {
+        content = "(unreadable)";
+      }
+      lines.push(`### ${w.id}: ${out}`, "", "```json", content.trimEnd(), "```", "");
+    }
+  }
+  if (!anyJson) lines.push("(none)", "");
   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")}`, "");

package/src/scheduler.ts

@@ -1,15 +1,17 @@
 import { mkdir, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { verifyOutputs } from "./contracts.js";
+import { contractFailureNote, 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, WorkerSpec } from "./types.js";
+import { commitWorktree, createWorktree, prepareIntegratorWorktree } from "./worktree.js";
 
 export type SpawnFn = (nodeId: string) => Promise<{ ok: boolean; turns: number; tokens: number; cost?: number; error?: string }>;
 
 export interface RunFleetOpts {
   spec: FleetSpec;
   fleetRoot: string;
+  baseRepo?: string;
   repoCwd: string | ((nodeId: string) => string);
   spawn: SpawnFn;
   onNodeChange?: (nodeId: string, s: NodeState) => void;
@@ -72,6 +74,41 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
   const repoCwdFor = (nodeId: string): string =>
     typeof opts.repoCwd === "function" ? opts.repoCwd(nodeId) : opts.repoCwd;
 
+  const baseRepo = (): string | undefined =>
+    opts.baseRepo ?? (typeof opts.repoCwd === "string" ? opts.repoCwd : undefined);
+
+  function orderedWorktreeBranches(spec: FleetSpec): string[] {
+    const ids = spec.workers.filter((w) => w.worktree).map((w) => w.id);
+    const set = new Set(ids);
+    const indeg = new Map(ids.map((id) => [id, 0]));
+    const rev = new Map(ids.map((id) => [id, [] as string[]]));
+    for (const w of spec.workers) {
+      if (!set.has(w.id)) continue;
+      for (const d of w.depends_on) {
+        if (set.has(d)) {
+          indeg.set(w.id, (indeg.get(w.id) ?? 0) + 1);
+          rev.get(d)?.push(w.id);
+        }
+      }
+    }
+    const sorted: string[] = [];
+    let current = ids.filter((id) => indeg.get(id) === 0);
+    while (current.length > 0) {
+      sorted.push(...current);
+      const next: string[] = [];
+      for (const id of current) {
+        for (const m of rev.get(id) ?? []) {
+          const v = (indeg.get(m) ?? 0) - 1;
+          indeg.set(m, v);
+          if (v === 0) next.push(m);
+        }
+      }
+      current = next;
+    }
+    if (sorted.length !== ids.length) sorted.push(...ids.filter((id) => !sorted.includes(id)));
+    return sorted.map((id) => `fleet/${spec.fleet_name}/${id}`);
+  }
+
   const runPass = async (): Promise<void> => {
     while (true) {
       // auto-initialize workers inserted into the spec after the run started
@@ -122,6 +159,61 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
         const depsDone = w.depends_on.every((d) => state.nodes[d]?.status === "completed");
         if (!depsDone) continue;
         slots--;
+
+        if (w.worktree) {
+          const repo = baseRepo();
+          if (!repo) {
+            await patch(w.id, {
+              status: "failed",
+              ended_at: new Date().toISOString(),
+              status_note: "worktree worker requires a baseRepo",
+            });
+            continue;
+          }
+          try {
+            await createWorktree({
+              baseRepo: repo,
+              fleetName: spec.fleet_name,
+              nodeId: w.id,
+              fleetRoot,
+            });
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            await patch(w.id, {
+              status: "failed",
+              ended_at: new Date().toISOString(),
+              status_note: `worktree creation failed: ${msg}`,
+            });
+            continue;
+          }
+        }
+
+        if (w.id === "fleet-integrator") {
+          const repo = baseRepo();
+          if (!repo) {
+            await patch(w.id, {
+              status: "failed",
+              ended_at: new Date().toISOString(),
+              status_note: "integrator requires a baseRepo",
+            });
+            continue;
+          }
+          const prep = await prepareIntegratorWorktree({
+            baseRepo: repo,
+            fleetName: spec.fleet_name,
+            fleetRoot,
+            branches: orderedWorktreeBranches(spec),
+          });
+          if (!prep.ok) {
+            await patch(w.id, {
+              status: "failed",
+              ended_at: new Date().toISOString(),
+              status_note: prep.conflict,
+            });
+            continue;
+          }
+        }
+
         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;
@@ -133,6 +225,27 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
             await patch(w.id, { status: "failed", ended_at: new Date().toISOString(), turns: res.turns, tokens: res.tokens, cost_usd_estimate: res.cost ?? 0 });
             return;
           }
+          if (w.worktree) {
+            try {
+              await commitWorktree({
+                worktreePath: repoCwdFor(w.id),
+                nodeId: w.id,
+                fleetName: spec.fleet_name,
+                iteration: state.iteration,
+              });
+            } catch (e) {
+              const msg = e instanceof Error ? e.message : String(e);
+              await patch(w.id, {
+                status: "failed",
+                ended_at: new Date().toISOString(),
+                turns: res.turns,
+                tokens: res.tokens,
+                cost_usd_estimate: res.cost ?? 0,
+                status_note: `commit failed: ${msg}`,
+              });
+              return;
+            }
+          }
           const contract = await verifyOutputs({
             workerDir: `${fleetRoot}/workers/${w.id}`,
             repoCwd: repoCwdFor(w.id),
@@ -145,7 +258,8 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
             tokens: res.tokens,
             cost_usd_estimate: res.cost ?? 0,
             contract_result: contract,
-            produced_outputs: contract.checks.filter((c) => c.ok).map((c) => c.path),
+            produced_outputs: contract.checks.filter((c) => c.ok || c.actualPath).map((c) => c.path),
+            status_note: contract.ok ? undefined : contractFailureNote(contract.checks),
           });
           if (contract.ok) {
             const note = await opts.onNodeCompleted?.(w.id);

package/src/tools.ts

@@ -1,4 +1,3 @@
-import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -8,8 +7,9 @@ import { loadPreferences, mergeFleetConfig } from "./preferences.js";
 import { activeFleet, currentState, dagPreview, ensureCanvas, killFleet, prepareRelaunch, startLoop, statusText, stopCanvas, updateWidget } from "./controller.js";
 import { openInBrowser, listFleetRoots } from "./canvas.js";
 import { editConfig, editNode, type ConfigEditKey, type NodeEditKey } from "./edits.js";
-import { ensureFleetGitignore, fleetRootFor, isInsideGitRepo, writePlanFiles, writeWorkerPrompts } from "./fleet-store.js";
-import { resolveModelReference, validateFleetModels } from "./model-resolution.js";
+import { ensureFleetGitignore, fleetRootFor, isInsideGitRepo, persistFleetJson, writePlanFiles, writeWorkerPrompts } from "./fleet-store.js";
+import { recoverLatestFleet } from "./fleet-recovery.js";
+import { listModelRefs, resolveModelReference, validateFleetModels } from "./model-resolution.js";
 import { runFleetDesign, slugifyFleetName } from "./planner.js";
 import { writeReport } from "./report.js";
 import { initFleetState, resetForRelaunch, writeState } from "./state.js";
@@ -27,6 +27,10 @@ export function registerFleetTools(pi: ExtensionAPI): void {
       Type.Literal("verdict"), Type.Literal("json"), Type.Literal("yaml"),
     ]),
     required: Type.Optional(Type.Boolean()),
+    schema: Type.Optional(Type.Object({
+      required_keys: Type.Optional(Type.Array(Type.String(), { description: "JSON object keys that must be present" })),
+      number_keys: Type.Optional(Type.Array(Type.String(), { description: "JSON object keys that must be numbers or arrays of numbers" })),
+    }, { description: "Optional JSON object shape; only valid with kind json" })),
   });
   const EffortSchema = Type.Union([
     Type.Literal("off"), Type.Literal("minimal"), Type.Literal("low"),
@@ -67,7 +71,7 @@ export function registerFleetTools(pi: ExtensionAPI): void {
     name: "fleet_plan",
     label: "Fleet Plan",
     description:
-      "Validate a fleet DAG definition, create its fleet root, and return an ASCII preview. Does NOT launch. PREREQUISITE: if the user's request is prose requirements or a goal rather than an explicit fleet definition, you MUST call fleet_design first and pass its drafted definition here — do not hand-write the fleet JSON yourself. Present the preview to the user; call fleet_launch only after they explicitly confirm. Choose models by task difficulty: cheap/fast models for trivial writers and validators, mid-tier coding models for code-run workers, strongest reasoning models for reviewers and synthesizers. When several models fit a tier, vary providers across nodes instead of defaulting to one family. Set worker.model per node to override config.model. All model refs are validated against the live registry — planning fails if any model is unavailable.",
+      "Validate a fleet DAG definition, create its fleet root, and return an ASCII preview. Does NOT launch. PREREQUISITE: if the user's request is prose requirements or a goal rather than an explicit fleet definition, you MUST call fleet_design first and pass its drafted definition here — do not hand-write the fleet JSON yourself. Present the preview to the user; call fleet_launch only after they explicitly confirm. Choose models by task difficulty: cheap/fast models for trivial writers and validators, mid-tier coding models for code-run workers, strongest reasoning models for reviewers and synthesizers. When several models fit a tier, vary providers across nodes instead of defaulting to one family. Set worker.model per node to override config.model. All model refs are validated against the live registry — planning fails if any model is unavailable. Call fleet_models first if you do not know exact provider/model IDs.",
     promptSnippet: "Plan a DAG-of-agents fleet from a fleet definition without launching it.",
     parameters: Type.Object({
       fleet: FleetSchema,
@@ -84,11 +88,12 @@ export function registerFleetTools(pi: ExtensionAPI): void {
       const state = initFleetState(v.spec);
       await ensureFleetGitignore(ctx.cwd);
       await writePlanFiles(fleetRoot, v.spec, state);
-      const active = activeFleet.current = { spec: v.spec, fleetRoot, state, killSwitch: { killed: false }, pauseSwitch: { paused: false }, running: false, costWarned: false, sessions: new Map(), killedNodes: new Set() };
+      const active = activeFleet.current = { spec: v.spec, fleetRoot, state, killSwitch: { killed: false }, pauseSwitch: { paused: false }, running: false, costWarned: false, sessions: new Map(), killedNodes: new Set(), widgetVisible: false };
       updateWidget(ctx, active);
 
       const dag = await dagPreview(v.spec, undefined, fleetRoot);
-      return textResult(`${dag}\n\nfleet root: ${fleetRoot}\nShow this preview to the user. Call fleet_launch only after they explicitly confirm.`, { fleetRoot, layers: v.layers });
+      const canvas = ctx.hasUI ? await ensureCanvas(ctx) : undefined;
+      return textResult(`${dag}\n\nfleet root: ${fleetRoot}${canvas ? `\nfleet canvas: ${canvas.url}` : ""}\n\nShow this preview to the user. Call fleet_launch only after they explicitly confirm.`, { fleetRoot, layers: v.layers, canvasUrl: canvas?.url });
     },
   });
 
@@ -117,14 +122,32 @@ export function registerFleetTools(pi: ExtensionAPI): void {
         }
       }
 
+      if (fleet.state.status !== "planned" || Object.values(fleet.state.nodes).some((n) => n.status !== "pending")) {
+        return textResult(
+          `fleet already started (${fleet.state.status}); use fleet_continue to resume pending work, fleet_relaunch <node_id> to retry a failed node, or start a new fleet with fleet_plan`,
+        );
+      }
+
       if (ctx.hasUI && !params.skip_confirm) {
         const ok = await ctx.ui.confirm("Launch fleet?", renderDag(fleet.spec));
         if (!ok) return textResult("fleet launch aborted");
       }
 
       await writeWorkerPrompts(fleet);
+      const canvas = ctx.hasUI ? await ensureCanvas(ctx) : undefined;
       void startLoop(fleet, ctx, false);
-      return textResult("fleet launched");
+      return textResult(`fleet launched${canvas ? `\n\nfleet canvas: ${canvas.url}` : ""}`, { canvasUrl: canvas?.url });
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_models",
+    label: "Fleet Models",
+    description: "List available model refs (provider/id) from the live registry. Call this before fleet_plan if you do not know exact provider/model IDs.",
+    promptSnippet: "List available fleet model refs.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      return textResult(`available models:\n${listModelRefs(ctx.modelRegistry).join("\n")}`);
     },
   });
 
@@ -134,8 +157,9 @@ export function registerFleetTools(pi: ExtensionAPI): void {
     description: "Show the current active fleet DAG and live widget lines.",
     promptSnippet: "Show current active fleet status.",
     parameters: Type.Object({}),
-    async execute() {
-      const active = activeFleet.current;
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const active = activeFleet.current ?? await recoverLatestFleet(ctx.cwd);
+      if (active) activeFleet.current ??= active;
       if (!active) return textResult("no fleet planned yet");
       return textResult(await statusText(active));
     },
@@ -147,8 +171,8 @@ export function registerFleetTools(pi: ExtensionAPI): void {
     description: "Request a fleet-wide kill (target \"all\") or kill a single node by worker id. Killing a running node aborts its session; killing a pending node marks it killed at the next dispatch pass. Killed nodes can be revived with fleet_relaunch.",
     promptSnippet: "Kill the whole fleet or a single node by worker id.",
     parameters: Type.Object({ target: Type.String({ description: "all or a worker id" }) }),
-    async execute(_id, params) {
-      return textResult(await killFleet(params.target));
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return textResult(await killFleet(params.target, ctx.cwd));
     },
   });
 
@@ -188,6 +212,33 @@ export function registerFleetTools(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: "fleet_continue",
+    label: "Fleet Continue",
+    description: "Continue the active fleet from its current state without restarting completed nodes. Dispatches pending and ready nodes and unblocks downstream as dependencies complete. Use this after a failed/killed fleet to resume work safely.",
+    promptSnippet: "Continue the active fleet from current state.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const active = activeFleet.current ?? await recoverLatestFleet(ctx.cwd);
+      if (active) activeFleet.current ??= active;
+      if (!active) return textResult("no fleet planned yet");
+      if (active.running) return textResult("fleet already running");
+      await currentState(active);
+      if (active.state.status === "completed") return textResult("fleet completed, nothing to continue");
+      if (active.state.status === "paused") return textResult("fleet is paused; use fleet_resume for paused loop fleets");
+      if (active.state.status === "planned" && Object.values(active.state.nodes).every((n) => n.status === "pending")) {
+        return textResult("fleet has not started; use fleet_launch");
+      }
+      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);
+      return textResult("fleet continue requested");
+    },
+  });
+
   pi.registerTool({
     name: "fleet_relaunch",
     label: "Fleet Relaunch",
@@ -216,10 +267,11 @@ export function registerFleetTools(pi: ExtensionAPI): void {
         if (!resolved.ok) return textResult(resolved.error);
         const canonical = `${resolved.model.provider}/${resolved.model.id}`;
         fleet.spec.workers = fleet.spec.workers.map((w) => w.id === params.node_id ? { ...w, model: canonical } : w);
-        await writeFile(join(fleet.fleetRoot, "fleet.json"), `${JSON.stringify(fleet.spec, null, 2)}\n`, "utf-8");
+        await persistFleetJson(fleet);
       }
       fleet.state = resetForRelaunch(fleet.state, fleet.spec, params.node_id);
       await writeState(fleet.fleetRoot, fleet.state);
+      await writeWorkerPrompts(fleet);
       prepareRelaunch(fleet, params.node_id);
       void startLoop(fleet, ctx, false, true);
       return textResult(`fleet relaunch requested for ${params.node_id}`);
@@ -289,7 +341,8 @@ export function registerFleetTools(pi: ExtensionAPI): void {
     promptSnippet: "Regenerate the active fleet report.",
     parameters: Type.Object({}),
     async execute(_id, _params, _signal, _onUpdate, ctx) {
-      const active = activeFleet.current;
+      const active = activeFleet.current ?? await recoverLatestFleet(ctx.cwd);
+      if (active) activeFleet.current ??= active;
       if (!active) return textResult("no fleet planned yet");
       const state = await currentState(active);
       const report = await writeReport({ spec: active.spec, state, fleetRoot: active.fleetRoot, repoCwd: ctx.cwd });
@@ -300,7 +353,7 @@ export function registerFleetTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "fleet_edit",
     label: "Fleet Edit",
-    description: "Edit the active fleet: a pending node's model, effort, or task — or fleet config (max_concurrent, warn_cost_usd, model, effort) when node_id is omitted. Changes persist to fleet.json and apply to nodes not yet dispatched. Refuses edits to nodes already running or terminal.",
+    description: "Edit the active fleet: a pending or relaunchable node's model, effort, or task — or fleet config (max_concurrent, warn_cost_usd, model, effort) when node_id is omitted. Changes persist to fleet.json and apply immediately. Edits to running, completed, or blocked nodes are refused; failed, contract_failed, and killed nodes can be edited so relaunch uses the updated task.",
     promptSnippet: "Edit a pending fleet node or fleet config.",
     parameters: Type.Object({
       node_id: Type.Optional(Type.String({ description: "Worker id to edit; omit for fleet config edits" })),

package/src/types.ts

@@ -1,9 +1,15 @@
 export type OutputKind = "markdown" | "file-exists" | "verdict" | "json" | "yaml";
 
+export interface JsonOutputSchema {
+  required_keys?: string[];
+  number_keys?: string[];
+}
+
 export interface ContractOutput {
   path: string;
   kind: OutputKind;
   required: boolean;
+  schema?: JsonOutputSchema;
 }
 
 export type WorkerType = "research" | "code-run" | "reviewer" | "write" | "read-only";
@@ -64,6 +70,8 @@ export interface ContractCheck {
   required: boolean;
   ok: boolean;
   error?: string;
+  actualPath?: string;
+  firstLines?: string;
 }
 
 export interface ContractResult {

package/src/worktree.ts

@@ -0,0 +1,81 @@
+import { execFile } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+export interface CreateWorktreeOpts {
+  baseRepo: string;
+  fleetName: string;
+  nodeId: string;
+  fleetRoot: string;
+}
+
+export async function createWorktree(opts: CreateWorktreeOpts): Promise<string> {
+  const path = join(opts.fleetRoot, "worktrees", opts.nodeId);
+  const branch = `fleet/${opts.fleetName}/${opts.nodeId}`;
+  await mkdir(path, { recursive: true });
+  await removeWorktree(path, opts.baseRepo);
+  await removeBranch(opts.baseRepo, branch);
+  await execFileP("git", ["worktree", "add", "-b", branch, path], { cwd: opts.baseRepo });
+  return path;
+}
+
+export interface CommitWorktreeOpts {
+  worktreePath: string;
+  nodeId: string;
+  fleetName: string;
+  iteration: number;
+}
+
+export async function commitWorktree(opts: CommitWorktreeOpts): Promise<void> {
+  await execFileP("git", ["add", "-A"], { cwd: opts.worktreePath });
+  try {
+    await execFileP(
+      "git",
+      ["commit", "-m", `fleet: ${opts.fleetName} ${opts.nodeId} iteration ${opts.iteration}`],
+      { cwd: opts.worktreePath },
+    );
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (msg.includes("nothing to commit")) return;
+    throw e;
+  }
+}
+
+export interface PrepareIntegratorOpts {
+  baseRepo: string;
+  fleetName: string;
+  fleetRoot: string;
+  branches: string[];
+}
+
+export async function prepareIntegratorWorktree(
+  opts: PrepareIntegratorOpts,
+): Promise<{ path: string; ok: boolean; conflict?: string }> {
+  const path = join(opts.fleetRoot, "worktrees", "fleet-integrator");
+  await removeWorktree(path, opts.baseRepo);
+  await removeBranch(opts.baseRepo, `fleet/${opts.fleetName}/fleet-integrator`);
+  await mkdir(path, { recursive: true });
+  await execFileP("git", ["worktree", "add", "-b", `fleet/${opts.fleetName}/fleet-integrator`, path], {
+    cwd: opts.baseRepo,
+  });
+  for (const branch of opts.branches) {
+    try {
+      await execFileP("git", ["merge", "--no-ff", "--no-edit", branch], { cwd: path });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { path, ok: false, conflict: `merge ${branch} failed: ${msg}` };
+    }
+  }
+  return { path, ok: true };
+}
+
+export async function removeWorktree(path: string, baseRepo: string): Promise<void> {
+  await execFileP("git", ["worktree", "remove", "--force", path], { cwd: baseRepo }).catch(() => {});
+}
+
+export async function removeBranch(baseRepo: string, branch: string): Promise<void> {
+  await execFileP("git", ["branch", "-D", branch], { cwd: baseRepo }).catch(() => {});
+}