@assistkick/create 1.7.0 → 1.9.0

package/templates/assistkick-product-system/packages/shared/lib/workflow_engine.ts

@@ -0,0 +1,1437 @@
+/**
+ * WorkflowEngine — executes workflow graphs defined in the workflows table.
+ * Replaces the hardcoded Pipeline class with a data-driven, graph-traversal engine.
+ *
+ * Responsibilities:
+ * 1. Load workflow graph_data and parse into a traversable directed graph
+ * 2. Execute nodes sequentially following edges, dispatching to handlers
+ * 3. Evaluate branching conditions and follow matching output edges
+ * 4. Handle back-edges (loops) by re-executing previously visited nodes
+ * 5. Persist checkpoints after each node (workflow_node_executions)
+ * 6. Resume interrupted executions by skipping completed nodes
+ * 7. Manage worktree lifecycle (create before first node, merge/cleanup at End)
+ * 8. Maintain shared execution context passed between nodes
+ */
+
+import { randomUUID } from 'node:crypto';
+import { resolve as pathResolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { eq, and } from 'drizzle-orm';
+import {
+  workflows,
+  workflowExecutions,
+  workflowNodeExecutions,
+  workflowToolCalls,
+  agents,
+  nodes as nodesTable,
+} from '../db/schema.js';
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+interface WorkflowNode {
+  id: string;
+  type: string;
+  data: Record<string, unknown>;
+}
+
+interface WorkflowEdge {
+  id: string;
+  source: string;
+  target: string;
+  sourceHandle?: string;
+  data?: { label?: string };
+}
+
+interface WorkflowGraph {
+  nodes: WorkflowNode[];
+  edges: WorkflowEdge[];
+}
+
+interface ExecutionContext {
+  cycle: number;
+  featureId: string;
+  projectId: string;
+  worktreePath: string;
+  branchName: string;
+  [key: string]: unknown;
+}
+
+interface NodeHandlerResult {
+  /** Which output handle/label to follow (null = default/single outgoing edge) */
+  outputLabel: string | null;
+  /** Optional data to persist in workflow_node_executions.output_data */
+  outputData?: Record<string, unknown>;
+}
+
+interface BundleServiceDep {
+  buildBundle: () => Promise<{ ready: boolean; building: boolean; bundlePath: string | null; error: string | null }>;
+}
+
+interface TtsServiceDep {
+  generate: (opts: { scriptPath: string; projectId: string; featureId: string; force?: boolean; voiceId?: string }) => Promise<{
+    processed: number; generated: number; skipped: number; errors: string[]; durations: Record<string, number>; audioBasePath: string;
+  }>;
+}
+
+interface VideoRenderServiceDep {
+  startRender: (request: {
+    compositionId: string; projectId: string; featureId: string; resolution?: string; aspectRatio?: string; fileOutputPrefix?: string;
+  }) => Promise<{ id: string; status: string; progress: number; filePath: string | null; error: string | null; compositionId: string }>;
+}
+
+interface WorkflowEngineDeps {
+  db: ReturnType<typeof import('./db.js').getDb>;
+  kanban: {
+    getKanbanEntry: (featureId: string) => Promise<Record<string, unknown> | null>;
+    saveKanbanEntry: (featureId: string, entry: Record<string, unknown>, projectId?: string) => Promise<void>;
+  };
+  claudeService: {
+    spawnClaude: (prompt: string, cwd: string, label?: string, opts?: Record<string, unknown>) => Promise<string>;
+    spawnCommand: (cmd: string, args: string[], cwd: string) => Promise<string>;
+  };
+  gitWorkflow: {
+    createWorktree: (featureId: string) => Promise<string>;
+    removeWorktree: (worktreePath: string) => Promise<void>;
+    deleteBranch: (featureId: string, force?: boolean) => Promise<void>;
+    commitChanges: (featureId: string, worktreePath: string) => Promise<void>;
+    rebaseBranch: (featureId: string, worktreePath: string) => Promise<void>;
+    mergeBranch: (featureId: string) => Promise<void>;
+    fixMergeConflicts: (featureId: string) => Promise<boolean>;
+    stash: () => Promise<boolean>;
+    unstash: () => Promise<void>;
+    getDirtyFiles: () => Promise<string[]>;
+  };
+  bundleService?: BundleServiceDep;
+  ttsService?: TtsServiceDep;
+  videoRenderService?: VideoRenderServiceDep;
+  log: (tag: string, message: string) => void;
+}
+
+// ── WorkflowEngine ────────────────────────────────────────────────────
+
+export class WorkflowEngine {
+  private db: WorkflowEngineDeps['db'];
+  private kanban: WorkflowEngineDeps['kanban'];
+  private claudeService: WorkflowEngineDeps['claudeService'];
+  private gitWorkflow: WorkflowEngineDeps['gitWorkflow'];
+  private bundleService?: BundleServiceDep;
+  private ttsService?: TtsServiceDep;
+  private videoRenderService?: VideoRenderServiceDep;
+  private log: WorkflowEngineDeps['log'];
+
+  constructor({ db, kanban, claudeService, gitWorkflow, bundleService, ttsService, videoRenderService, log }: WorkflowEngineDeps) {
+    this.db = db;
+    this.kanban = kanban;
+    this.claudeService = claudeService;
+    this.gitWorkflow = gitWorkflow;
+    this.bundleService = bundleService;
+    this.ttsService = ttsService;
+    this.videoRenderService = videoRenderService;
+    this.log = log;
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────
+
+  /**
+   * Start a new workflow execution for a feature.
+   * Creates a workflow_execution row, creates a worktree, and begins
+   * graph traversal from the Start node. Returns immediately (fire-and-forget).
+   */
+  start = async (featureId: string, workflowId: string, projectId: string): Promise<{ executionId: string }> => {
+    this.log('WORKFLOW', `Starting workflow ${workflowId} for feature ${featureId}`);
+
+    // Load workflow
+    const [workflow] = await this.db.select().from(workflows).where(eq(workflows.id, workflowId));
+    if (!workflow) {
+      throw new Error(`Workflow ${workflowId} not found`);
+    }
+
+    const graph: WorkflowGraph = JSON.parse(workflow.graphData);
+    const startNode = graph.nodes.find(n => n.type === 'start');
+    if (!startNode) {
+      throw new Error(`Workflow ${workflowId} has no start node`);
+    }
+
+    // Create worktree and feature branch
+    const worktreePath = await this.gitWorkflow.createWorktree(featureId);
+    const branchName = `feature/${featureId}`;
+
+    // Build initial context
+    // Derive the monorepo root from this file's location (packages/shared/lib/workflow_engine.ts → ../../..)
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const mainSkillDir = pathResolve(__dirname, '..', '..', '..');
+    const mainToolsDir = pathResolve(mainSkillDir, 'packages', 'shared', 'tools');
+    const pidFlag = ` --project-id ${projectId}`;
+
+    const context: ExecutionContext = {
+      cycle: 0,
+      featureId,
+      projectId,
+      worktreePath,
+      branchName,
+      mainSkillDir,
+      mainToolsDir,
+      pidFlag,
+    };
+
+    // Enrich context with feature data for agent prompt resolution
+    const [featureNode] = await this.db.select().from(nodesTable).where(eq(nodesTable.id, featureId));
+    if (featureNode) {
+      context.featureDescription = this.extractFeatureDescription(featureNode.body, featureNode.name);
+      context.compositionName = this.deriveCompositionName(featureNode.name);
+    }
+
+    // Load iteration comments from kanban notes for re-runs
+    const kanbanEntry = await this.kanban.getKanbanEntry(featureId);
+    if (kanbanEntry?.notes?.length) {
+      context.iterationComments = '## Previous Review Notes\n' + (kanbanEntry.notes as Array<{ text?: string }>).map((n) => `- ${typeof n === 'string' ? n : (n.text || '')}`).join('\n');
+    } else {
+      context.iterationComments = '';
+    }
+
+    // Create execution row
+    const executionId = randomUUID();
+    const now = new Date().toISOString();
+    await this.db.insert(workflowExecutions).values({
+      id: executionId,
+      workflowId,
+      featureId,
+      status: 'running',
+      currentNodeId: startNode.id,
+      context: JSON.stringify(context),
+      startedAt: now,
+      updatedAt: now,
+    });
+
+    this.log('WORKFLOW', `Created execution ${executionId}, worktree at ${worktreePath}`);
+
+    // Fire-and-forget: traverse the graph asynchronously
+    this.executeGraph(executionId, graph, startNode.id, context).catch(err => {
+      this.log('WORKFLOW', `UNCAUGHT ERROR in execution ${executionId}: ${err.message}`);
+      this.setExecutionStatus(executionId, 'failed', null, context).catch(() => {});
+    });
+
+    return { executionId };
+  };
+
+  /**
+   * Resume a failed/interrupted workflow execution.
+   * Finds the current node, resets its status, and re-executes from that point.
+   */
+  resume = async (executionId: string): Promise<void> => {
+    this.log('WORKFLOW', `Resuming execution ${executionId}`);
+
+    const [execution] = await this.db.select().from(workflowExecutions)
+      .where(eq(workflowExecutions.id, executionId));
+    if (!execution) {
+      throw new Error(`Execution ${executionId} not found`);
+    }
+    if (execution.status === 'running') {
+      // Allow resuming stuck 'running' executions — mark them as failed first
+      this.log('WORKFLOW', `Execution ${executionId} is stuck in 'running' — marking as failed before resuming`);
+      await this.db.update(workflowExecutions)
+        .set({ status: 'failed', updatedAt: new Date().toISOString() })
+        .where(eq(workflowExecutions.id, executionId));
+    }
+
+    // Load workflow graph
+    const [workflow] = await this.db.select().from(workflows)
+      .where(eq(workflows.id, execution.workflowId));
+    if (!workflow) {
+      throw new Error(`Workflow ${execution.workflowId} not found`);
+    }
+
+    const graph: WorkflowGraph = JSON.parse(workflow.graphData);
+    const context: ExecutionContext = JSON.parse(execution.context);
+    const currentNodeId = execution.currentNodeId;
+
+    if (!currentNodeId) {
+      throw new Error(`Execution ${executionId} has no current node to resume from`);
+    }
+
+    // Find the failed/interrupted node execution and increment its attempt
+    const nodeExecs = await this.db.select().from(workflowNodeExecutions)
+      .where(and(
+        eq(workflowNodeExecutions.executionId, executionId),
+        eq(workflowNodeExecutions.nodeId, currentNodeId),
+      ));
+
+    const failedExec = nodeExecs.find(ne => ne.status === 'failed' || ne.status === 'running');
+    if (failedExec) {
+      await this.db.update(workflowNodeExecutions)
+        .set({ status: 'pending', attempt: failedExec.attempt + 1 })
+        .where(eq(workflowNodeExecutions.id, failedExec.id));
+    }
+
+    // Set execution back to running
+    await this.db.update(workflowExecutions)
+      .set({ status: 'running', updatedAt: new Date().toISOString() })
+      .where(eq(workflowExecutions.id, executionId));
+
+    // Resume graph traversal from the current node
+    this.executeGraph(executionId, graph, currentNodeId, context).catch(err => {
+      this.log('WORKFLOW', `UNCAUGHT ERROR resuming ${executionId}: ${err.message}`);
+      this.setExecutionStatus(executionId, 'failed', currentNodeId, context).catch(() => {});
+    });
+  };
+
+  /**
+   * Force-advance the workflow to the next node, skipping the current one.
+   * Marks the current node as completed and resumes from the next node in the graph.
+   */
+  forceNextNode = async (featureId: string, nodeId: string): Promise<void> => {
+    this.log('WORKFLOW', `Force-next requested for feature ${featureId}, node ${nodeId}`);
+
+    const execution = await this.findLatestExecution(featureId);
+    if (!execution) throw new Error(`No execution found for feature ${featureId}`);
+    if (execution.currentNodeId !== nodeId) {
+      throw new Error(`Node ${nodeId} is not the current execution node (current: ${execution.currentNodeId})`);
+    }
+
+    const [workflow] = await this.db.select().from(workflows)
+      .where(eq(workflows.id, execution.workflowId));
+    if (!workflow) throw new Error(`Workflow ${execution.workflowId} not found`);
+
+    const graph: WorkflowGraph = JSON.parse(workflow.graphData);
+    const context: ExecutionContext = JSON.parse(execution.context);
+
+    // Mark current node execution as completed (skipped)
+    const nodeExecs = await this.db.select().from(workflowNodeExecutions)
+      .where(and(
+        eq(workflowNodeExecutions.executionId, execution.id),
+        eq(workflowNodeExecutions.nodeId, nodeId),
+      ));
+    const currentNodeExec = nodeExecs.find(ne => ne.status === 'running' || ne.status === 'failed');
+    if (currentNodeExec) {
+      await this.db.update(workflowNodeExecutions)
+        .set({ status: 'completed', completedAt: new Date().toISOString() })
+        .where(eq(workflowNodeExecutions.id, currentNodeExec.id));
+    }
+
+    // Resolve the next node in the graph (follow the default edge)
+    const nextNodeId = this.resolveNextNode(graph, nodeId, null);
+    if (!nextNodeId) {
+      // No next node — mark execution as completed
+      this.log('WORKFLOW', `No next node after ${nodeId} — marking execution completed`);
+      await this.setExecutionStatus(execution.id, 'completed', null, context);
+      return;
+    }
+
+    this.log('WORKFLOW', `Force-advancing from ${nodeId} to ${nextNodeId}`);
+
+    // Ensure execution is in 'running' state
+    await this.db.update(workflowExecutions)
+      .set({ status: 'running', updatedAt: new Date().toISOString() })
+      .where(eq(workflowExecutions.id, execution.id));
+
+    // Resume graph traversal from the next node
+    this.executeGraph(execution.id, graph, nextNodeId, context).catch(err => {
+      this.log('WORKFLOW', `UNCAUGHT ERROR after force-next ${execution.id}: ${err.message}`);
+      this.setExecutionStatus(execution.id, 'failed', nextNodeId, context).catch(() => {});
+    });
+  };
+
+  /**
+   * Restart the current workflow node — resets it and re-executes from that point.
+   */
+  restartNode = async (featureId: string, nodeId: string): Promise<void> => {
+    this.log('WORKFLOW', `Restart-node requested for feature ${featureId}, node ${nodeId}`);
+
+    const execution = await this.findLatestExecution(featureId);
+    if (!execution) throw new Error(`No execution found for feature ${featureId}`);
+    if (execution.currentNodeId !== nodeId) {
+      throw new Error(`Node ${nodeId} is not the current execution node (current: ${execution.currentNodeId})`);
+    }
+
+    const [workflow] = await this.db.select().from(workflows)
+      .where(eq(workflows.id, execution.workflowId));
+    if (!workflow) throw new Error(`Workflow ${execution.workflowId} not found`);
+
+    const graph: WorkflowGraph = JSON.parse(workflow.graphData);
+    const context: ExecutionContext = JSON.parse(execution.context);
+
+    // Reset the current node execution — increment attempt counter
+    const nodeExecs = await this.db.select().from(workflowNodeExecutions)
+      .where(and(
+        eq(workflowNodeExecutions.executionId, execution.id),
+        eq(workflowNodeExecutions.nodeId, nodeId),
+      ));
+    const currentNodeExec = nodeExecs.find(ne => ne.status === 'running' || ne.status === 'failed');
+    if (currentNodeExec) {
+      await this.db.update(workflowNodeExecutions)
+        .set({ status: 'pending', attempt: currentNodeExec.attempt + 1 })
+        .where(eq(workflowNodeExecutions.id, currentNodeExec.id));
+    }
+
+    // Set execution back to running
+    await this.db.update(workflowExecutions)
+      .set({ status: 'running', updatedAt: new Date().toISOString() })
+      .where(eq(workflowExecutions.id, execution.id));
+
+    // Re-execute from the current node
+    this.executeGraph(execution.id, graph, nodeId, context).catch(err => {
+      this.log('WORKFLOW', `UNCAUGHT ERROR after restart-node ${execution.id}: ${err.message}`);
+      this.setExecutionStatus(execution.id, 'failed', nodeId, context).catch(() => {});
+    });
+  };
+
+  /**
+   * Find the most recent execution for a feature (any status).
+   * Returns the execution row or null.
+   */
+  private findLatestExecution = async (featureId: string) => {
+    const executions = await this.db.select().from(workflowExecutions)
+      .where(eq(workflowExecutions.featureId, featureId));
+    if (executions.length === 0) return null;
+    return executions.sort((a, b) =>
+      new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime()
+    )[0];
+  };
+
+  /**
+   * Get the current execution status for a feature.
+   * Returns execution state, current node, and per-node statuses.
+   */
+  getStatus = async (featureId: string): Promise<Record<string, unknown>> => {
+    // Find the most recent execution for this feature
+    const executions = await this.db.select().from(workflowExecutions)
+      .where(eq(workflowExecutions.featureId, featureId));
+
+    if (executions.length === 0) {
+      return { status: 'idle', featureId };
+    }
+
+    // Pick the most recent by startedAt
+    const execution = executions.sort((a, b) =>
+      new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime()
+    )[0];
+
+    // Load node executions
+    const nodeExecs = await this.db.select().from(workflowNodeExecutions)
+      .where(eq(workflowNodeExecutions.executionId, execution.id));
+
+    const completed = nodeExecs.filter(ne => ne.status === 'completed').map(ne => ne.nodeId);
+    const failed = nodeExecs.filter(ne => ne.status === 'failed').map(ne => ne.nodeId);
+    const pending = nodeExecs.filter(ne => ne.status === 'pending' || ne.status === 'running').map(ne => ne.nodeId);
+
+    // Resolve current node type and agent name from workflow graph
+    let currentNodeType: string | null = null;
+    let currentAgentName: string | null = null;
+    if (execution.currentNodeId) {
+      try {
+        const [workflow] = await this.db.select().from(workflows)
+          .where(eq(workflows.id, execution.workflowId));
+        if (workflow) {
+          const graph: WorkflowGraph = JSON.parse(workflow.graphData);
+          const currentNode = graph.nodes.find(n => n.id === execution.currentNodeId);
+          if (currentNode) {
+            currentNodeType = currentNode.type;
+            // If the current node is a RunAgent node and execution is running, resolve agent name
+            if (currentNode.type === 'runAgent' && execution.status === 'running') {
+              const agentId = (currentNode.data as { agentId?: string }).agentId;
+              if (agentId) {
+                const [agent] = await this.db.select().from(agents).where(eq(agents.id, agentId));
+                if (agent) currentAgentName = agent.name;
+              }
+            }
+          }
+        }
+      } catch { /* non-critical */ }
+    }
+
+    // Get error message from the most recent failed node execution
+    let errorMessage: string | null = null;
+    if (execution.status === 'failed') {
+      const failedExec = nodeExecs.find(ne => ne.status === 'failed' && ne.error);
+      if (failedExec) errorMessage = failedExec.error;
+    }
+
+    return {
+      executionId: execution.id,
+      status: execution.status,
+      featureId,
+      currentNodeId: execution.currentNodeId,
+      currentNodeType,
+      currentAgentName,
+      error: errorMessage,
+      completedNodes: completed,
+      failedNodes: failed,
+      pendingNodes: pending,
+    };
+  };
+
+  /**
+   * Get per-node KPI metrics for a workflow execution.
+   * Returns an array of metrics for each runAgent node execution.
+   */
+  getExecutionMetrics = async (executionId: string): Promise<Record<string, unknown>[]> => {
+    const nodeExecs = await this.db.select().from(workflowNodeExecutions)
+      .where(eq(workflowNodeExecutions.executionId, executionId));
+
+    // Load the workflow graph to identify runAgent nodes
+    const [execution] = await this.db.select().from(workflowExecutions)
+      .where(eq(workflowExecutions.id, executionId));
+    if (!execution) return [];
+
+    const [workflow] = await this.db.select().from(workflows)
+      .where(eq(workflows.id, execution.workflowId));
+    if (!workflow) return [];
+
+    const graph: WorkflowGraph = JSON.parse(workflow.graphData);
+    const runAgentNodes = new Set(
+      graph.nodes.filter(n => n.type === 'runAgent').map(n => n.id),
+    );
+
+    return nodeExecs
+      .filter(ne => runAgentNodes.has(ne.nodeId) && ne.outputData)
+      .map(ne => {
+        const data = JSON.parse(ne.outputData!);
+        return {
+          nodeId: ne.nodeId,
+          agentName: data.agentName ?? null,
+          toolCalls: data.toolCalls ?? null,
+          costUsd: data.costUsd ?? null,
+          numTurns: data.numTurns ?? null,
+          stopReason: data.stopReason ?? null,
+          model: data.model ?? null,
+          contextWindowPct: data.contextWindowPct ?? null,
+          status: ne.status,
+        };
+      });
+  };
+
+  /**
+   * Find the most recent resumable execution for a feature (failed or interrupted).
+   * Returns the executionId or null if none found.
+   */
+  findResumableExecution = async (featureId: string): Promise<string | null> => {
+    const executions = await this.db.select().from(workflowExecutions)
+      .where(eq(workflowExecutions.featureId, featureId));
+
+    if (executions.length === 0) return null;
+
+    // Find the most recent failed or stuck-running execution.
+    // A 'running' execution is considered stuck if updatedAt is older than 5 minutes.
+    const STALE_THRESHOLD_MS = 5 * 60 * 1000;
+    const now = Date.now();
+    const resumable = executions
+      .filter((e: any) => {
+        if (e.status === 'failed') return true;
+        if (e.status === 'running') {
+          const updatedAt = new Date(e.updatedAt).getTime();
+          return (now - updatedAt) > STALE_THRESHOLD_MS;
+        }
+        return false;
+      })
+      .sort((a: any, b: any) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+
+    return resumable.length > 0 ? resumable[0].id : null;
+  };
+
+  // ── Graph Traversal ─────────────────────────────────────────────────
+
+  /**
+   * Main graph traversal loop. Executes nodes sequentially, following edges.
+   * Back-edges cause re-execution (loops). Branching nodes return an outputLabel
+   * to pick the correct outgoing edge.
+   */
+  private executeGraph = async (
+    executionId: string,
+    graph: WorkflowGraph,
+    startNodeId: string,
+    context: ExecutionContext,
+  ): Promise<void> => {
+    let currentNodeId: string | null = startNodeId;
+
+    while (currentNodeId) {
+      const node = graph.nodes.find(n => n.id === currentNodeId);
+      if (!node) {
+        throw new Error(`Node ${currentNodeId} not found in workflow graph`);
+      }
+
+      // Update execution's current_node_id before executing
+      await this.setExecutionCurrentNode(executionId, currentNodeId, context);
+
+      this.log('WORKFLOW', `Executing node ${node.id} (${node.type})`);
+
+      // Create or reset node execution record
+      const nodeExecId = await this.upsertNodeExecution(executionId, node.id, 'running');
+
+      try {
+        const result = await this.executeNode(node, context, executionId);
+
+        // Mark node as completed
+        await this.completeNodeExecution(nodeExecId, result.outputData || null);
+        this.log('WORKFLOW', `Node ${node.id} completed (output: ${result.outputLabel || 'default'})`);
+
+        // Find the next node via edges
+        currentNodeId = this.resolveNextNode(graph, node.id, result.outputLabel);
+
+        if (currentNodeId) {
+          this.log('WORKFLOW', `Next node: ${currentNodeId}`);
+        } else {
+          this.log('WORKFLOW', `No outgoing edge from ${node.id} — traversal complete`);
+        }
+      } catch (err: any) {
+        this.log('WORKFLOW', `Node ${node.id} FAILED: ${err.message}`);
+
+        // Mark node execution as failed
+        await this.db.update(workflowNodeExecutions)
+          .set({
+            status: 'failed',
+            error: err.message,
+            completedAt: new Date().toISOString(),
+          })
+          .where(eq(workflowNodeExecutions.id, nodeExecId));
+
+        // Mark workflow execution as failed — do NOT clean up worktree (enables resume)
+        await this.setExecutionStatus(executionId, 'failed', node.id, context);
+        return;
+      }
+    }
+
+    // Loop exited normally (no more outgoing edges) without hitting an End node —
+    // ensure execution is finalized so it doesn't stay stuck in 'running'.
+    this.log('WORKFLOW', `Graph traversal ended without End node — marking execution completed`);
+    await this.setExecutionStatus(executionId, 'completed', null, context);
+  };
+
+  // ── Node Handlers ───────────────────────────────────────────────────
+
+  /**
+   * Dispatch to the appropriate handler based on node type.
+   */
+  private executeNode = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+    executionId: string,
+  ): Promise<NodeHandlerResult> => {
+    switch (node.type) {
+      case 'start':
+        return this.handleStart(node, context);
+      case 'transitionCard':
+        return this.handleTransitionCard(node, context);
+      case 'runAgent':
+        return this.handleRunAgent(node, context, executionId);
+      case 'checkCardPosition':
+        return this.handleCheckCardPosition(node, context);
+      case 'checkCycleCount':
+        return this.handleCheckCycleCount(node, context);
+      case 'setCardMetadata':
+        return this.handleSetCardMetadata(node, context);
+      case 'end':
+        return this.handleEnd(node, context, executionId);
+      case 'group':
+        return this.handleGroup(node, context, executionId);
+      case 'rebuildBundle':
+        return this.handleRebuildBundle(node, context);
+      case 'generateTTS':
+        return this.handleGenerateTTS(node, context);
+      case 'renderVideo':
+        return this.handleRenderVideo(node, context);
+      default:
+        throw new Error(`Unknown node type: ${node.type}`);
+    }
+  };
+
+  /**
+   * Start node — no-op passthrough.
+   */
+  private handleStart = async (_node: WorkflowNode, _context: ExecutionContext): Promise<NodeHandlerResult> => {
+    return { outputLabel: null };
+  };
+
+  /**
+   * TransitionCard — moves the kanban card from one column to another.
+   * Fails if the card is not in the expected source column.
+   */
+  private handleTransitionCard = async (node: WorkflowNode, context: ExecutionContext): Promise<NodeHandlerResult> => {
+    const { fromColumn, toColumn } = node.data as { fromColumn: string; toColumn: string };
+    const { featureId } = context;
+
+    const entry = await this.kanban.getKanbanEntry(featureId);
+    if (!entry) {
+      throw new Error(`Feature ${featureId} not found in kanban`);
+    }
+
+    if ((entry as any).column !== fromColumn) {
+      throw new Error(
+        `Expected card in "${fromColumn}" but found in "${(entry as any).column}"`,
+      );
+    }
+
+    (entry as any).column = toColumn;
+    (entry as any).moved_at = new Date().toISOString();
+    await this.kanban.saveKanbanEntry(featureId, entry);
+    this.log('WORKFLOW', `Moved ${featureId} from ${fromColumn} → ${toColumn}`);
+
+    return { outputLabel: null };
+  };
+
+  /**
+   * RunAgent — loads agent from DB, resolves prompt template placeholders,
+   * spawns Claude in the worktree, and captures output.
+   * Wires onToolUse/onResult/onTurnUsage callbacks to capture KPI metrics.
+   */
+  private handleRunAgent = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+    executionId: string,
+  ): Promise<NodeHandlerResult> => {
+    const { agentId } = node.data as { agentId: string };
+    const { featureId, worktreePath } = context;
+
+    // Load agent from DB
+    const [agent] = await this.db.select().from(agents).where(eq(agents.id, agentId));
+    if (!agent) {
+      throw new Error(`Agent ${agentId} not found`);
+    }
+
+    // Resolve {{placeholder}} variables in prompt template
+    const resolvedPrompt = this.resolvePromptTemplate(agent.promptTemplate, context);
+
+    // Find the node execution ID for persisting tool calls
+    const nodeExecs = await this.db.select().from(workflowNodeExecutions)
+      .where(and(
+        eq(workflowNodeExecutions.executionId, executionId),
+        eq(workflowNodeExecutions.nodeId, node.id),
+      ));
+    const currentNodeExecId = nodeExecs.length > 0
+      ? nodeExecs.sort((a, b) => b.attempt - a.attempt)[0].id
+      : null;
+
+    // Accumulate KPI metrics during execution
+    const toolCalls: Record<string, number> = { total: 0, read: 0, write: 0, edit: 0, bash: 0, glob: 0, grep: 0 };
+    let costUsd: number | null = null;
+    let numTurns: number | null = null;
+    let stopReason: string | null = null;
+    let model: string | null = null;
+    let contextWindowPct: number | null = null;
+
+    const onToolUse = (toolName: string, toolInput: object) => {
+      toolCalls.total++;
+      const key = toolName.toLowerCase();
+      if (key in toolCalls) {
+        toolCalls[key]++;
+      }
+
+      // Persist individual tool call to workflow_tool_calls table
+      if (currentNodeExecId) {
+        const target = this.extractToolTarget(toolName, toolInput);
+        this.db.insert(workflowToolCalls).values({
+          id: randomUUID(),
+          nodeExecutionId: currentNodeExecId,
+          timestamp: new Date().toISOString(),
+          toolName,
+          target,
+          createdAt: new Date().toISOString(),
+        }).catch(() => {}); // fire-and-forget, don't block agent execution
+      }
+    };
+
+    const onAssistantText = (text: string) => {
+      // Persist assistant text messages to the same table with a special toolName
+      if (currentNodeExecId) {
+        this.db.insert(workflowToolCalls).values({
+          id: randomUUID(),
+          nodeExecutionId: currentNodeExecId,
+          timestamp: new Date().toISOString(),
+          toolName: '__assistant__',
+          target: text,
+          createdAt: new Date().toISOString(),
+        }).catch(() => {}); // fire-and-forget
+      }
+    };
+
+    const onResult = (metadata: {
+      costUsd: number | null;
+      numTurns: number | null;
+      stopReason: string | null;
+      model: string | null;
+      contextWindow: number | null;
+    }) => {
+      costUsd = metadata.costUsd;
+      numTurns = metadata.numTurns;
+      stopReason = metadata.stopReason;
+      model = metadata.model;
+      contextWindowPct = metadata.contextWindow;
+    };
+
+    this.log('WORKFLOW', `Running agent "${agent.name}" (${agentId}) for ${featureId}`);
+    const output = await this.claudeService.spawnClaude(
+      resolvedPrompt,
+      worktreePath,
+      `${agent.name.toLowerCase().replace(/\s+/g, '-')}:${featureId}`,
+      { onToolUse, onResult, onAssistantText },
+    );
+
+    // Commit any changes the agent made
+    try {
+      await this.gitWorkflow.commitChanges(featureId, worktreePath);
+    } catch (err: any) {
+      this.log('WORKFLOW', `WARN: Auto-commit after agent failed: ${err.message}`);
+    }
+
+    // Rebase onto main
+    try {
+      await this.gitWorkflow.rebaseBranch(featureId, worktreePath);
+    } catch (err: any) {
+      this.log('WORKFLOW', `WARN: Rebase after agent failed: ${err.message}`);
+    }
+
+    this.log('WORKFLOW', `Agent "${agent.name}" completed (${output.length} chars output)`);
+
+    return {
+      outputLabel: null,
+      outputData: {
+        agentId,
+        agentName: agent.name,
+        output,
+        toolCalls,
+        costUsd,
+        numTurns,
+        stopReason,
+        model,
+        contextWindowPct,
+      },
+    };
+  };
+
+  /**
+   * CheckCardPosition — reads the kanban column and follows the matching output edge.
+   * The edge's sourceHandle or data.label must match the column name.
+   */
+  private handleCheckCardPosition = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+  ): Promise<NodeHandlerResult> => {
+    const { featureId } = context;
+
+    const entry = await this.kanban.getKanbanEntry(featureId);
+    if (!entry) {
+      throw new Error(`Feature ${featureId} not found in kanban`);
+    }
+
+    const column = (entry as any).column as string;
+
+    // If reviewer didn't move the card (still in_review), treat as rejection
+    if (column === 'in_review') {
+      this.log('WORKFLOW', `Card still in in_review — treating as rejection (todo)`);
+      (entry as any).column = 'todo';
+      (entry as any).moved_at = new Date().toISOString();
+      await this.kanban.saveKanbanEntry(featureId, entry);
+      return { outputLabel: 'todo' };
+    }
+
+    this.log('WORKFLOW', `Card position for ${featureId}: ${column}`);
+    return { outputLabel: column };
+  };
+
+  /**
+   * CheckCycleCount — increments the cycle counter and branches on limit.
+   * Follows 'under_limit' if count < max, 'at_limit' if count >= max.
+   */
+  private handleCheckCycleCount = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+  ): Promise<NodeHandlerResult> => {
+    const { maxCycles } = node.data as { maxCycles: number };
+
+    context.cycle = (context.cycle || 0) + 1;
+    const currentCycle = context.cycle;
+
+    this.log('WORKFLOW', `Cycle count: ${currentCycle}/${maxCycles}`);
+
+    if (currentCycle >= maxCycles) {
+      return { outputLabel: 'at_limit', outputData: { cycle: currentCycle, maxCycles } };
+    }
+    return { outputLabel: 'under_limit', outputData: { cycle: currentCycle, maxCycles } };
+  };
+
+  /**
+   * SetCardMetadata — sets a key/value on the kanban card metadata.
+   */
+  private handleSetCardMetadata = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+  ): Promise<NodeHandlerResult> => {
+    const { key, value } = node.data as { key: string; value: string };
+    const { featureId } = context;
+
+    const entry = await this.kanban.getKanbanEntry(featureId);
+    if (!entry) {
+      throw new Error(`Feature ${featureId} not found in kanban`);
+    }
+
+    // Parse value — "true"/"false" become booleans
+    let parsedValue: unknown = value;
+    if (value === 'true') parsedValue = true;
+    else if (value === 'false') parsedValue = false;
+
+    (entry as any)[key] = parsedValue;
+    await this.kanban.saveKanbanEntry(featureId, entry);
+    this.log('WORKFLOW', `Set metadata ${key}=${value} on ${featureId}`);
+
+    return { outputLabel: null };
+  };
+
+  /**
+   * End node — finalizes the execution based on outcome.
+   * - success: merge feature branch, cleanup worktree, status=completed
+   * - blocked: cleanup worktree without merge, status=completed
+   * - failed: cleanup worktree without merge, status=failed
+   */
+  private handleEnd = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+    executionId: string,
+  ): Promise<NodeHandlerResult> => {
+    const { outcome } = node.data as { outcome: string };
+    const { featureId, worktreePath } = context;
+
+    this.log('WORKFLOW', `End node reached: outcome=${outcome}`);
+
+    if (outcome === 'success') {
+      await this.handleMerge(featureId, worktreePath, context);
+      await this.setExecutionStatus(executionId, 'completed', node.id, context);
+    } else if (outcome === 'blocked') {
+      await this.cleanupWorktree(featureId, worktreePath);
+      await this.setExecutionStatus(executionId, 'completed', node.id, context);
+    } else {
+      // failed or unknown outcome
+      await this.cleanupWorktree(featureId, worktreePath);
+      await this.setExecutionStatus(executionId, 'failed', node.id, context);
+    }
+
+    return { outputLabel: null };
+  };
+
+  /**
+   * Group node — expands the group's internal nodes/edges into a sub-graph
+   * and traverses them sequentially. Checkpoint/resume works correctly
+   * because each internal node gets its own workflow_node_execution record
+   * with a prefixed ID (groupNodeId:internalNodeId).
+   */
+  private handleGroup = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+    executionId: string,
+  ): Promise<NodeHandlerResult> => {
+    const { internalNodes, internalEdges, groupName } = node.data as {
+      internalNodes: WorkflowNode[];
+      internalEdges: WorkflowEdge[];
+      groupName: string;
+    };
+
+    this.log('WORKFLOW', `Expanding group "${groupName}" (${node.id}) with ${internalNodes.length} internal nodes`);
+
+    if (!internalNodes || internalNodes.length === 0) {
+      this.log('WORKFLOW', `Group "${groupName}" is empty — skipping`);
+      return { outputLabel: null };
+    }
+
+    // Build a sub-graph from the group's internal nodes/edges
+    const subGraph: WorkflowGraph = {
+      nodes: internalNodes,
+      edges: internalEdges || [],
+    };
+
+    // Find the start node in the sub-graph (first node with no incoming edges, or type=start)
+    const targetIds = new Set((internalEdges || []).map(e => e.target));
+    const startNode = internalNodes.find(n => n.type === 'start') ||
+                      internalNodes.find(n => !targetIds.has(n.id)) ||
+                      internalNodes[0];
+
+    // Execute the sub-graph using the same traversal logic
+    // Each internal node execution is tracked with a composite ID for resume support
+    await this.executeGraph(executionId, subGraph, startNode.id, context);
+
+    this.log('WORKFLOW', `Group "${groupName}" (${node.id}) completed`);
+    return { outputLabel: null };
+  };
+
+  /**
+   * RebuildBundle — triggers BundleService to compile the Remotion webpack bundle.
+   */
+  private handleRebuildBundle = async (
+    _node: WorkflowNode,
+    _context: ExecutionContext,
+  ): Promise<NodeHandlerResult> => {
+    if (!this.bundleService) {
+      throw new Error('BundleService not configured — cannot execute rebuildBundle node');
+    }
+
+    this.log('WORKFLOW', 'Building Remotion bundle...');
+    const result = await this.bundleService.buildBundle();
+
+    if (!result.ready) {
+      throw new Error(`Bundle build failed: ${result.error || 'unknown error'}`);
+    }
+
+    this.log('WORKFLOW', `Bundle built successfully at ${result.bundlePath}`);
+    return {
+      outputLabel: null,
+      outputData: { bundlePath: result.bundlePath, ready: result.ready },
+    };
+  };
+
+  /**
+   * GenerateTTS — runs TtsService to generate audio from a video script.
+   * Resolves scriptPath relative to the feature's worktree.
+   */
+  private handleGenerateTTS = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+  ): Promise<NodeHandlerResult> => {
+    if (!this.ttsService) {
+      throw new Error('TtsService not configured — cannot execute generateTTS node');
+    }
+
+    const { scriptPath, force, voiceId } = node.data as {
+      scriptPath?: string;
+      force?: boolean;
+      voiceId?: string;
+    };
+    const { featureId, projectId, worktreePath } = context;
+
+    // Resolve script path relative to worktree
+    const resolvedScriptPath = scriptPath
+      ? pathResolve(worktreePath as string, scriptPath)
+      : pathResolve(worktreePath as string, 'script.md');
+
+    this.log('WORKFLOW', `Generating TTS for feature=${featureId} script=${resolvedScriptPath}`);
+
+    const result = await this.ttsService.generate({
+      scriptPath: resolvedScriptPath,
+      projectId: projectId as string,
+      featureId: featureId as string,
+      force: force || false,
+      voiceId: voiceId || undefined,
+    });
+
+    if (result.errors.length > 0) {
+      this.log('WORKFLOW', `TTS completed with errors: ${result.errors.join(', ')}`);
+    }
+
+    this.log('WORKFLOW', `TTS complete: ${result.generated} generated, ${result.skipped} skipped`);
+    return {
+      outputLabel: null,
+      outputData: {
+        processed: result.processed,
+        generated: result.generated,
+        skipped: result.skipped,
+        errors: result.errors,
+        audioBasePath: result.audioBasePath,
+      },
+    };
+  };
+
+  /**
+   * RenderVideo — triggers VideoRenderService to render a composition to MP4.
+   * Waits for the render to complete by polling status.
+   */
+  private handleRenderVideo = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+  ): Promise<NodeHandlerResult> => {
+    if (!this.videoRenderService) {
+      throw new Error('VideoRenderService not configured — cannot execute renderVideo node');
+    }
+
+    const { compositionId, resolution, aspectRatio, fileOutputPrefix } = node.data as {
+      compositionId?: string;
+      resolution?: string;
+      aspectRatio?: string;
+      fileOutputPrefix?: string;
+    };
+    const { featureId, projectId, compositionName } = context;
+
+    // Use compositionId from node data, or fall back to context compositionName
+    const resolvedCompositionId = compositionId || (compositionName as string) || '';
+    if (!resolvedCompositionId) {
+      throw new Error('No compositionId configured on renderVideo node and no compositionName in context');
+    }
+
+    this.log('WORKFLOW', `Starting render: composition=${resolvedCompositionId} resolution=${resolution || '1920x1080'}`);
+
+    const renderStatus = await this.videoRenderService.startRender({
+      compositionId: resolvedCompositionId,
+      projectId: projectId as string,
+      featureId: featureId as string,
+      resolution,
+      aspectRatio,
+      fileOutputPrefix,
+    });
+
+    this.log('WORKFLOW', `Render started: id=${renderStatus.id} status=${renderStatus.status}`);
+    return {
+      outputLabel: null,
+      outputData: {
+        renderId: renderStatus.id,
+        status: renderStatus.status,
+        compositionId: resolvedCompositionId,
+        filePath: renderStatus.filePath,
+      },
+    };
+  };
+
+  // ── Merge & Cleanup Helpers ─────────────────────────────────────────
+
+  /**
+   * Merge the feature branch into main, then cleanup worktree and branch.
+   */
+  private handleMerge = async (
+    featureId: string,
+    worktreePath: string,
+    context: ExecutionContext,
+  ): Promise<void> => {
+    this.log('WORKFLOW', `Merging feature/${featureId} into main...`);
+
+    // Stash local changes on the parent branch
+    let stashed = false;
+    try {
+      stashed = await this.gitWorkflow.stash();
+    } catch (err: any) {
+      this.log('WORKFLOW', `Stash failed (non-fatal): ${err.message}`);
+    }
+
+    // Merge
+    let mergeSucceeded = false;
+    try {
+      await this.gitWorkflow.mergeBranch(featureId);
+      mergeSucceeded = true;
+    } catch (mergeErr: any) {
+      this.log('WORKFLOW', `Merge FAILED: ${mergeErr.message} — attempting fix`);
+      try {
+        const fixed = await this.gitWorkflow.fixMergeConflicts(featureId);
+        if (fixed) {
+          this.log('WORKFLOW', `Merge fix succeeded`);
+          mergeSucceeded = true;
+        } else {
+          throw new Error(`Merge fix did not result in a successful merge`);
+        }
+      } catch (fixErr: any) {
+        this.log('WORKFLOW', `Merge fix FAILED: ${fixErr.message}`);
+        throw new Error(`Merge failed: ${mergeErr.message}`);
+      }
+    }
+
+    // Pop stash
+    if (stashed) {
+      try {
+        await this.gitWorkflow.unstash();
+      } catch (popErr: any) {
+        this.log('WORKFLOW', `Stash pop failed: ${popErr.message}`);
+      }
+    }
+
+    // Cleanup worktree + branch
+    if (mergeSucceeded) {
+      await this.gitWorkflow.removeWorktree(worktreePath);
+      await this.gitWorkflow.deleteBranch(featureId);
+      this.log('WORKFLOW', `Merge completed, worktree and branch cleaned up for ${featureId}`);
+    }
+  };
+
+  /**
+   * Remove the worktree and branch without merging.
+   */
+  private cleanupWorktree = async (featureId: string, worktreePath: string): Promise<void> => {
+    this.log('WORKFLOW', `Cleaning up worktree for ${featureId} (no merge)`);
+    await this.gitWorkflow.removeWorktree(worktreePath);
+    await this.gitWorkflow.deleteBranch(featureId, true);
+  };
+
+  // ── Graph Helpers ───────────────────────────────────────────────────
+
+  /**
+   * Given a node ID and an optional output label, find the target node ID
+   * by matching outgoing edges. If outputLabel is null, returns the single
+   * outgoing edge's target (or null if none).
+   */
+  private resolveNextNode = (
+    graph: WorkflowGraph,
+    nodeId: string,
+    outputLabel: string | null,
+  ): string | null => {
+    const outgoing = graph.edges.filter(e => e.source === nodeId);
+
+    if (outgoing.length === 0) return null;
+
+    if (outputLabel === null) {
+      // No branching — take the single outgoing edge
+      if (outgoing.length === 1) return outgoing[0].target;
+      // If multiple edges but no label, take the first (shouldn't happen in well-formed graphs)
+      this.log('WORKFLOW', `WARN: Node ${nodeId} has ${outgoing.length} outgoing edges but no output label — taking first`);
+      return outgoing[0].target;
+    }
+
+    // Find the edge matching the output label (by sourceHandle or data.label)
+    const match = outgoing.find(e =>
+      e.sourceHandle === outputLabel ||
+      e.data?.label === outputLabel,
+    );
+
+    if (!match) {
+      throw new Error(
+        `No outgoing edge from node ${nodeId} matches output label "${outputLabel}". ` +
+        `Available: ${outgoing.map(e => e.sourceHandle || e.data?.label || '(unlabeled)').join(', ')}`,
+      );
+    }
+
+    return match.target;
+  };
+
+  /**
+   * Replace {{placeholder}} variables in a prompt template with values from context.
+   */
+  private resolvePromptTemplate = (template: string, context: ExecutionContext): string => {
+    return template.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+      if (key in context) {
+        return String(context[key]);
+      }
+      return `{{${key}}}`;  // leave unresolved placeholders as-is
+    });
+  };
+
+  // ── Feature Context Helpers ──────────────────────────────────────────
+
+  /**
+   * Extract the Description section content from a node body.
+   * Falls back to the node name if no description section is found.
+   */
+  private extractFeatureDescription = (body: string | null, fallbackName: string): string => {
+    if (!body) return fallbackName;
+    const match = body.match(/## Description *\n([\s\S]*?)(?=\n## |$)/);
+    return match ? match[1].trim() || fallbackName : fallbackName;
+  };
+
+  /**
+   * Derive a kebab-case composition name from a feature name.
+   * E.g. "Product Feature Walkthrough" → "product-feature-walkthrough"
+   */
+  private deriveCompositionName = (name: string): string => {
+    return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+  };
+
+  // ── Tool Target Extraction ─────────────────────────────────────────
+
+  /**
+   * Extract the primary target from a tool's input object.
+   * For Read/Write/Edit: file_path. For Bash: command. For Grep/Glob: pattern.
+   */
+  private extractToolTarget = (toolName: string, toolInput: object): string => {
+    const input = toolInput as Record<string, unknown>;
+    switch (toolName.toLowerCase()) {
+      case 'read':
+      case 'write':
+      case 'edit':
+        return (input.file_path as string) || (input.filePath as string) || '';
+      case 'bash':
+        return (input.command as string) || '';
+      case 'grep':
+        return (input.pattern as string) || '';
+      case 'glob':
+        return (input.pattern as string) || '';
+      default:
+        // For unknown tools, try common field names
+        return (input.file_path as string) || (input.command as string) || (input.pattern as string) || '';
+    }
+  };
+
+  // ── Monitor Data ──────────────────────────────────────────────────
+
+  /**
+   * Get full monitor data for a feature's workflow execution.
+   * Returns workflow graph, all node executions with statuses/timings/errors,
+   * and tool calls for each node.
+   */
+  getMonitorData = async (featureId: string): Promise<Record<string, unknown> | null> => {
+    // Find the most recent execution for this feature
+    const executions = await this.db.select().from(workflowExecutions)
+      .where(eq(workflowExecutions.featureId, featureId));
+
+    if (executions.length === 0) return null;
+
+    const execution = executions.sort((a, b) =>
+      new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime()
+    )[0];
+
+    // Load workflow graph
+    const [workflow] = await this.db.select().from(workflows)
+      .where(eq(workflows.id, execution.workflowId));
+    if (!workflow) return null;
+
+    // Load node executions
+    const nodeExecs = await this.db.select().from(workflowNodeExecutions)
+      .where(eq(workflowNodeExecutions.executionId, execution.id));
+
+    // Load tool calls for all node executions
+    const nodeExecIds = nodeExecs.map(ne => ne.id);
+    let allToolCalls: Array<Record<string, unknown>> = [];
+    if (nodeExecIds.length > 0) {
+      // Batch query: get all tool calls for this execution's node executions
+      for (const neId of nodeExecIds) {
+        const calls = await this.db.select().from(workflowToolCalls)
+          .where(eq(workflowToolCalls.nodeExecutionId, neId));
+        allToolCalls = allToolCalls.concat(calls);
+      }
+    }
+
+    // Group tool calls by node execution ID
+    const toolCallsByNodeExec: Record<string, Array<Record<string, unknown>>> = {};
+    for (const tc of allToolCalls) {
+      const neId = tc.nodeExecutionId as string;
+      if (!toolCallsByNodeExec[neId]) toolCallsByNodeExec[neId] = [];
+      toolCallsByNodeExec[neId].push({
+        id: tc.id,
+        timestamp: tc.timestamp,
+        toolName: tc.toolName,
+        target: tc.target,
+      });
+    }
+
+    // Parse graph data
+    const graphData = JSON.parse(workflow.graphData);
+
+    // Build node execution map
+    const nodeExecutionMap: Record<string, Record<string, unknown>> = {};
+    for (const ne of nodeExecs) {
+      nodeExecutionMap[ne.nodeId] = {
+        id: ne.id,
+        nodeId: ne.nodeId,
+        status: ne.status,
+        startedAt: ne.startedAt,
+        completedAt: ne.completedAt,
+        outputData: ne.outputData ? JSON.parse(ne.outputData) : null,
+        error: ne.error,
+        attempt: ne.attempt,
+        toolCalls: toolCallsByNodeExec[ne.id] || [],
+      };
+    }
+
+    return {
+      executionId: execution.id,
+      workflowId: execution.workflowId,
+      workflowName: workflow.name,
+      featureId: execution.featureId,
+      status: execution.status,
+      currentNodeId: execution.currentNodeId,
+      startedAt: execution.startedAt,
+      updatedAt: execution.updatedAt,
+      graphData,
+      nodeExecutions: nodeExecutionMap,
+    };
+  };
+
+  // ── Persistence Helpers ─────────────────────────────────────────────
+
+  /**
+   * Update the execution's current_node_id and persist context.
+   */
+  private setExecutionCurrentNode = async (
+    executionId: string,
+    nodeId: string,
+    context: ExecutionContext,
+  ): Promise<void> => {
+    await this.db.update(workflowExecutions)
+      .set({
+        currentNodeId: nodeId,
+        context: JSON.stringify(context),
+        updatedAt: new Date().toISOString(),
+      })
+      .where(eq(workflowExecutions.id, executionId));
+  };
+
+  /**
+   * Set the execution's final status.
+   */
+  private setExecutionStatus = async (
+    executionId: string,
+    status: string,
+    currentNodeId: string | null,
+    context: ExecutionContext,
+  ): Promise<void> => {
+    await this.db.update(workflowExecutions)
+      .set({
+        status,
+        currentNodeId,
+        context: JSON.stringify(context),
+        updatedAt: new Date().toISOString(),
+      })
+      .where(eq(workflowExecutions.id, executionId));
+  };
+
+  /**
+   * Create or reset a node execution record. Returns the record ID.
+   * For back-edges (re-execution), increments attempt counter.
+   */
+  private upsertNodeExecution = async (
+    executionId: string,
+    nodeId: string,
+    status: string,
+  ): Promise<string> => {
+    // Check for existing records for this node in this execution
+    const existing = await this.db.select().from(workflowNodeExecutions)
+      .where(and(
+        eq(workflowNodeExecutions.executionId, executionId),
+        eq(workflowNodeExecutions.nodeId, nodeId),
+      ));
+
+    const now = new Date().toISOString();
+
+    if (existing.length > 0) {
+      // Re-execution (back-edge or resume) — update existing record
+      const latest = existing.sort((a, b) => b.attempt - a.attempt)[0];
+      const newAttempt = latest.status === 'completed' ? latest.attempt + 1 : latest.attempt;
+
+      await this.db.update(workflowNodeExecutions)
+        .set({
+          status,
+          startedAt: now,
+          completedAt: null,
+          outputData: null,
+          error: null,
+          attempt: newAttempt,
+        })
+        .where(eq(workflowNodeExecutions.id, latest.id));
+
+      return latest.id;
+    }
+
+    // First execution of this node
+    const id = randomUUID();
+    await this.db.insert(workflowNodeExecutions).values({
+      id,
+      executionId,
+      nodeId,
+      status,
+      startedAt: now,
+      completedAt: null,
+      outputData: null,
+      error: null,
+      attempt: 1,
+    });
+
+    return id;
+  };
+
+  /**
+   * Mark a node execution as completed with optional output data.
+   */
+  private completeNodeExecution = async (
+    nodeExecId: string,
+    outputData: Record<string, unknown> | null,
+  ): Promise<void> => {
+    await this.db.update(workflowNodeExecutions)
+      .set({
+        status: 'completed',
+        completedAt: new Date().toISOString(),
+        outputData: outputData ? JSON.stringify(outputData) : null,
+      })
+      .where(eq(workflowNodeExecutions.id, nodeExecId));
+  };
+}