pi-agent-fleet 0.4.0 → 0.6.0

package/src/contracts.ts

@@ -4,53 +4,94 @@ 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);
 }
 
-async function checkOne(workerDir: string, repoCwd: string, o: ContractOutput): Promise<ContractCheck> {
+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, notBeforeMs?: number): 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 }
-        : fail("empty file");
+      if (s.size === 0) return fail("empty file");
+      const repoRelative = !isAbsolute(o.path) && !o.path.startsWith("output/");
+      if (repoRelative && notBeforeMs !== undefined && s.mtimeMs < notBeforeMs) {
+        return fail("pre-existing repo file not modified since worker start");
+      }
+      return { ...base, ok: true };
     }
     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`);
@@ -61,8 +102,9 @@ export async function verifyOutputs(opts: {
   workerDir: string;
   repoCwd: string;
   outputs: ContractOutput[];
+  notBeforeMs?: number;
 }): Promise<ContractResult> {
-  const checks = await Promise.all(opts.outputs.map((o) => checkOne(opts.workerDir, opts.repoCwd, o)));
+  const checks = await Promise.all(opts.outputs.map((o) => checkOne(opts.workerDir, opts.repoCwd, o, opts.notBeforeMs)));
   const ok = checks.every((c) => !c.required || c.ok);
 
   const verdictCheck = checks.find((c) => c.kind === "verdict" && c.ok);
@@ -76,3 +118,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

@@ -2,13 +2,14 @@ import { readFile, writeFile } from "node:fs/promises";
 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 { persistFleetJson, 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";
 import { runWorker, sessionFactoryForModel, workerWithResolvedModel, type AgentSessionLike } from "./runner.js";
 import { runFleet } from "./scheduler.js";
-import { patchNode, readState, writeState } from "./state.js";
+import { patchNode, readState, resetForRelaunch, writeState } from "./state.js";
 import type { FleetSpec, FleetState } from "./types.js";
 import { TERMINAL_NODE_STATUSES } from "./types.js";
 import { buildWidgetLines } from "./ui.js";
@@ -25,6 +26,8 @@ export interface ActiveFleet {
   costWarned?: boolean;
   sessions: Map<string, AgentSessionLike>;
   killedNodes: Set<string>;
+  relaunchRequests: Set<string>;
+  widgetVisible?: boolean;
 }
 
 export interface ActiveFleetCell {
@@ -34,7 +37,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 +63,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> {
@@ -80,6 +90,48 @@ export function prepareRelaunch(fleet: ActiveFleet, nodeId: string): void {
   fleet.pauseSwitch.paused = false;
 }
 
+export interface RelaunchRequestResult {
+  message: string;
+  startNow: boolean;
+}
+
+export async function requestRelaunch(
+  fleet: ActiveFleet,
+  nodeId: string,
+  model: string | undefined,
+  registry: ModelRegistryLike,
+): Promise<RelaunchRequestResult> {
+  const worker = fleet.spec.workers.find((w) => w.id === nodeId);
+  if (!worker) return { message: `unknown node "${nodeId}"`, startNow: false };
+  const node = fleet.state.nodes[nodeId];
+  const relaunchable: ReadonlySet<string> = new Set(["failed", "contract_failed", "killed"]);
+  if (!node || !relaunchable.has(node.status)) {
+    return {
+      message: `node "${nodeId}" status ${node?.status ?? "missing"} cannot be relaunched; must be failed, contract_failed, or killed`,
+      startNow: false,
+    };
+  }
+  if (model) {
+    const resolved = resolveModelReference(registry, model);
+    if (!resolved.ok) return { message: resolved.error, startNow: false };
+    const canonical = `${resolved.model.provider}/${resolved.model.id}`;
+    fleet.spec.workers = fleet.spec.workers.map((w) => (w.id === nodeId ? { ...w, model: canonical } : w));
+    await persistFleetJson(fleet);
+  }
+  prepareRelaunch(fleet, nodeId);
+  if (fleet.running) {
+    fleet.relaunchRequests.add(nodeId);
+    return {
+      message: `relaunch queued for ${nodeId} (fleet running; dispatches on next scheduler pass)`,
+      startNow: false,
+    };
+  }
+  fleet.state = resetForRelaunch(fleet.state, fleet.spec, nodeId);
+  await writeState(fleet.fleetRoot, fleet.state);
+  await writeWorkerPrompts(fleet);
+  return { message: `fleet relaunch requested for ${nodeId}`, startNow: true };
+}
+
 export function registerNodeSession(fleet: ActiveFleet, nodeId: string, session: AgentSessionLike): void {
   fleet.sessions.set(nodeId, session);
   if (fleet.killedNodes.has(nodeId)) void session.abort().catch(() => {});
@@ -214,6 +266,7 @@ export async function startLoop(fleet: ActiveFleet, ctx: ExtensionContext, resum
       killSwitch: fleet.killSwitch,
       pauseSwitch: fleet.pauseSwitch,
       nodeKills: fleet.killedNodes,
+      relaunchRequests: fleet.relaunchRequests,
       onNodeChange: (nodeId, nodeState) => {
         fleet.state = fleet.state.nodes[nodeId]
           ? patchNode(fleet.fleetRoot, fleet.state, nodeId, nodeState)
@@ -263,9 +316,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";
@@ -273,7 +338,7 @@ export async function killFleet(target: string): Promise<string> {
   const worker = active.spec.workers.find((w) => w.id === target);
   const node = active.state.nodes[target];
   if (!worker || !node) return `unknown node "${target}"`;
-  if (TERMINAL_NODE_STATUSES.has(node.status)) return `node "${target}" already ${node.status}`;
+  if (TERMINAL_NODE_STATUSES.has(node.status) && node.status !== "blocked") return `node "${target}" already ${node.status}`;
   active.killedNodes.add(target);
   const session = active.sessions.get(target);
   if (session) {

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,10 +49,9 @@ export function getDependents(spec: FleetSpec, nodeId: string): string[] {
   return spec.workers.filter((w) => w.depends_on.includes(nodeId)).map((w) => w.id);
 }
 
-function findWorktreeOwnershipConflicts(workers: WorkerSpec[]): string[] {
-  const worktrees = workers.filter((w) => w.worktree);
+export function findRepoOutputOwnershipConflicts(workers: WorkerSpec[]): string[] {
   const claims = new Map<string, string[]>();
-  for (const w of worktrees) {
+  for (const w of workers) {
     for (const o of w.outputs) {
       if (!o.path.startsWith("output/")) {
         const list = claims.get(o.path) ?? [];
@@ -71,7 +70,7 @@ function findWorktreeOwnershipConflicts(workers: WorkerSpec[]): string[] {
         const aBeforeB = byId.get(a)!.depends_on.includes(b);
         const bBeforeA = byId.get(b)!.depends_on.includes(a);
         if (!aBeforeB && !bBeforeA) {
-          errors.push(`worktree ownership conflict: "${path}" claimed by "${a}" and "${b}" without ordered handoff`);
+          errors.push(`repo output ownership conflict: "${path}" claimed by "${a}" and "${b}" without ordered handoff`);
         }
       }
     }
@@ -132,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)) {
@@ -144,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,
     });
@@ -170,8 +195,8 @@ export function validateFleetSpec(
     if (!hasIntegratorPath(workers)) {
       errors.push("multiple worktree workers require an integrator that depends on all worktree workers");
     }
-    errors.push(...findWorktreeOwnershipConflicts(workers));
   }
+  errors.push(...findRepoOutputOwnershipConflicts(workers));
 
   let loopConfig: LoopConfig | undefined;
   if (cfg.loop !== undefined && cfg.loop !== null) {

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", "blocked"]);
 
 export async function editNode(
   fleet: ActiveFleet,
@@ -28,8 +27,8 @@ 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, blocked, failed, contract_failed, or killed nodes can be edited` };
   }
   switch (key) {
     case "model": {
@@ -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,83 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { ActiveFleet } from "./controller.js";
+import { initFleetState, 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;
+  // Bare fleet.json-only root (e.g. hand-copied spec, never planned/launched):
+  // synthesize a fresh pending state so the canvas can still render the DAG.
+  let state: FleetState;
+  try {
+    state = await readState(fleetRoot);
+  } catch (e: unknown) {
+    const err = e as { code?: string };
+    if (err.code !== "ENOENT") throw e;
+    state = initFleetState(spec);
+  }
+  return {
+    spec,
+    fleetRoot,
+    state,
+    killSwitch: { killed: false },
+    pauseSwitch: { paused: false },
+    running: false,
+    sessions: new Map(),
+    killedNodes: new Set(),
+    relaunchRequests: 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,

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 } };
 }