@devflow-tools/workflow-engine 0.16.17 → 0.16.19

package/dist/workflow-engine.js

@@ -1,39 +1,41 @@
+import { resolveCapabilityRollout } from "@devflow-tools/sdk/capability-rollout";
 import { resolveStepRef } from "@devflow-tools/sdk/step-templates";
 import { getLogWriter } from "@devflow-tools/telemetry";
-import { topologicalSort, executeLevels } from "./dag.js";
+import { topologicalSort } from "./dag.js";
 import { StepResolver } from "./step-resolver.js";
 import { BUILTIN_STEPS } from "./steps/builtin.js";
 import { classifyWorkflowFailure } from "./failure-classifier.js";
 export class WorkflowEngine {
     definitions = new Map();
     runs = new Map();
+    runtimes = new Map();
+    advancing = new Map();
     resolver = new StepResolver();
     eventListeners = new Map();
     data;
     options;
+    truthfulWorkflow;
     pluginStepHandlers = new Map();
     constructor(data, options = {}) {
         this.data = data;
         this.options = options;
+        this.truthfulWorkflow = options.truthfulWorkflow
+            ?? resolveCapabilityRollout(options.projectRoot ?? ".").config.truthfulWorkflow;
         for (const [id, handler] of Object.entries(BUILTIN_STEPS)) {
             this.resolver.register(id, handler);
         }
         this.registerDefaults();
     }
-    // --- Step Ref Resolution ---
-    /**
-     * Resolve all `WorkflowStepRef` entries in a workflow definition into
-     * concrete `StepInstruction` objects. Non-ref steps pass through unchanged.
-     */
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
     resolveStepRefs(definition) {
         return definition.steps.map((step) => {
-            if ("stepTemplate" in step) {
+            if ("stepTemplate" in step)
                 return resolveStepRef(step);
-            }
             return step;
         });
     }
-    // --- Registration ---
     register(definition) {
         this.definitions.set(definition.name, definition);
     }
@@ -52,286 +54,516 @@ export class WorkflowEngine {
                 this.pluginStepHandlers.set(workflowName, handlerId);
         }
     }
-    async runPluginWorkflow(pluginName, templateName, input) {
-        return this.run(this.pluginWorkflowName(pluginName, templateName), input);
+    async runPluginWorkflow(pluginName, templateName, input, execution) {
+        return this.run(this.pluginWorkflowName(pluginName, templateName), input, execution);
     }
     pluginWorkflowName(pluginName, templateName) {
         return `${pluginName}:${templateName}`;
     }
     async list() {
-        return Array.from(this.definitions.values()).map((d) => ({
-            name: d.name,
-            description: d.description,
-            version: d.version,
-            stepCount: d.steps.length,
+        return Array.from(this.definitions.values()).map((definition) => ({
+            name: definition.name,
+            description: definition.description,
+            version: definition.version,
+            stepCount: definition.steps.length,
         }));
     }
     getDefinition(name) {
         return this.definitions.get(name);
     }
-    // --- Running ---
-    async run(name, input) {
-        const def = this.definitions.get(name);
-        if (!def)
+    async run(name, input, execution = {}) {
+        const definition = this.definitions.get(name);
+        if (!definition)
             throw new Error(`Workflow "${name}" not registered`);
-        const runId = `run:${Date.now()}:${Math.random().toString(36).slice(2, 7)}`;
-        const startedAt = Date.now();
-        const logWriter = getLogWriter();
-        logWriter.startRun({ name, agent: "workflow-engine" });
-        // Resolve WorkflowStepRef entries into concrete StepInstruction objects
-        const resolvedSteps = this.resolveStepRefs(def);
-        // Create initial step states
-        const stepStates = new Map();
-        for (const step of resolvedSteps) {
-            stepStates.set(step.id, {
-                stepId: step.id,
-                status: "pending",
-            });
-        }
-        const runState = {
-            runId,
+        const startedAt = this.now();
+        const engineRunId = `run:${startedAt}:${Math.random().toString(36).slice(2, 7)}`;
+        const telemetryRunId = execution.telemetryRunId ?? engineRunId;
+        const resolvedSteps = this.resolveStepRefs(definition);
+        const dependencyIssue = validateWorkflowDependencies(resolvedSteps);
+        const run = {
+            runId: engineRunId,
             workflowName: name,
             input,
             status: "running",
-            steps: Array.from(stepStates.values()),
+            steps: resolvedSteps.map((step) => ({ stepId: step.id, status: "pending" })),
             startedAt,
             failureCategory: null,
+            metadata: {
+                engineRunId,
+                telemetryRunId,
+                projectRoot: this.options.projectRoot ?? ".",
+                sessionId: execution.sessionId ?? this.options.sessionId ?? "default",
+                executionId: execution.executionId,
+                contextReceipt: execution.contextReceipt,
+                truthfulWorkflow: this.truthfulWorkflow,
+            },
         };
-        this.runs.set(runId, runState);
-        // Build a map of step outputs for variable substitution
-        const outputs = new Map();
-        const dependencyIssue = validateWorkflowDependencies(resolvedSteps);
-        const levels = topologicalSort(resolvedSteps);
+        this.runs.set(engineRunId, run);
+        this.runtimes.set(engineRunId, {
+            steps: resolvedSteps,
+            outputs: new Map(),
+            loggedEnded: false,
+        });
+        getLogWriter().startRun({ name, agent: "workflow-engine" });
+        if (dependencyIssue) {
+            run.status = "failed";
+            run.finishedAt = this.now();
+            this.setRunFailure(run, classifyWorkflowFailure({
+                workflowDesignIssue: dependencyIssue,
+            }));
+            await this.persistRun(run);
+            return this.runResult(run);
+        }
+        await this.advanceRun(engineRunId);
+        return this.runResult(run);
+    }
+    async advanceRun(runId) {
+        const current = this.advancing.get(runId);
+        if (current)
+            return current;
+        const advancement = this.advanceRunInternal(runId);
+        this.advancing.set(runId, advancement);
         try {
-            if (dependencyIssue) {
-                throw new WorkflowDesignError(dependencyIssue);
-            }
-            await executeLevels(levels, async (stepDef) => {
-                const state = stepStates.get(stepDef.id);
-                const failedDependencies = (stepDef.depends ?? []).filter((dependency) => {
-                    const status = stepStates.get(dependency)?.status;
-                    return status === "failed" || status === "skipped";
+            await advancement;
+        }
+        finally {
+            this.advancing.delete(runId);
+        }
+    }
+    async advanceRunInternal(runId) {
+        const run = this.runs.get(runId);
+        const runtime = this.runtimes.get(runId);
+        if (!run || !runtime)
+            throw new Error(`Run "${runId}" not found`);
+        if (run.status === "completed" || run.status === "canceled")
+            return;
+        while (true) {
+            this.skipFailedDescendants(run, runtime.steps);
+            const eligible = runtime.steps.filter((definition) => {
+                const state = this.stepState(run, definition.id);
+                if (state.status !== "pending")
+                    return false;
+                return (definition.depends ?? []).every((dependency) => this.stepState(run, dependency).status === "success");
+            });
+            if (eligible.length === 0)
+                break;
+            await Promise.all(eligible.map((definition) => this.executeStep(run, runtime, definition)));
+        }
+        this.recomputeRunStatus(run);
+        await this.persistRun(run);
+        this.finishLogIfTerminal(run, runtime);
+    }
+    skipFailedDescendants(run, definitions) {
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const definition of definitions) {
+                const state = this.stepState(run, definition.id);
+                if (state.status !== "pending")
+                    continue;
+                const failed = (definition.depends ?? []).filter((dependency) => {
+                    const dependencyStatus = this.stepState(run, dependency).status;
+                    return dependencyStatus === "failed" || dependencyStatus === "skipped";
                 });
-                if (failedDependencies.length > 0) {
-                    state.status = "skipped";
-                    state.error = `Dependencies failed: ${failedDependencies.join(", ")}`;
-                    state.finishedAt = Date.now();
-                    if (!runState.failureCategory) {
-                        this.setRunFailure(runState, classifyWorkflowFailure({
-                            stepId: stepDef.id,
-                            dependencyFailed: failedDependencies,
-                        }));
-                    }
-                    return;
+                if (failed.length === 0)
+                    continue;
+                state.status = "skipped";
+                state.error = `Dependencies failed: ${failed.join(", ")}`;
+                state.finishedAt = this.now();
+                changed = true;
+                if (!run.failureCategory) {
+                    this.setRunFailure(run, classifyWorkflowFailure({
+                        stepId: definition.id,
+                        dependencyFailed: failed,
+                    }));
                 }
-                const waitingDependencies = (stepDef.depends ?? []).filter((dependency) => {
-                    const status = stepStates.get(dependency)?.status;
-                    return status === "pending" || status === "running" || status === "awaiting_approval";
-                });
-                if (waitingDependencies.length > 0)
-                    return;
-                state.status = "running";
-                state.startedAt = Date.now();
-                const stepLogId = logWriter.startStep(runId, { name: stepDef.id });
-                const wfStep = stepDef;
-                const declaredInputs = "inputs" in stepDef ? wfStep.inputs ?? {} : {};
-                state.input = Object.keys(declaredInputs).length > 0
-                    ? resolveInputs(declaredInputs, outputs, input)
-                    : { ...input };
-                this.emit(runId, { type: "step-start", stepId: stepDef.id, time: new Date().toISOString() });
-                try {
-                    let output;
-                    if ("type" in stepDef) {
-                        switch (wfStep.type) {
-                            case "manual":
-                                // Manual steps wait for approve()
-                                state.status = "awaiting_approval";
-                                // Will be resolved by approve() method
-                                break;
-                            case "stateful":
-                                output = await this.executeStateful(wfStep, state, outputs, input);
-                                break;
-                            case "simple":
-                            case "llm":
-                            default:
-                                output = await this.executeSimple(wfStep, state);
-                                break;
-                        }
-                    }
-                    else {
-                        if (stepDef.requiresUserConfirmation) {
-                            state.status = "awaiting_approval";
-                            return;
-                        }
-                        const handlerId = this.pluginStepHandlers.get(name);
-                        const handler = handlerId ? this.resolver.resolve(handlerId) : undefined;
-                        output = handler
-                            ? await handler.run({
-                                workflowName: name,
-                                stepId: stepDef.id,
-                                title: stepDef.title,
-                                instruction: stepDef.instruction,
-                                suggestedTools: stepDef.suggestedTools ?? [],
-                                expectedOutput: stepDef.output,
-                                input: state.input,
-                            }, this.stepContext())
-                            : {
-                                status: "host_action_required",
-                                workflowName: name,
-                                stepId: stepDef.id,
-                                instruction: stepDef.instruction,
-                                suggestedTools: stepDef.suggestedTools ?? [],
-                                expectedOutput: stepDef.output,
-                            };
-                    }
-                    if (output) {
-                        const outputRecord = output;
-                        const semanticFailure = classifyWorkflowFailure({
-                            stepId: stepDef.id,
-                            toolName: typeof outputRecord.retrievalTool === "string"
-                                ? outputRecord.retrievalTool
-                                : "type" in stepDef ? wfStep.run : undefined,
-                            output,
-                        });
-                        if (semanticFailure.category === "context_insufficient"
-                            || semanticFailure.category === "knowledge_missing") {
-                            if (!runState.failureCategory)
-                                this.setRunFailure(runState, semanticFailure);
-                            throw new Error(semanticFailure.reason);
-                        }
-                        if ("type" in stepDef && wfStep.outputSchema) {
-                            const errors = validateOutputSchema(output, wfStep.outputSchema);
-                            if (errors.length > 0) {
-                                throw new WorkflowDesignError(`Step ${JSON.stringify(stepDef.id)} output contract failed: ${errors.join("; ")}`);
-                            }
-                        }
-                        outputs.set(stepDef.id, output);
-                        state.output = output;
-                        state.status = "success";
-                        state.finishedAt = Date.now();
-                        logWriter.endStep(stepLogId, { duration: state.finishedAt - (state.startedAt ?? state.finishedAt) });
-                    }
-                    this.emit(runId, {
-                        type: "step-done",
-                        stepId: stepDef.id,
-                        duration: (state.finishedAt ?? Date.now()) - (state.startedAt ?? Date.now()),
-                        output,
-                    });
+            }
+        }
+    }
+    async executeStep(run, runtime, definition) {
+        const state = this.stepState(run, definition.id);
+        if (state.status !== "pending")
+            return;
+        state.status = "running";
+        state.startedAt = this.now();
+        const logWriter = getLogWriter();
+        const stepLogId = logWriter.startStep(run.runId, { name: definition.id });
+        const declaredInputs = isWorkflowStepDef(definition) ? definition.inputs ?? {} : {};
+        state.input = Object.keys(declaredInputs).length > 0
+            ? resolveInputs(declaredInputs, runtime.outputs, run.input)
+            : { ...run.input };
+        this.emit(run.runId, {
+            type: "step-start",
+            stepId: definition.id,
+            time: new Date(this.now()).toISOString(),
+        });
+        try {
+            if (this.isManualStep(definition)) {
+                await this.prepareManualStep(run, definition, state);
+                return;
+            }
+            const { output, handlerId } = await this.invokeStep(run, definition, state);
+            const hostAction = normalizeHostActionRequest(output);
+            if (hostAction) {
+                if (run.metadata.truthfulWorkflow === "shadow") {
+                    state.shadowCandidate = { ...hostAction };
                 }
-                catch (err) {
-                    state.status = "failed";
-                    state.error = err.message;
-                    state.finishedAt = Date.now();
-                    const failure = classifyWorkflowFailure({
-                        stepId: stepDef.id,
-                        toolName: "type" in stepDef ? wfStep.run : undefined,
-                        error: err,
-                        workflowDesignIssue: err instanceof WorkflowDesignError ? err.message : undefined,
-                    });
-                    if (!runState.failureCategory)
-                        this.setRunFailure(runState, failure);
-                    logWriter.toolCall({
-                        tool: "workflow-step",
-                        runId,
-                        stepId: stepLogId,
-                        input: state.input ?? {},
-                        output: null,
-                        duration: state.finishedAt - (state.startedAt ?? state.finishedAt),
-                        success: false,
-                        error: state.error,
-                    });
-                    this.emit(runId, { type: "step-error", stepId: stepDef.id, error: state.error });
+                if (run.metadata.truthfulWorkflow === "on") {
+                    await this.requestHostAction(run, state, hostAction);
+                    return;
                 }
+            }
+            const authoritativeOutput = hostAction && isLegacyBuiltinHostAction(handlerId)
+                ? legacyBuiltinOutput(handlerId, state.input ?? {})
+                : output;
+            this.validateSuccessfulOutput(run, definition, authoritativeOutput, handlerId);
+            runtime.outputs.set(definition.id, authoritativeOutput);
+            state.output = authoritativeOutput;
+            state.status = "success";
+            state.finishedAt = this.now();
+            logWriter.endStep(stepLogId, {
+                duration: state.finishedAt - (state.startedAt ?? state.finishedAt),
+            });
+            this.emit(run.runId, {
+                type: "step-done",
+                stepId: definition.id,
+                duration: state.finishedAt - (state.startedAt ?? state.finishedAt),
+                output: authoritativeOutput,
             });
         }
         catch (error) {
-            runState.status = "failed";
-            runState.finishedAt = Date.now();
-            this.setRunFailure(runState, classifyWorkflowFailure({
+            state.status = "failed";
+            state.error = error instanceof Error ? error.message : String(error);
+            state.finishedAt = this.now();
+            const failure = classifyWorkflowFailure({
+                stepId: definition.id,
+                toolName: isWorkflowStepDef(definition) ? definition.run : undefined,
                 error,
                 workflowDesignIssue: error instanceof WorkflowDesignError ? error.message : undefined,
-            }));
-            await this.persistRun(runState);
-            return this.runResult(runState);
-        }
-        // Check if any manual steps are awaiting approval
-        const hasAwaitingApproval = stepStates.has(Array.from(stepStates.values()).find((s) => s.status === "awaiting_approval")?.stepId ?? "_none");
-        // Wait — re-check correctly
-        const awaiting = Array.from(stepStates.values()).some((s) => s.status === "awaiting_approval");
-        if (!awaiting) {
-            const allSuccess = Array.from(stepStates.values()).every((s) => s.status === "success" || s.status === "skipped");
-            runState.status = allSuccess ? "completed" : "failed";
-        }
-        else {
-            runState.status = "running"; // Stay running until manual steps are approved
-        }
-        runState.finishedAt = runState.status !== "running" ? Date.now() : undefined;
-        runState.steps = Array.from(stepStates.values());
-        await this.persistRun(runState);
-        const completed = Array.from(stepStates.values()).filter(s => s.status === "success" || s.status === "failed");
-        logWriter.endRun(runId, {
-            steps: stepStates.size,
-            tools: completed.length,
-            errors: Array.from(stepStates.values()).filter(s => s.status === "failed").length,
-            tokens: 0,
-        });
-        return this.runResult(runState);
-    }
-    async executeSimple(step, state) {
-        const handler = step.run ? this.resolver.resolve(step.run) : undefined;
-        if (handler) {
-            return await handler.run(state.input ?? {}, {
-                ...this.stepContext(),
             });
+            if (!run.failureCategory)
+                this.setRunFailure(run, failure);
+            logWriter.toolCall({
+                tool: "workflow-step",
+                runId: run.runId,
+                stepId: stepLogId,
+                input: state.input ?? {},
+                output: null,
+                duration: state.finishedAt - (state.startedAt ?? state.finishedAt),
+                success: false,
+                error: state.error,
+            });
+            this.emit(run.runId, { type: "step-error", stepId: definition.id, error: state.error });
+        }
+    }
+    isManualStep(definition) {
+        return isWorkflowStepDef(definition)
+            ? definition.type === "manual"
+            : definition.requiresUserConfirmation === true;
+    }
+    async prepareManualStep(run, definition, state) {
+        if (isWorkflowStepDef(definition) && definition.run) {
+            const handler = this.resolver.resolve(definition.run);
+            if (handler) {
+                const candidate = await handler.run(state.input ?? {}, this.stepContext(run));
+                let readiness = candidate;
+                if (definition.run === "builtin:commit") {
+                    if (run.metadata.truthfulWorkflow === "shadow")
+                        state.shadowCandidate = candidate;
+                    if (run.metadata.truthfulWorkflow !== "on") {
+                        readiness = legacyBuiltinOutput(definition.run, state.input ?? {});
+                    }
+                }
+                if (readiness.ready === false) {
+                    const reason = typeof readiness.reason === "string"
+                        ? readiness.reason
+                        : "commit_not_ready";
+                    throw new Error(`Manual step is not ready: ${reason}`);
+                }
+                if (run.metadata.truthfulWorkflow === "on")
+                    state.output = candidate;
+            }
+        }
+        state.status = "awaiting_approval";
+    }
+    async invokeStep(run, definition, state) {
+        if (isWorkflowStepDef(definition)) {
+            const handlerId = definition.run;
+            if (definition.type === "stateful") {
+                return {
+                    output: await this.executeStateful(definition, state, run),
+                    handlerId,
+                };
+            }
+            const handler = handlerId ? this.resolver.resolve(handlerId) : undefined;
+            return {
+                output: handler
+                    ? await handler.run(state.input ?? {}, this.stepContext(run))
+                    : { ok: true },
+                handlerId,
+            };
         }
-        // No handler — return empty success
-        return { ok: true };
+        const handlerId = this.pluginStepHandlers.get(run.workflowName);
+        const handler = handlerId ? this.resolver.resolve(handlerId) : undefined;
+        const output = handler
+            ? await handler.run({
+                workflowName: run.workflowName,
+                stepId: definition.id,
+                title: definition.title,
+                instruction: definition.instruction,
+                suggestedTools: definition.suggestedTools ?? [],
+                expectedOutput: definition.output,
+                input: state.input,
+            }, this.stepContext(run))
+            : {
+                status: "host_action_required",
+                workflowName: run.workflowName,
+                stepId: definition.id,
+                instruction: definition.instruction,
+                suggestedTools: definition.suggestedTools ?? [],
+                expectedOutput: definition.output,
+            };
+        return { output, handlerId };
     }
-    async executeStateful(step, state, _outputs, _input) {
-        // Stateful steps go through generate → validate → (retry | confirm) → done
-        const maxRetries = step.retry ?? 3;
+    async executeStateful(definition, state, run) {
+        const maxRetries = definition.retry ?? 3;
+        const handler = definition.run ? this.resolver.resolve(definition.run) : undefined;
         let attempts = 0;
         let lastOutput = {};
         while (attempts < maxRetries) {
-            // Generate
-            const handler = step.run ? this.resolver.resolve(step.run) : undefined;
-            if (handler) {
-                lastOutput = await handler.run(state.input ?? {}, {
-                    ...this.stepContext(),
-                });
-            }
-            // Validate — default to pass if no output validator
-            const isValid = lastOutput?.valid !== false;
-            if (isValid) {
+            if (handler)
+                lastOutput = await handler.run(state.input ?? {}, this.stepContext(run));
+            if (normalizeHostActionRequest(lastOutput) || lastOutput.valid !== false)
                 return lastOutput;
-            }
             attempts++;
         }
-        // All retries exhausted — return best effort
         return { ...lastOutput, validated: false, attempts };
     }
-    // --- Manual Step Control ---
+    validateSuccessfulOutput(run, definition, output, handlerId) {
+        const semanticFailure = classifyWorkflowFailure({
+            stepId: definition.id,
+            toolName: typeof output.retrievalTool === "string" ? output.retrievalTool : handlerId,
+            output,
+        });
+        if (semanticFailure.category === "context_insufficient"
+            || semanticFailure.category === "knowledge_missing") {
+            if (!run.failureCategory)
+                this.setRunFailure(run, semanticFailure);
+            throw new Error(semanticFailure.reason);
+        }
+        if (isWorkflowStepDef(definition) && definition.outputSchema) {
+            const errors = validateOutputSchema(output, definition.outputSchema);
+            if (errors.length > 0) {
+                throw new WorkflowDesignError(`Step ${JSON.stringify(definition.id)} output contract failed: ${errors.join("; ")}`);
+            }
+        }
+    }
+    async requestHostAction(run, state, request) {
+        const store = this.options.hostActionStore;
+        if (!store)
+            throw new Error("Truthful workflow requires a HostActionStore");
+        const actionId = `action:${run.runId}:${state.stepId}`;
+        const record = await store.requestHostAction({
+            actionId,
+            runId: run.metadata.telemetryRunId,
+            engineRunId: run.runId,
+            stepId: state.stepId,
+            projectRoot: run.metadata.projectRoot,
+            sessionId: run.metadata.sessionId,
+            executionId: run.metadata.executionId,
+            contextReceipt: run.metadata.contextReceipt,
+        });
+        this.validateRequestedRecord(run, state, actionId, record);
+        const priorActionIds = stringArray(state.input?.actionIds);
+        const priorVerifiedActionIds = stringArray(state.input?.verifiedActionIds);
+        state.actionId = record.actionId;
+        state.actionKind = request.actionKind;
+        state.actionIds = uniqueStrings([...priorActionIds, record.actionId]);
+        state.verifiedActionIds = priorVerifiedActionIds;
+        state.output = {
+            ...request,
+            actionId: record.actionId,
+            actionIds: state.actionIds,
+            verifiedActionIds: state.verifiedActionIds,
+        };
+        state.status = "waiting_host";
+    }
+    validateRequestedRecord(run, state, actionId, record) {
+        if (record.actionId !== actionId
+            || record.runId !== run.metadata.telemetryRunId
+            || record.engineRunId !== run.runId
+            || record.stepId !== state.stepId
+            || record.projectRoot !== run.metadata.projectRoot
+            || record.sessionId !== optionalString(run.metadata.sessionId)
+            || record.executionId !== run.metadata.executionId
+            || record.contextReceipt !== run.metadata.contextReceipt
+            || record.state !== "waiting") {
+            throw new Error("HostActionStore returned a mismatched action record");
+        }
+    }
+    async resumeHostAction(record) {
+        if (record.state === "waiting" || record.state === "running") {
+            throw new Error(`Host action record is not resumable (state: ${record.state})`);
+        }
+        const run = this.runs.get(record.engineRunId);
+        if (!run)
+            throw new Error(`Engine run "${record.engineRunId}" not found`);
+        if (run.metadata.truthfulWorkflow !== "on") {
+            throw new Error("Host action resume requires truthful workflow mode on");
+        }
+        if (record.projectRoot !== run.metadata.projectRoot)
+            throw new Error("Host action project mismatch");
+        if (record.runId !== run.metadata.telemetryRunId)
+            throw new Error("Host action telemetry run mismatch");
+        if (record.engineRunId !== run.runId)
+            throw new Error("Host action engine run mismatch");
+        const state = run.steps.find((step) => step.stepId === record.stepId);
+        if (!state)
+            throw new Error(`Host action step "${record.stepId}" not found`);
+        if (!state.actionId || state.actionId !== record.actionId)
+            throw new Error("Host action ID mismatch");
+        if (record.sessionId !== run.metadata.sessionId)
+            throw new Error("Host action session mismatch");
+        if (record.executionId !== run.metadata.executionId)
+            throw new Error("Host action execution mismatch");
+        if (record.contextReceipt !== run.metadata.contextReceipt)
+            throw new Error("Host action context receipt mismatch");
+        const persisted = await this.options.hostActionStore?.getHostAction(record.projectRoot, record.actionId);
+        if (!persisted || !sameHostActionRecord(persisted, record)) {
+            throw new Error("Host action record does not match persisted evidence");
+        }
+        if (record.state === "reported") {
+            if (state.status === "verifying")
+                return this.publicRun(run);
+            if (state.status !== "waiting_host") {
+                throw new Error(`Host action step is not waiting (status: ${state.status})`);
+            }
+            state.status = "verifying";
+            state.output = { ...state.output, report: record.report, state: "reported" };
+            run.status = "waiting_host";
+            await this.persistRun(run);
+            return this.publicRun(run);
+        }
+        if (record.state === "verified") {
+            if (!record.evidenceHash)
+                throw new Error("Verified host action requires an evidence hash");
+            if (state.status === "success") {
+                if (state.evidenceHash === record.evidenceHash)
+                    return this.publicRun(run);
+                throw new Error("Host action terminal evidence mismatch");
+            }
+            if (state.status !== "waiting_host" && state.status !== "verifying") {
+                throw new Error(`Host action step is not resumable (status: ${state.status})`);
+            }
+            const runtime = this.runtimes.get(run.runId);
+            if (!runtime)
+                throw new Error(`Run runtime "${run.runId}" not found`);
+            const priorActionIds = stringArray(state.input?.actionIds);
+            const priorVerifiedActionIds = stringArray(state.input?.verifiedActionIds);
+            state.actionIds = uniqueStrings([...priorActionIds, record.actionId]);
+            state.verifiedActionIds = uniqueStrings([...priorVerifiedActionIds, ...state.actionIds]);
+            state.evidenceHash = record.evidenceHash;
+            state.output = {
+                ...record.report,
+                state: "verified",
+                actionId: record.actionId,
+                actionIds: state.actionIds,
+                verifiedActionIds: state.verifiedActionIds,
+                evidenceHash: record.evidenceHash,
+            };
+            state.status = "success";
+            state.finishedAt = record.finishedAt ?? this.now();
+            runtime.outputs.set(state.stepId, state.output);
+            await this.advanceRun(run.runId);
+            return this.publicRun(run);
+        }
+        if (state.status === "failed" && state.output?.state === record.state) {
+            return this.publicRun(run);
+        }
+        if (state.status !== "waiting_host" && state.status !== "verifying") {
+            throw new Error(`Host action step is not resumable (status: ${state.status})`);
+        }
+        state.status = "failed";
+        state.error = `Host action ${record.state}`;
+        state.output = {
+            ...record.report,
+            state: record.state,
+            actionId: record.actionId,
+            evidenceHash: record.evidenceHash,
+        };
+        state.evidenceHash = record.evidenceHash;
+        state.finishedAt = record.finishedAt ?? this.now();
+        run.status = "failed";
+        run.finishedAt = state.finishedAt;
+        this.setRunFailure(run, {
+            category: "tool_error",
+            reason: state.error,
+            evidence: { actionId: record.actionId, state: record.state },
+        });
+        await this.advanceRun(run.runId);
+        return this.publicRun(run);
+    }
+    async reconcileTimedOutActions(now = this.now()) {
+        const reconciled = [];
+        for (const run of this.runs.values()) {
+            if (run.metadata.truthfulWorkflow !== "on")
+                continue;
+            const runtime = this.runtimes.get(run.runId);
+            if (!runtime)
+                continue;
+            for (const state of run.steps) {
+                if (state.status !== "waiting_host" && state.status !== "verifying")
+                    continue;
+                const definition = runtime.steps.find((step) => step.id === state.stepId);
+                if (!definition || state.startedAt === undefined || now - state.startedAt < stepTimeout(definition)) {
+                    continue;
+                }
+                if (!state.actionId || !this.options.hostActionStore) {
+                    throw new Error("Timed out host action has no durable store identity");
+                }
+                const existing = await this.options.hostActionStore.getHostAction(run.metadata.projectRoot, state.actionId);
+                if (!existing)
+                    throw new Error(`Host action "${state.actionId}" not found during timeout`);
+                const terminal = existing.state === "verified"
+                    || existing.state === "failed"
+                    || existing.state === "cancelled"
+                    || existing.state === "degraded";
+                const record = terminal
+                    ? existing
+                    : await this.options.hostActionStore.failHostAction({
+                        actionId: state.actionId,
+                        projectRoot: run.metadata.projectRoot,
+                        outcome: "degraded",
+                        report: { reason: "step_timeout", timedOutAt: now },
+                    });
+                await this.resumeHostAction(record);
+                reconciled.push(state.actionId);
+            }
+        }
+        return reconciled;
+    }
     async approve(runId, stepId) {
         const run = this.runs.get(runId);
         if (!run)
             throw new Error(`Run "${runId}" not found`);
-        const step = run.steps.find((s) => s.stepId === stepId);
+        const step = run.steps.find((candidate) => candidate.stepId === stepId);
         if (!step)
             throw new Error(`Step "${stepId}" not found in run "${runId}"`);
         if (step.status !== "awaiting_approval") {
             throw new Error(`Step "${stepId}" is not awaiting approval (status: ${step.status})`);
         }
         step.status = "success";
-        step.finishedAt = Date.now();
-        // Check if all steps complete
-        this.maybeCompleteRun(run);
-        await this.persistRun(run);
+        step.finishedAt = this.now();
+        const runtime = this.runtimes.get(runId);
+        if (runtime && step.output)
+            runtime.outputs.set(stepId, step.output);
+        await this.advanceRun(runId);
     }
     async reject(runId, stepId, rejection) {
         const run = this.runs.get(runId);
         if (!run)
             throw new Error(`Run "${runId}" not found`);
-        const step = run.steps.find((s) => s.stepId === stepId);
+        const step = run.steps.find((candidate) => candidate.stepId === stepId);
         if (!step)
             throw new Error(`Step "${stepId}" not found in run "${runId}"`);
         if (step.status !== "awaiting_approval") {
@@ -342,45 +574,23 @@ export class WorkflowEngine {
             : rejection;
         step.status = "failed";
         step.error = normalized.reason;
-        step.finishedAt = Date.now();
+        step.finishedAt = this.now();
         run.status = "failed";
-        run.finishedAt = Date.now();
+        run.finishedAt = this.now();
         run.failureCategory = normalized.category;
         run.failureReason = normalized.reason;
         run.failureEvidence = normalized.evidence;
-        await this.persistRun(run);
+        await this.advanceRun(runId);
     }
-    maybeCompleteRun(run) {
-        const allDone = run.steps.every((s) => s.status === "success" || s.status === "failed" || s.status === "skipped");
-        if (allDone) {
-            const allSuccess = run.steps.every((s) => s.status === "success" || s.status === "skipped");
-            run.status = allSuccess ? "completed" : "failed";
-            run.finishedAt = Date.now();
-        }
-    }
-    // --- Plan Rendering ---
-    /**
-     * Render a markdown execution plan from a telemetry run and workflow template.
-     *
-     * The output is a human-readable plan that Claude Code (or another agent)
-     * can follow step-by-step. Each step includes the instruction, suggested
-     * tools, expected output, and a `devflow_report_step` call template.
-     *
-     * Steps may be in the new `StepInstruction` format (with `instruction`,
-     * `title`, `suggestedTools`) or the legacy `WorkflowStepDef` format (with
-     * only `description`). Both are handled gracefully.
-     */
     renderPlan(run, template) {
-        const resolvedSteps = this.resolveStepRefs(template);
-        const steps = resolvedSteps
+        const steps = this.resolveStepRefs(template)
             .map((step, index) => {
-            const stepAny = step;
-            const title = stepAny.title || stepAny.description || "";
-            const instruction = stepAny.instruction || stepAny.description || "";
-            const suggestedTools = Array.isArray(stepAny.suggestedTools)
-                ? stepAny.suggestedTools.join(", ")
+            const title = isWorkflowStepDef(step) ? step.description : step.title;
+            const instruction = isWorkflowStepDef(step) ? step.description : step.instruction;
+            const suggestedTools = !isWorkflowStepDef(step) && Array.isArray(step.suggestedTools)
+                ? step.suggestedTools.join(", ")
                 : "N/A";
-            const output = stepAny.output || "N/A";
+            const output = !isWorkflowStepDef(step) ? step.output ?? "N/A" : "N/A";
             return `---
 ## Step ${index + 1}: ${title} (\`${step.id}\`)
 
@@ -412,51 +622,59 @@ Follow these steps strictly in order. After each step, call \`devflow_report_ste
 ${steps}
 `;
     }
-    // --- Queries ---
     getRun(runId) {
         const run = this.runs.get(runId);
-        if (!run)
-            return undefined;
+        return run ? this.publicRun(run) : undefined;
+    }
+    async listRuns() {
+        return Array.from(this.runs.values()).map((run) => this.publicRun(run, true));
+    }
+    publicRun(run, compact = false) {
+        const actionIds = uniqueStrings(run.steps.flatMap((step) => step.actionIds ?? []));
         return {
             runId: run.runId,
             type: run.workflowName,
-            status: run.status,
+            status: publicRunStatus(run.status),
             startedAt: run.startedAt,
             finishedAt: run.finishedAt,
-            steps: run.steps.map((s) => ({
-                stepId: s.stepId,
-                status: s.status,
-                input: s.input,
-                output: s.output,
-                duration: s.finishedAt && s.startedAt ? s.finishedAt - s.startedAt : undefined,
-                error: s.error,
+            steps: run.steps.map((step) => ({
+                stepId: step.stepId,
+                status: publicStepStatus(step.status),
+                input: compact ? undefined : step.input,
+                output: compact ? undefined : step.output,
+                duration: step.finishedAt !== undefined && step.startedAt !== undefined
+                    ? step.finishedAt - step.startedAt
+                    : undefined,
+                error: step.error,
+                metadata: {
+                    canonicalStatus: step.status,
+                    actionId: step.actionId,
+                    actionKind: step.actionKind,
+                    actionIds: step.actionIds,
+                    verifiedActionIds: step.verifiedActionIds,
+                    evidenceHash: step.evidenceHash,
+                    shadowCandidate: step.shadowCandidate,
+                },
             })),
             failureCategory: run.failureCategory,
             failureReason: run.failureReason,
             failureEvidence: run.failureEvidence,
+            metadata: {
+                canonicalStatus: run.status,
+                engineRunId: run.metadata.engineRunId,
+                telemetryRunId: run.metadata.telemetryRunId,
+                projectRoot: run.metadata.projectRoot,
+                sessionId: run.metadata.sessionId,
+                executionId: run.metadata.executionId,
+                contextReceipt: run.metadata.contextReceipt,
+                actionIds,
+            },
         };
     }
-    async listRuns() {
-        return Array.from(this.runs.values()).map((r) => ({
-            runId: r.runId,
-            type: r.workflowName,
-            status: r.status,
-            startedAt: r.startedAt,
-            finishedAt: r.finishedAt,
-            steps: r.steps.map((s) => ({
-                stepId: s.stepId,
-                status: s.status,
-                error: s.error,
-            })),
-            failureCategory: r.failureCategory,
-            failureReason: r.failureReason,
-            failureEvidence: r.failureEvidence,
-        }));
-    }
-    stepContext() {
+    stepContext(run) {
         return {
-            sessionId: this.options.sessionId ?? "default",
-            projectRoot: this.options.projectRoot ?? ".",
+            sessionId: run.metadata.sessionId,
+            projectRoot: run.metadata.projectRoot,
             context: this.options.context,
             memory: this.options.memory,
             knowledge: this.options.knowledge,
@@ -464,24 +682,46 @@ ${steps}
             executeInstruction: this.options.executeInstruction,
         };
     }
+    stepState(run, stepId) {
+        const state = run.steps.find((step) => step.stepId === stepId);
+        if (!state)
+            throw new WorkflowDesignError(`Step ${JSON.stringify(stepId)} not found`);
+        return state;
+    }
+    recomputeRunStatus(run) {
+        const hasFailed = run.steps.some((step) => step.status === "failed");
+        const allTerminal = run.steps.every((step) => step.status === "success" || step.status === "skipped");
+        if (hasFailed)
+            run.status = "failed";
+        else if (allTerminal)
+            run.status = "completed";
+        else if (run.steps.some((step) => step.status === "waiting_host" || step.status === "verifying")) {
+            run.status = "waiting_host";
+        }
+        else
+            run.status = "running";
+        run.finishedAt = run.status === "completed" || run.status === "failed" ? this.now() : undefined;
+    }
     setRunFailure(run, failure) {
         run.failureCategory = failure.category;
         run.failureReason = failure.reason;
         run.failureEvidence = failure.evidence;
     }
     runResult(run) {
+        const publicRun = this.publicRun(run, true);
         return {
             runId: run.runId,
-            status: run.status,
-            duration: (run.finishedAt ?? Date.now()) - run.startedAt,
+            status: publicRun.status,
+            duration: (run.finishedAt ?? this.now()) - run.startedAt,
             failureCategory: run.failureCategory,
             failureReason: run.failureReason,
+            metadata: publicRun.metadata,
         };
     }
     async persistRun(run) {
         if (!this.data)
             return;
-        try {
+        const persist = async () => {
             await this.data.sqlExecute(`INSERT OR REPLACE INTO devflow_workflow_runs
           (run_id, type, status, input, steps, started_at, finished_at,
            failure_category, failure_reason, failure_evidence)
@@ -497,23 +737,81 @@ ${steps}
                 run.failureReason ?? null,
                 run.failureEvidence ? JSON.stringify(run.failureEvidence) : null,
             ]);
+            await this.data.kvSet(`workflow:run-metadata:${run.runId}`, {
+                ...run.metadata,
+                canonicalStatus: run.status,
+                actionIds: uniqueStrings(run.steps.flatMap((step) => step.actionIds ?? [])),
+            });
+        };
+        if (run.metadata.truthfulWorkflow === "on") {
+            await persist();
+            return;
+        }
+        try {
+            await persist();
         }
         catch {
-            // Persistence is best-effort for embedders with legacy schemas.
+            // Legacy off/shadow embedders may not have the current persistence schema.
         }
     }
-    // --- Events (SSE support) ---
+    finishLogIfTerminal(run, runtime) {
+        if (runtime.loggedEnded || (run.status !== "completed" && run.status !== "failed"))
+            return;
+        runtime.loggedEnded = true;
+        getLogWriter().endRun(run.runId, {
+            steps: run.steps.length,
+            tools: run.steps.filter((step) => step.status === "success" || step.status === "failed").length,
+            errors: run.steps.filter((step) => step.status === "failed").length,
+            tokens: 0,
+        });
+    }
     onEvent(runId, listener) {
         if (!this.eventListeners.has(runId))
             this.eventListeners.set(runId, []);
         this.eventListeners.get(runId).push(listener);
     }
     emit(runId, event) {
-        const listeners = this.eventListeners.get(runId) ?? [];
-        for (const fn of listeners)
-            fn(event);
+        for (const listener of this.eventListeners.get(runId) ?? [])
+            listener(event);
     }
     registerDefaults() {
+        const actions = (executeTimeout) => [
+            {
+                id: "execute",
+                description: "Execute changes",
+                type: "stateful",
+                run: "builtin:execute",
+                depends: ["plan"],
+                inputs: { plan: "${plan.plan}" },
+                retry: 3,
+                timeout: executeTimeout,
+            },
+            {
+                id: "verify",
+                description: "Verify changes",
+                type: "simple",
+                run: "builtin:verify",
+                depends: ["execute"],
+                inputs: {
+                    actionIds: "${execute.actionIds}",
+                    verifiedActionIds: "${execute.verifiedActionIds}",
+                },
+                timeout: 60000,
+            },
+            {
+                id: "commit",
+                description: "Generate commit message",
+                type: "manual",
+                run: "builtin:commit",
+                depends: ["verify"],
+                inputs: {
+                    summary: "${trigger.input}",
+                    actionIds: "${verify.actionIds}",
+                    verifiedActionIds: "${verify.verifiedActionIds}",
+                },
+                timeout: 30000,
+            },
+        ];
         this.register({
             name: "bugfix",
             description: "Standard bug fix workflow: analyze → plan → execute → verify → commit",
@@ -522,9 +820,7 @@ ${steps}
                 { id: "analyze", description: "Analyze bug description", type: "simple", run: "builtin:analyze", timeout: 30000 },
                 { id: "retrieve", description: "Retrieve relevant context", type: "simple", run: "builtin:retrieve", depends: ["analyze"], timeout: 30000 },
                 { id: "plan", description: "Generate fix plan", type: "simple", run: "builtin:plan", depends: ["retrieve"], timeout: 30000 },
-                { id: "execute", description: "Execute fix", type: "stateful", run: "builtin:execute", depends: ["plan"], retry: 3, timeout: 120000 },
-                { id: "verify", description: "Verify fix", type: "simple", run: "builtin:verify", depends: ["execute"], timeout: 60000 },
-                { id: "commit", description: "Generate commit message", type: "manual", run: "builtin:commit", depends: ["verify"], timeout: 30000 },
+                ...actions(120000),
             ],
             triggers: [{ type: "mcp", tool: "run_workflow" }, { type: "cli", command: "bugfix" }],
         });
@@ -536,9 +832,7 @@ ${steps}
                 { id: "analyze", description: "Analyze feature requirements", type: "simple", run: "builtin:analyze", timeout: 30000 },
                 { id: "retrieve", description: "Retrieve context", type: "simple", run: "builtin:retrieve", depends: ["analyze"], timeout: 30000 },
                 { id: "plan", description: "Generate implementation plan", type: "simple", run: "builtin:plan", depends: ["retrieve"], timeout: 30000 },
-                { id: "execute", description: "Implement feature", type: "stateful", run: "builtin:execute", depends: ["plan"], retry: 3, timeout: 300000 },
-                { id: "verify", description: "Verify implementation", type: "simple", run: "builtin:verify", depends: ["execute"], timeout: 60000 },
-                { id: "commit", description: "Generate commit message", type: "manual", run: "builtin:commit", depends: ["verify"], timeout: 30000 },
+                ...actions(300000),
             ],
             triggers: [{ type: "mcp", tool: "run_workflow" }, { type: "cli", command: "feature" }],
         });
@@ -549,35 +843,154 @@ ${steps}
             steps: [
                 { id: "analyze", description: "Analyze review scope", type: "simple", run: "builtin:analyze", timeout: 30000 },
                 { id: "plan", description: "Generate review checklist", type: "simple", run: "builtin:plan", depends: ["analyze"], timeout: 30000 },
-                { id: "verify", description: "Run review checks", type: "simple", run: "builtin:verify", depends: ["plan"], timeout: 60000 },
-                { id: "commit", description: "Post review summary", type: "manual", run: "builtin:commit", depends: ["verify"], timeout: 30000 },
+                {
+                    id: "verify",
+                    description: "Run review checks",
+                    type: "simple",
+                    run: "builtin:verify",
+                    depends: ["plan"],
+                    timeout: 60000,
+                },
+                {
+                    id: "commit",
+                    description: "Post review summary",
+                    type: "manual",
+                    run: "builtin:commit",
+                    depends: ["verify"],
+                    inputs: {
+                        summary: "${trigger.input}",
+                        actionIds: "${verify.actionIds}",
+                        verifiedActionIds: "${verify.verifiedActionIds}",
+                    },
+                    timeout: 30000,
+                },
             ],
             triggers: [{ type: "mcp", tool: "run_workflow" }, { type: "cli", command: "review" }],
         });
     }
 }
-/**
- * Resolve ${variable} references in input values.
- * ${trigger.X} comes from the top-level input.
- * ${stepId.field} comes from previous step outputs.
- */
 function resolveInputs(inputs, outputs, triggerInput) {
     const resolved = {};
     for (const [key, value] of Object.entries(inputs)) {
+        const exact = /^\$\{([^}]+)\}$/.exec(value);
+        if (exact) {
+            const referenced = resolveReference(exact[1], outputs, triggerInput);
+            resolved[key] = referenced !== null && typeof referenced === "object"
+                ? referenced
+                : String(referenced ?? "");
+            continue;
+        }
         resolved[key] = value.replace(/\$\{([^}]+)\}/g, (_match, path) => {
-            const parts = path.split(".");
-            if (parts[0] === "trigger") {
-                return String(triggerInput[parts.slice(1).join(".")] ?? "");
-            }
-            const stepOutput = outputs.get(parts[0]);
-            if (stepOutput && parts.length > 1) {
-                return String(stepOutput[parts.slice(1).join(".")] ?? "");
-            }
-            return String(stepOutput ?? "");
+            return String(resolveReference(path, outputs, triggerInput) ?? "");
         });
     }
     return resolved;
 }
+function resolveReference(path, outputs, triggerInput) {
+    const parts = path.split(".");
+    if (parts[0] === "trigger")
+        return readPath(triggerInput, parts.slice(1));
+    const output = outputs.get(parts[0]);
+    if (!output)
+        return "";
+    return parts.length === 1 ? output : readPath(output, parts.slice(1));
+}
+function readPath(value, parts) {
+    let current = value;
+    for (const part of parts) {
+        if (typeof current !== "object" || current === null)
+            return "";
+        current = current[part];
+    }
+    return current ?? "";
+}
+function normalizeHostActionRequest(output) {
+    const canonical = output.actionRequired === true && output.state === "waiting";
+    const legacy = output.status === "host_action_required";
+    if (!canonical && !legacy)
+        return null;
+    return {
+        actionRequired: true,
+        actionKind: output.actionKind === "verify" ? "verify" : "execute",
+        state: "waiting",
+        requiredEvidence: ["context_receipt", "tool_or_diff", "report_step"],
+    };
+}
+function legacyBuiltinOutput(handlerId, input) {
+    if (handlerId === "builtin:execute") {
+        const plan = Array.isArray(input.plan) ? input.plan : [];
+        return {
+            changes: plan.map((step, index) => ({
+                step: index + 1,
+                description: String(step),
+                status: "done",
+            })),
+            totalChanges: plan.length,
+            valid: true,
+        };
+    }
+    if (handlerId === "builtin:verify") {
+        const changes = Array.isArray(input.changes) ? input.changes : [];
+        return { verified: changes.length, passed: changes.length, failed: 0, valid: true };
+    }
+    const summary = typeof input.summary === "string" ? input.summary : "Apply changes";
+    const verified = typeof input.verified === "number" ? input.verified : 0;
+    return { message: `feat: ${summary}\n\nVerified ${verified} changes.`, ready: true };
+}
+function isLegacyBuiltinHostAction(handlerId) {
+    return handlerId === "builtin:execute" || handlerId === "builtin:verify";
+}
+function isWorkflowStepDef(step) {
+    return "type" in step;
+}
+function stepTimeout(step) {
+    return isWorkflowStepDef(step) ? step.timeout : 60000;
+}
+function publicRunStatus(status) {
+    return status === "waiting_host" ? "running" : status;
+}
+function publicStepStatus(status) {
+    if (status === "waiting_host"
+        || status === "verifying"
+        || status === "awaiting_approval")
+        return "running";
+    return status;
+}
+function sameHostActionRecord(left, right) {
+    return left.actionId === right.actionId
+        && left.runId === right.runId
+        && left.engineRunId === right.engineRunId
+        && left.stepId === right.stepId
+        && left.projectRoot === right.projectRoot
+        && left.sessionId === right.sessionId
+        && left.executionId === right.executionId
+        && left.contextReceipt === right.contextReceipt
+        && left.state === right.state
+        && left.evidenceHash === right.evidenceHash
+        && stableJson(left.report) === stableJson(right.report);
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string" && item.length > 0)
+        : [];
+}
+function uniqueStrings(values) {
+    return Array.from(new Set(values));
+}
+function optionalString(value) {
+    return value;
+}
 class WorkflowDesignError extends Error {
     constructor(message) {
         super(message);