@assistkick/create 1.10.0 → 1.11.0

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

@@ -14,8 +14,10 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { resolve as pathResolve, dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { resolve as pathResolve, dirname, join as pathJoin } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import type { ChildProcess } from 'node:child_process';
 import { eq, and } from 'drizzle-orm';
 import {
   workflows,
@@ -25,6 +27,7 @@ import {
   agents,
   nodes as nodesTable,
 } from '../db/schema.js';
+import { ProgrammableNodeExecutor } from './programmable_node_executor.js';
 
 // ── Types ──────────────────────────────────────────────────────────────
 
@@ -86,7 +89,7 @@ interface WorkflowEngineDeps {
     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>;
+    spawnClaude: (prompt: string, cwd: string, label?: string, opts?: Record<string, unknown> & { sessionId?: string; resume?: string; model?: string }) => Promise<string>;
     spawnCommand: (cmd: string, args: string[], cwd: string) => Promise<string>;
   };
   gitWorkflow: {
@@ -100,11 +103,14 @@ interface WorkflowEngineDeps {
     stash: () => Promise<boolean>;
     unstash: () => Promise<void>;
     getDirtyFiles: () => Promise<string[]>;
+    pullDefaultBranch: (projectId: string, branch?: string) => Promise<void>;
+    pushToRemote: (projectId: string, branch?: string) => Promise<void>;
   };
+  skillsDir: string;
   bundleService?: BundleServiceDep;
   ttsService?: TtsServiceDep;
   videoRenderService?: VideoRenderServiceDep;
-  log: (tag: string, message: string) => void;
+  log: (tag: string, ...args: any[]) => void;
 }
 
 // ── WorkflowEngine ────────────────────────────────────────────────────
@@ -114,20 +120,29 @@ export class WorkflowEngine {
   private kanban: WorkflowEngineDeps['kanban'];
   private claudeService: WorkflowEngineDeps['claudeService'];
   private gitWorkflow: WorkflowEngineDeps['gitWorkflow'];
+  private skillsDir: string;
   private bundleService?: BundleServiceDep;
   private ttsService?: TtsServiceDep;
   private videoRenderService?: VideoRenderServiceDep;
-  private log: WorkflowEngineDeps['log'];
+  private log: (tag: string, ...args: any[]) => void;
+  private programmableExecutor: ProgrammableNodeExecutor;
 
-  constructor({ db, kanban, claudeService, gitWorkflow, bundleService, ttsService, videoRenderService, log }: WorkflowEngineDeps) {
+  /** Active Claude child processes keyed by executionId — for kill support */
+  private activeProcesses = new Map<string, ChildProcess>();
+  /** Execution IDs that were stopped by user — prevents executeGraph from overwriting statuses */
+  private stoppedExecutions = new Set<string>();
+
+  constructor({ db, kanban, claudeService, gitWorkflow, skillsDir, bundleService, ttsService, videoRenderService, log }: WorkflowEngineDeps) {
     this.db = db;
     this.kanban = kanban;
     this.claudeService = claudeService;
     this.gitWorkflow = gitWorkflow;
+    this.skillsDir = skillsDir;
     this.bundleService = bundleService;
     this.ttsService = ttsService;
     this.videoRenderService = videoRenderService;
     this.log = log;
+    this.programmableExecutor = new ProgrammableNodeExecutor({ log });
   }
 
   // ── Public API ──────────────────────────────────────────────────────
@@ -152,8 +167,15 @@ export class WorkflowEngine {
       throw new Error(`Workflow ${workflowId} has no start node`);
     }
 
+    // Pull latest default branch before creating worktree to ensure up-to-date base
+    try {
+      await this.gitWorkflow.pullDefaultBranch(projectId);
+    } catch (pullErr: any) {
+      this.log('WORKFLOW', `Pull before worktree creation failed (non-fatal):`, pullErr.stack || pullErr.message);
+    }
+
     // Create worktree and feature branch
-    const worktreePath = await this.gitWorkflow.createWorktree(featureId);
+    const worktreePath = await this.gitWorkflow.createWorktree(featureId, projectId);
     const branchName = `feature/${featureId}`;
 
     // Build initial context
@@ -172,6 +194,7 @@ export class WorkflowEngine {
       mainSkillDir,
       mainToolsDir,
       pidFlag,
+      nodeOutputs: {},
     };
 
     // Enrich context with feature data for agent prompt resolution
@@ -207,8 +230,8 @@ export class WorkflowEngine {
 
     // 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(() => {});
+      this.log('WORKFLOW', `UNCAUGHT ERROR in execution ${executionId}:`, err.stack || err.message);
+      this.setExecutionStatus(executionId, 'failed', null, context).catch((e: any) => { this.log('WORKFLOW', 'Failed to set execution status:', e.message); });
     });
 
     return { executionId };
@@ -256,7 +279,7 @@ export class WorkflowEngine {
         eq(workflowNodeExecutions.nodeId, currentNodeId),
       ));
 
-    const failedExec = nodeExecs.find(ne => ne.status === 'failed' || ne.status === 'running');
+    const failedExec = nodeExecs.find(ne => ne.status === 'failed' || ne.status === 'running' || ne.status === 'stopped');
     if (failedExec) {
       await this.db.update(workflowNodeExecutions)
         .set({ status: 'pending', attempt: failedExec.attempt + 1 })
@@ -270,8 +293,8 @@ export class WorkflowEngine {
 
     // 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(() => {});
+      this.log('WORKFLOW', `UNCAUGHT ERROR resuming ${executionId}:`, err.stack || err.message);
+      this.setExecutionStatus(executionId, 'failed', currentNodeId, context).catch((e: any) => { this.log('WORKFLOW', 'Failed to set execution status:', e.message); });
     });
   };
 
@@ -301,7 +324,7 @@ export class WorkflowEngine {
         eq(workflowNodeExecutions.executionId, execution.id),
         eq(workflowNodeExecutions.nodeId, nodeId),
       ));
-    const currentNodeExec = nodeExecs.find(ne => ne.status === 'running' || ne.status === 'failed');
+    const currentNodeExec = nodeExecs.find(ne => ne.status === 'running' || ne.status === 'failed' || ne.status === 'stopped');
     if (currentNodeExec) {
       await this.db.update(workflowNodeExecutions)
         .set({ status: 'completed', completedAt: new Date().toISOString() })
@@ -326,8 +349,8 @@ export class WorkflowEngine {
 
     // 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(() => {});
+      this.log('WORKFLOW', `UNCAUGHT ERROR after force-next ${execution.id}:`, err.stack || err.message);
+      this.setExecutionStatus(execution.id, 'failed', nextNodeId, context).catch((e: any) => { this.log('WORKFLOW', 'Failed to set execution status:', e.message); });
     });
   };
 
@@ -356,7 +379,7 @@ export class WorkflowEngine {
         eq(workflowNodeExecutions.executionId, execution.id),
         eq(workflowNodeExecutions.nodeId, nodeId),
       ));
-    const currentNodeExec = nodeExecs.find(ne => ne.status === 'running' || ne.status === 'failed');
+    const currentNodeExec = nodeExecs.find(ne => ne.status === 'running' || ne.status === 'failed' || ne.status === 'stopped');
     if (currentNodeExec) {
       await this.db.update(workflowNodeExecutions)
         .set({ status: 'pending', attempt: currentNodeExec.attempt + 1 })
@@ -370,11 +393,268 @@ export class WorkflowEngine {
 
     // 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(() => {});
+      this.log('WORKFLOW', `UNCAUGHT ERROR after restart-node ${execution.id}:`, err.stack || err.message);
+      this.setExecutionStatus(execution.id, 'failed', nodeId, context).catch((e: any) => { this.log('WORKFLOW', 'Failed to set execution status:', e.message); });
     });
   };
 
+  /**
+   * Stop the currently executing workflow node.
+   * Sends SIGTERM to the Claude child process, waits 3s, then SIGKILL if still alive.
+   * Marks node execution as 'stopped' and workflow execution as 'failed'.
+   * Does NOT clean up the worktree (same as error behavior — preserves work for resume).
+   */
+  stopNode = async (featureId: string, nodeId: string): Promise<void> => {
+    this.log('WORKFLOW', `Stop-node requested for feature ${featureId}, node ${nodeId}`);
+
+    const execution = await this.findLatestExecution(featureId);
+    if (!execution || execution.status !== 'running') {
+      throw new Error(`No running execution found for feature ${featureId}`);
+    }
+    if (execution.currentNodeId !== nodeId) {
+      throw new Error(`Node ${nodeId} is not the current execution node (current: ${execution.currentNodeId})`);
+    }
+
+    // Mark as stopped BEFORE killing to prevent executeGraph from overwriting statuses
+    this.stoppedExecutions.add(execution.id);
+
+    // Update node execution → 'stopped'
+    const nodeExecs = await this.db.select().from(workflowNodeExecutions)
+      .where(and(
+        eq(workflowNodeExecutions.executionId, execution.id),
+        eq(workflowNodeExecutions.nodeId, nodeId),
+      ));
+    const runningExec = nodeExecs.find(ne => ne.status === 'running');
+    if (runningExec) {
+      await this.db.update(workflowNodeExecutions)
+        .set({
+          status: 'stopped',
+          error: 'Stopped by user',
+          completedAt: new Date().toISOString(),
+        })
+        .where(eq(workflowNodeExecutions.id, runningExec.id));
+    }
+
+    // Update workflow execution → 'failed'
+    const context: ExecutionContext = JSON.parse(execution.context);
+    await this.setExecutionStatus(execution.id, 'failed', nodeId, context);
+
+    // Kill the child process
+    const child = this.activeProcesses.get(execution.id);
+    if (child) {
+      this.log('WORKFLOW', `Sending SIGTERM to child process for execution ${execution.id}`);
+      child.kill('SIGTERM');
+      // After 3s, send SIGKILL if still alive
+      setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch { /* already dead */ }
+      }, 3000);
+    }
+
+    this.log('WORKFLOW', `Node ${nodeId} stopped for feature ${featureId}`);
+  };
+
+  /**
+   * Continue a stuck/failed agent node by resuming the Claude session.
+   * Spawns a new Claude process with '--resume <sessionId>' using the original session ID.
+   * If the process is still alive, kills it first before resuming.
+   */
+  continueNode = async (featureId: string, nodeId: string): Promise<void> => {
+    this.log('WORKFLOW', `Continue-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})`);
+    }
+
+    // Find the node execution record with the Claude session ID
+    const nodeExecs = await this.db.select().from(workflowNodeExecutions)
+      .where(and(
+        eq(workflowNodeExecutions.executionId, execution.id),
+        eq(workflowNodeExecutions.nodeId, nodeId),
+      ));
+    const nodeExec = nodeExecs.sort((a, b) => b.attempt - a.attempt)[0];
+    if (!nodeExec) throw new Error(`No execution record found for node ${nodeId}`);
+    if (!nodeExec.claudeSessionId) {
+      throw new Error(`Node ${nodeId} has no Claude session ID — not an agent node`);
+    }
+
+    // If the process is still alive, kill it first
+    const existingChild = this.activeProcesses.get(execution.id);
+    if (existingChild) {
+      this.log('WORKFLOW', `Killing existing process for execution ${execution.id} before resuming`);
+      this.stoppedExecutions.add(execution.id);
+      existingChild.kill('SIGTERM');
+      await new Promise<void>(resolve => {
+        const timeout = setTimeout(() => {
+          try { existingChild.kill('SIGKILL'); } catch { /* already dead */ }
+          resolve();
+        }, 3000);
+        existingChild.on('close', () => { clearTimeout(timeout); resolve(); });
+      });
+      this.activeProcesses.delete(execution.id);
+      this.stoppedExecutions.delete(execution.id);
+    }
+
+    // Reset node execution status to 'running' — do NOT increment attempt (continuation, not retry)
+    await this.db.update(workflowNodeExecutions)
+      .set({
+        status: 'running',
+        error: null,
+        completedAt: null,
+      })
+      .where(eq(workflowNodeExecutions.id, nodeExec.id));
+
+    // Set workflow execution back to 'running'
+    const context: ExecutionContext = JSON.parse(execution.context);
+    await this.db.update(workflowExecutions)
+      .set({ status: 'running', updatedAt: new Date().toISOString() })
+      .where(eq(workflowExecutions.id, execution.id));
+
+    // Load workflow graph for post-continue traversal
+    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);
+
+    // Resolve agent name for logging
+    const graphNode = graph.nodes.find(n => n.id === nodeId);
+    const agentId = (graphNode?.data as { agentId?: string })?.agentId;
+    let agentName = 'agent';
+    if (agentId) {
+      const [agent] = await this.db.select().from(agents).where(eq(agents.id, agentId));
+      if (agent) agentName = agent.name;
+    }
+
+    // Set up the same streaming callbacks as handleRunAgent
+    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]++;
+
+      // Append tool calls to existing records — no duplication
+      const target = this.extractToolTarget(toolName, toolInput);
+      this.db.insert(workflowToolCalls).values({
+        id: randomUUID(),
+        nodeExecutionId: nodeExec.id,
+        timestamp: new Date().toISOString(),
+        toolName,
+        target,
+        createdAt: new Date().toISOString(),
+      }).catch(() => {});
+    };
+
+    const onAssistantText = (text: string) => {
+      this.db.insert(workflowToolCalls).values({
+        id: randomUUID(),
+        nodeExecutionId: nodeExec.id,
+        timestamp: new Date().toISOString(),
+        toolName: '__assistant__',
+        target: text,
+        createdAt: new Date().toISOString(),
+      }).catch(() => {});
+    };
+
+    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;
+    };
+
+    const onSpawn = (child: ChildProcess) => {
+      this.activeProcesses.set(execution.id, child);
+    };
+
+    // Fire-and-forget: resume the Claude session and continue graph traversal
+    const { worktreePath } = context;
+    const label = `${agentName.toLowerCase().replace(/\s+/g, '-')}:${featureId}`;
+
+    this.log('WORKFLOW', `Resuming Claude session ${nodeExec.claudeSessionId} for agent "${agentName}"`);
+
+    (async () => {
+      try {
+        const output = await this.claudeService.spawnClaude(
+          'Continue',
+          worktreePath,
+          label,
+          { onToolUse, onResult, onAssistantText, onSpawn, resume: nodeExec.claudeSessionId },
+        );
+        this.activeProcesses.delete(execution.id);
+
+        // If execution was stopped while continuing, exit
+        if (this.stoppedExecutions.has(execution.id)) {
+          this.stoppedExecutions.delete(execution.id);
+          return;
+        }
+
+        // Commit any changes
+        try {
+          await this.gitWorkflow.commitChanges(featureId, worktreePath);
+        } catch (err: any) {
+          this.log('WORKFLOW', `WARN: Auto-commit after continue failed: ${err.message}`);
+        }
+
+        // Rebase onto main
+        try {
+          await this.gitWorkflow.rebaseBranch(featureId, worktreePath);
+        } catch (err: any) {
+          this.log('WORKFLOW', `WARN: Rebase after continue failed: ${err.message}`);
+        }
+
+        // Mark node as completed
+        await this.completeNodeExecution(nodeExec.id, {
+          agentId,
+          agentName,
+          output,
+          toolCalls,
+          costUsd,
+          numTurns,
+          stopReason,
+          model,
+          contextWindowPct,
+        });
+
+        this.log('WORKFLOW', `Continued agent "${agentName}" completed — resuming graph traversal`);
+
+        // Continue graph traversal from next node
+        const nextNodeId = this.resolveNextNode(graph, nodeId, null);
+        if (nextNodeId) {
+          await this.executeGraph(execution.id, graph, nextNodeId, context);
+        } else {
+          await this.setExecutionStatus(execution.id, 'completed', null, context);
+        }
+      } catch (err: any) {
+        this.activeProcesses.delete(execution.id);
+
+        if (this.stoppedExecutions.has(execution.id)) {
+          this.stoppedExecutions.delete(execution.id);
+          return;
+        }
+
+        this.log('WORKFLOW', `Continue-node FAILED: ${err.message}`);
+        await this.db.update(workflowNodeExecutions)
+          .set({ status: 'failed', error: err.message, completedAt: new Date().toISOString() })
+          .where(eq(workflowNodeExecutions.id, nodeExec.id));
+        await this.setExecutionStatus(execution.id, 'failed', nodeId, context);
+      }
+    })();
+  };
+
   /**
    * Find the most recent execution for a feature (any status).
    * Returns the execution row or null.
@@ -411,7 +691,7 @@ export class WorkflowEngine {
       .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 failed = nodeExecs.filter(ne => ne.status === 'failed' || ne.status === 'stopped').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
@@ -436,13 +716,13 @@ export class WorkflowEngine {
             }
           }
         }
-      } catch { /* non-critical */ }
+      } catch (err: any) { this.log('WORKFLOW', 'Non-critical error:', err.message); }
     }
 
-    // Get error message from the most recent failed node execution
+    // Get error message from the most recent failed/stopped node execution
     let errorMessage: string | null = null;
     if (execution.status === 'failed') {
-      const failedExec = nodeExecs.find(ne => ne.status === 'failed' && ne.error);
+      const failedExec = nodeExecs.find(ne => (ne.status === 'failed' || ne.status === 'stopped') && ne.error);
       if (failedExec) errorMessage = failedExec.error;
     }
 
@@ -555,7 +835,7 @@ export class WorkflowEngine {
       this.log('WORKFLOW', `Executing node ${node.id} (${node.type})`);
 
       // Create or reset node execution record
-      const nodeExecId = await this.upsertNodeExecution(executionId, node.id, 'running');
+      const nodeExecId = await this.upsertNodeExecution(executionId, node.id, 'running', context.cycle || 1);
 
       try {
         const result = await this.executeNode(node, context, executionId);
@@ -564,6 +844,14 @@ export class WorkflowEngine {
         await this.completeNodeExecution(nodeExecId, result.outputData || null);
         this.log('WORKFLOW', `Node ${node.id} completed (output: ${result.outputLabel || 'default'})`);
 
+        // Store output in context.nodeOutputs under the node's label (dec_2266dcd3)
+        if (result.outputData) {
+          const nodeOutputs = (context.nodeOutputs || {}) as Record<string, unknown>;
+          const nodeLabel = (node.data?.label as string) || node.id;
+          nodeOutputs[nodeLabel] = result.outputData;
+          context.nodeOutputs = nodeOutputs;
+        }
+
         // Find the next node via edges
         currentNodeId = this.resolveNextNode(graph, node.id, result.outputLabel);
 
@@ -573,7 +861,14 @@ export class WorkflowEngine {
           this.log('WORKFLOW', `No outgoing edge from ${node.id} — traversal complete`);
         }
       } catch (err: any) {
-        this.log('WORKFLOW', `Node ${node.id} FAILED: ${err.message}`);
+        // If this execution was stopped by user, statuses are already set — just exit
+        if (this.stoppedExecutions.has(executionId)) {
+          this.stoppedExecutions.delete(executionId);
+          this.log('WORKFLOW', `Node ${node.id} stopped by user — exiting graph traversal`);
+          return;
+        }
+
+        this.log('WORKFLOW', `Node ${node.id} FAILED:`, err.stack || err.message);
 
         // Mark node execution as failed
         await this.db.update(workflowNodeExecutions)
@@ -629,6 +924,8 @@ export class WorkflowEngine {
         return this.handleGenerateTTS(node, context);
       case 'renderVideo':
         return this.handleRenderVideo(node, context);
+      case 'programmable':
+        return this.handleProgrammable(node, context);
       default:
         throw new Error(`Unknown node type: ${node.type}`);
     }
@@ -687,8 +984,23 @@ export class WorkflowEngine {
       throw new Error(`Agent ${agentId} not found`);
     }
 
-    // Resolve {{placeholder}} variables in prompt template
-    const resolvedPrompt = this.resolvePromptTemplate(agent.promptTemplate, context);
+    // Load skill file contents from disk (never interpolated)
+    const skillIdentifiers: string[] = JSON.parse(agent.skills);
+    const skillContents: string[] = [];
+    for (const skillId of skillIdentifiers) {
+      const skillPath = pathJoin(this.skillsDir, skillId, 'SKILL.md');
+      try {
+        skillContents.push(readFileSync(skillPath, 'utf-8'));
+      } catch (err: any) {
+        throw new Error(`Failed to read skill file for "${skillId}" at ${skillPath}: ${err.message}`);
+      }
+    }
+
+    // Resolve {{placeholder}} variables only in the grounding portion
+    const resolvedGrounding = this.resolvePromptTemplate(agent.grounding, context);
+
+    // Compose final system prompt: skill contents + resolved grounding
+    const resolvedPrompt = [...skillContents, resolvedGrounding].join('\n\n');
 
     // Find the node execution ID for persisting tool calls
     const nodeExecs = await this.db.select().from(workflowNodeExecutions)
@@ -696,9 +1008,18 @@ export class WorkflowEngine {
         eq(workflowNodeExecutions.executionId, executionId),
         eq(workflowNodeExecutions.nodeId, node.id),
       ));
-    const currentNodeExecId = nodeExecs.length > 0
-      ? nodeExecs.sort((a, b) => b.attempt - a.attempt)[0].id
+    const currentNodeExec = nodeExecs.length > 0
+      ? nodeExecs.sort((a, b) => b.attempt - a.attempt)[0]
       : null;
+    const currentNodeExecId = currentNodeExec?.id ?? null;
+
+    // Generate a Claude session ID and store it on the node execution record
+    const claudeSessionId = randomUUID();
+    if (currentNodeExecId) {
+      await this.db.update(workflowNodeExecutions)
+        .set({ claudeSessionId })
+        .where(eq(workflowNodeExecutions.id, currentNodeExecId));
+    }
 
     // Accumulate KPI metrics during execution
     const toolCalls: Record<string, number> = { total: 0, read: 0, write: 0, edit: 0, bash: 0, glob: 0, grep: 0 };
@@ -757,26 +1078,36 @@ export class WorkflowEngine {
       contextWindowPct = metadata.contextWindow;
     };
 
+    // Track child process for kill support
+    const onSpawn = (child: ChildProcess) => {
+      this.activeProcesses.set(executionId, child);
+    };
+
     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 },
-    );
+    let output: string;
+    try {
+      output = await this.claudeService.spawnClaude(
+        resolvedPrompt,
+        worktreePath,
+        `${agent.name.toLowerCase().replace(/\s+/g, '-')}:${featureId}`,
+        { onToolUse, onResult, onAssistantText, onSpawn, sessionId: claudeSessionId, model: agent.model },
+      );
+    } finally {
+      this.activeProcesses.delete(executionId);
+    }
 
     // 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}`);
+      this.log('WORKFLOW', `WARN: Auto-commit after agent failed:`, err.stack || 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', `WARN: Rebase after agent failed:`, err.stack || err.message);
     }
 
     this.log('WORKFLOW', `Agent "${agent.name}" completed (${output.length} chars output)`);
@@ -895,11 +1226,11 @@ export class WorkflowEngine {
       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.cleanupWorktree(featureId, worktreePath, context.projectId);
       await this.setExecutionStatus(executionId, 'completed', node.id, context);
     } else {
       // failed or unknown outcome
-      await this.cleanupWorktree(featureId, worktreePath);
+      await this.cleanupWorktree(featureId, worktreePath, context.projectId);
       await this.setExecutionStatus(executionId, 'failed', node.id, context);
     }
 
@@ -1075,6 +1406,67 @@ export class WorkflowEngine {
     };
   };
 
+  /**
+   * Programmable — executes user-written JavaScript in an isolated-vm V8 isolate.
+   * Returns { outputLabel: 'success', outputData } on success,
+   * or { outputLabel: 'error', outputData: { error } } on throw.
+   *
+   * The error output label mechanism:
+   * - If the 'error' output handle is wired → workflow continues on the error path.
+   * - If the 'error' output handle is NOT wired → resolveNextNode throws → workflow fails.
+   */
+  private handleProgrammable = async (
+    node: WorkflowNode,
+    context: ExecutionContext,
+  ): Promise<NodeHandlerResult> => {
+    const { code, label, timeout, memory, maxRequests, maxResponseSize } = node.data as {
+      code: string;
+      label: string;
+      timeout?: number;
+      memory?: number;
+      maxRequests?: number;
+      maxResponseSize?: number;
+    };
+
+    if (!code || !code.trim()) {
+      throw new Error(`Programmable node "${label || node.id}" has no code`);
+    }
+
+    const nodeLabel = label || node.id;
+    this.log('WORKFLOW', `Running programmable node "${nodeLabel}"`);
+
+    // Build the context object that the user's run(context) receives.
+    // Include nodeOutputs from previous nodes for data piping.
+    const sandboxContext: Record<string, unknown> = {
+      featureId: context.featureId,
+      projectId: context.projectId,
+      cycle: context.cycle,
+      nodeOutputs: context.nodeOutputs || {},
+    };
+
+    const executionResult = await this.programmableExecutor.execute(code, sandboxContext, {
+      timeout,
+      memory,
+      maxRequests,
+      maxResponseSize,
+    });
+
+    if (executionResult.success) {
+      this.log('WORKFLOW', `Programmable node "${nodeLabel}" succeeded`);
+      return {
+        outputLabel: 'success',
+        outputData: executionResult.result as Record<string, unknown> ?? {},
+      };
+    }
+
+    // User code threw — follow the error output handle
+    this.log('WORKFLOW', `Programmable node "${nodeLabel}" errored: ${executionResult.error}`);
+    return {
+      outputLabel: 'error',
+      outputData: { error: executionResult.error },
+    };
+  };
+
   // ── Merge & Cleanup Helpers ─────────────────────────────────────────
 
   /**
@@ -1090,20 +1482,20 @@ export class WorkflowEngine {
     // Stash local changes on the parent branch
     let stashed = false;
     try {
-      stashed = await this.gitWorkflow.stash();
+      stashed = await this.gitWorkflow.stash(context.projectId);
     } catch (err: any) {
-      this.log('WORKFLOW', `Stash failed (non-fatal): ${err.message}`);
+      this.log('WORKFLOW', `Stash failed (non-fatal):`, err.stack || err.message);
     }
 
     // Merge
     let mergeSucceeded = false;
     try {
-      await this.gitWorkflow.mergeBranch(featureId);
+      await this.gitWorkflow.mergeBranch(featureId, context.projectId);
       mergeSucceeded = true;
     } catch (mergeErr: any) {
-      this.log('WORKFLOW', `Merge FAILED: ${mergeErr.message} — attempting fix`);
+      this.log('WORKFLOW', `Merge FAILED:`, mergeErr.stack || mergeErr.message, '— attempting fix');
       try {
-        const fixed = await this.gitWorkflow.fixMergeConflicts(featureId);
+        const fixed = await this.gitWorkflow.fixMergeConflicts(featureId, context.projectId);
         if (fixed) {
           this.log('WORKFLOW', `Merge fix succeeded`);
           mergeSucceeded = true;
@@ -1111,7 +1503,7 @@ export class WorkflowEngine {
           throw new Error(`Merge fix did not result in a successful merge`);
         }
       } catch (fixErr: any) {
-        this.log('WORKFLOW', `Merge fix FAILED: ${fixErr.message}`);
+        this.log('WORKFLOW', `Merge fix FAILED:`, fixErr.stack || fixErr.message);
         throw new Error(`Merge failed: ${mergeErr.message}`);
       }
     }
@@ -1119,16 +1511,26 @@ export class WorkflowEngine {
     // Pop stash
     if (stashed) {
       try {
-        await this.gitWorkflow.unstash();
+        await this.gitWorkflow.unstash(context.projectId);
       } catch (popErr: any) {
-        this.log('WORKFLOW', `Stash pop failed: ${popErr.message}`);
+        this.log('WORKFLOW', `Stash pop failed:`, popErr.stack || popErr.message);
+      }
+    }
+
+    // Push to remote after successful merge (non-fatal — merge already succeeded locally)
+    if (mergeSucceeded) {
+      try {
+        await this.gitWorkflow.pushToRemote(context.projectId);
+        this.log('WORKFLOW', `Push to remote succeeded for ${featureId}`);
+      } catch (pushErr: any) {
+        this.log('WORKFLOW', `WARN: Push to remote failed (non-fatal, merge succeeded locally):`, pushErr.stack || pushErr.message);
       }
     }
 
     // Cleanup worktree + branch
     if (mergeSucceeded) {
-      await this.gitWorkflow.removeWorktree(worktreePath);
-      await this.gitWorkflow.deleteBranch(featureId);
+      await this.gitWorkflow.removeWorktree(worktreePath, context.projectId);
+      await this.gitWorkflow.deleteBranch(featureId, context.projectId);
       this.log('WORKFLOW', `Merge completed, worktree and branch cleaned up for ${featureId}`);
     }
   };
@@ -1136,10 +1538,10 @@ export class WorkflowEngine {
   /**
    * Remove the worktree and branch without merging.
    */
-  private cleanupWorktree = async (featureId: string, worktreePath: string): Promise<void> => {
+  private cleanupWorktree = async (featureId: string, worktreePath: string, projectId?: string): Promise<void> => {
     this.log('WORKFLOW', `Cleaning up worktree for ${featureId} (no merge)`);
-    await this.gitWorkflow.removeWorktree(worktreePath);
-    await this.gitWorkflow.deleteBranch(featureId, true);
+    await this.gitWorkflow.removeWorktree(worktreePath, projectId!);
+    await this.gitWorkflow.deleteBranch(featureId, projectId!, true);
   };
 
   // ── Graph Helpers ───────────────────────────────────────────────────
@@ -1297,10 +1699,10 @@ export class WorkflowEngine {
     // Parse graph data
     const graphData = JSON.parse(workflow.graphData);
 
-    // Build node execution map
-    const nodeExecutionMap: Record<string, Record<string, unknown>> = {};
+    // Build node execution map — array per node, sorted by cycle
+    const nodeExecutionMap: Record<string, Array<Record<string, unknown>>> = {};
     for (const ne of nodeExecs) {
-      nodeExecutionMap[ne.nodeId] = {
+      const entry = {
         id: ne.id,
         nodeId: ne.nodeId,
         status: ne.status,
@@ -1309,8 +1711,17 @@ export class WorkflowEngine {
         outputData: ne.outputData ? JSON.parse(ne.outputData) : null,
         error: ne.error,
         attempt: ne.attempt,
+        cycle: ne.cycle,
         toolCalls: toolCallsByNodeExec[ne.id] || [],
+        claudeSessionId: ne.claudeSessionId || null,
+        processAlive: this.activeProcesses.has(execution.id) && ne.status === 'running',
       };
+      if (!nodeExecutionMap[ne.nodeId]) nodeExecutionMap[ne.nodeId] = [];
+      nodeExecutionMap[ne.nodeId].push(entry);
+    }
+    // Sort each node's executions by cycle ascending
+    for (const nodeId of Object.keys(nodeExecutionMap)) {
+      nodeExecutionMap[nodeId].sort((a, b) => (a.cycle as number) - (b.cycle as number));
     }
 
     return {
@@ -1367,12 +1778,14 @@ export class WorkflowEngine {
 
   /**
    * Create or reset a node execution record. Returns the record ID.
-   * For back-edges (re-execution), increments attempt counter.
+   * For same-cycle re-execution (restart), updates existing record.
+   * For new cycle, creates a new row preserving previous cycle data.
    */
   private upsertNodeExecution = async (
     executionId: string,
     nodeId: string,
     status: string,
+    cycle: number = 1,
   ): Promise<string> => {
     // Check for existing records for this node in this execution
     const existing = await this.db.select().from(workflowNodeExecutions)
@@ -1384,22 +1797,42 @@ export class WorkflowEngine {
     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;
+      // Check if there's already a record for this cycle
+      const sameCycle = existing.find(e => e.cycle === cycle);
+      if (sameCycle) {
+        // Same cycle re-execution (restart) — update existing record
+        const newAttempt = sameCycle.status === 'completed' ? sameCycle.attempt + 1 : sameCycle.attempt;
 
-      await this.db.update(workflowNodeExecutions)
-        .set({
-          status,
-          startedAt: now,
-          completedAt: null,
-          outputData: null,
-          error: null,
-          attempt: newAttempt,
-        })
-        .where(eq(workflowNodeExecutions.id, latest.id));
+        await this.db.update(workflowNodeExecutions)
+          .set({
+            status,
+            startedAt: now,
+            completedAt: null,
+            outputData: null,
+            error: null,
+            attempt: newAttempt,
+          })
+          .where(eq(workflowNodeExecutions.id, sameCycle.id));
+
+        return sameCycle.id;
+      }
+
+      // New cycle — create a new row to preserve previous cycle data
+      const id = randomUUID();
+      await this.db.insert(workflowNodeExecutions).values({
+        id,
+        executionId,
+        nodeId,
+        status,
+        startedAt: now,
+        completedAt: null,
+        outputData: null,
+        error: null,
+        attempt: 1,
+        cycle,
+      });
 
-      return latest.id;
+      return id;
     }
 
     // First execution of this node
@@ -1414,6 +1847,7 @@ export class WorkflowEngine {
       outputData: null,
       error: null,
       attempt: 1,
+      cycle,
     });
 
     return id;