usesteady 0.1.0-alpha.1

package/dist/src/workflow/coordinator.js

@@ -0,0 +1,682 @@
+/**
+ * Phase 9C: Workflow coordinator.
+ *
+ * ── Purpose ───────────────────────────────────────────────────────────────────
+ *
+ *   Sequences CursorProductSession and ClaudeProductSession instances,
+ *   one at a time, through a human-authored list of task specs.
+ *
+ * ── What this is NOT (W1) ─────────────────────────────────────────────────────
+ *
+ *   NOT authority — calls session functions; makes no decisions.
+ *   NOT a planner — task specs are fixed at definition time; none are derived.
+ *   NOT a retry engine — retry creates a new session; H re-approves every time.
+ *   NOT a batch approver — each session requires explicit H approval (W2).
+ *   NOT stateful — all functions return new WorkflowRun objects.
+ *
+ * ── Function contract ─────────────────────────────────────────────────────────
+ *
+ *   createWorkflowRun(spec)               → "reviewing"
+ *   startWorkflow(run, ...)              → "task_ready" | "task_conflict" | "completed"
+ *   cancelWorkflow(run)                  → "stopped" (no session created)
+ *   advanceWorkflow(run, ...)             → "task_ready" | "task_conflict" | "completed"
+ *   acceptWorkflowConflict(run)           → "task_ready"
+ *   confirmWorkflowTask(run, yes)         → "task_approved" | "task_failed"
+ *   deliverWorkflowTask(run, ...)         → "running" | "task_scope" | "task_failed"
+ *   answerWorkflowScope(run, idx, ...)    → "task_approved" (→ call deliverWorkflowTask)
+ *   applyFailureAction(run, action, ...)  → "running" | "stopped"
+ *
+ * ── Shell loop ─────────────────────────────────────────────────────────────────
+ *
+ *   run = createWorkflowRun(spec)            // → "reviewing"
+ *   // (H confirms pre-flight list)
+ *   run = startWorkflow(run, ...)           // → "task_ready" | "task_conflict"
+ *   while (!isWorkflowTerminal(run)):
+ *     if "task_conflict": run = acceptWorkflowConflict(run)  // or reject
+ *     if "task_ready":    run = confirmWorkflowTask(run, yes)
+ *     if "task_approved": run = await deliverWorkflowTask(run, ...)
+ *     if "task_scope":    run = await answerWorkflowScope(run, idx, ...)
+ *                         run = await deliverWorkflowTask(run, ...)
+ *     if "task_failed":   run = applyFailureAction(run, action)
+ *     if "running":       run = advanceWorkflow(run, ...)
+ *
+ * ── Authority invariants (W1–W8) ──────────────────────────────────────────────
+ *
+ *   W2: confirmWorkflowTask(yes) → calls approve() only. deliverWorkflowTask
+ *       is a separate explicit call. The coordinator never auto-delivers.
+ *   W3: applyFailureAction("retry") creates a new session; never resumes.
+ *   W6: applyOCDOverride() adds to prohibited globs; never removes.
+ *   W7: task spec inputs are read-only; never modified after createWorkflowRun.
+ *   W8: runtime is taken from task spec; never derived or converted.
+ *
+ * See: docs/phase-9b-workflow-design.md
+ */
+import { createHash } from "node:crypto";
+// ─── Product session imports ──────────────────────────────────────────────────
+import { createSession, submit, approve, reject, acceptConflict, answerScope, deliver, } from "../product/cursor-product-session.js";
+import { createClaudeSession, submitClaude, approveClaude, rejectClaude, acceptClaudeConflict, answerClaudeScope, deliverClaude, } from "../product/claude-product-session.js";
+import { parseChange } from "../understand/interpretation/parser.js";
+import { isFsChange } from "../understand/interpretation/types.js";
+import { createWorkflowRunEnvelope } from "../ucp/envelope.js";
+import { persistEnvelope } from "../ucp/persistence/index.js";
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+const DEFAULT_MAX_RETRIES = 2;
+function taskLabel(t) {
+    return t.spec.label ?? t.spec.input.slice(0, 60);
+}
+function runtimeFor(run, index) {
+    // W8: runtime comes from spec only. Never derived from content.
+    return run.spec.tasks[index]?.runtime ?? run.spec.defaultRuntime ?? "cursor";
+}
+function maxRetries(run) {
+    return run.spec.maxRetries ?? DEFAULT_MAX_RETRIES;
+}
+function applyOCDOverride(base, override) {
+    // W6: can only add prohibited globs, never remove.
+    if (!override || override.additionalProhibitedGlobs.length === 0)
+        return base;
+    return {
+        ...base,
+        alwaysProhibitedGlobs: [
+            ...base.alwaysProhibitedGlobs,
+            ...override.additionalProhibitedGlobs,
+        ],
+    };
+}
+// ─── FS operation helpers ──────────────────────────────────────────────────────
+/**
+ * Build an FsChange from a structured WorkflowTaskSpec (when operationType is set).
+ * Returns undefined if the spec fields are incomplete for the given operation.
+ */
+function buildFsChangeFromSpec(spec) {
+    switch (spec.operationType) {
+        case "create_dir": {
+            const p = spec.targetFiles?.[0];
+            return p ? { operationType: "create_dir", dirPath: p } : undefined;
+        }
+        case "write_file": {
+            const p = spec.targetFiles?.[0];
+            return p !== undefined && spec.content !== undefined
+                ? { operationType: "write_file", filePath: p, content: spec.content }
+                : undefined;
+        }
+        case "rename": {
+            const p = spec.targetFiles?.[0];
+            return p !== undefined && spec.newPath !== undefined
+                ? { operationType: "rename", filePath: p, newPath: spec.newPath }
+                : undefined;
+        }
+        case "delete_file": {
+            const p = spec.targetFiles?.[0];
+            return p ? { operationType: "delete_file", filePath: p } : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+function fsOpHeadline(op, taskNum) {
+    switch (op.operationType) {
+        case "create_dir": return `Task ${taskNum}: Create directory ${op.dirPath}`;
+        case "write_file": return `Task ${taskNum}: Create file ${op.filePath}`;
+        case "rename": return `Task ${taskNum}: Rename ${op.filePath} → ${op.newPath}`;
+        case "delete_file": return `Task ${taskNum}: Delete ${op.filePath}`;
+    }
+}
+function applyClaudeOCDOverride(base, override) {
+    // W6: can only add prohibited globs, never remove.
+    if (!override || override.additionalProhibitedGlobs.length === 0)
+        return base;
+    return {
+        ...base,
+        alwaysProhibitedGlobs: [
+            ...base.alwaysProhibitedGlobs,
+            ...override.additionalProhibitedGlobs,
+        ],
+    };
+}
+function deriveWorkflowRunId(spec) {
+    const content = JSON.stringify({ name: spec.name, tasks: spec.tasks });
+    return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+// ─── Display builders ─────────────────────────────────────────────────────────
+function buildDisplay(run, headline, extras = {}) {
+    const total = run.spec.tasks.length;
+    const current = run.currentIndex + 1;
+    const progress = `Task ${Math.min(current, total)} of ${total}`;
+    const currentTask = run.spec.tasks[run.currentIndex];
+    const currentLabel = currentTask
+        ? (currentTask.label ?? currentTask.input.slice(0, 60))
+        : undefined;
+    const taskSummary = run.tasks
+        .filter(t => t.outcome !== "pending")
+        .map(t => ({ index: t.index, label: taskLabel(t), outcome: t.outcome }));
+    return {
+        headline,
+        progress,
+        ...(currentLabel !== undefined ? { currentLabel } : {}),
+        ...(taskSummary.length > 0 ? { taskSummary } : {}),
+        ...(extras.failureNote ? { failureNote: extras.failureNote } : {}),
+    };
+}
+// ─── Task array helpers ───────────────────────────────────────────────────────
+function updateTask(tasks, index, updater) {
+    return tasks.map((t, i) => (i === index ? updater(t) : t));
+}
+function mk(phase, base, overrides) {
+    const merged = { ...base, phase, ...overrides };
+    // Filter undefined values when explicitly clearing currentSession or currentFsOp.
+    if ("currentSession" in overrides || "currentFsOp" in overrides) {
+        return Object.fromEntries(Object.entries(merged).filter(([, v]) => v !== undefined));
+    }
+    return merged;
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Create a new WorkflowRun from a spec.
+ *
+ * The run begins in "reviewing" phase (Phase 11D / WF-R1).
+ * No session is created until H explicitly starts the workflow via startWorkflow().
+ *
+ * WF-R2: currentSession is absent in "reviewing".
+ *
+ * @param opts.mode             "break_glass" to skip per-step human confirm (BG-1).
+ * @param opts.breakGlassReason Required when mode is "break_glass" (BG-4).
+ *                              Recorded in audit permanently (BG-3).
+ */
+export function createWorkflowRun(spec, opts) {
+    const tasks = spec.tasks.map((s, i) => ({
+        index: i,
+        spec: s,
+        outcome: "pending",
+        retryCount: 0,
+    }));
+    const display = buildDisplay({ spec, tasks, currentIndex: 0 }, `Workflow "${spec.name}" ready. ${spec.tasks.length} task(s).`);
+    const mode = opts?.mode ?? "normal";
+    const breakGlassReason = opts?.breakGlassReason;
+    return {
+        phase: "reviewing",
+        workflowRunId: deriveWorkflowRunId(spec),
+        spec,
+        tasks,
+        currentIndex: 0,
+        display,
+        ...(mode !== "normal" ? { mode } : {}),
+        ...(breakGlassReason ? { breakGlassReason } : {}),
+    };
+}
+// ─── startWorkflow ────────────────────────────────────────────────────────────
+/**
+ * Confirm the pre-flight review and start executing the first task.
+ *
+ * WF-R3: the only path out of "reviewing" into execution.
+ *
+ * Transitions "reviewing" → "idle" → immediately calls advanceWorkflow to
+ * prepare the first task. Returns the same result advanceWorkflow would:
+ * "task_ready" | "task_conflict" | "completed" (if all tasks auto-skip).
+ *
+ * Valid from "reviewing" only; no-op from any other phase.
+ */
+export function startWorkflow(run, cursorPolicy, claudeOCDPolicy, claudeToolPolicy) {
+    if (run.phase !== "reviewing")
+        return run;
+    // Transition to "idle" (internal phase) without touching tasks or sessions.
+    const idleRun = { ...run, phase: "idle" };
+    return advanceWorkflow(idleRun, cursorPolicy, claudeOCDPolicy, claudeToolPolicy);
+}
+// ─── cancelWorkflow ───────────────────────────────────────────────────────────
+/**
+ * Cancel the workflow at the pre-flight stage.
+ *
+ * H declined to start. No session was ever created (WF-R1).
+ * Transitions "reviewing" → "stopped" cleanly.
+ *
+ * Valid from "reviewing" only; no-op from any other phase.
+ */
+export function cancelWorkflow(run) {
+    if (run.phase !== "reviewing")
+        return run;
+    const display = buildDisplay(run, `Workflow "${run.spec.name}" cancelled before start.`);
+    return mk("stopped", run, { currentSession: undefined, display });
+}
+// ─── Terminal guard ───────────────────────────────────────────────────────────
+export function isWorkflowTerminal(run) {
+    return run.phase === "completed" || run.phase === "stopped";
+}
+// ─── advanceWorkflow ──────────────────────────────────────────────────────────
+/**
+ * Advance the workflow to the next task.
+ *
+ * Called when phase is "idle" or "running".
+ *
+ * Creates a new session for the current task spec, submits the task input,
+ * and transitions to "task_ready", "task_conflict", or "completed".
+ *
+ * Auto-skips tasks where intake returns a non-execute mode ("skipped_by_intake").
+ * This is the V1 default policy for non-execute inputs (see Phase 9B design).
+ *
+ * @param cursorPolicy    Workspace Cursor OCD policy (workflow override is applied internally).
+ * @param claudeOCDPolicy Workspace Claude OCD policy (workflow override is applied internally).
+ * @param claudeToolPolicy Claude tool policy.
+ */
+export function advanceWorkflow(run, cursorPolicy, claudeOCDPolicy, claudeToolPolicy) {
+    if (isWorkflowTerminal(run))
+        return run;
+    // "reviewing" is guarded here (WF-R3): only startWorkflow() may exit reviewing.
+    if (run.phase !== "idle" && run.phase !== "running")
+        return run;
+    // All tasks exhausted.
+    if (run.currentIndex >= run.spec.tasks.length) {
+        const display = buildDisplay(run, `Workflow "${run.spec.name}" completed.`);
+        return mk("completed", run, { display });
+    }
+    const idx = run.currentIndex;
+    const runtime = runtimeFor(run, idx);
+    const taskSpec = run.spec.tasks[idx];
+    // ── FS operation fast path (bypasses intake entirely) ────────────────────
+    //
+    // If the task spec declares an explicit operationType, or if NL parsing
+    // returns an FsChange, route to the FS op path. No session is created.
+    // These operations are always-executable deterministic primitives.
+    let detectedFsOp;
+    if (taskSpec.operationType && taskSpec.operationType !== "replace") {
+        detectedFsOp = buildFsChangeFromSpec(taskSpec);
+    }
+    if (!detectedFsOp) {
+        const parsed = parseChange(taskSpec.input);
+        if (parsed !== null && isFsChange(parsed)) {
+            detectedFsOp = parsed;
+        }
+    }
+    if (detectedFsOp !== undefined) {
+        const updatedTasks = updateTask(run.tasks, idx, t => ({ ...t }));
+        const display = buildDisplay({ spec: run.spec, tasks: updatedTasks, currentIndex: idx }, fsOpHeadline(detectedFsOp, idx + 1));
+        return mk("task_ready", run, { currentFsOp: detectedFsOp, tasks: updatedTasks, display });
+    }
+    // ── Submit the task to its session ───────────────────────────────────────
+    let currentSession;
+    if (runtime === "cursor") {
+        // W8: runtime comes from spec. W6: override can only tighten.
+        const policy = applyOCDOverride(cursorPolicy, run.spec.ocdOverride);
+        const session = submit(createSession(), taskSpec.input, policy);
+        currentSession = { runtime: "cursor", state: session };
+    }
+    else {
+        const ocdPolicy = applyClaudeOCDOverride(claudeOCDPolicy, run.spec.ocdOverride);
+        const session = submitClaude(createClaudeSession(), taskSpec.input, ocdPolicy, claudeToolPolicy);
+        currentSession = { runtime: "claude", state: session };
+    }
+    const sessionPhase = currentSession.state.phase;
+    // ── Surface non-execute modes explicitly (no silent skips) ───────────────
+    // V1 default: intake_failed and not_execute are auto-skipped.
+    // The display message and task record preserve the reason for the UI.
+    if (sessionPhase === "not_execute" || sessionPhase === "intake_failed") {
+        const display_msg = sessionPhase === "intake_failed"
+            ? `Task ${idx + 1}: Input could not be processed.`
+            : `Task ${idx + 1}: Input is not a supported operation.`;
+        const updatedTasks = updateTask(run.tasks, idx, t => ({
+            ...t,
+            outcome: "skipped_by_intake",
+            ...(currentSession.state.intentId !== undefined ? { intentId: currentSession.state.intentId } : {}),
+            ...(currentSession.state.responseId !== undefined ? { responseId: currentSession.state.responseId } : {}),
+        }));
+        const nextIndex = idx + 1;
+        const next = {
+            ...run,
+            tasks: updatedTasks,
+            currentIndex: nextIndex,
+            phase: "running",
+            display: buildDisplay({ spec: run.spec, tasks: updatedTasks, currentIndex: nextIndex }, display_msg),
+        };
+        // Recurse to advance to the next task.
+        return advanceWorkflow(next, cursorPolicy, claudeOCDPolicy, claudeToolPolicy);
+    }
+    // ── Surface prepared / conflict ───────────────────────────────────────────
+    const nextPhase = sessionPhase === "conflict" ? "task_conflict" : "task_ready";
+    const updatedTasks = updateTask(run.tasks, idx, t => ({
+        ...t,
+        ...(currentSession.state.intentId !== undefined ? { intentId: currentSession.state.intentId } : {}),
+        ...(currentSession.state.responseId !== undefined ? { responseId: currentSession.state.responseId } : {}),
+    }));
+    const display = buildDisplay({ spec: run.spec, tasks: updatedTasks, currentIndex: idx }, sessionPhase === "conflict"
+        ? `Task ${idx + 1}: OCD conflict detected.`
+        : (taskSpec.label ?? taskSpec.input.slice(0, 60)));
+    return mk(nextPhase, run, { tasks: updatedTasks, currentSession, display });
+}
+// ─── acceptWorkflowConflict ───────────────────────────────────────────────────
+/**
+ * Accept the OCD conflict on the current task.
+ *
+ * Valid from "task_conflict" only.
+ * Transitions to "task_ready".
+ */
+export function acceptWorkflowConflict(run) {
+    if (isWorkflowTerminal(run))
+        return run;
+    if (run.phase !== "task_conflict" || !run.currentSession)
+        return run;
+    let nextSession;
+    if (run.currentSession.runtime === "cursor") {
+        nextSession = { runtime: "cursor", state: acceptConflict(run.currentSession.state) };
+    }
+    else {
+        nextSession = { runtime: "claude", state: acceptClaudeConflict(run.currentSession.state) };
+    }
+    const idx = run.currentIndex;
+    const display = buildDisplay(run, `Task ${idx + 1}: Conflict accepted. Ready for approval.`);
+    return mk("task_ready", run, { currentSession: nextSession, display });
+}
+// ─── confirmWorkflowTask ──────────────────────────────────────────────────────
+/**
+ * Confirm (approve) or reject the current prepared task.
+ *
+ * Valid from "task_ready" and "task_conflict" (rejection path).
+ *
+ * yes=true  → calls approve() / approveClaude() → "task_approved"
+ * yes=false → calls reject() / rejectClaude()   → "task_failed" (outcome: "rejected")
+ *
+ * ── Proof W2 (never approves on behalf of H) ────────────────────────────────
+ *
+ *   This function calls approve() exactly once when yes=true.
+ *   It does NOT call deliver() or deliverClaude().
+ *   The session transitions to "approved", not "accepted".
+ *   deliverWorkflowTask() is the separate, explicit delivery step.
+ */
+export function confirmWorkflowTask(run, yes) {
+    if (isWorkflowTerminal(run))
+        return run;
+    if (run.phase !== "task_ready" && run.phase !== "task_conflict")
+        return run;
+    const idx = run.currentIndex;
+    // ── FS operation path (no session needed) ────────────────────────────────
+    if (run.currentFsOp) {
+        if (!yes) {
+            const updatedTasks = updateTask(run.tasks, idx, t => ({ ...t, outcome: "rejected" }));
+            const display = buildDisplay({ ...run, tasks: updatedTasks }, `Task ${idx + 1}: Rejected by H.`, { failureNote: "Task was rejected." });
+            return mk("task_failed", run, { currentFsOp: undefined, tasks: updatedTasks, display });
+        }
+        const display = buildDisplay(run, `Task ${idx + 1}: Approved. Executing operation.`);
+        return mk("task_approved", run, { display });
+    }
+    // ── Session path ──────────────────────────────────────────────────────────
+    if (!run.currentSession)
+        return run;
+    if (!yes) {
+        // H rejected. Transition to task_failed with rejected outcome.
+        let nextSession;
+        if (run.currentSession.runtime === "cursor") {
+            nextSession = { runtime: "cursor", state: reject(run.currentSession.state) };
+        }
+        else {
+            nextSession = { runtime: "claude", state: rejectClaude(run.currentSession.state) };
+        }
+        const updatedTasks = updateTask(run.tasks, idx, t => ({ ...t, outcome: "rejected" }));
+        const display = buildDisplay({ ...run, tasks: updatedTasks }, `Task ${idx + 1}: Rejected by H.`, { failureNote: "Task was rejected." });
+        return mk("task_failed", run, { currentSession: nextSession, tasks: updatedTasks, display });
+    }
+    // H approved. Call approve() only — NO delivery. (W2 proof point)
+    let nextSession;
+    if (run.currentSession.runtime === "cursor") {
+        nextSession = { runtime: "cursor", state: approve(run.currentSession.state) };
+    }
+    else {
+        nextSession = { runtime: "claude", state: approveClaude(run.currentSession.state) };
+    }
+    const display = buildDisplay(run, `Task ${idx + 1}: Approved. Ready to deliver.`);
+    return mk("task_approved", run, { currentSession: nextSession, display });
+}
+// ─── deliverWorkflowTask ──────────────────────────────────────────────────────
+/**
+ * Deliver the current approved task to its runtime.
+ *
+ * Valid from "task_approved" only.
+ *
+ * Outcome:
+ *   accepted    → record outcome, increment currentIndex → "running"
+ *   scope_question → "task_scope"
+ *   exec_error / blocked → "task_failed"
+ *
+ * @param plugins  WorkflowPlugins — coordinator picks the right one by runtime (W8 / Proof 3).
+ * @param storeDir UCP store directory.
+ * @param deps     Optional gate dependencies (for test injection, Claude only).
+ */
+export async function deliverWorkflowTask(run, plugins, storeDir, deps) {
+    if (isWorkflowTerminal(run))
+        return run;
+    if (run.phase !== "task_approved")
+        return run;
+    const idx = run.currentIndex;
+    // ── FS operation delivery path ────────────────────────────────────────────
+    if (run.currentFsOp) {
+        if (!plugins.fs) {
+            return transitionToFailed(run, idx, "No filesystem plugin configured for this server.");
+        }
+        const result = await plugins.fs.executeFsOp(run.currentFsOp);
+        if (result.kind === "accepted") {
+            const updatedTasks = updateTask(run.tasks, idx, t => ({
+                ...t, outcome: "accepted",
+            }));
+            const nextIndex = idx + 1;
+            const isDone = nextIndex >= run.spec.tasks.length;
+            const display = buildDisplay({ spec: run.spec, tasks: updatedTasks, currentIndex: nextIndex }, isDone
+                ? `Workflow "${run.spec.name}" completed.`
+                : `Task ${idx + 1}: Done. Advancing to task ${nextIndex + 1}.`);
+            return mk(isDone ? "completed" : "running", run, { tasks: updatedTasks, currentIndex: nextIndex, currentFsOp: undefined, currentSession: undefined, display });
+        }
+        return transitionToFailed(run, idx, result.detail ?? "Filesystem operation failed.");
+    }
+    // ── Session delivery path (existing) ─────────────────────────────────────
+    if (!run.currentSession)
+        return run;
+    // ── Deliver via the correct plugin (W8 / Proof 3) ────────────────────────
+    let nextSession;
+    if (run.currentSession.runtime === "cursor") {
+        const plugin = plugins.cursor;
+        if (!plugin) {
+            // No cursor plugin provided — block.
+            return transitionToFailed(run, idx, "No cursor plugin provided for this task.");
+        }
+        const delivered = await deliver(run.currentSession.state, plugin, storeDir);
+        nextSession = { runtime: "cursor", state: delivered };
+    }
+    else {
+        const plugin = plugins.claude;
+        if (!plugin) {
+            return transitionToFailed(run, idx, "No claude plugin provided for this task.");
+        }
+        const delivered = await deliverClaude(run.currentSession.state, plugin, storeDir, deps);
+        nextSession = { runtime: "claude", state: delivered };
+    }
+    const deliveredPhase = nextSession.state.phase;
+    // ── Map delivery outcome ──────────────────────────────────────────────────
+    if (deliveredPhase === "accepted") {
+        // Record outcome and advance to next task.
+        const updatedTasks = updateTask(run.tasks, idx, t => ({ ...t, outcome: "accepted" }));
+        const nextIndex = idx + 1;
+        const isDone = nextIndex >= run.spec.tasks.length;
+        const display = buildDisplay({ spec: run.spec, tasks: updatedTasks, currentIndex: nextIndex }, isDone
+            ? `Workflow "${run.spec.name}" completed.`
+            : `Task ${idx + 1}: Accepted. Advancing to task ${nextIndex + 1}.`);
+        return mk(isDone ? "completed" : "running", run, { tasks: updatedTasks, currentIndex: nextIndex, currentSession: undefined, display });
+    }
+    if (deliveredPhase === "scope_question") {
+        // F9 / WF-S3: if taskSpec carries explicit targetFiles, auto-resolve scope.
+        const taskSpec = run.spec.tasks[idx];
+        if (taskSpec.targetFiles && taskSpec.targetFiles.length > 0) {
+            const candidates = nextSession.runtime === "cursor"
+                ? (nextSession.state.scopeQuestion?.candidates ?? [])
+                : (nextSession.state.scopeQuestion?.candidates ?? []);
+            const match = taskSpec.targetFiles.find(tf => candidates.includes(tf));
+            if (!match) {
+                // WF-S1: explicit scope provided but no candidate matches — contradiction.
+                return transitionToFailed(run, idx, `Scope contradiction: targetFiles [${taskSpec.targetFiles.join(", ")}] ` +
+                    `did not match any delivery candidates [${candidates.join(", ")}]. ` +
+                    `Verify that task input and targetFiles refer to the same file.`);
+            }
+            // Auto-answer scope without prompting H (WF-S3).
+            let answeredSession;
+            if (nextSession.runtime === "cursor") {
+                answeredSession = { runtime: "cursor", state: answerScope(nextSession.state, match) };
+            }
+            else {
+                answeredSession = { runtime: "claude", state: answerClaudeScope(nextSession.state, match) };
+            }
+            const autoDisplay = buildDisplay(run, `Task ${idx + 1}: Scope auto-resolved to ${match}.`);
+            const autoApprovedRun = mk("task_approved", run, {
+                currentSession: answeredSession,
+                display: autoDisplay,
+            });
+            // Re-deliver with the auto-approved, scope-narrowed session.
+            return deliverWorkflowTask(autoApprovedRun, plugins, storeDir, deps);
+        }
+        const display = buildDisplay(run, `Task ${idx + 1}: Scope clarification needed.`);
+        return mk("task_scope", run, { currentSession: nextSession, display });
+    }
+    // exec_error, blocked — surface as task_failed.
+    const note = nextSession.state.display.resultNote ?? "Execution failed.";
+    return transitionToFailed(run, idx, note, nextSession);
+}
+// ─── answerWorkflowScope ──────────────────────────────────────────────────────
+/**
+ * Answer a scope clarification question for the current task.
+ *
+ * Valid from "task_scope" only.
+ * Transitions to "task_approved" so the caller can call deliverWorkflowTask again.
+ *
+ * @param choiceIdx 1-based index into the scope candidates.
+ *                  Out-of-range → returns state unchanged.
+ */
+export function answerWorkflowScope(run, choiceIdx) {
+    if (isWorkflowTerminal(run))
+        return run;
+    if (run.phase !== "task_scope" || !run.currentSession)
+        return run;
+    const candidates = run.currentSession.runtime === "cursor"
+        ? (run.currentSession.state.scopeQuestion?.candidates ?? [])
+        : (run.currentSession.state.scopeQuestion?.candidates ?? []);
+    const file = candidates[choiceIdx - 1];
+    if (!file)
+        return run; // Out of range — re-prompt.
+    let nextSession;
+    if (run.currentSession.runtime === "cursor") {
+        nextSession = { runtime: "cursor", state: answerScope(run.currentSession.state, file) };
+    }
+    else {
+        nextSession = { runtime: "claude", state: answerClaudeScope(run.currentSession.state, file) };
+    }
+    const idx = run.currentIndex;
+    const display = buildDisplay(run, `Task ${idx + 1}: Scope answered. Re-approving.`);
+    return mk("task_approved", run, { currentSession: nextSession, display });
+}
+// ─── applyFailureAction ───────────────────────────────────────────────────────
+/**
+ * Apply a failure action to the current failed task.
+ *
+ * Valid from "task_failed" only.
+ *
+ * Actions:
+ *   stop  → "stopped" (terminal)
+ *   skip  → record as "skipped", advance currentIndex → "running"
+ *   retry → if retryCount < maxRetries: increment retryCount, reset session → "running"
+ *            if retryCount >= maxRetries: returns state unchanged (stop/skip only)
+ *
+ * W3: retry creates a new session via advanceWorkflow; no session is re-opened.
+ *
+ * @returns Next WorkflowRun. Caller must call advanceWorkflow() after "running".
+ */
+export function applyFailureAction(run, action) {
+    if (isWorkflowTerminal(run))
+        return run;
+    if (run.phase !== "task_failed")
+        return run;
+    const idx = run.currentIndex;
+    if (action === "stop") {
+        const updatedTasks = updateTask(run.tasks, idx, t => ({ ...t, outcome: "stopped" }));
+        const display = buildDisplay({ ...run, tasks: updatedTasks }, `Workflow "${run.spec.name}" stopped at task ${idx + 1}.`);
+        return mk("stopped", run, { tasks: updatedTasks, currentSession: undefined, display });
+    }
+    if (action === "skip") {
+        const updatedTasks = updateTask(run.tasks, idx, t => ({ ...t, outcome: "skipped" }));
+        const nextIndex = idx + 1;
+        const isDone = nextIndex >= run.spec.tasks.length;
+        const display = buildDisplay({ spec: run.spec, tasks: updatedTasks, currentIndex: nextIndex }, isDone
+            ? `Workflow "${run.spec.name}" completed (task ${idx + 1} skipped).`
+            : `Task ${idx + 1} skipped. Advancing to task ${nextIndex + 1}.`);
+        return mk(isDone ? "completed" : "running", run, { tasks: updatedTasks, currentIndex: nextIndex, currentSession: undefined, display });
+    }
+    // retry
+    const currentTask = run.tasks[idx];
+    if (!currentTask)
+        return run;
+    if (currentTask.retryCount >= maxRetries(run)) {
+        // Max retries exceeded — only stop/skip are valid. Return unchanged.
+        return run;
+    }
+    const updatedTasks = updateTask(run.tasks, idx, t => ({
+        ...t,
+        retryCount: t.retryCount + 1,
+        outcome: "pending",
+        // Clear provenance IDs — new session will set new ones.
+    }));
+    const display = buildDisplay({ spec: run.spec, tasks: updatedTasks, currentIndex: idx }, `Task ${idx + 1}: Retrying (attempt ${currentTask.retryCount + 2}).`);
+    // W3: session is cleared. advanceWorkflow will create a new one.
+    return mk("running", run, { tasks: updatedTasks, currentSession: undefined, display });
+}
+// ─── UCP workflow run provenance ──────────────────────────────────────────────
+/**
+ * buildWorkflowRunPayload — produce the UCP payload for ucp.workflow_run.v1.
+ *
+ * Called when the workflow reaches "completed" or "stopped" (W5).
+ * Not called for in-progress runs.
+ *
+ * @throws {Error} If run is not in a terminal phase.
+ */
+export function buildWorkflowRunPayload(run) {
+    if (run.phase !== "completed" && run.phase !== "stopped") {
+        throw new Error(`buildWorkflowRunPayload: run must be terminal, got "${run.phase}"`);
+    }
+    const finalOutcome = run.phase === "completed" ? "completed" : "stopped";
+    const acceptedCount = run.tasks.filter(t => t.outcome === "accepted").length;
+    const skippedCount = run.tasks.filter(t => t.outcome === "skipped" || t.outcome === "skipped_by_intake").length;
+    const sessionRefs = run.tasks
+        .filter(t => t.outcome !== "pending")
+        .map(t => ({
+        taskIndex: t.index,
+        outcome: t.outcome,
+        retryCount: t.retryCount,
+        ...(t.intentId ? { intentId: t.intentId } : {}),
+        ...(t.responseId ? { responseId: t.responseId } : {}),
+    }));
+    return {
+        workflowRunId: run.workflowRunId,
+        workflowName: run.spec.name,
+        finalOutcome,
+        taskCount: run.spec.tasks.length,
+        acceptedCount,
+        skippedCount,
+        taskInputs: run.spec.tasks.map(t => t.input),
+        sessionRefs,
+    };
+}
+/**
+ * persistWorkflowRun — build a ucp.workflow_run.v1 envelope and persist it.
+ *
+ * This is fire-and-forget (uses persistEnvelope, not persistEnvelopeOrThrow).
+ * A persistence failure must NOT block the shell from rendering a terminal
+ * state to the user. The UCP record is an audit artifact, not a gate.
+ *
+ * @throws {Error} If run is not terminal. Call only after isWorkflowTerminal(run).
+ */
+export function persistWorkflowRun(run, storeDir) {
+    const payload = buildWorkflowRunPayload(run);
+    const envelope = createWorkflowRunEnvelope(payload);
+    persistEnvelope(storeDir, envelope);
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+function transitionToFailed(run, idx, failureNote, nextSession) {
+    const display = buildDisplay(run, `Task ${idx + 1}: Failed.`, { failureNote });
+    return mk("task_failed", run, {
+        ...(nextSession !== undefined ? { currentSession: nextSession } : {}),
+        display,
+    });
+}
+//# sourceMappingURL=coordinator.js.map