refactor(workflows): move signal handling logic to dedicated handlers

Consolidate pause/skip signal handling into their respective handler files.
Remove duplicate state transition and status update logic from runStepFresh.
Add session capture for pause to enable resume functionality.

Author: moazbuilds

src/workflows/signals/handlers/pause.ts

@@ -2,10 +2,12 @@
  * Pause Signal Handler
  *
  * Handles workflow:pause process events (user keypress Ctrl+P or 'p').
- * Logs, aborts current step, transitions state machine.
+ * Captures session for resume, updates status, transitions state machine, and aborts.
  */
 
 import { debug } from '../../../shared/logging/logger.js';
+import { AgentMonitorService } from '../../../agents/monitoring/index.js';
+import { initStepSession } from '../../../shared/workflows/steps.js';
 import type { SignalContext } from '../manager/types.js';
 
 /**
@@ -20,13 +22,40 @@ export function handlePauseSignal(ctx: SignalContext): void {
     return;
   }
 
-  // Abort step if running
   if (ctx.machine.state === 'running') {
+    // Update UI status
+    ctx.emitter.updateAgentStatus(stepContext.agentId, 'awaiting');
+
+    // Transition state machine
     ctx.machine.send({ type: 'PAUSE' });
+
+    // Capture session from monitor before aborting so resume can find it
+    // Agent is registered with base ID (e.g., "bmad-architect" not "bmad-architect-step-2")
+    const baseAgentId = stepContext.agentId.replace(/-step-\d+$/, '');
+    const monitor = AgentMonitorService.getInstance();
+    const agents = monitor.queryAgents({ name: baseAgentId });
+
+    if (agents.length > 0) {
+      const agent = agents.reduce((a, b) => (a.id > b.id ? a : b));
+      debug('[PauseSignal] Captured agent: id=%d sessionId=%s', agent.id, agent.sessionId);
+
+      // Set in machine context so handleWaiting can pass to resume
+      const machineCtx = ctx.machine.context;
+      machineCtx.currentMonitoringId = agent.id;
+      machineCtx.currentOutput = { output: '', monitoringId: agent.id };
+
+      // Persist session to step data for resume lookup
+      if (agent.sessionId) {
+        initStepSession(ctx.cmRoot, stepContext.stepIndex, agent.sessionId, agent.id)
+          .catch(err => debug('[PauseSignal] Failed to save session: %s', err.message));
+      }
+    }
+
+    // Abort the step execution
     ctx.getAbortController()?.abort();
   }
 
-  // Emit mode-change to switch to manual (ignored if already manual)
+  // Switch to manual mode
   (process as NodeJS.EventEmitter).emit('workflow:mode-change', { autonomousMode: false });
 
   debug('[PauseSignal] Pause handled');

src/workflows/signals/handlers/skip.ts

@@ -2,7 +2,7 @@
  * Skip Signal Handler
  *
  * Handles workflow:skip process events (Ctrl+S while agent running).
- * Aborts current step execution.
+ * Updates status, transitions state machine to next step, and aborts.
  */
 
 import { debug } from '../../../shared/logging/logger.js';
@@ -12,6 +12,24 @@ import type { SignalContext } from '../manager/types.js';
  * Handle skip signal
  */
 export function handleSkipSignal(ctx: SignalContext): void {
-  debug('[SkipSignal] Skip requested');
-  ctx.getAbortController()?.abort();
+  debug('[SkipSignal] workflow:skip received, state=%s', ctx.machine.state);
+
+  const stepContext = ctx.getStepContext();
+  if (!stepContext) {
+    debug('[SkipSignal] No step context, ignoring skip');
+    return;
+  }
+
+  if (ctx.machine.state === 'running') {
+    // Update UI status
+    ctx.emitter.updateAgentStatus(stepContext.agentId, 'skipped');
+
+    // Transition state machine to next step
+    ctx.machine.send({ type: 'SKIP' });
+
+    // Abort the step execution
+    ctx.getAbortController()?.abort();
+
+    debug('[SkipSignal] Skip handled, advancing to next step');
+  }
 }

src/workflows/step/run.ts

@@ -202,18 +202,8 @@ export async function runStepFresh(ctx: RunnerContext): Promise<RunStepResult |
     return { output: stepOutput };
   } catch (error) {
     if (error instanceof Error && error.name === 'AbortError') {
-      // PAUSE sends PAUSE event (transitions running→awaiting) BEFORE calling abort()
-      // SKIP only calls abort() without sending any event first
-      // So if machine is still 'running', this was a skip - send SKIP to advance
-      // If machine is 'awaiting', this was a pause - preserve that state
-      if (ctx.machine.state === 'running') {
-        debug('[step/run] Step aborted via skip, advancing to next step');
-        ctx.emitter.updateAgentStatus(uniqueAgentId, 'skipped');
-        ctx.machine.send({ type: 'SKIP' });
-      } else {
-        debug('[step/run] Step aborted via pause, entering awaiting state');
-        ctx.emitter.updateAgentStatus(uniqueAgentId, 'awaiting');
-      }
+      // Signal handlers (pause/skip) handle status updates and state transitions
+      debug('[step/run] Step aborted');
       return null;
     }