@getpipher/armory-fleet 0.11.0 → 0.12.0

package/src/workflows/helpers/judge-panel.ts

@@ -0,0 +1,33 @@
+import type { HelperCtx } from "./types.ts";
+
+interface Judgment { score: number; reason?: string }
+interface PanelResult { index: number; attempt: unknown; score: number; judgments: Judgment[] }
+
+/** SPEC-6-3 §3.3 — N judges score every attempt; highest average score wins. Closes 6-2.1. */
+export async function judgePanel(
+  attempts: unknown[],
+  opts: { judges?: number; rubric?: string; tier?: string; model?: string; skills?: string[]; backend?: "pi" | "claude"; retries?: number; timeoutMs?: number } = {},
+  ctx: HelperCtx,
+): Promise<PanelResult | undefined> {
+  if (attempts.length === 0) return undefined;
+  const judges = opts.judges ?? 3;
+  const rubric = opts.rubric ?? "overall quality and correctness";
+  const perAttempt: Judgment[][] = attempts.map(() => []);
+  for (let j = 0; j < judges; j++) {
+    for (let a = 0; a < attempts.length; a++) {
+      const prompt = `You are judge ${j + 1} of ${judges}. Score this attempt on a 0-10 scale.\nRubric: ${rubric}\nAttempt ${a}: ${JSON.stringify(attempts[a])}\nRespond as JSON: {"score": number, "reason": string}`;
+      const res = await ctx.spawn(prompt, { agent: "reviewer", ...(opts.tier ? { tier: opts.tier } : {}), ...(opts.model ? { model: opts.model } : {}), ...(opts.skills ? { skills: opts.skills } : {}), ...(opts.backend ? { backend: opts.backend } : {}), ...(opts.retries ? { retries: opts.retries } : {}), ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+      if (res && res.status === "completed") {
+        try { const p = JSON.parse(res.finalText) as { score?: number; reason?: string }; perAttempt[a]!.push({ score: typeof p.score === "number" ? p.score : 0, ...(p.reason ? { reason: p.reason } : {}) }); }
+        catch { perAttempt[a]!.push({ score: 0 }); }
+      } else { perAttempt[a]!.push({ score: 0 }); }
+    }
+  }
+  let best: PanelResult | undefined;
+  for (let a = 0; a < attempts.length; a++) {
+    const js = perAttempt[a]!;
+    const score = js.reduce((s, x) => s + x.score, 0) / (js.length || 1);
+    if (!best || score > best.score) best = { index: a, attempt: attempts[a], score, judgments: js };
+  }
+  return best;
+}

package/src/workflows/helpers/loop-until-dry.ts

@@ -0,0 +1,21 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — discovery loop: call round(n) → items; de-dupe by key; stop after consecutiveEmpty empty rounds or maxRounds. */
+export async function loopUntilDry(
+  opts: { round: (roundIndex: number) => unknown[] | Promise<unknown[]>; key?: (item: unknown) => string; consecutiveEmpty?: number; maxRounds?: number },
+  ctx: HelperCtx,
+): Promise<unknown[]> {
+  const consecutiveEmpty = opts.consecutiveEmpty ?? 2;
+  const maxRounds = opts.maxRounds ?? 50;
+  const key = opts.key ?? ((item: unknown) => JSON.stringify(item));
+  const seen = new Set<string>();
+  const acc: unknown[] = [];
+  let emptyStreak = 0;
+  for (let n = 0; n < maxRounds; n++) {
+    const items = await opts.round(n);
+    const fresh = (Array.isArray(items) ? items : []).filter((it) => { const k = key(it); if (seen.has(k)) return false; seen.add(k); return true; });
+    for (const f of fresh) acc.push(f);
+    if (fresh.length === 0) { emptyStreak++; if (emptyStreak >= consecutiveEmpty) break; } else emptyStreak = 0;
+  }
+  return acc;
+}

package/src/workflows/helpers/retry.ts

@@ -0,0 +1,17 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — retry a thunk up to `attempts`; `until` decides when to stop. */
+export async function retry(
+  thunk: (attempt: number) => unknown | Promise<unknown>,
+  opts: { attempts?: number; until?: (result: unknown) => boolean } = {},
+  ctx: HelperCtx,
+): Promise<unknown> {
+  const attempts = opts.attempts ?? 3;
+  const until = opts.until ?? (() => true);
+  let last: unknown;
+  for (let n = 0; n < attempts; n++) {
+    try { last = await thunk(n); } catch { continue; } // recoverable: try again
+    if (until(last)) return last;
+  }
+  return last;
+}

package/src/workflows/helpers/types.ts

@@ -0,0 +1,19 @@
+import type { WorkflowJournal } from "../journal.ts";
+
+export interface HelperSpawnResult {
+  finalText: string;
+  runId: string;
+  status: "completed" | "failed";
+  costTotal?: number;
+  tokenTotal?: number;
+}
+
+export interface HelperCtx {
+  spawn: (prompt: string, opts?: { agent?: string; tier?: string; model?: string; skills?: string[]; backend?: "pi" | "claude"; retries?: number; timeoutMs?: number }) => Promise<HelperSpawnResult | null>;
+  journal: WorkflowJournal;
+  runId: string;
+  budget?: { spent: () => number; remaining: () => number };
+  onCheckpoint?: (prompt: string, opts: Record<string, unknown>) => Promise<unknown>;
+  getModelContextWindow?: (model: string) => number | undefined;
+  nextCallIndex: () => number;
+}

package/src/workflows/helpers/verify.ts

@@ -0,0 +1,27 @@
+import type { HelperCtx } from "./types.ts";
+
+const REAL_RE = /\b(real|valid|correct|true|confirmed|legit)\b/i;
+
+function judgeVote(text: string): { real: boolean; reason?: string } {
+  return { real: REAL_RE.test(text), reason: text.slice(0, 200) };
+}
+
+/** SPEC-6-3 §3.3 — N reviewers vote; real = realCount/total >= threshold (default 0.5). */
+export async function verify(
+  item: unknown,
+  opts: { reviewers?: number; threshold?: number; lens?: string | string[]; tier?: string; model?: string; skills?: string[]; backend?: "pi" | "claude"; retries?: number; timeoutMs?: number } = {},
+  ctx: HelperCtx,
+): Promise<{ real: boolean; realCount: number; total: number; votes: Array<{ real: boolean; reason?: string }> }> {
+  const reviewers = opts.reviewers ?? 2;
+  const threshold = opts.threshold ?? 0.5;
+  const lens = opts.lens ? ` Focus lens: ${Array.isArray(opts.lens) ? opts.lens.join(", ") : opts.lens}.` : "";
+  const prompt = `You are an independent reviewer. Decide if the following item is REAL/valid.\nItem: ${JSON.stringify(item)}${lens}\nRespond with "real" or "fake" + a one-line reason.`;
+  const votes: Array<{ real: boolean; reason?: string }> = [];
+  for (let i = 0; i < reviewers; i++) {
+    const res = await ctx.spawn(prompt, { agent: "reviewer", ...(opts.tier ? { tier: opts.tier } : {}), ...(opts.model ? { model: opts.model } : {}), ...(opts.skills ? { skills: opts.skills } : {}), ...(opts.backend ? { backend: opts.backend } : {}), ...(opts.retries ? { retries: opts.retries } : {}), ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+    if (!res || res.status !== "completed") { votes.push({ real: false, reason: "reviewer failed" }); continue; }
+    votes.push(judgeVote(res.finalText));
+  }
+  const realCount = votes.filter((v) => v.real).length;
+  return { real: realCount / reviewers >= threshold, realCount, total: reviewers, votes };
+}

package/src/workflows/journal.ts

@@ -0,0 +1,76 @@
+// SPEC-6-3 — the per-workflow positional-call-index journal.
+// Append-only JSONL at <dir>/<runId>.jsonl. Crash-safe: a partial last line is discarded.
+// Separate from RunLog (per-agent conversations/) and RunJournal (per-lifecycle runs/).
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export interface WorkflowStartedEvent { type: "wf:started"; runId: string; script: string; args?: unknown; phases?: { title: string }[]; mode: "auto" | "checkpointed"; ts: number; }
+export interface AgentCallEvent { type: "agent:call"; callIndex: number; label: string; phase: string; prompt: string; opts: Record<string, unknown>; childRunId?: string; ts: number; }
+export interface AgentResultEvent { type: "agent:result"; callIndex: number; childRunId: string; result: unknown; status: "completed" | "failed"; costTotal?: number; tokenTotal?: number; ts: number; }
+export interface HelperCallEvent { type: "helper:call"; callIndex: number; name: string; args: unknown; ts: number; }
+export interface HelperResultEvent { type: "helper:result"; callIndex: number; name: string; result: unknown; ts: number; }
+export interface CheckpointEvent { type: "checkpoint"; callIndex: number; prompt: string; response: unknown; ts: number; }
+export interface WorkflowCompletedEvent { type: "wf:completed"; runId: string; result: unknown; costTotal?: number; tokenTotal?: number; ts: number; }
+export interface WorkflowAbortedEvent { type: "wf:aborted"; runId: string; reason: string; ts: number; }
+
+export interface WorkflowProgressJournalEvent {
+  type: "wf:progress";
+  kind: "started" | "phase" | "child-started" | "child-completed" | "child-failed" | "helper-started" | "helper-completed" | "log" | "checkpoint" | "checkpoint-resolved" | "completed" | "failed" | "aborted";
+  runId: string;
+  status: string;
+  currentPhase: string;
+  phases: Array<{ title: string; agents: number; cached: number; reRun: number }>;
+  childRunIds: string[];
+  logs: string[];
+  tokenTotal: number;
+  costTotal: number;
+  checkpoint?: { prompt: string; opts: Record<string, unknown> };
+  ts: number;
+}
+
+export type WorkflowJournalEvent =
+  | WorkflowStartedEvent | AgentCallEvent | AgentResultEvent | HelperCallEvent
+  | HelperResultEvent | CheckpointEvent | WorkflowCompletedEvent | WorkflowAbortedEvent
+  | WorkflowProgressJournalEvent;
+
+const WORKFLOW_TERMINAL = new Set<WorkflowJournalEvent["type"]>(["wf:completed", "wf:aborted"]);
+
+export class WorkflowJournal {
+  constructor(private readonly dir: string) {}
+
+  private file(runId: string): string { return join(this.dir, `${runId}.jsonl`); }
+
+  append(runId: string, event: WorkflowJournalEvent): void {
+    try {
+      mkdirSync(this.dir, { recursive: true });
+      appendFileSync(this.file(runId), JSON.stringify(event) + "\n", "utf8");
+    } catch {
+      // best-effort: never fail the workflow because the journal couldn't persist.
+    }
+  }
+
+  replay(runId: string): WorkflowJournalEvent[] {
+    const f = this.file(runId);
+    if (!existsSync(f)) return [];
+    const events: WorkflowJournalEvent[] = [];
+    for (const line of readFileSync(f, "utf8").split("\n")) {
+      if (!line) continue;
+      try { events.push(JSON.parse(line) as WorkflowJournalEvent); }
+      catch { /* partial last line (crash mid-append) — discard */ }
+    }
+    return events;
+  }
+
+  scanNonTerminal(): string[] {
+    if (!existsSync(this.dir)) return [];
+    const ids: string[] = [];
+    for (const f of readdirSync(this.dir)) {
+      if (!f.endsWith(".jsonl")) continue;
+      const runId = f.slice(0, -".jsonl".length);
+      const events = this.replay(runId);
+      const last = events[events.length - 1];
+      if (last && !WORKFLOW_TERMINAL.has(last.type)) ids.push(runId);
+    }
+    return ids;
+  }
+}

package/src/workflows/keyword.ts

@@ -0,0 +1,22 @@
+// SPEC-6-3 §9 — bounded keyword authorization for workflow capability.
+// Returns a bounded system hint when the prompt mentions "workflow"/"workflows"
+// as a standalone word (not as part of an identifier or file path).
+
+const WORKFLOW_KEYWORD = /(?:^|[^A-Za-z0-9_])workflows?(?=$|[^A-Za-z0-9_])/i
+
+export function workflowKeywordHint(prompt: string): string | undefined {
+  const match = prompt.match(WORKFLOW_KEYWORD)
+  if (!match) return undefined
+
+  const fullMatch = match[0]!
+  // If the match includes a preceding non-word char, check if it's a path separator.
+  const firstChar = fullMatch[0]!
+  if (firstChar === "/" || firstChar === ".") return undefined
+
+  // Check the character after "workflow" in the original string.
+  const afterIdx = (match.index ?? 0) + fullMatch.length
+  const afterChar = prompt[afterIdx]
+  if (afterChar === "-" || afterChar === ".") return undefined
+
+  return "workflow capability authorized — use action:'workflow' with a script or workflowName"
+}

package/src/workflows/panel/workflows-items.ts

@@ -0,0 +1,150 @@
+// SPEC-6-3 §7/§10 — combined Workflows panel item + action model (pure functions).
+// Definitions first (sorted by source rank, then name), then runs (newest-first).
+import type { SelectItem } from "@earendil-works/pi-tui"
+
+import type { WorkflowDef } from "../registry.ts"
+import type { WorkflowRunState } from "../runtime/types.ts"
+
+export type WorkflowPanelItem =
+  | { kind: "definition"; definition: WorkflowDef }
+  | { kind: "run"; run: WorkflowRunState }
+
+export type WorkflowPanelAction =
+  | "run"
+  | "open"
+  | "pause"
+  | "resume"
+  | "stop"
+  | "save"
+  | "respond"
+  | "edit-resume"
+  | "view-result"
+  | "resume-unchanged"
+
+const SOURCE_RANK: Record<WorkflowDef["source"], number> = {
+  project: 0,
+  global: 1,
+  builtin: 2,
+}
+
+const RUN_STATUS_GLYPH: Record<WorkflowRunState["status"], string> = {
+  queued: "○",
+  running: "▶",
+  paused: "⏸",
+  checkpoint: "⏸",
+  completed: "✓",
+  failed: "✗",
+  aborted: "✗",
+  interrupted: "⚠",
+}
+
+const DESC_BOUND = 80
+const LOG_BOUND = 120
+
+function bound(text: string, max: number): string {
+  return text.length > max ? text.slice(0, max - 1) + "…" : text
+}
+
+function phaseStrip(phases: { title: string }[], current: string): string {
+  return phases.map((p) => (p.title === current ? `${p.title} ▶` : `${p.title} ○`)).join(" ")
+}
+
+function definitionLabel(def: WorkflowDef): string {
+  const desc = def.description ? ` — ${bound(def.description, DESC_BOUND)}` : ""
+  return `◇ ${def.name}  [${def.source}]${desc}`
+}
+
+function runLabel(state: WorkflowRunState): string {
+  const glyph = RUN_STATUS_GLYPH[state.status]
+  const strip = state.phases.length > 0 ? `  ${phaseStrip(state.phases, state.currentPhase)}` : ""
+  const tokens = state.tokenTotal > 0 ? ` · ${(state.tokenTotal / 1000).toFixed(1)}K tok` : ""
+  const cost = state.costTotal > 0 ? ` · $${state.costTotal.toFixed(2)}` : ""
+  const lastLog = state.logs.length > 0 ? `  ${bound(state.logs.at(-1) ?? "", LOG_BOUND)}` : ""
+  return `${glyph} ${state.runId}  [${state.status}]${strip}${tokens}${cost}${lastLog}`
+}
+
+export function buildWorkflowPanelItems(input: {
+  definitions: WorkflowDef[]
+  runs: WorkflowRunState[]
+}): SelectItem[] {
+  const sortedDefs = [...input.definitions].sort((a, b) => {
+    const rankDiff = SOURCE_RANK[a.source] - SOURCE_RANK[b.source]
+    if (rankDiff !== 0) return rankDiff
+    return a.name.localeCompare(b.name)
+  })
+
+  const sortedRuns = [...input.runs].sort((a, b) => b.startedAt - a.startedAt)
+
+  const defItems: SelectItem[] = sortedDefs.map((def) => ({
+    value: `definition:${def.name}`,
+    label: definitionLabel(def),
+  }))
+
+  const runItems: SelectItem[] = sortedRuns.map((r) => ({
+    value: `run:${r.runId}`,
+    label: runLabel(r),
+  }))
+
+  return [...defItems, ...runItems]
+}
+
+export function actionsForWorkflowItem(item: WorkflowPanelItem): WorkflowPanelAction[] {
+  if (item.kind === "definition") {
+    return ["run", "open"]
+  }
+
+  const status = item.run.status
+  switch (status) {
+    case "queued":
+      return ["open", "stop"]
+    case "running":
+      return ["open", "pause", "stop", "save"]
+    case "paused":
+      return ["open", "resume", "stop", "save"]
+    case "checkpoint":
+      return ["respond", "stop", "open"]
+    case "completed":
+      return ["open", "edit-resume", "save", "view-result"]
+    case "failed":
+      return ["open", "edit-resume", "save", "view-result"]
+    case "aborted":
+      return ["open", "edit-resume", "save", "view-result"]
+    case "interrupted":
+      return ["open", "edit-resume", "resume-unchanged", "stop", "save"]
+  }
+}
+
+export function parseWorkflowPanelKey(
+  value: string,
+): { kind: "definition"; name: string } | { kind: "run"; runId: string } {
+  if (value.startsWith("definition:")) {
+    return { kind: "definition", name: value.slice("definition:".length) }
+  }
+  if (value.startsWith("run:")) {
+    return { kind: "run", runId: value.slice("run:".length) }
+  }
+  throw new Error(`invalid workflow panel key: ${value}`)
+}
+
+// ── Backward-compat shim (Task 12 will rewire the panel to the new model) ──
+
+export interface WorkflowRunRow {
+  runId: string
+  name: string
+  status: "running" | "completed" | "failed" | "aborted" | "paused" | "checkpoint"
+  currentPhase: string
+  phases: { title: string }[]
+  agents: number
+  cached: number
+  reRun: number
+  tokens: number
+  cost: number
+}
+
+export function buildWorkflowsItems(runs: WorkflowRunRow[]): SelectItem[] {
+  return runs.map((r) => ({
+    id: r.runId,
+    label: `${RUN_STATUS_GLYPH[r.status] ?? "▶"} ${r.name}  [${r.status}]  ${phaseStrip(r.phases, r.currentPhase)} · ${r.agents} agents (${r.cached} cached, ${r.reRun} re-run) · ${(r.tokens / 1000).toFixed(1)}K tok · $${r.cost.toFixed(2)}`,
+    value: r.runId,
+  }))
+}

package/src/workflows/panel/workflows-rows.ts

@@ -0,0 +1,3 @@
+// SPEC-6-3 — row rendering helpers (pure). Re-exported for the panel; kept thin.
+export { buildWorkflowsItems, buildWorkflowPanelItems, actionsForWorkflowItem, parseWorkflowPanelKey } from "./workflows-items.ts"
+export type { WorkflowRunRow, WorkflowPanelItem, WorkflowPanelAction } from "./workflows-items.ts"

package/src/workflows/panel-host.ts

@@ -0,0 +1,179 @@
+// SPEC-6-3 §12 — panel host loop: consumes WorkflowPanelIntent from the panel
+// and drives editor/input/confirm around it. Never nests ui.editor inside ui.custom.
+import type { Theme } from "@earendil-works/pi-coding-agent"
+import type { Container } from "@earendil-works/pi-tui"
+import type { FleetPanelDeps } from "../panel/fleet-panel.ts"
+import type { WorkflowDef } from "./registry.ts"
+import type { WorkflowRunState } from "./runtime/types.ts"
+import { FleetPanel } from "../panel/fleet-panel.ts"
+
+export type WorkflowPanelIntent =
+  | { action: "close" }
+  | { action: "run"; definitionName: string; prompt: string }
+  | { action: "open-definition"; name: string }
+  | { action: "open-child"; runId: string; childRunId: string }
+  | { action: "edit-resume"; runId: string }
+  | { action: "save"; runId: string }
+  | { action: "view-result"; runId: string }
+  | { action: "respond"; runId: string }
+
+export interface WorkflowPanelHostContext {
+  custom: (factory: (tui: unknown, theme: Theme, kb: unknown, done: () => void) => Container) => void
+  editor: (initial: string) => Promise<string>
+  input: (prompt: string) => Promise<string>
+  confirm: (prompt: string) => Promise<boolean>
+  notify: (msg: string, type?: "info" | "warning" | "error") => void
+  sendUserMessage: (text: string) => void
+}
+
+const MAX_SOURCE_BYTES = 50_000
+const MAX_SOURCE_LINES = 2000
+
+function boundSource(source: string): string {
+  const lines = source.split("\n")
+  if (lines.length > MAX_SOURCE_LINES) {
+    return lines.slice(0, MAX_SOURCE_LINES).join("\n") + "\n… (truncated)"
+  }
+  if (source.length > MAX_SOURCE_BYTES) {
+    return source.slice(0, MAX_SOURCE_BYTES) + "… (truncated)"
+  }
+  return source
+}
+
+function boundResult(result: unknown): string {
+  let text: string
+  try {
+    text = JSON.stringify(result) ?? String(result)
+  } catch {
+    text = String(result)
+  }
+  return text.slice(0, MAX_SOURCE_BYTES)
+}
+
+export async function openWorkflowPanelLoop(
+  deps: FleetPanelDeps,
+  host: WorkflowPanelHostContext,
+): Promise<void> {
+  let running = true
+
+  while (running) {
+    const intent = await openPanelOnce(deps, host)
+
+    if (!intent || intent.action === "close") {
+      running = false
+      continue
+    }
+
+    switch (intent.action) {
+      case "run": {
+        if (intent.prompt.trim()) {
+          const instruction = `${intent.prompt}\n\nUse the fleet workflow tool (action:'workflow') with the '${intent.definitionName}' workflow to execute this.`
+          host.sendUserMessage(instruction)
+          running = false
+        } else {
+          await deps.workflowController.start({
+            workflowName: intent.definitionName,
+            mode: "checkpointed",
+          })
+        }
+        break
+      }
+
+      case "edit-resume": {
+        const run = deps.workflowController.getRun(intent.runId)
+        if (!run) {
+          host.notify(`run '${intent.runId}' not found`, "error")
+          break
+        }
+        const editedSource = await host.editor(run.script)
+        await deps.workflowController.editAndResume(intent.runId, editedSource, "checkpointed")
+        break
+      }
+
+      case "save": {
+        const run = deps.workflowController.getRun(intent.runId)
+        if (!run) {
+          host.notify(`run '${intent.runId}' not found`, "error")
+          break
+        }
+        const name = await host.input("Save-as name?")
+        let overwrite = false
+        const existing = deps.workflowRegistry.get(name)
+        const controllerWithCollision = deps.workflowController as unknown as { saveCollision?: boolean }
+        if (existing || controllerWithCollision.saveCollision) {
+          overwrite = await host.confirm(`Workflow '${name}' already exists. Overwrite?`)
+        }
+        deps.workflowController.save({ name, source: run.script, overwrite })
+        break
+      }
+
+      case "open-definition": {
+        const def = deps.workflowRegistry.get(intent.name)
+        if (!def) {
+          host.notify(`workflow '${intent.name}' not found`, "warning")
+          break
+        }
+        host.notify(`Source: ${def.name}\n${boundSource(def.sourceText)}`, "info")
+        break
+      }
+
+      case "open-child": {
+        host.notify(`Open child run '${intent.childRunId}' from '${intent.runId}' — use the Runs viewer.`, "info")
+        break
+      }
+
+      case "view-result": {
+        const run = deps.workflowController.getRun(intent.runId)
+        if (!run) {
+          host.notify(`run '${intent.runId}' not found`, "error")
+          break
+        }
+        const resultText = run.result !== undefined ? boundResult(run.result) : "(no result)"
+        const logText = run.logs.length > 0 ? run.logs.join("\n") : "(no logs)"
+        host.notify(`Result: ${resultText}\n\nLogs:\n${logText}`, "info")
+        break
+      }
+
+      case "respond": {
+        const shouldContinue = await host.confirm("Continue checkpoint?")
+        if (shouldContinue) {
+          deps.workflowController.respondToCheckpoint(intent.runId, { action: "continue" })
+        } else {
+          const feedback = await host.input("Revise feedback (blank to abort):")
+          if (feedback.trim()) {
+            deps.workflowController.respondToCheckpoint(intent.runId, { action: "revise", feedback })
+          } else {
+            deps.workflowController.respondToCheckpoint(intent.runId, { action: "abort" })
+          }
+        }
+        break
+      }
+    }
+  }
+}
+
+function openPanelOnce(
+  deps: FleetPanelDeps,
+  host: WorkflowPanelHostContext,
+): Promise<WorkflowPanelIntent | null> {
+  return new Promise((resolve) => {
+    let resolved = false
+    const safeResolve = (intent: WorkflowPanelIntent | null) => {
+      if (resolved) return
+      resolved = true
+      resolve(intent)
+    }
+    host.custom((_tui, theme, _kb, done) => {
+      const panel = new FleetPanel({
+        theme,
+        deps,
+        onDone: (intent?: WorkflowPanelIntent | null) => {
+          safeResolve(intent ?? null)
+          done()
+        },
+        onNotify: (m: string, t?: "info" | "warning" | "error") => host.notify(m, t),
+      })
+      return panel
+    })
+  })
+}

package/src/workflows/registry.ts

@@ -0,0 +1,68 @@
+// SPEC-6-3 §3.7 — saved-workflow discovery. Project > global > builtin (later scopes win by name).
+// A workflow .js exports `meta` { name, description, phases? } + a script body. We parse the
+// source via the canonical balanced-brace parser (source.ts) which produces the meta, the
+// stripped body, and a normalized `executable` string the vm realm can compile as CommonJS.
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { parseWorkflowSource } from "./source.ts";
+
+export type WorkflowSource = "builtin" | "global" | "project";
+
+export interface WorkflowDef {
+  name: string;
+  description: string;
+  phases: { title: string }[];
+  sourceText: string;   // the original file content
+  body: string;         // script body after the meta declaration is removed
+  executable: string;    // normalized CommonJS executable (passed to the runner)
+  source: WorkflowSource;
+  filePath: string;
+}
+
+export interface DiscoverOpts { projectDir: string; globalDir: string; builtinDir: string; }
+
+export interface DiscoverResult {
+  workflows: Map<string, WorkflowDef>;
+  errors: string[];
+  warnings: string[];
+}
+
+function loadDir(dir: string, source: WorkflowSource, into: Map<string, WorkflowDef>, errors: string[]): void {
+  if (!existsSync(dir)) return;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".js")) continue;
+    const filePath = join(dir, f);
+    const content = readFileSync(filePath, "utf8");
+    try {
+      const parsed = parseWorkflowSource(content, { filePath, requireMeta: true });
+      if (!parsed.meta) { errors.push(`${filePath}: missing \`export const meta = {…}\``); continue; }
+      const { name, description, phases } = parsed.meta;
+      into.set(name, { name, description, phases, sourceText: parsed.source, body: parsed.body, executable: parsed.executable, source, filePath });
+    } catch (e) {
+      errors.push((e as Error).message);
+    }
+  }
+}
+
+/** Discover workflows from three scopes. Later scopes win by name (project > global > builtin). */
+export function discoverWorkflows(opts: DiscoverOpts): DiscoverResult {
+  const map = new Map<string, WorkflowDef>();
+  const errors: string[] = [];
+  loadDir(opts.builtinDir, "builtin", map, errors);
+  loadDir(opts.globalDir, "global", map, errors);
+  loadDir(opts.projectDir, "project", map, errors); // project shadows (set last wins)
+  return { workflows: map, errors, warnings: [] };
+}
+
+export class WorkflowRegistry {
+  private readonly byName = new Map<string, WorkflowDef>();
+  constructor(workflows: Map<string, WorkflowDef>) { for (const [k, v] of workflows) this.byName.set(k, v); }
+  get(name: string): WorkflowDef | undefined { return this.byName.get(name); }
+  list(): WorkflowDef[] { return [...this.byName.values()]; }
+
+  /** SPEC-6-3 §6: clear + repopulate the existing map (live reference preserved for all consumers). */
+  replace(workflows: WorkflowDef[]): void {
+    this.byName.clear();
+    for (const w of workflows) this.byName.set(w.name, w);
+  }
+}