@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

package/src/host-phases.ts

@@ -0,0 +1,264 @@
+import { type PersistedRun } from "./persistence.js";
+import { type AgentRecord, type LaunchSnapshot, type RunState, type WorkflowPhaseShellActivity } from "./types.js";
+import { object } from "./utils.js";
+
+export const WORKFLOW_PHASE_STATES = ["not started", "running", "completed", "failed", "cancelled", "interrupted", "budget_exhausted"] as const;
+export type WorkflowPhaseState = (typeof WORKFLOW_PHASE_STATES)[number];
+export interface WorkflowPhaseAgentCounts { total: number; completed: number; running: number; failed: number; cancelled: number; pending: number }
+export interface WorkflowPhaseView { id: string; name: string; occurrence: number; state: WorkflowPhaseState; observed: boolean; afterAgent?: number; agents: readonly AgentRecord[]; counts: WorkflowPhaseAgentCounts; shellActivity?: WorkflowPhaseShellActivity }
+export interface WorkflowPhaseModel { runState: RunState; declaredPhases: readonly string[]; phases: readonly WorkflowPhaseView[]; currentPhaseIndex?: number; currentPhaseId?: string; counts: Readonly<Partial<Record<WorkflowPhaseState, number>>>; unassignedAgents?: readonly AgentRecord[] }
+type WorkflowPhaseSource = readonly string[] | Pick<LaunchSnapshot, "phases"> | undefined;
+function phaseNames(source: WorkflowPhaseSource): string[] {
+  const phases: readonly unknown[] = source === undefined ? [] : Array.isArray(source) ? source : object(source) ? source.phases ?? [] : [];
+  return phases.filter((phase): phase is string => typeof phase === "string" && phase.trim() !== "").map((phase) => phase.trim());
+}
+export function phaseAgentCounts(agents: readonly AgentRecord[]): WorkflowPhaseAgentCounts {
+  const counts: WorkflowPhaseAgentCounts = { total: agents.length, completed: 0, running: 0, failed: 0, cancelled: 0, pending: 0 };
+  for (const agent of agents) {
+    if (agent.state === "completed") counts.completed += 1;
+    else if (agent.state === "running") counts.running += 1;
+    else if (agent.state === "failed") counts.failed += 1;
+    else if (agent.state === "cancelled") counts.cancelled += 1;
+    else counts.pending += 1;
+  }
+  return counts;
+}
+/** The live shell activity recorded for one phase index; `-1` is the preflight scope before any phase. */
+export function shellActivityFor(run: Pick<PersistedRun, "activeShellsByPhase">, phaseIndex: number): WorkflowPhaseShellActivity | undefined {
+  return run.activeShellsByPhase?.find((activity) => activity.phaseIndex === phaseIndex && activity.active > 0);
+}
+function phaseState(runState: RunState, counts: WorkflowPhaseAgentCounts, isLatest: boolean, shellActive = false): WorkflowPhaseState {
+  if (!isLatest && !shellActive) return "completed";
+  if (runState === "failed") return "failed";
+  if (runState === "stopped") return "cancelled";
+  if (runState === "interrupted") return "interrupted";
+  if (runState === "budget_exhausted") return "budget_exhausted";
+  if (counts.failed > 0) return "failed";
+  if (shellActive) return "running";
+  if (counts.cancelled > 0) return "cancelled";
+  if (counts.running > 0 || counts.pending > 0) return "running";
+  return runState === "completed" ? "completed" : "running";
+}
+type WorkflowPhaseRun = Omit<Pick<PersistedRun, "state" | "phase" | "phaseHistory" | "agents" | "activeShellsByPhase">, "phaseHistory"> & { phaseHistory?: unknown };
+export function buildWorkflowPhaseModel(run: WorkflowPhaseRun, source?: WorkflowPhaseSource): WorkflowPhaseModel {
+  const declaredPhases = phaseNames(source);
+  const rawHistory: readonly unknown[] = Array.isArray(run.phaseHistory) ? run.phaseHistory : [];
+  const observed: Array<{ name: string; afterAgent: number }> = [];
+  let boundary = 0;
+  for (const record of rawHistory) {
+    if (!object(record) || typeof record.phase !== "string" || !record.phase.trim() || typeof record.afterAgent !== "number" || !Number.isSafeInteger(record.afterAgent)) continue;
+    boundary = Math.max(boundary, Math.min(run.agents.length, Math.max(0, record.afterAgent)));
+    observed.push({ name: record.phase.trim(), afterAgent: boundary });
+  }
+  if (!observed.length && typeof run.phase === "string" && run.phase.trim()) observed.push({ name: run.phase.trim(), afterAgent: 0 });
+  const observedEntries = observed.map((entry, index) => ({ ...entry, index, agents: run.agents.slice(entry.afterAgent, observed[index + 1]?.afterAgent ?? run.agents.length) }));
+  const matchedDeclarations = new Set<number>();
+  const declarationIndices = observedEntries.map((entry) => {
+    const index = declaredPhases.findIndex((name, candidate) => !matchedDeclarations.has(candidate) && name === entry.name);
+    if (index >= 0) matchedDeclarations.add(index);
+    return index >= 0 ? index : undefined;
+  });
+  const entries: Array<{ name: string; observedIndex?: number; declarationIndex?: number }> = observedEntries.map((entry, index) => ({ name: entry.name, observedIndex: index, ...(declarationIndices[index] === undefined ? {} : { declarationIndex: declarationIndices[index] }) }));
+  for (const [declarationIndex, name] of declaredPhases.entries()) {
+    if (matchedDeclarations.has(declarationIndex)) continue;
+    const insertion = entries.findIndex((entry) => entry.declarationIndex !== undefined && entry.declarationIndex > declarationIndex);
+    const pending = { name };
+    if (insertion < 0) entries.push(pending); else entries.splice(insertion, 0, pending);
+  }
+  const occurrences = new Map<string, number>();
+  const phases = entries.map((entry) => {
+    const occurrence = (occurrences.get(entry.name) ?? 0) + 1;
+    occurrences.set(entry.name, occurrence);
+    const observation = entry.observedIndex === undefined ? undefined : observedEntries[entry.observedIndex];
+    const agents = observation?.agents ?? [];
+    const shellActivity = observation ? shellActivityFor(run, observation.index) : undefined;
+    const counts = phaseAgentCounts(agents);
+    const state = observation ? phaseState(run.state, counts, entry.observedIndex === observedEntries.length - 1, shellActivity !== undefined) : "not started";
+    return { id: `${entry.name}#${String(occurrence)}`, name: entry.name, occurrence, state, observed: observation !== undefined, ...(observation ? { afterAgent: observation.afterAgent } : {}), agents, counts, ...(shellActivity ? { shellActivity } : {}) };
+  });
+  const preflightActivity = shellActivityFor(run, -1);
+  const phasesWithPreflight = preflightActivity ? [{ id: "preflight", name: "Preflight", occurrence: 1, state: phaseState(run.state, phaseAgentCounts([]), true, true), observed: true, afterAgent: 0, agents: [], counts: phaseAgentCounts([]), shellActivity: preflightActivity }, ...phases] : phases;
+  let currentPhaseIndex: number | undefined;
+  for (let index = phasesWithPreflight.length - 1; index >= 0; index -= 1) { if (phasesWithPreflight[index]?.observed) { currentPhaseIndex = index; break; } }
+  const counts: Partial<Record<WorkflowPhaseState, number>> = {};
+  for (const phase of phasesWithPreflight) counts[phase.state] = (counts[phase.state] ?? 0) + 1;
+  const current = currentPhaseIndex === undefined ? undefined : phasesWithPreflight[currentPhaseIndex];
+  const assigned = new Set(observedEntries.flatMap(({ agents }) => agents.map((agent) => agent.id)));
+  const unassignedAgents = run.agents.filter((agent) => !assigned.has(agent.id));
+  const result: WorkflowPhaseModel = { runState: run.state, declaredPhases, phases: phasesWithPreflight, counts };
+  if (current !== undefined && currentPhaseIndex !== undefined) { result.currentPhaseIndex = currentPhaseIndex; result.currentPhaseId = current.id; }
+  if (unassignedAgents.length) result.unassignedAgents = unassignedAgents;
+  return result;
+}
+export interface WorkflowPhaseSelection { phaseId?: string | undefined; agentId?: string | undefined; nodeId?: string | undefined; expandedNodeIds?: readonly string[] | undefined; treeOnly?: boolean | undefined; detailsOnly?: boolean | undefined; actions?: { title: string; options: readonly string[]; index: number } | undefined }
+export type WorkflowPhaseTreeNodeKind = "workflow" | "phase" | "operation" | "agent" | "shell";
+export interface WorkflowPhaseTreeNode { id: string; kind: WorkflowPhaseTreeNodeKind; label: string; depth: number; phaseId: string; operationPath: readonly string[]; parentId?: string; children: readonly string[]; state: WorkflowPhaseState | RunState | AgentRecord["state"]; agentId?: string; agent?: AgentRecord; phase?: WorkflowPhaseView; shellActivity?: WorkflowPhaseShellActivity }
+export interface WorkflowPhaseTree { roots: readonly string[]; nodes: readonly WorkflowPhaseTreeNode[]; byId: ReadonlyMap<string, WorkflowPhaseTreeNode> }
+export interface WorkflowPhaseTreeSelection { nodeId?: string | undefined }
+export type WorkflowPhaseTreeDirection = "up" | "down" | "left" | "right";
+export function workflowPhaseTreePath(kind: WorkflowPhaseTreeNodeKind, phaseId: string, operationPath: readonly string[], agentId?: string): string {
+  if (kind === "workflow") return "workflow";
+  const root = `phase/${encodeURIComponent(phaseId)}`;
+  if (kind === "phase") return root;
+  if (kind === "shell") return `${root}/shell`;
+  const operation = operationPath.map((part) => encodeURIComponent(part)).join("/");
+  if (kind === "operation") return `${root}/operation/${operation}`;
+  return operation ? `${root}/operation/${operation}/agent/${encodeURIComponent(agentId ?? "")}` : `${root}/agent/${encodeURIComponent(agentId ?? "")}`;
+}
+function workflowPhaseTreeAggregateState(states: readonly AgentRecord["state"][]): AgentRecord["state"] {
+  if (!states.length || states.every((state) => state === "completed")) return "completed";
+  if (states.some((state) => state === "failed")) return "failed";
+  if (states.some((state) => state === "cancelled")) return "cancelled";
+  if (states.some((state) => state === "running")) return "running";
+  return "queued";
+}
+export function buildWorkflowPhaseTree(model: WorkflowPhaseModel): WorkflowPhaseTree {
+  type Draft = Omit<WorkflowPhaseTreeNode, "children"> & { children: string[] };
+  type AgentEntry = { agent: AgentRecord; node?: Draft; structuralPath: readonly string[]; operationPath: readonly string[]; defaultParentId: string };
+  const drafts = new Map<string, Draft>();
+  const roots: string[] = [];
+  const add = (node: Omit<Draft, "children">, parentId?: string): Draft => {
+    const existing = drafts.get(node.id);
+    if (existing) return existing;
+    const draft: Draft = { ...node, ...(parentId === undefined ? {} : { parentId }), children: [] };
+    drafts.set(draft.id, draft);
+    if (parentId === undefined) roots.push(draft.id); else drafts.get(parentId)?.children.push(draft.id);
+    return draft;
+  };
+  const samePath = (left: readonly string[], right: readonly string[]): boolean => left.length === right.length && left.every((part, index) => part === right[index]);
+  const addPhase = (phaseId: string, label: string, agents: readonly AgentRecord[], phase?: WorkflowPhaseView): void => {
+    const phaseNode = add({ id: workflowPhaseTreePath("phase", phaseId, []), kind: "phase", label, depth: 0, phaseId, operationPath: [], state: phase?.state ?? workflowPhaseTreeAggregateState(agents.map((agent) => agent.state)), ...(phase ? { phase } : {}) }, workflowNode.id);
+    if (phase?.shellActivity) add({ id: workflowPhaseTreePath("shell", phaseId, []), kind: "shell", label: `shell [running] (${String(phase.shellActivity.active)} active)`, depth: 0, phaseId, operationPath: [], state: "running", phase, shellActivity: phase.shellActivity }, phaseNode.id);
+    const operationNodes = new Map<string, Draft>();
+    const entries: AgentEntry[] = agents.map((agent) => {
+      const structuralPath = [...(agent.structuralPath ?? [])];
+      return { agent, structuralPath, operationPath: [...structuralPath, ...(agent.parentBreadcrumb ? [agent.parentBreadcrumb] : [])], defaultParentId: phaseNode.id };
+    });
+    const agentEntries = new Map(entries.map((entry) => [entry.agent.id, entry]));
+    const acceptedParents = new Map<string, string>();
+    const wouldCycle = (childId: string, parentId: string): boolean => {
+      const seen = new Set<string>([childId]);
+      let current: string | undefined = parentId;
+      while (current) {
+        if (seen.has(current)) return true;
+        seen.add(current);
+        current = acceptedParents.get(current);
+      }
+      return false;
+    };
+    for (const entry of entries) {
+      const parent = entry.agent.parentId ? agentEntries.get(entry.agent.parentId) : undefined;
+      if (parent && !wouldCycle(entry.agent.id, parent.agent.id)) acceptedParents.set(entry.agent.id, parent.agent.id);
+    }
+    const operationChain = (path: readonly string[], owner: Draft, startIndex = 0): Draft => {
+      let parent = owner;
+      for (let index = startIndex; index < path.length; index += 1) {
+        const prefix = path.slice(0, index + 1);
+        const key = `${owner.id}:${JSON.stringify(prefix)}`;
+        const existing = operationNodes.get(key);
+        if (existing) { parent = existing; continue; }
+        const suffix = path.slice(startIndex, index + 1).map((part) => encodeURIComponent(part)).join("/");
+        const id = owner.id === phaseNode.id ? workflowPhaseTreePath("operation", phaseId, prefix) : `${owner.id}/operation/${suffix}`;
+        const operation = add({ id, kind: "operation", label: prefix.at(-1) ?? "", depth: 0, phaseId, operationPath: prefix, state: "queued", ...(phase ? { phase } : {}) }, parent.id);
+        operationNodes.set(key, operation);
+        parent = operation;
+      }
+      return parent;
+    };
+    for (const entry of entries) {
+      if (!acceptedParents.has(entry.agent.id)) entry.defaultParentId = operationChain(entry.operationPath, phaseNode).id;
+    }
+    for (const entry of entries) {
+      entry.node = add({ id: workflowPhaseTreePath("agent", phaseId, entry.structuralPath, entry.agent.id), kind: "agent", label: entry.agent.label ?? entry.agent.name, depth: 0, phaseId, operationPath: entry.structuralPath, state: entry.agent.state, agentId: entry.agent.id, agent: entry.agent }, phaseNode.id);
+    }
+    const attach = (node: Draft, parentId: string): void => {
+      const previous = node.parentId ? drafts.get(node.parentId) : undefined;
+      if (previous) previous.children = previous.children.filter((childId) => childId !== node.id);
+      node.parentId = parentId;
+      const parent = drafts.get(parentId);
+      if (parent && !parent.children.includes(node.id)) parent.children.push(node.id);
+    };
+    for (const entry of entries) {
+      const node = entry.node;
+      if (!node) continue;
+      const parentId = acceptedParents.get(entry.agent.id);
+      const parent = parentId ? agentEntries.get(parentId) : undefined;
+      const parentNode = parent?.node;
+      if (parent && parentNode) {
+        if (samePath(entry.operationPath, parent.operationPath)) entry.defaultParentId = parentNode.id;
+        else {
+          const commonLength = entry.operationPath.findIndex((part, index) => parent.operationPath[index] !== part);
+          const startIndex = commonLength < 0 ? Math.min(entry.operationPath.length, parent.operationPath.length) : commonLength;
+          entry.defaultParentId = operationChain(entry.operationPath, parentNode, startIndex).id;
+        }
+      }
+      attach(node, entry.defaultParentId);
+    }
+    const setDepth = (node: Draft, depth: number, seen = new Set<string>()): void => {
+      if (seen.has(node.id)) return;
+      seen.add(node.id);
+      node.depth = depth;
+      for (const childId of node.children) { const child = drafts.get(childId); if (child) setDepth(child, depth + 1, seen); }
+    };
+    setDepth(phaseNode, 0);
+    const statesFor = (node: Draft, seen = new Set<string>()): AgentRecord["state"][] => {
+      if (seen.has(node.id)) return [];
+      const nextSeen = new Set(seen).add(node.id);
+      return node.children.flatMap((childId) => {
+        const child = drafts.get(childId);
+        return child?.kind === "agent" ? [child.agent?.state ?? "queued", ...statesFor(child, nextSeen)] : child ? statesFor(child, nextSeen) : [];
+      });
+    };
+    for (const operation of operationNodes.values()) operation.state = workflowPhaseTreeAggregateState(statesFor(operation));
+  };
+  const workflowNode = add({ id: "workflow", kind: "workflow", label: "Workflow", depth: 0, phaseId: "", operationPath: [], state: model.runState });
+  for (const phase of model.phases) addPhase(phase.id, `${phase.name}${phase.occurrence > 1 ? ` #${String(phase.occurrence)}` : ""}`, phase.agents, phase);
+  if (model.unassignedAgents?.length) addPhase("unassigned", "Unassigned", model.unassignedAgents);
+  const nodes = [...drafts.values()].map((node) => ({ ...node, children: [...node.children] }));
+  return { roots, nodes, byId: new Map(nodes.map((node) => [node.id, node])) };
+}
+export function workflowPhaseTreeVisibleNodes(tree: WorkflowPhaseTree, expanded: ReadonlySet<string> = new Set()): readonly WorkflowPhaseTreeNode[] {
+  const visible: WorkflowPhaseTreeNode[] = [];
+  const visit = (id: string): void => {
+    const node = tree.byId.get(id);
+    if (!node) return;
+    visible.push(node);
+    if (expanded.has(node.id)) for (const childId of node.children) visit(childId);
+  };
+  for (const root of tree.roots) visit(root);
+  return visible;
+}
+export function workflowPhaseTreeInitialExpanded(tree: WorkflowPhaseTree): ReadonlySet<string> {
+  return new Set(tree.nodes.filter((node) => node.children.length > 0).map((node) => node.id));
+}
+export function preserveWorkflowPhaseTreeSelection(tree: WorkflowPhaseTree, selection: WorkflowPhaseTreeSelection): WorkflowPhaseTreeSelection {
+  const node = (selection.nodeId ? tree.byId.get(selection.nodeId) : undefined) ?? tree.nodes[0];
+  return node ? { nodeId: node.id } : {};
+}
+export function navigateWorkflowPhaseTree(tree: WorkflowPhaseTree, selectedNodeId: string | undefined, expandedNodeIds: ReadonlySet<string>, direction: WorkflowPhaseTreeDirection): { nodeId?: string; expandedNodeIds: ReadonlySet<string> } {
+  const expanded = new Set(expandedNodeIds);
+  const current = (selectedNodeId ? tree.byId.get(selectedNodeId) : undefined) ?? tree.nodes[0];
+  if (!current) return { expandedNodeIds: expanded };
+  if (direction === "left") {
+    if (current.children.length && expanded.delete(current.id)) return { nodeId: current.id, expandedNodeIds: expanded };
+    return { nodeId: current.parentId ?? current.id, expandedNodeIds: expanded };
+  }
+  if (direction === "right") {
+    if (current.children.length && !expanded.has(current.id)) { expanded.add(current.id); return { nodeId: current.id, expandedNodeIds: expanded }; }
+    return { nodeId: current.children[0] ?? current.id, expandedNodeIds: expanded };
+  }
+  const visible = workflowPhaseTreeVisibleNodes(tree, expanded);
+  const index = Math.max(0, visible.findIndex((node) => node.id === current.id));
+  const next = visible[(index + (direction === "up" ? visible.length - 1 : 1)) % visible.length];
+  return { nodeId: next?.id ?? current.id, expandedNodeIds: expanded };
+}
+export function preserveWorkflowPhaseSelection(model: WorkflowPhaseModel, selection: WorkflowPhaseSelection): WorkflowPhaseSelection {
+  const phase = model.phases.find((candidate) => candidate.id === selection.phaseId) ?? (model.currentPhaseIndex === undefined ? undefined : model.phases[model.currentPhaseIndex]) ?? model.phases[0];
+  if (!phase) return model.unassignedAgents?.length ? { nodeId: workflowPhaseTreePath("phase", "unassigned", []) } : {};
+  const tree = buildWorkflowPhaseTree(model);
+  const selectedAgent = selection.agentId ? phase.agents.find((candidate) => candidate.id === selection.agentId) : undefined;
+  const selectedCandidate = selection.nodeId ? tree.byId.get(selection.nodeId) : undefined;
+  const selected = selectedCandidate?.phaseId === phase.id ? selectedCandidate : selectedAgent ? tree.byId.get(workflowPhaseTreePath("agent", phase.id, selectedAgent.structuralPath ?? [], selectedAgent.id)) : undefined;
+  const nodeId = selected?.id ?? tree.byId.get(workflowPhaseTreePath("phase", phase.id, []))?.id;
+  return { phaseId: phase.id, ...(selection.agentId && phase.agents.some((agent) => agent.id === selection.agentId) ? { agentId: selection.agentId } : phase.agents[0] ? { agentId: phase.agents[0].id } : {}), ...(nodeId ? { nodeId } : {}), ...(selection.expandedNodeIds ? { expandedNodeIds: selection.expandedNodeIds } : {}) };
+}

package/src/host-recovery.ts

@@ -0,0 +1,333 @@
+import { randomUUID } from "node:crypto";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { FairAgentScheduler, WorkflowAgentExecutor, type AgentDefinition, type AgentExecutionRoot, type AgentProviderFailure, type AgentProviderRecovery } from "./agent-execution.js";
+import { listRunIds, RunStore, structuralPath as operationPath, type PersistedRun } from "./persistence.js";
+import { budgetUsage, budgetRelaxed, mergeBudget, resumeBudgetAllowed, validateBudget, validateBudgetPatch, WorkflowBudgetRuntime } from "./budget.js";
+import { aliasDrift, createLaunchSnapshot, errorCode, errorText, jsonValue, object } from "./utils.js";
+import { LAUNCH_SNAPSHOT_IDENTITY_VERSION, WorkflowError, isExternallyEndedRunState, type AgentIdentity, type AgentResourcePolicy, type BudgetApprovalRequest, type JsonValue, type LaunchSnapshot, type ModelSpec, type RunState, type ShellIdentity, type ShellOptions, type ShellResult, type WorkflowExtensionSettings, type WorkflowMetadata, type WorkflowRetryProvenance, type WorkflowWorktreeReference } from "./types.js";
+import { type WorkflowRegistryApi } from "./registry.js";
+import { RunLifecycle, WorkflowEventPublisher, hostSessionContext, withWorkflowFunctions, withoutActiveShells, workflowRunContext, type WorkflowRunRecord, type WorkflowToolUpdate } from "./host-runtime.js";
+import { runWorkflow } from "./execution.js";
+import { createWorkflowFailureDiagnostics, formatWorkflowFailureDelivery, formatWorkflowFailureDeliveryFallback, failureDiagnosticsFrom, completionDeliveryFromStore, incompleteRetryPaths, markWorkflowFailureDiagnostics, workflowFailedAt, type CompletionDeliveryContext, type CompletionDeliveryResult } from "./host-delivery.js";
+
+/** The subset of Pi's model registry the host relies on; every member is optional because older or headless hosts expose fewer of them. */
+export type ModelRegistryCapability = { getAll?: () => readonly Model<Api>[]; getAvailable?: () => readonly Model<Api>[]; find?: (provider: string, model: string) => Model<Api> | undefined; refresh?: () => Promise<void>; getError?: () => string | undefined };
+export type WorkflowRecoveryContext = { model: { provider: string; id: string } | undefined; modelRegistry: ModelRegistryCapability | undefined; deliveryContext: CompletionDeliveryContext; signal?: AbortSignal; resolvedAliases?: Readonly<Record<string, string>>; blockedAliases?: ReadonlySet<string>; blockedAliasTargets?: Readonly<Record<string, string>> };
+export type WorkflowRecoveryDependencies = {
+  pi: Pick<ExtensionAPI, "getThinkingLevel">;
+  home: string | undefined;
+  runs: Map<string, WorkflowRunRecord>;
+  scheduler: FairAgentScheduler;
+  eventPublisher: WorkflowEventPublisher;
+  persistRunState: (store: RunStore, metadata: WorkflowMetadata, update: (run: PersistedRun) => PersistedRun | Promise<PersistedRun>) => Promise<PersistedRun>;
+  projectTrusted: (context: unknown) => boolean;
+  resumeHostContext: (context: unknown) => WorkflowRecoveryContext;
+  ensureSessionLease: (cwd: string, sessionId: string) => Promise<void>;
+  coordinateRunMutation?: <T>(task: () => Promise<T>) => Promise<T>;
+  createAgentExecutor: (root: Omit<AgentExecutionRoot, "agentDir" | "agentSetupHooks">) => WorkflowAgentExecutor;
+  activeSnapshotTools: (tools: readonly string[], active: ReadonlySet<string> | "session") => Set<string>;
+  frozenResourcePolicy: (policy: AgentResourcePolicy) => () => AgentResourcePolicy;
+  resolveLaunchPrologue: (input: { snapshot: Readonly<LaunchSnapshot>; cwd: string; trustedProject: boolean; rootModel: ModelSpec; modelRegistry?: WorkflowRecoveryContext["modelRegistry"]; signal: AbortSignal; resolvedAliases?: Readonly<Record<string, string>>; blockedAliases?: ReadonlySet<string>; blockedAliasTargets?: Readonly<Record<string, string>>; withPreflight: boolean }) => Promise<{ active: Set<string>; settingsPath: string; currentPolicy: AgentResourcePolicy; previousAliases: Readonly<Record<string, string>>; knownModels: ReadonlySet<string>; availableModels: ReadonlySet<string>; currentAliases: Readonly<Record<string, string>>; blockedAliases: ReadonlySet<string>; blockedAliasTargets: Readonly<Record<string, string>>; snapshot: Readonly<LaunchSnapshot>; script: string | undefined }>;
+  resumeRoles: (store: RunStore, snapshot: Readonly<LaunchSnapshot>, cwd: string, trustedProject: boolean) => { definitions: Readonly<Record<string, AgentDefinition>>; capture: (role: string, model: ModelSpec) => Promise<void> };
+  workflowAgentHandler: (store: RunStore, metadata: WorkflowMetadata, lifecycle: RunLifecycle, executor: WorkflowAgentExecutor, cwd: string, runId: string, captureRole?: (role: string, model: ModelSpec) => Promise<void>) => (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
+  shellForRun: (store: RunStore, metadata: WorkflowMetadata, lifecycle: RunLifecycle, command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity) => Promise<ShellResult>;
+  resolveWorktree: (store: RunStore, metadata: WorkflowMetadata, owner: string) => Promise<Readonly<WorkflowWorktreeReference>>;
+  checkpointBridge: (runId: string, store: RunStore, metadata: WorkflowMetadata, foreground: boolean, ui?: { select?: (prompt: string, options: string[]) => Promise<string | undefined> }, headless?: boolean) => (raw: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => Promise<boolean>;
+  phaseBridge: (store: RunStore, metadata: WorkflowMetadata, lifecycle: RunLifecycle) => (phase: string) => Promise<void>;
+  logBridge: (store: RunStore, lifecycle: RunLifecycle, workflowName: string) => (message: string) => Promise<void>;
+  lifecycleFor: (store: RunStore, state: RunState, metadata: WorkflowMetadata) => RunLifecycle;
+  createProviderErrorRecovery: (host: unknown, fallbackModels: ReadonlySet<string>, abort: () => void) => ((failure: AgentProviderFailure) => Promise<AgentProviderRecovery>) | undefined;
+  cleanupTerminalRun: (runId: string) => Promise<void>;
+  deliver: (content: string) => void;
+  deliverTerminal: (store: RunStore, content: string | (() => string | Promise<string>), failure?: boolean) => Promise<void>;
+  workflowToolUpdate: (run: PersistedRun) => WorkflowToolUpdate;
+  registry: WorkflowRegistryApi;
+  modelSpec: (value: string, fallback: ModelSpec) => ModelSpec;
+};
+
+function workflowRecoveryGuidance(action: "resume" | "retry", state: RunState): string {
+  if (action === "resume") {
+    if (state === "failed") return "Failed workflow runs must use workflow_retry({ runId })";
+    if (state === "completed") return "Completed workflow runs have no recovery action";
+    if (state === "stopped") return "Stopped workflow runs have no recovery action; launch a new workflow";
+    if (state === "interrupted") return "Interrupted workflow runs must be resumed from the interactive /workflow picker";
+    return `Only budget-exhausted runs can be resumed with workflow_resume; source is ${state}`;
+  }
+  if (state === "budget_exhausted") return "Budget-exhausted workflow runs must use workflow_resume({ runId, budget? })";
+  if (state === "completed") return "Completed workflow runs have no recovery action";
+  if (state === "stopped") return "Stopped workflow runs cannot be retried; launch a new workflow";
+  if (state === "interrupted") return "Interrupted workflow runs must be resumed from the interactive /workflow picker";
+  return `Only failed workflow runs can be retried; source is ${state}`;
+}
+/** A snapshot can only be re-executed when it carries the current identity scheme and every role its script references. */
+function assertResumableSnapshot(snapshot: Readonly<LaunchSnapshot>, trustedProject: boolean): void {
+  if (snapshot.identityVersion !== LAUNCH_SNAPSHOT_IDENTITY_VERSION) throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow launch snapshot identity version is incompatible");
+  if (snapshot.roles === undefined) throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow role definitions are missing from the launch snapshot");
+  if ((snapshot.projectRoles?.length ?? 0) > 0 && !trustedProject) throw new WorkflowError("RESUME_INCOMPATIBLE", "Cannot restore project roles in an untrusted project");
+  const missingRole = snapshot.agentTypes.find((role) => !snapshot.roles?.[role]);
+  if (missingRole) throw new WorkflowError("RESUME_INCOMPATIBLE", `Role definition is missing from the launch snapshot: ${missingRole}`);
+}
+function assertExpectedWorkflowState(expectedState: string | undefined, actualState: RunState): void {
+  if (expectedState !== undefined && expectedState !== actualState) throw new WorkflowError("RESUME_INCOMPATIBLE", `Workflow run state changed: expected state ${expectedState}, actual state ${actualState}`);
+}
+export function persistedFailure(run: PersistedRun, error: WorkflowError): PersistedRun { const failedAt = workflowFailedAt(error); return { ...run, error: { code: error.code, message: error.message, ...(failedAt ? { failedAt } : {}) }, ...(failedAt ? { failedAt } : {}) }; }
+
+export function createWorkflowRecovery(deps: WorkflowRecoveryDependencies) {
+  const { pi, home, runs, scheduler, eventPublisher, persistRunState, projectTrusted, resumeHostContext, ensureSessionLease, createAgentExecutor, activeSnapshotTools, frozenResourcePolicy, resolveLaunchPrologue, resumeRoles, workflowAgentHandler, shellForRun, resolveWorktree, checkpointBridge, phaseBridge, logBridge, lifecycleFor, createProviderErrorRecovery, cleanupTerminalRun, deliver, deliverTerminal, workflowToolUpdate, registry, modelSpec } = deps;
+  const coordinateRunMutation = deps.coordinateRunMutation ?? (<T>(task: () => Promise<T>): Promise<T> => task());
+  type BudgetDecisionResult = { state: "running" | "completed" | "budget_exhausted"; approved: boolean; value?: JsonValue; run?: PersistedRun; completion?: CompletionDeliveryResult };
+  const budgetDecisionDelivery = (metadata: WorkflowMetadata, request: BudgetApprovalRequest) => `Workflow ${metadata.name} budget adjustment ${request.proposalId} for run ${request.runId} requires approval. Consumed usage: ${JSON.stringify(request.consumed)}. Previous limits: ${JSON.stringify(request.previous)}. Proposed limits: ${JSON.stringify(request.proposed)}. Respond with workflow_respond using proposalId ${request.proposalId}.`;
+  const appendBudgetDecisionEvent = async (run: WorkflowRunRecord, request: BudgetApprovalRequest, type: "adjustment_requested" | "adjustment_approved" | "adjustment_rejected") => {
+    run.budget.recordEvent({ type, budgetVersion: request.budgetVersion, dimensions: [], usage: structuredClone(request.consumed), limits: structuredClone(request.proposed), at: Date.now(), proposalId: request.proposalId, previous: structuredClone(request.previous), proposed: structuredClone(request.proposed) });
+    await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
+  };
+  const answerBudgetDecision = async (runId: string, proposalId: string, approved: boolean, silent = false, context?: unknown, signal?: AbortSignal, waitForCompletion = true): Promise<BudgetDecisionResult | undefined> => {
+    const run = runs.get(runId);
+    if (!run) return undefined;
+    const request = await run.store.answerWorkflowDecision(proposalId, approved);
+    if (!request) return undefined;
+    await appendBudgetDecisionEvent(run, request, approved ? "adjustment_approved" : "adjustment_rejected");
+    const result = await applyBudgetDecision(request, approved, context, signal, waitForCompletion);
+    if (!silent) deliver(`Workflow ${run.metadata.name} budget adjustment ${proposalId}: ${approved ? "Approved" : "Rejected"}.`);
+    return result;
+  };
+  const refreshPausedRunAliases = async (run: WorkflowRunRecord, context?: { model: { provider: string; id: string } | undefined; modelRegistry: WorkflowRecoveryContext["modelRegistry"]; projectTrusted?: boolean }) => {
+    const loaded = await run.store.load();
+    const trustedProject = context?.projectTrusted ?? run.projectTrusted();
+    const rootModel = context?.model ? { ...run.model, provider: context.model.provider, model: context.model.id } : run.model;
+    const { settingsPath, currentPolicy, previousAliases, knownModels, availableModels, currentAliases, blockedAliases, blockedAliasTargets, snapshot } = await resolveLaunchPrologue({ snapshot: loaded.snapshot, cwd: run.store.cwd, trustedProject, rootModel, ...(context?.modelRegistry ? { modelRegistry: context.modelRegistry } : {}), signal: run.abortController.signal, withPreflight: false });
+    await run.store.saveSnapshot(snapshot);
+    scheduler.updateRunLimit(run.store.runId, snapshot.settings.concurrency);
+    scheduler.setRunExtensionSettings(run.store.runId, snapshot.settings.extensionSettings);
+    run.executor = createAgentExecutor({ cwd: run.store.cwd, model: run.model, tools: activeSnapshotTools(snapshot.tools, "session"), resourceSelectors: currentPolicy.effective, extensionSettings: snapshot.settings.extensionSettings, availableModels, knownModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: resumeRoles(run.store, snapshot, run.store.cwd, trustedProject).definitions, runStore: run.store, providerPause: async () => { deliver(`Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentResourcePolicy: frozenResourcePolicy(currentPolicy) });
+    run.executor.setRunContext(workflowRunContext(run.store.cwd, run.store.sessionId, run.store.runId, loaded.snapshot.metadata, loaded.snapshot.args, run.abortController.signal));
+    const drift = aliasDrift(previousAliases, currentAliases);
+    if (drift.length) await run.store.appendEvent({ type: "warning", message: `Model alias mappings changed on resume: ${drift.join("; ")}` });
+  };
+  const recoveryUi = (context: unknown): { hasUI: boolean; ui: { select?: (prompt: string, options: string[]) => Promise<string | undefined> } } => {
+    const host = object(context) ? context : undefined;
+    const ui = host && object(host.ui) ? host.ui as { select?: (prompt: string, options: string[]) => Promise<string | undefined> } : {};
+    return { hasUI: host?.hasUI === true, ui };
+  };
+  type ColdResumeResult = { value: JsonValue; resultPath: string; resultBytes: number; completion: CompletionDeliveryResult };
+  const coldResumeRun = async (run: WorkflowRunRecord, hasUI: boolean, ui: { select?: (prompt: string, options: string[]) => Promise<string | undefined> }, trustedProject: boolean, context?: { model: { provider: string; id: string } | undefined; modelRegistry: WorkflowRecoveryContext["modelRegistry"]; deliveryContext: CompletionDeliveryContext; signal?: AbortSignal | undefined; resolvedAliases?: Readonly<Record<string, string>>; blockedAliases?: ReadonlySet<string>; blockedAliasTargets?: Readonly<Record<string, string>> }, modeOverride?: boolean, waitForCompletion = true): Promise<ColdResumeResult | undefined> => {
+    const loaded = await run.store.load();
+    const foreground = modeOverride ?? (loaded.run.delivery?.mode === "foreground" || (loaded.run.delivery?.mode === "background" && loaded.run.delivery.toolCallId !== undefined) || (loaded.run.delivery === undefined && loaded.snapshot.launchMode === "foreground"));
+    if (loaded.run.activeShells !== undefined || loaded.run.activeShellStartedAt !== undefined || loaded.run.activeShellsByPhase !== undefined) await persistRunState(run.store, run.metadata, withoutActiveShells);
+    await run.store.validateRetrySource();
+    await run.store.validateBorrowedWorktrees();
+    assertResumableSnapshot(loaded.snapshot, trustedProject);
+    const rootModel = context?.model ? { ...run.model, provider: context.model.provider, model: context.model.id } : run.model;
+    const controller = new AbortController();
+    if (context?.signal?.aborted) controller.abort(); else { context?.signal?.addEventListener("abort", () => { controller.abort(); }, { once: true }); }
+    run.abortController = controller;
+    const { settingsPath, currentPolicy, previousAliases, knownModels, availableModels, currentAliases, blockedAliases, blockedAliasTargets, snapshot, script } = await resolveLaunchPrologue({ snapshot: loaded.snapshot, cwd: run.store.cwd, trustedProject, rootModel, ...(context?.modelRegistry ? { modelRegistry: context.modelRegistry } : {}), signal: controller.signal, ...(context?.resolvedAliases ? { resolvedAliases: context.resolvedAliases } : {}), ...(context?.blockedAliases ? { blockedAliases: context.blockedAliases } : {}), ...(context?.blockedAliasTargets ? { blockedAliasTargets: context.blockedAliasTargets } : {}), withPreflight: true });
+    if (!script) throw new WorkflowError("INTERNAL_ERROR", "Resume preflight did not produce a launch script");
+    const persistedSnapshot = modeOverride === undefined ? snapshot : createLaunchSnapshot({ ...snapshot, launchMode: foreground ? "foreground" : "background" });
+    await run.store.saveSnapshot(persistedSnapshot);
+    if (modeOverride !== undefined) await persistRunState(run.store, run.metadata, (current) => ({ ...current, delivery: { ...(current.delivery ?? {}), mode: foreground ? "foreground" : "background", state: foreground ? "attached" : "pending" } }));
+    scheduler.updateRunLimit(run.store.runId, snapshot.settings.concurrency);
+    scheduler.setRunExtensionSettings(run.store.runId, snapshot.settings.extensionSettings);
+    const roles = resumeRoles(run.store, persistedSnapshot, run.store.cwd, trustedProject);
+    run.executor = createAgentExecutor({ cwd: run.store.cwd, model: rootModel, tools: activeSnapshotTools(snapshot.tools, "session"), resourceSelectors: currentPolicy.effective, extensionSettings: snapshot.settings.extensionSettings, availableModels, knownModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: roles.definitions, runStore: run.store, providerPause: async () => { deliver(`Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentResourcePolicy: frozenResourcePolicy(currentPolicy) });
+    const drift = aliasDrift(previousAliases, currentAliases);
+    if (drift.length) await run.store.appendEvent({ type: "warning", message: `Model alias mappings changed on resume: ${drift.join("; ")}` });
+    const runContext = workflowRunContext(run.store.cwd, run.store.sessionId, run.store.runId, loaded.snapshot.metadata, loaded.snapshot.args, controller.signal);
+    run.executor.setRunContext(runContext);
+    await scheduler.cancelRun(run.store.runId);
+    await run.lifecycle.resume();
+    const execution = runWorkflow(script, loaded.snapshot.args, withWorkflowFunctions({ shell: (command, options, signal, identity) => shellForRun(run.store, run.metadata, run.lifecycle, command, options, signal, identity), agent: workflowAgentHandler(run.store, run.metadata, run.lifecycle, run.executor, run.store.cwd, run.store.runId, roles.capture), worktree: async (owner) => resolveWorktree(run.store, run.metadata, owner), checkpoint: checkpointBridge(run.store.runId, run.store, run.metadata, foreground, hasUI ? ui : undefined), phase: phaseBridge(run.store, run.metadata, run.lifecycle), log: logBridge(run.store, run.lifecycle, run.metadata.name) }, run.store, runContext, registry, snapshot.settings.extensionSettings), controller.signal);
+    run.execution = execution;
+    const completion = execution.result.then(async (value) => {
+      await scheduler.flush(run.store.runId);
+      if (run.budget.hardExhausted) throw new WorkflowError("BUDGET_EXHAUSTED", "Budgeted work was attempted after hard exhaustion");
+      const resultPath = await run.store.saveResult(value);
+      const resultBytes = await run.store.resultBytes();
+      await run.lifecycle.terminal("completed", "completed");
+      await eventPublisher.runCompleted(run.store, run.metadata, resultPath);
+      return { value, resultPath, resultBytes };
+    }).catch(async (error: unknown) => {
+      await scheduler.flush(run.store.runId);
+      const typed = error instanceof WorkflowError ? error : new WorkflowError(errorCode(error) ?? "INTERNAL_ERROR", errorText(error));
+      if (!isExternallyEndedRunState(run.lifecycle.state)) await run.lifecycle.terminal(typed.code === "BUDGET_EXHAUSTED" ? "budget_exhausted" : "failed", typed.code);
+      const persisted = await persistRunState(run.store, run.metadata, (current) => persistedFailure({ ...current, ...run.budget.snapshot() }, typed));
+      const ended = run.lifecycle.state;
+      const state = isExternallyEndedRunState(ended) ? ended : "failed";
+      if (state === "failed") retryReservations.delete(persisted.retry?.lineageRootRunId ?? run.store.runId);
+      await eventPublisher.runFailed(run.store, run.metadata, typed, state);
+      run.update?.(workflowToolUpdate(persisted));
+      if (state === "failed") { const diagnostic = await createWorkflowFailureDiagnostics(run.store, run.metadata, typed, persisted); markWorkflowFailureDiagnostics(typed, diagnostic); }
+      throw typed;
+    }).finally(() => cleanupTerminalRun(run.store.runId));
+    run.completion = completion;
+    if (!foreground || !waitForCompletion) {
+      void completion.then(async (result) => {
+        await deliverTerminal(run.store, async () => (await completionDeliveryFromStore({ mode: "background", name: run.metadata.name, runId: run.store.runId, value: result.value, resultPath: result.resultPath, resultBytes: result.resultBytes, store: run.store, ...(context === undefined ? {} : { context: context.deliveryContext }) })).content);
+      }, async (error: unknown) => {
+        const diagnostic = failureDiagnosticsFrom(error);
+        await deliverTerminal(run.store, diagnostic ? formatWorkflowFailureDelivery(diagnostic) : formatWorkflowFailureDeliveryFallback(run.metadata.name, run.store.runId, run.store.directory, error), true);
+      });
+      return undefined;
+    }
+    const markDelivered = () => run.store.updateState((current) => current.delivery?.mode === "foreground" && (current.delivery.state === "attached" || current.delivery.state === "pending") ? { ...current, delivery: { ...current.delivery, state: "delivered" } } : current);
+    try {
+      const result = await completion;
+      await markDelivered();
+      const completionResult = await completionDeliveryFromStore({ mode: "foreground", name: run.metadata.name, runId: run.store.runId, value: result.value, resultPath: result.resultPath, resultBytes: result.resultBytes, store: run.store, ...(context === undefined ? {} : { context: context.deliveryContext }) });
+      return { ...result, completion: completionResult };
+    } catch (error) {
+      await markDelivered();
+      throw error;
+    }
+  };
+  const applyBudgetDecision = async (request: BudgetApprovalRequest, approved: boolean, context?: unknown, signal?: AbortSignal, waitForCompletion = true): Promise<BudgetDecisionResult> => {
+    const run = runs.get(request.runId);
+    if (!run) throw new WorkflowError("RESUME_INCOMPATIBLE", `Unknown workflow run: ${request.runId}`);
+    if (!approved) return { state: "budget_exhausted", approved: false };
+    const nextBudget = validateBudget(request.proposed);
+    const nextVersion = request.budgetVersion + 1;
+    const runtime = new WorkflowBudgetRuntime(nextBudget, nextVersion, request.consumed, run.budget.events, { active: false });
+    run.budget = runtime;
+    await persistRunState(run.store, run.metadata, (current) => { const next = { ...current, ...runtime.snapshot(), budgetVersion: nextVersion }; if (nextBudget) next.budget = nextBudget; else delete next.budget; return next; });
+    const { hasUI, ui } = recoveryUi(context);
+    const completed = await coldResumeRun(run, hasUI, ui, projectTrusted(context), { ...resumeHostContext(context), ...(signal ? { signal } : {}) }, request.foreground, waitForCompletion);
+    if (completed) return { state: "completed", approved: true, value: completed.value, run: (await run.store.load()).run, completion: completed.completion };
+    return { state: "running", approved: true };
+  };
+  const resumeWorkflowRun = async (runId: string, rawPatch?: unknown, context?: unknown, signal?: AbortSignal, modeOverride?: boolean, waitForCompletion = true, expectedState?: string): Promise<Record<string, JsonValue>> => {
+    const run = runs.get(runId);
+    if (!run) {
+      const { cwd, sessionId } = hostSessionContext(context);
+      if (cwd && sessionId) {
+        try {
+          const state = (await new RunStore(cwd, sessionId, runId, home).load()).run.state;
+          assertExpectedWorkflowState(expectedState, state);
+          throw new WorkflowError("RESUME_INCOMPATIBLE", workflowRecoveryGuidance("resume", state));
+        } catch (error) {
+          if (error instanceof WorkflowError) throw error;
+        }
+      }
+      throw new WorkflowError("RESUME_INCOMPATIBLE", `Unknown workflow run ${runId} in the current project and Pi session`);
+    }
+    const loaded = await run.store.load();
+    assertExpectedWorkflowState(expectedState, loaded.run.state);
+    if (loaded.run.state !== "budget_exhausted") throw new WorkflowError("RESUME_INCOMPATIBLE", workflowRecoveryGuidance("resume", loaded.run.state));
+    const currentBudget = validateBudget(loaded.run.budget ?? loaded.snapshot.budget);
+    const patch = rawPatch === undefined ? {} : validateBudgetPatch(rawPatch);
+    const nextBudget = mergeBudget(currentBudget, patch);
+    const usage = budgetUsage(loaded.run.usage);
+    if (!resumeBudgetAllowed(nextBudget, usage)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Every exhausted hard budget must be raised above retained usage or removed");
+    if (budgetRelaxed(currentBudget, nextBudget)) {
+      const proposalId = randomUUID();
+      const request: BudgetApprovalRequest = { kind: "budget", proposalId, runId, consumed: usage, previous: currentBudget ?? {}, proposed: nextBudget ?? {}, budgetVersion: loaded.run.budgetVersion ?? 1, ...(modeOverride === undefined ? {} : { foreground: modeOverride }) };
+      await run.store.requestWorkflowDecision(request);
+      await appendBudgetDecisionEvent(run, request, "adjustment_requested");
+      deliver(budgetDecisionDelivery(run.metadata, request));
+      return { state: "awaiting_approval", proposalId };
+    }
+    const changed = JSON.stringify(currentBudget ?? {}) !== JSON.stringify(nextBudget ?? {});
+    if (changed) {
+      const nextVersion = (loaded.run.budgetVersion ?? 1) + 1;
+      const runtime = new WorkflowBudgetRuntime(nextBudget, nextVersion, usage, loaded.run.budgetEvents, { active: false });
+      run.budget = runtime;
+      await persistRunState(run.store, run.metadata, (current) => { const next = { ...current, ...runtime.snapshot(), budgetVersion: nextVersion }; if (nextBudget) next.budget = nextBudget; else delete next.budget; return next; });
+    }
+    const { hasUI, ui } = recoveryUi(context);
+    const completed = await coldResumeRun(run, hasUI, ui, projectTrusted(context), { ...resumeHostContext(context), ...(signal ? { signal } : {}) }, modeOverride, waitForCompletion);
+    if (completed) {
+      const persistedRun = structuredClone((await run.store.load()).run);
+      if (!jsonValue(persistedRun)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Persisted run is not JSON-compatible");
+      return { state: "completed", runId, value: completed.value, run: persistedRun, completion: { content: completed.completion.content, inlined: completed.completion.inlined } };
+    }
+    return { state: "running" };
+  };
+  const retryReservations = new Set<string>();
+  type PreparedRetryWorkflowRun = { childRun: WorkflowRunRecord; parentRunId: string; lineageRootRunId: string; concurrency: number; extensionSettings?: Readonly<WorkflowExtensionSettings>; hostModel: { provider: string; id: string }; modelRegistry: WorkflowRecoveryContext["modelRegistry"]; currentAliases: Readonly<Record<string, string>>; blockedAliases: ReadonlySet<string>; blockedAliasTargets: Readonly<Record<string, string>> };
+  const retryWorkflowRunUnlocked = async (runId: string, context: unknown, signal?: AbortSignal, expectedState?: string): Promise<PreparedRetryWorkflowRun> => {
+    if (typeof runId !== "string" || !runId.trim()) throw new WorkflowError("RESUME_INCOMPATIBLE", "workflow_retry requires an explicit run ID");
+    const host = object(context) ? context : {};
+    const { cwd, sessionId } = hostSessionContext(context);
+    if (!cwd || !sessionId) throw new WorkflowError("RESUME_INCOMPATIBLE", "workflow_retry requires the current project and Pi session");
+    await ensureSessionLease(cwd, sessionId);
+    const sourceStore = new RunStore(cwd, sessionId, runId, home);
+    let loaded: { run: PersistedRun; snapshot: Readonly<LaunchSnapshot> };
+    try { loaded = await sourceStore.load(); } catch (error) { throw new WorkflowError("RESUME_INCOMPATIBLE", `Unknown workflow run ${runId} in the current project and Pi session: ${errorText(error)}`); }
+    assertExpectedWorkflowState(expectedState, loaded.run.state);
+    if (loaded.run.state !== "failed") throw new WorkflowError("RESUME_INCOMPATIBLE", workflowRecoveryGuidance("retry", loaded.run.state));
+    // decodeRetry() already guarantees the field shapes; only the semantic constraints remain to check here.
+    if (loaded.run.retry && (!loaded.run.retry.sourceRunId || !loaded.run.retry.lineageRootRunId)) throw new WorkflowError("RESUME_INCOMPATIBLE", "The source retry provenance is incomplete");
+    const lineageRootRunId = loaded.run.retry?.lineageRootRunId ?? loaded.run.id;
+    if (retryReservations.has(lineageRootRunId)) throw new WorkflowError("RESUME_INCOMPATIBLE", `An active retry already owns lineage ${lineageRootRunId}`);
+    const activeStates = new Set<RunState>(["queued", "running", "pausing", "paused", "awaiting_input", "interrupted", "budget_exhausted"]);
+    for (const candidateId of await listRunIds(cwd, sessionId, home)) {
+      if (candidateId === runId) continue;
+      const candidate = new RunStore(cwd, sessionId, candidateId, home);
+      try {
+        const candidateRun = (await candidate.load()).run;
+        if (activeStates.has(candidateRun.state) && candidateRun.retry?.lineageRootRunId === lineageRootRunId) throw new WorkflowError("RESUME_INCOMPATIBLE", `An active retry child already exists for source lineage ${lineageRootRunId}`);
+      } catch (error) {
+        if (error instanceof WorkflowError && error.code === "RESUME_INCOMPATIBLE") throw error;
+      }
+    }
+    retryReservations.add(lineageRootRunId);
+    let childCreated = false;
+    try {
+      const trustedProject = projectTrusted(context);
+      await sourceStore.validateRetrySource();
+      await sourceStore.validateBorrowedWorktrees();
+      assertResumableSnapshot(loaded.snapshot, trustedProject);
+      const modelRegistry = resumeHostContext(context).modelRegistry;
+      const hostModel = object(host.model) && typeof host.model.provider === "string" && typeof host.model.id === "string" ? { provider: host.model.provider, id: host.model.id } : { provider: "", id: "" };
+      const rootModel: ModelSpec = { provider: hostModel.provider, model: hostModel.id, thinking: pi.getThinkingLevel() };
+      const { active, settingsPath, currentPolicy, knownModels, availableModels, currentAliases, blockedAliases, blockedAliasTargets, snapshot: childBaseSnapshot } = await resolveLaunchPrologue({ snapshot: loaded.snapshot, cwd, trustedProject, rootModel, ...(modelRegistry ? { modelRegistry } : {}), signal: signal ?? new AbortController().signal, withPreflight: true });
+      await sourceStore.validateNamedWorktrees();
+      for (const name of loaded.run.retry?.namedWorktrees ?? []) await sourceStore.resolveNamedWorktree(name);
+      const completedPaths = (await sourceStore.replayableOperations()).map(({ path }) => path);
+      const incompletePaths = incompleteRetryPaths([...(loaded.run.retry?.incompletePaths ?? []), ...loaded.run.agents.filter((agent) => agent.state !== "completed").map((agent) => operationPath("agent", ...(agent.structuralPath ?? [])))], completedPaths);
+      const namedWorktrees = [...new Set([...(loaded.run.retry?.namedWorktrees ?? []), ...(await sourceStore.worktrees()).filter(({ owner }) => owner.startsWith(`${operationPath("worktree", "named")}/`)).map(({ owner }) => decodeURIComponent(owner.split("/").at(-1) ?? owner))])];
+      const budget = validateBudget(loaded.run.budget ?? loaded.snapshot.budget);
+      const childRunId = randomUUID();
+      const childStore = new RunStore(cwd, sessionId, childRunId, home);
+      const childBudget = new WorkflowBudgetRuntime(budget, loaded.run.budgetVersion ?? 1, loaded.run.usage, loaded.run.budgetEvents);
+      const childInitialBudget = childBudget.snapshot();
+      const retry: WorkflowRetryProvenance = { sourceRunId: loaded.run.id, lineageRootRunId, completedPaths, incompletePaths, namedWorktrees };
+      await childStore.create({ id: childRunId, workflowName: loaded.snapshot.metadata.name, cwd, sessionId, state: "interrupted", parentRunId: loaded.run.id, retry, agents: [], agentSessions: [], ...(budget ? { budget } : {}), budgetVersion: loaded.run.budgetVersion ?? 1, ...childInitialBudget }, childBaseSnapshot);
+      const model = modelSpec(loaded.snapshot.models[0] ?? "", rootModel);
+      const lifecycle = lifecycleFor(childStore, "interrupted", loaded.snapshot.metadata);
+      const abortController = new AbortController();
+      const providerErrorRecovery = createProviderErrorRecovery(context, availableModels, () => { abortController.abort(); });
+      const providerPause = async () => { deliver(`Workflow ${loaded.snapshot.metadata.name} paused: provider limit.`); await lifecycle.providerPause(); };
+      const childRun: WorkflowRunRecord = { executor: createAgentExecutor({ cwd, model, tools: activeSnapshotTools(loaded.snapshot.tools, active), resourceSelectors: currentPolicy.effective, extensionSettings: childBaseSnapshot.settings.extensionSettings, availableModels, knownModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: loaded.snapshot.roles ?? {}, runStore: childStore, providerPause, agentResourcePolicy: frozenResourcePolicy(currentPolicy) }), store: childStore, metadata: loaded.snapshot.metadata, model, lifecycle, budget: childBudget, abortController, projectTrusted: () => projectTrusted(context), checkpointResolvers: new Map(), ...(providerErrorRecovery ? { providerErrorRecovery } : {}) };
+      runs.set(childRunId, childRun);
+      childCreated = true;
+      return { childRun, parentRunId: loaded.run.id, lineageRootRunId, concurrency: loaded.snapshot.settings.concurrency, ...(childBaseSnapshot.settings.extensionSettings === undefined ? {} : { extensionSettings: childBaseSnapshot.settings.extensionSettings }), hostModel, modelRegistry, currentAliases, blockedAliases, blockedAliasTargets };
+    } finally {
+      if (!childCreated) retryReservations.delete(lineageRootRunId);
+    }
+  };
+  const retryWorkflowRun = async (runId: string, context: unknown, signal?: AbortSignal, modeOverride?: boolean, expectedState?: string): Promise<{ runId: string; parentRunId: string; state: "running" | "completed"; value?: JsonValue; run?: PersistedRun; completion?: CompletionDeliveryResult }> => {
+    const prepared = await coordinateRunMutation(() => retryWorkflowRunUnlocked(runId, context, signal, expectedState));
+    let childStarted = false;
+    try {
+      scheduler.addRun(prepared.childRun.store.runId, prepared.concurrency, () => { prepared.childRun.budget.checkAgentLaunch(); }, prepared.extensionSettings);
+      await eventPublisher.runStarted(prepared.childRun.store, prepared.childRun.metadata);
+      const { hasUI, ui } = recoveryUi(context);
+      const recoveryContext = resumeHostContext(context);
+      const completed = await coldResumeRun(prepared.childRun, hasUI, ui, projectTrusted(context), { model: prepared.hostModel, modelRegistry: prepared.modelRegistry, deliveryContext: recoveryContext.deliveryContext, resolvedAliases: prepared.currentAliases, blockedAliases: prepared.blockedAliases, blockedAliasTargets: prepared.blockedAliasTargets, ...(signal ? { signal } : {}) }, modeOverride);
+      const completion = runs.get(prepared.childRun.store.runId)?.completion;
+      if (completion) {
+        childStarted = true;
+        void completion.then(() => { retryReservations.delete(prepared.lineageRootRunId); }, () => { retryReservations.delete(prepared.lineageRootRunId); });
+      } else if (completed) {
+        childStarted = true;
+        retryReservations.delete(prepared.lineageRootRunId);
+      }
+      if (completed) return { runId: prepared.childRun.store.runId, parentRunId: prepared.parentRunId, state: "completed", value: completed.value, run: (await prepared.childRun.store.load()).run, completion: completed.completion };
+      return { runId: prepared.childRun.store.runId, parentRunId: prepared.parentRunId, state: "running" };
+    } finally {
+      if (!childStarted) retryReservations.delete(prepared.lineageRootRunId);
+    }
+  };
+  return { refreshPausedRunAliases, coldResumeRun, applyBudgetDecision, answerBudgetDecision, budgetDecisionDelivery, resumeWorkflowRun, retryWorkflowRun };
+}