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

package/dist/src/host-recovery.js

@@ -0,0 +1,356 @@
+import { randomUUID } from "node:crypto";
+import { listRunIds, RunStore, structuralPath as operationPath } 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 } from "./types.js";
+import { hostSessionContext, withWorkflowFunctions, withoutActiveShells, workflowRunContext } from "./host-runtime.js";
+import { runWorkflow } from "./execution.js";
+import { createWorkflowFailureDiagnostics, formatWorkflowFailureDelivery, formatWorkflowFailureDeliveryFallback, failureDiagnosticsFrom, completionDeliveryFromStore, incompleteRetryPaths, markWorkflowFailureDiagnostics, workflowFailedAt } from "./host-delivery.js";
+function workflowRecoveryGuidance(action, state) {
+    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, trustedProject) {
+    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, actualState) {
+    if (expectedState !== undefined && expectedState !== actualState)
+        throw new WorkflowError("RESUME_INCOMPATIBLE", `Workflow run state changed: expected state ${expectedState}, actual state ${actualState}`);
+}
+export function persistedFailure(run, error) { const failedAt = workflowFailedAt(error); return { ...run, error: { code: error.code, message: error.message, ...(failedAt ? { failedAt } : {}) }, ...(failedAt ? { failedAt } : {}) }; }
+export function createWorkflowRecovery(deps) {
+    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 ?? ((task) => task());
+    const budgetDecisionDelivery = (metadata, request) => `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, request, type) => {
+        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, proposalId, approved, silent = false, context, signal, waitForCompletion = true) => {
+        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, context) => {
+        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) => {
+        const host = object(context) ? context : undefined;
+        const ui = host && object(host.ui) ? host.ui : {};
+        return { hasUI: host?.hasUI === true, ui };
+    };
+    const coldResumeRun = async (run, hasUI, ui, trustedProject, context, modeOverride, waitForCompletion = true) => {
+        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) => {
+            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) => {
+                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, approved, context, signal, waitForCompletion = true) => {
+        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, rawPatch, context, signal, modeOverride, waitForCompletion = true, expectedState) => {
+        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 = { 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();
+    const retryWorkflowRunUnlocked = async (runId, context, signal, expectedState) => {
+        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;
+        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(["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 = { 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 = { 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 = { 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, context, signal, modeOverride, expectedState) => {
+        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 };
+}

package/dist/src/host-runtime.d.ts

@@ -0,0 +1,78 @@
+import { type AgentProviderFailure, type AgentProviderRecovery, WorkflowAgentExecutor } from "./agent-execution.js";
+import { type WorkflowBudgetRuntime } from "./budget.js";
+import { type PersistedRun, type RunStore, type WorktreeReference } from "./persistence.js";
+import { type WorkflowRegistryApi } from "./registry.js";
+import { type AgentRecord, type BudgetEvent, type JsonValue, type ModelSpec, type RunState, type WorkflowBridge, type WorkflowCheckpointState, type WorkflowExecution, type WorkflowExtensionSettings, type WorkflowMetadata, type WorkflowRunContext } from "./types.js";
+export type WorkflowEventSink = {
+    emit: (name: string, payload: unknown) => unknown;
+};
+export type WorkflowToolUpdate = {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    details: {
+        runId: string;
+        run: PersistedRun;
+    };
+};
+export type WorkflowRunRecord = {
+    executor: WorkflowAgentExecutor;
+    store: RunStore;
+    metadata: WorkflowMetadata;
+    model: ModelSpec;
+    lifecycle: RunLifecycle;
+    budget: WorkflowBudgetRuntime;
+    abortController: AbortController;
+    projectTrusted: () => boolean;
+    providerErrorRecovery?: (failure: AgentProviderFailure) => Promise<AgentProviderRecovery>;
+    execution?: WorkflowExecution;
+    completion?: Promise<unknown>;
+    foreground?: boolean;
+    checkpointResolvers: Map<string, (value: boolean) => void>;
+    update?: (result: WorkflowToolUpdate) => void;
+};
+/** Drops the transient shell-activity counters a run only holds while its host process is alive. */
+export declare function withoutActiveShells(run: PersistedRun): PersistedRun;
+/** Reads the project cwd and Pi session ID that an extension context exposes, when present. */
+export declare function hostSessionContext(context: unknown): {
+    cwd?: string;
+    sessionId?: string;
+};
+export declare class RunLifecycle {
+    #private;
+    private readonly changed?;
+    constructor(state?: RunState, changed?: ((state: RunState, previousState: RunState, reason?: string) => void | Promise<void>) | undefined);
+    get state(): RunState;
+    enter(): Promise<void>;
+    leave(): Promise<void>;
+    enterAwaitingInput(): Promise<void>;
+    resolveAwaitingInput(): Promise<void>;
+    pause(): Promise<void>;
+    /** Resumes a paused, interrupted, or budget-exhausted run; on a `pausing` run it cancels the pending pause instead. */
+    resume(): Promise<void>;
+    providerPause(): Promise<void>;
+    terminal(state: "completed" | "failed" | "stopped" | "interrupted" | "budget_exhausted", reason?: string): Promise<void>;
+}
+export declare class WorkflowEventPublisher {
+    #private;
+    private readonly sink;
+    constructor(sink: WorkflowEventSink | undefined);
+    removeRun(runId: string): void;
+    seedBudget(runId: string, events: readonly BudgetEvent[] | undefined): void;
+    runStarted(store: RunStore, metadata: WorkflowMetadata): Promise<void>;
+    runResumed(store: RunStore, metadata: WorkflowMetadata): Promise<void>;
+    runState(store: RunStore, metadata: WorkflowMetadata, previousState: RunState, state: RunState, reason?: string): Promise<void>;
+    runCompleted(store: RunStore, metadata: WorkflowMetadata, resultPath: string): Promise<void>;
+    runFailed(store: RunStore, metadata: WorkflowMetadata, error: unknown, state: "failed" | "stopped" | "interrupted" | "budget_exhausted"): Promise<void>;
+    agentState(store: RunStore, metadata: WorkflowMetadata, previous: AgentRecord | undefined, agent: AgentRecord): Promise<void>;
+    agentStates(store: RunStore, metadata: WorkflowMetadata, previous: readonly AgentRecord[], current: readonly AgentRecord[]): Promise<void>;
+    phase(store: RunStore, metadata: WorkflowMetadata, previousPhase: string | undefined, phase: string): Promise<void>;
+    checkpoint(store: RunStore, metadata: WorkflowMetadata, name: string, state: WorkflowCheckpointState): Promise<void>;
+    budget(store: RunStore, metadata: WorkflowMetadata, run: Pick<PersistedRun, "budgetEvents">): Promise<void>;
+    worktree(store: RunStore, metadata: WorkflowMetadata, worktree: WorktreeReference): Promise<void>;
+    private budgetKey;
+}
+export declare function workflowRunContext(cwd: string, sessionId: string, runId: string, workflow: WorkflowMetadata, args: JsonValue, signal: AbortSignal): Readonly<WorkflowRunContext>;
+export declare function nextNamedOccurrence(counters: Map<string, number>, label: string): string;
+export declare function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runContext: Readonly<WorkflowRunContext>, registry: WorkflowRegistryApi, settings?: Readonly<WorkflowExtensionSettings>): WorkflowBridge;