pi-agent-fleet 0.4.0 → 0.5.0

package/src/canvas.ts

@@ -1,14 +1,16 @@
 import { execFile } from "node:child_process";
 import { createRequire } from "node:module";
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import type { AddressInfo } from "node:net";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import type { ActiveFleet } from "./controller.js";
-import { readState } from "./state.js";
-import type { FleetSpec, FleetState } from "./types.js";
+import { listFleetRoots, readDiskFleet } from "./fleet-recovery.js";
+
+export { listFleetRoots, readDiskFleet };
+export type { FleetRootInfo } from "./fleet-recovery.js";
 
 const execFileP = promisify(execFile);
 
@@ -479,31 +481,129 @@ export interface SessionEntryView {
   text: string;
 }
 
-export function parseSessionTail(jsonl: string, maxEntries: number): SessionEntryView[] {
-  const out: SessionEntryView[] = [];
-  for (const line of jsonl.split("\n")) {
-    if (!line.includes('"type":"message"')) continue;
-    try {
-      const e = JSON.parse(line) as { message?: { role?: unknown; content?: unknown } };
-      const msg = e.message;
-      if (!msg || typeof msg.role !== "string" || !Array.isArray(msg.content)) continue;
-      const parts: string[] = [];
-      for (const p of msg.content as Array<{ type?: string; text?: string; name?: string }>) {
-        if (p?.type === "text" && typeof p.text === "string") parts.push(p.text);
-        else if ((p?.type === "toolCall" || p?.type === "tool_call") && typeof p.name === "string") parts.push(`[tool: ${p.name}]`);
-        else if (p?.type === "toolResult" || p?.type === "tool_result") parts.push("[tool result]");
-      }
-      const text = parts.join("\n").trim();
-      if (text.length > 0) {
-        out.push({ role: msg.role as string, text: text.length > 4000 ? `${text.slice(0, 4000)}…` : text });
+export interface ActionView {
+  type: "tool_call" | "tool_result" | "model_change" | "thinking_level_change" | "complete";
+  name?: string;
+  toolName?: string;
+  arguments?: Record<string, unknown>;
+  provider?: string;
+  modelId?: string;
+  thinkingLevel?: string;
+  stopReason?: string;
+  isError?: boolean;
+  timestamp?: string;
+}
+
+export type TimelineEvent =
+  | { type: "message"; role: string; text: string; timestamp?: string }
+  | { type: "tool_call"; name: string; arguments?: Record<string, unknown>; timestamp?: string }
+  | { type: "tool_result"; toolName?: string; isError?: boolean; text?: string; timestamp?: string }
+  | { type: "model_change"; provider: string; modelId: string; timestamp?: string }
+  | { type: "thinking_level_change"; thinkingLevel: string; timestamp?: string }
+  | { type: "complete"; stopReason: string; timestamp?: string };
+
+export interface SessionTailView {
+  entries: SessionEntryView[];
+  actions: ActionView[];
+  events: TimelineEvent[];
+}
+
+export function parseSessionTail(jsonl: string, maxEntries: number): SessionTailView {
+  const events: TimelineEvent[] = [];
+  const entries: SessionEntryView[] = [];
+  const actions: ActionView[] = [];
+  for (const raw of jsonl.split("\n")) {
+    if (!raw.trim()) continue;
+    let e: { type?: string; timestamp?: string; message?: { role?: unknown; content?: unknown; stopReason?: string; toolName?: string; isError?: boolean }; provider?: string; modelId?: string; thinkingLevel?: string } | undefined;
+    try { e = JSON.parse(raw); } catch { continue; }
+    if (!e) continue;
+    const ts = typeof e.timestamp === "string" ? e.timestamp : undefined;
+    if (e.type === "model_change" && typeof e.provider === "string" && typeof e.modelId === "string") {
+      const a: ActionView = { type: "model_change", provider: e.provider, modelId: e.modelId, timestamp: ts };
+      actions.push(a);
+      events.push({ type: "model_change", provider: e.provider, modelId: e.modelId, timestamp: ts });
+      continue;
+    }
+    if (e.type === "thinking_level_change" && typeof e.thinkingLevel === "string") {
+      const a: ActionView = { type: "thinking_level_change", thinkingLevel: e.thinkingLevel, timestamp: ts };
+      actions.push(a);
+      events.push({ type: "thinking_level_change", thinkingLevel: e.thinkingLevel, timestamp: ts });
+      continue;
+    }
+    if (e.type !== "message") continue;
+    const msg = e.message;
+    if (!msg || typeof msg.role !== "string" || !Array.isArray(msg.content)) continue;
+    // tool result messages carry the result at the message level
+    if (msg.role === "toolResult" || msg.role === "tool_result") {
+      const a: ActionView = { type: "tool_result", toolName: typeof msg.toolName === "string" ? msg.toolName : undefined, isError: msg.isError, timestamp: ts };
+      actions.push(a);
+      events.push({ type: "tool_result", toolName: a.toolName, isError: a.isError, timestamp: ts });
+    }
+    const parts: string[] = [];
+    for (const p of msg.content as Array<{ type?: string; text?: string; name?: string; toolName?: string; isError?: boolean; arguments?: Record<string, unknown> }>) {
+      if (!p) continue;
+      if (p.type === "text" && typeof p.text === "string") parts.push(p.text);
+      else if ((p.type === "toolCall" || p.type === "tool_call") && typeof p.name === "string") {
+        parts.push(`[tool: ${p.name}]`);
+        const a: ActionView = { type: "tool_call", name: p.name, arguments: p.arguments, timestamp: ts };
+        actions.push(a);
+        events.push({ type: "tool_call", name: p.name, arguments: p.arguments, timestamp: ts });
+      } else if (p.type === "toolResult" || p.type === "tool_result") {
+        parts.push("[tool result]");
+        const a: ActionView = { type: "tool_result", toolName: typeof p.toolName === "string" ? p.toolName : p.name, isError: p.isError, timestamp: ts };
+        actions.push(a);
+        events.push({ type: "tool_result", toolName: a.toolName, isError: a.isError, timestamp: ts });
       }
-    } catch {
-      // skip unparseable line
+    }
+    if (msg.stopReason && typeof msg.stopReason === "string" && msg.stopReason !== "toolUse" && msg.stopReason !== "tool_use") {
+      const a: ActionView = { type: "complete", stopReason: msg.stopReason, timestamp: ts };
+      actions.push(a);
+      events.push({ type: "complete", stopReason: msg.stopReason, timestamp: ts });
+    }
+    const text = parts.join("\n").trim();
+    if (text.length > 0) {
+      const entry: SessionEntryView = { role: msg.role as string, text: text.length > 4000 ? `${text.slice(0, 4000)}…` : text };
+      entries.push(entry);
+      events.push({ type: "message", role: entry.role, text: entry.text, timestamp: ts });
     }
   }
-  return out.slice(-maxEntries);
+  return { entries: entries.slice(-maxEntries), actions: actions.slice(-maxEntries), events: events.slice(-maxEntries) };
 }
 
+const DEMO_TASK = `You are L1 (lay-of-the-land) researcher in a 2-layer research fleet.\n\nMission context: founder built QuickCall — a daemon watching engineers' AI coding-agent sessions (Claude Code, Cursor, Codex), extracting team conventions, capturing accept/reject signals and human corrections on agent output.\n\nYour job:\n1. Read the mission brief and upstream inputs.\n2. Search for relevant precedents, code patterns, and competitive landscape.\n3. Write a concise markdown report to the required output path.\n4. Save ALL output files to the worker output directory using absolute paths.\n\nSave the report to output/l1-methods.md. The file must use markdown headings and keep each section focused. Do not modify source code.`;
+
+export function buildDemoSession(_id: string, task?: string): SessionTailView & { task: string } {
+  const taskText = task || DEMO_TASK;
+  const baseTs = "2026-08-01T09:57:";
+  const events: TimelineEvent[] = [
+    { type: "model_change", provider: "openai-codex", modelId: "gpt-5.4-mini", timestamp: baseTs + "04.987Z" },
+    { type: "thinking_level_change", thinkingLevel: "high", timestamp: baseTs + "04.987Z" },
+    { type: "message", role: "assistant", text: "I'll review the scheduler changes and write the verdict.", timestamp: baseTs + "05.000Z" },
+    { type: "tool_call", name: "read", arguments: { path: "docs/superpowers/specs/reviewer-contract.md" }, timestamp: baseTs + "06.000Z" },
+    { type: "tool_call", name: "read", arguments: { path: "src/scheduler.ts" }, timestamp: baseTs + "06.500Z" },
+    { type: "message", role: "assistant", text: "The scheduler uses a priority queue. I'll run the test suite to verify behavior.", timestamp: baseTs + "08.000Z" },
+    { type: "tool_call", name: "bash", arguments: { command: "npm run typecheck" }, timestamp: baseTs + "09.000Z" },
+    { type: "tool_result", toolName: "bash", isError: false, text: "✓ typecheck passed", timestamp: baseTs + "12.000Z" },
+    { type: "message", role: "assistant", text: "Typecheck passes. I'll search for fleet reviewer patterns and inspect tests.", timestamp: baseTs + "12.500Z" },
+    { type: "tool_call", name: "web_search", arguments: { queries: ["fleet reviewer DAG pattern"] }, timestamp: baseTs + "13.000Z" },
+    { type: "tool_call", name: "read", arguments: { path: "test/scheduler.test.ts" }, timestamp: baseTs + "15.000Z" },
+    { type: "tool_result", toolName: "read", isError: false, text: "# 123", timestamp: baseTs + "15.500Z" },
+    { type: "message", role: "assistant", text: "Upstream outputs look good. Tests pass and search results confirm the pattern. Writing the review verdict now.", timestamp: baseTs + "17.000Z" },
+    { type: "tool_call", name: "write", arguments: { path: "output/review.md" }, timestamp: baseTs + "18.000Z" },
+    { type: "tool_result", toolName: "write", isError: false, text: "Successfully wrote 45 bytes to output/review.md", timestamp: baseTs + "18.500Z" },
+    { type: "message", role: "assistant", text: "Done.", timestamp: baseTs + "19.000Z" },
+    { type: "complete", stopReason: "complete", timestamp: baseTs + "20.000Z" },
+  ];
+  const entries: SessionEntryView[] = events.filter((e) => e.type === "message").map((e) => ({ role: (e as TimelineEvent & { type: "message" }).role, text: (e as TimelineEvent & { type: "message" }).text }));
+  const actions: ActionView[] = events.filter((e) => e.type !== "message").map((e) => {
+    if (e.type === "tool_call") return { type: e.type, name: e.name, arguments: e.arguments, timestamp: e.timestamp };
+    if (e.type === "tool_result") return { type: e.type, toolName: e.toolName, isError: e.isError, timestamp: e.timestamp };
+    if (e.type === "model_change") return { type: e.type, provider: e.provider, modelId: e.modelId, timestamp: e.timestamp };
+    if (e.type === "thinking_level_change") return { type: e.type, thinkingLevel: e.thinkingLevel, timestamp: e.timestamp };
+    return { type: e.type, stopReason: e.stopReason, timestamp: e.timestamp };
+  }) as ActionView[];
+  return { entries, actions, events, task: taskText };
+}
 async function latestSessionFile(workerDir: string): Promise<string | undefined> {
   try {
     const files = (await readdir(workerDir)).filter((f) => f.endsWith(".jsonl")).sort();
@@ -626,14 +726,49 @@ main { display:flex; flex:1 1 auto; min-height:0; }
 .flags { margin-top:6px; font-size:11px; color:var(--warn); }
 .flags span { cursor:help; }
 .note { margin-top:6px; font-size:13px; color:var(--warn); }
-#side { width:420px; flex:0 0 auto; border-left:1px solid var(--line); overflow:auto; padding:12px; background:var(--bg); }
+#side { width:420px; flex:0 0 auto; border-left:1px solid var(--line); overflow:hidden; display:flex; flex-direction:column; background:var(--bg); }
 #side:focus, #side:focus-visible { outline:none; }
-.side-head { display:flex; justify-content:space-between; align-items:center; margin-bottom:8px; }
-.side-head .meta { color:var(--muted); }
+.side-head { display:flex; flex-wrap:wrap; justify-content:space-between; align-items:center; flex-shrink:0; gap:6px; padding:12px 12px 8px; border-bottom:1px solid var(--line); background:var(--bg); }
+.side-head .side-meta { display:flex; gap:6px; width:100%; }
+.side-head .side-meta-chip { font-size:11px; color:var(--muted); border:1px solid var(--line); border-radius:4px; padding:2px 6px; white-space:nowrap; }
+.side-head .meta { color:var(--muted); font-size:12px; display:flex; align-items:center; gap:4px; }
+.side-head .side-hash { color:var(--muted); font-weight:400; }
+.side-head .side-id { font-weight:700; color:var(--hdr); font-size:15px; letter-spacing:-0.01em; }
+.side-body { flex:1; overflow:auto; padding:8px 12px 12px; }
 .taskbox-side { border:1px solid var(--line); border-radius:6px; padding:8px; margin-bottom:10px; white-space:pre-wrap; word-break:break-word; font-size:13px; }
 .msg { margin-bottom:10px; padding:8px; border-radius:6px; background:var(--panel); white-space:pre-wrap; word-break:break-word; }
 .msg .role { font-weight:700; margin-bottom:4px; }
 .role-user { color:var(--accent); } .role-assistant { color:var(--ok); } .role-tool { color:var(--warn); }
+.collapsible { position:sticky; top:8px; z-index:1; border:1px solid var(--line); border-radius:6px; margin-bottom:10px; background:var(--bg); }
+.collapsible-head { display:flex; align-items:center; gap:6px; width:100%; padding:8px; background:transparent; border:none; font:inherit; font-size:12px; color:var(--muted); cursor:pointer; text-align:left; }
+.collapsible-head:hover { background:var(--panel); }
+.collapsible-body { padding:8px; border-top:1px solid var(--line); white-space:pre-wrap; word-break:break-word; font-size:13px; max-height:260px; overflow:auto; }
+.collapsible.collapsed .collapsible-body { display:none; }
+.collapsible .chevron { display:inline-block; transition:transform .15s; }
+.collapsible.collapsed .chevron { transform:rotate(-90deg); }
+.timeline { margin-bottom:12px; }
+.timeline-action { background:var(--panel); border-radius:5px; margin-bottom:5px; }
+.timeline-action.open { background:var(--panel-2); }
+.timeline-action.action-error { border-left:3px solid var(--bad); background:color-mix(in srgb, var(--bad) 9%, var(--panel)); }
+.timeline-row { display:flex; align-items:center; gap:8px; padding:5px 8px; font-size:12px; }
+.timeline-row .action-icon { flex-shrink:0; width:34px; text-align:center; color:var(--accent); font-family:var(--mono); font-size:11px; text-transform:uppercase; letter-spacing:0.02em; }
+.timeline-row .action-name { flex-shrink:0; font-weight:600; min-width:48px; font-size:12px; white-space:nowrap; }
+.timeline-row .action-detail { flex:1; min-width:0; color:var(--muted); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; font-size:12px; }
+.timeline-row .action-error { color:var(--bad); }
+.timeline-row .ts { flex-shrink:0; color:var(--wire); font-size:11px; font-variant-numeric:tabular-nums; }
+.timeline-msg { padding:8px; margin-bottom:6px; border-radius:5px; background:var(--panel); font-size:13px; }
+.timeline-msg.user { border-left:1px solid var(--accent); background:color-mix(in srgb, var(--accent) 5%, var(--panel)); }
+.timeline-msg.assistant { border-left:1px solid var(--ok); background:color-mix(in srgb, var(--ok) 5%, var(--panel)); }
+.timeline-msg .role { font-weight:700; margin-bottom:4px; }
+.timeline-msg .timeline-meta { display:flex; justify-content:space-between; align-items:center; margin-bottom:3px; }
+.timeline-msg .timeline-meta .ts { color:var(--wire); font-size:11px; }
+.timeline-msg .timeline-text { white-space:pre-wrap; word-break:break-word; }
+.timeline-loading { display:flex; align-items:center; justify-content:center; gap:8px; padding:16px 8px; color:var(--muted); font-size:13px; }
+.timeline-empty { padding:16px 8px; color:var(--muted); font-size:13px; text-align:center; }
+.activity-toggle { flex-shrink:0; width:18px; height:18px; padding:0; background:transparent; border:1px solid var(--line); border-radius:4px; color:var(--muted); cursor:pointer; font-size:11px; line-height:1; }
+.activity-toggle:hover { background:var(--bg); color:var(--fg); }
+.activity-body { padding:8px; border-top:1px solid var(--line); font-size:12px; color:var(--muted); font-family:var(--mono); white-space:pre-wrap; word-break:break-word; }
+.activity-body pre { margin:0; background:var(--bg); padding:8px; border-radius:4px; overflow:auto; font-size:11px; }
 .react-flow__minimap-node.st-completed { fill:var(--ok); }
 .react-flow__minimap-node.st-running { fill:var(--accent); }
 .react-flow__minimap-node.st-failed, .react-flow__minimap-node.st-contract_failed { fill:var(--bad); }
@@ -713,63 +848,6 @@ export async function renderCanvasPage(): Promise<string> {
 </html>`;
 }
 
-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 interface CanvasServer {
   url: string;
   port: number;
@@ -824,6 +902,14 @@ export async function startCanvasServer(opts: {
       }
       const m = url.pathname.match(/^\/api\/session\/([a-z0-9][a-z0-9-]*)$/);
       if (m) {
+        const isDemo = url.searchParams.get("demo") === "1";
+        let workerTask: string | undefined;
+        if (isDemo) {
+          const demo = buildDemoSession(m[1]);
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify(demo));
+          return;
+        }
         const f = await resolveFleet(url.searchParams.get("fleet"));
         if (!f || f === "unknown" || !f.spec.workers.some((w) => w.id === m[1])) {
           res.writeHead(404);
@@ -835,12 +921,14 @@ export async function startCanvasServer(opts: {
         const file = await latestSessionFile(join(f.fleetRoot, "workers", m[1]));
         res.writeHead(200, { "content-type": "application/json" });
         const worker = f.spec.workers.find((w) => w.id === m[1]);
+        workerTask = worker?.task;
         if (!file) {
-          res.end(JSON.stringify({ entries: [], task: worker?.task }));
+          res.end(JSON.stringify({ entries: [], actions: [], events: [], task: workerTask }));
           return;
         }
         const content = await readFile(file, "utf-8");
-        res.end(JSON.stringify({ entries: parseSessionTail(content, tail), task: worker?.task }));
+        const { entries, actions, events } = parseSessionTail(content, tail);
+        res.end(JSON.stringify({ entries, actions, events, task: workerTask }));
         return;
       }
       res.writeHead(404);

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("; ");
+}